Strophe: SSL/TLS specific functionality

Strophe 0.14 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.
typedef int(* | xmpp_password_callback) (char *pw, size_t pw_max, xmpp_conn_t *conn, void *userdata)
| The Handler function which will be called when the TLS stack can't decrypt a password protected key file.

## 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.
void | xmpp_conn_set_cafile (xmpp_conn_t *const conn, const char *path)
| Set the CAfile.
void | xmpp_conn_set_capath (xmpp_conn_t *const conn, const char *path)
| Set the CApath.
xmpp_tlscert_t * | xmpp_conn_get_peer_cert (xmpp_conn_t *const conn)
| Retrieve the peer certificate.
void | xmpp_conn_set_password_callback (xmpp_conn_t *conn, xmpp_password_callback cb, void *userdata)
| Set the Callback function which will be called when the TLS stack can't decrypt a password protected key file.
void | xmpp_conn_set_password_retries (xmpp_conn_t *conn, unsigned int retries)
| Set the number of retry attempts to decrypt a private key file.
const char * | xmpp_conn_get_keyfile (const xmpp_conn_t *conn)
| Retrieve the path of the key file that shall be unlocked.
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 or PKCS#12 encoded file that will be bound to the connection.
unsigned int | xmpp_conn_cert_xmppaddr_num (xmpp_conn_t *const conn)
| Get the number of xmppAddr entries in the client certificate.
char * | xmpp_conn_cert_xmppaddr (xmpp_conn_t *const conn, unsigned int n)
| Get a specific xmppAddr entry.
xmpp_ctx_t * | xmpp_tlscert_get_ctx (const xmpp_tlscert_t *cert)
| Get the Strophe context which is assigned to this certificate.
xmpp_conn_t * | xmpp_tlscert_get_conn (const xmpp_tlscert_t *cert)
| Get the Strophe connection which is assigned to this certificate.
const char * | xmpp_tlscert_get_pem (const xmpp_tlscert_t *cert)
| Get the complete PEM of this certificate.
const char * | xmpp_tlscert_get_dnsname (const xmpp_tlscert_t *cert, size_t n)
| Get the dnsName entries out of the SubjectAlternativeNames.
const char * | xmpp_tlscert_get_string (const xmpp_tlscert_t *cert, xmpp_cert_element_t elmnt)
| Get various parts of the certificate as String.
const char * | xmpp_tlscert_get_description (xmpp_cert_element_t elmnt)
| Get a descriptive string for each xmpp_cert_element_t.
void | xmpp_tlscert_free (xmpp_tlscert_t *cert)
| Free a certificate object.

## 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.

## ◆ xmpp_password_callback

typedef int(* xmpp_password_callback) (char *pw, size_t pw_max, xmpp_conn_t *conn, void *userdata)

The Handler function which will be called when the TLS stack can't decrypt a password protected key file.

When this callback is called it shall write a NULL-terminated string of maximum length pw_max - 1 to pw.

This is currently only supported for GnuTLS and OpenSSL.

On 2022-02-02 the following maximum lengths are valid:

include/gnutls/pkcs11.h: #define GNUTLS_PKCS11_MAX_PIN_LEN 256
include/openssl/pem.h: #define PEM_BUFSIZE 1024

We expect the buffer to be NULL-terminated, therefore the usable lengths are:

- 255 for GnuTLS
- 1023 for OpenSSL

Useful API's inside this callback are e.g.

xmpp_conn_get_keyfile

Parameters

  pw | The buffer where the password shall be stored.
  pw_max | The maximum length of the password.
  conn | The Strophe connection object this callback originates from.
  userdata | The userdata pointer as supplied when setting this callback.

Returns
  -1 on error, else the number of bytes written to pw w/o terminating NUL byte

## 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
  path | 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
  path | 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_password_callback()

void xmpp_conn_set_password_callback | ( | xmpp_conn_t * | conn,
|  | xmpp_password_callback | cb,
|  | void * | userdata )

Set the Callback function which will be called when the TLS stack can't decrypt a password protected key file.

Parameters

  conn | a Strophe connection object
  cb | The callback function that shall be called
  userdata | An opaque data pointer that will be passed to the callback

## ◆ xmpp_conn_set_password_retries()

void xmpp_conn_set_password_retries | ( | xmpp_conn_t * | conn,
|  | unsigned int | retries )

Set the number of retry attempts to decrypt a private key file.

In case the user enters the password manually it can be useful to directly retry if the decryption of the key file failed.

Parameters

  conn | a Strophe connection object
  retries | The number of retries that should be tried

## ◆ xmpp_conn_get_keyfile()

const char * xmpp_conn_get_keyfile | ( | const xmpp_conn_t * | conn | ) |

Retrieve the path of the key file that shall be unlocked.

This makes usually sense to be called from the xmpp_password_callback .

Parameters

  conn | a Strophe connection object

Returns
  a String of the path to the key file

## ◆ 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 or PKCS#12 encoded file that will be bound to the connection.

If any of them 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.

In case the Private Key is encrypted, a callback must be set via xmpp_conn_set_password_callback so the TLS stack can retrieve the password.

In case one wants to use a PKCS#12 encoded file, it should be passed via the cert parameter and key should be NULL. Passing a PKCS#12 file in key is deprecated.

Parameters

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

  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