Strophe 0.11
XMPP client library
Typedefs | Enumerations | Functions
SSL/TLS specific functionality

These functions provide SSL/TLS specific functionality. More...

Typedefs

typedef int(* xmpp_certfail_handler) (const xmpp_tlscert_t *cert, const char *const errormsg)
 The Handler function which will be called when the TLS stack can't verify the authenticity of a Certificate that gets presented by the server we're trying to connect to. More...
 

Enumerations

enum  xmpp_cert_element_t {
  XMPP_CERT_VERSION , XMPP_CERT_SERIALNUMBER , XMPP_CERT_SUBJECT , XMPP_CERT_ISSUER ,
  XMPP_CERT_NOTBEFORE , XMPP_CERT_NOTAFTER , XMPP_CERT_KEYALG , XMPP_CERT_SIGALG ,
  XMPP_CERT_FINGERPRINT_SHA1 , XMPP_CERT_FINGERPRINT_SHA256 , XMPP_CERT_ELEMENT_MAX
}
 Certificate Elements. More...
 

Functions

void xmpp_conn_set_certfail_handler (xmpp_conn_t *const conn, xmpp_certfail_handler hndl)
 Set the Handler function which will be called when the TLS stack can't verify the CA of the server we're trying to connect to. More...
 
void xmpp_conn_set_cafile (xmpp_conn_t *const conn, const char *path)
 Set the CAfile. More...
 
void xmpp_conn_set_capath (xmpp_conn_t *const conn, const char *path)
 Set the CApath. More...
 
xmpp_tlscert_t * xmpp_conn_get_peer_cert (xmpp_conn_t *const conn)
 Retrieve the peer certificate. More...
 
void xmpp_conn_set_client_cert (xmpp_conn_t *const conn, const char *const cert, const char *const key)
 Set the Client Certificate and Private Key that will be bound to the connection. More...
 
unsigned int xmpp_conn_cert_xmppaddr_num (xmpp_conn_t *const conn)
 Get the number of xmppAddr entries in the client certificate. More...
 
char * xmpp_conn_cert_xmppaddr (xmpp_conn_t *const conn, unsigned int n)
 Get a specific xmppAddr entry. More...
 
xmpp_ctx_t * xmpp_tlscert_get_ctx (const xmpp_tlscert_t *cert)
 Get the Strophe context which is assigned to this certificate. More...
 
xmpp_conn_t * xmpp_tlscert_get_conn (const xmpp_tlscert_t *cert)
 Get the Strophe connection which is assigned to this certificate. More...
 
const char * xmpp_tlscert_get_pem (const xmpp_tlscert_t *cert)
 Get the complete PEM of this certificate. More...
 
const char * xmpp_tlscert_get_dnsname (const xmpp_tlscert_t *cert, size_t n)
 Get the dnsName entries out of the SubjectAlternativeNames. More...
 
const char * xmpp_tlscert_get_string (const xmpp_tlscert_t *cert, xmpp_cert_element_t elmnt)
 Get various parts of the certificate as String. More...
 
const char * xmpp_tlscert_get_description (xmpp_cert_element_t elmnt)
 Get a descriptive string for each xmpp_cert_element_t. More...
 
void xmpp_tlscert_free (xmpp_tlscert_t *cert)
 Free a certificate object. More...
 

Detailed Description

These functions provide SSL/TLS specific functionality.

Typedef Documentation

◆ xmpp_certfail_handler

typedef int(* xmpp_certfail_handler) (const xmpp_tlscert_t *cert, const char *const errormsg)

The Handler function which will be called when the TLS stack can't verify the authenticity of a Certificate that gets presented by the server we're trying to connect to.

When this function is called and details of the cert have to be kept, please copy them yourself. The cert object will be free'd automatically when this function returns.

NB: errormsg is specific per certificate on OpenSSL and the same for all certificates on GnuTLS.

Parameters
certa Strophe certificate object
errormsgThe error that caused this.
Returns
0 if the connection attempt should be terminated, 1 if the connection should be established.

Enumeration Type Documentation

◆ xmpp_cert_element_t

Certificate Elements.

Enumerator
XMPP_CERT_VERSION 

X.509 Version.

XMPP_CERT_SERIALNUMBER 

SerialNumber.

XMPP_CERT_SUBJECT 

Subject.

XMPP_CERT_ISSUER 

Issuer.

XMPP_CERT_NOTBEFORE 

Issued on.

XMPP_CERT_NOTAFTER 

Expires on.

XMPP_CERT_KEYALG 

Public Key Algorithm.

XMPP_CERT_SIGALG 

Certificate Signature Algorithm.

XMPP_CERT_FINGERPRINT_SHA1 

Fingerprint SHA-1.

XMPP_CERT_FINGERPRINT_SHA256 

Fingerprint SHA-256.

XMPP_CERT_ELEMENT_MAX 

Last element of the enum.

Function Documentation

◆ xmpp_conn_set_certfail_handler()

void xmpp_conn_set_certfail_handler ( xmpp_conn_t *const  conn,
xmpp_certfail_handler  hndl 
)

Set the Handler function which will be called when the TLS stack can't verify the CA of the server we're trying to connect to.

Parameters
conna Strophe connection object
hndlcertfail Handler function

◆ xmpp_conn_set_cafile()

void xmpp_conn_set_cafile ( xmpp_conn_t *const  conn,
const char *  path 
)

Set the CAfile.

Parameters
conna Strophe connection object
certpath to a certificate file

◆ xmpp_conn_set_capath()

void xmpp_conn_set_capath ( xmpp_conn_t *const  conn,
const char *  path 
)

Set the CApath.

Parameters
conna Strophe connection object
certpath to a folder containing certificates

◆ xmpp_conn_get_peer_cert()

xmpp_tlscert_t * xmpp_conn_get_peer_cert ( xmpp_conn_t *const  conn)

Retrieve the peer certificate.

The returned Certificate object must be free'd by calling xmpp_tlscert_free

Parameters
conna Strophe connection object
Returns
a Strophe Certificate object

◆ xmpp_conn_set_client_cert()

void xmpp_conn_set_client_cert ( xmpp_conn_t *const  conn,
const char *const  cert,
const char *const  key 
)

Set the Client Certificate and Private Key that will be bound to the connection.

If any of the both was previously set, it will be discarded. This should not be used after a connection is created. The function will make a copy of the strings passed in. Currently only non-encrypted Private Keys are supported.

Parameters
conna Strophe connection object
certpath to a certificate file
keypath to a private key file

◆ xmpp_conn_cert_xmppaddr_num()

unsigned int xmpp_conn_cert_xmppaddr_num ( xmpp_conn_t *const  conn)

Get the number of xmppAddr entries in the client certificate.

Parameters
conna Strophe connection object
Returns
the number of xmppAddr entries in the client certificate

◆ xmpp_conn_cert_xmppaddr()

char * xmpp_conn_cert_xmppaddr ( xmpp_conn_t *const  conn,
unsigned int  n 
)

Get a specific xmppAddr entry.

Parameters
conna Strophe connection object
nthe index of the entry, starting at 0
Returns
a string containing the xmppAddr or NULL if n is out of range

◆ xmpp_tlscert_get_ctx()

xmpp_ctx_t * xmpp_tlscert_get_ctx ( const xmpp_tlscert_t *  cert)

Get the Strophe context which is assigned to this certificate.

Parameters
certa Strophe TLS certificate object
Returns
the Strophe context object where this certificate originates from

◆ xmpp_tlscert_get_conn()

xmpp_conn_t * xmpp_tlscert_get_conn ( const xmpp_tlscert_t *  cert)

Get the Strophe connection which is assigned to this certificate.

Parameters
certa Strophe TLS certificate object
Returns
the Strophe connection object where this certificate originates from

◆ xmpp_tlscert_get_pem()

const char * xmpp_tlscert_get_pem ( const xmpp_tlscert_t *  cert)

Get the complete PEM of this certificate.

Parameters
certa Strophe TLS certificate object
Returns
a string containing the PEM of this certificate

◆ xmpp_tlscert_get_dnsname()

const char * xmpp_tlscert_get_dnsname ( const xmpp_tlscert_t *  cert,
size_t  n 
)

Get the dnsName entries out of the SubjectAlternativeNames.

Note: Max. MAX_NUM_DNSNAMES are supported.

Parameters
certa Strophe TLS certificate object
nwhich dnsName entry
Returns
a string with the n'th dnsName

◆ xmpp_tlscert_get_string()

const char * xmpp_tlscert_get_string ( const xmpp_tlscert_t *  cert,
xmpp_cert_element_t  elmnt 
)

Get various parts of the certificate as String.

c.f. xmpp_cert_element_t for details.

Parameters
certa Strophe TLS certificate object
elmntwhich part of the certificate
Returns
a string with the part of the certificate

◆ xmpp_tlscert_get_description()

const char * xmpp_tlscert_get_description ( xmpp_cert_element_t  elmnt)

Get a descriptive string for each xmpp_cert_element_t.

c.f. xmpp_cert_element_t for details.

Parameters
certa Strophe TLS certificate object
elmntwhich element
Returns
a string with the description

◆ xmpp_tlscert_free()

void xmpp_tlscert_free ( xmpp_tlscert_t *  cert)

Free a certificate object.

Parameters
certa Strophe TLS certificate object