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