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

cert	a Strophe certificate object
errormsg	The 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

enum 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

conn	a Strophe connection object
hndl	certfail Handler function

xmpp_conn_set_cafile()

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

Set the CAfile.

Parameters

conn	a Strophe connection object
cert	path 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

conn	a Strophe connection object
cert	path 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

conn	a 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

conn	a Strophe connection object
cert	path to a certificate file
key	path 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

conn	a 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

conn	a Strophe connection object
n	the 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

cert	a 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

cert	a 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

cert	a 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

cert	a Strophe TLS certificate object
n	which 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

cert	a Strophe TLS certificate object
elmnt	which 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

cert	a Strophe TLS certificate object
elmnt	which element

Returns

a string with the description

xmpp_tlscert_free()

void xmpp_tlscert_free

(

xmpp_tlscert_t *

cert

)

Free a certificate object.

Parameters

cert	a Strophe TLS certificate object