Macros | |
#define | PN_TLS_OK |
Error codes. | |
#define | PN_TLS_INIT_ERR |
Failure in initialization, unrelated to activity with the peer. | |
#define | PN_TLS_PROTOCOL_ERR |
Failure in the TLS protocol between peers. | |
#define | PN_TLS_AUTHENTICATION_ERR |
Peer authentication failure. | |
#define | PN_TLS_STATE_ERR |
Requested action not possible due to session state. | |
Typedefs | |
typedef struct pn_tls_config_t | pn_tls_config_t |
API for using TLS separate from AMQP connections. | |
typedef struct pn_tls_t | pn_tls_t |
Enumerations | |
enum | pn_tls_mode_t { PN_TLS_MODE_CLIENT , PN_TLS_MODE_SERVER } |
Determines the type of TLS endpoint. More... | |
enum | pn_tls_verify_mode_t { PN_TLS_VERIFY_NULL , PN_TLS_VERIFY_PEER , PN_TLS_ANONYMOUS_PEER , PN_TLS_VERIFY_PEER_NAME } |
Determines the level of peer validation. More... | |
enum | pn_tls_cert_subject_subfield { PN_TLS_CERT_SUBJECT_COUNTRY_NAME , PN_TLS_CERT_SUBJECT_STATE_OR_PROVINCE , PN_TLS_CERT_SUBJECT_CITY_OR_LOCALITY , PN_TLS_CERT_SUBJECT_ORGANIZATION_NAME , PN_TLS_CERT_SUBJECT_ORGANIZATION_UNIT , PN_TLS_CERT_SUBJECT_COMMON_NAME } |
Enumeration identifying the sub fields of the subject field in the tls certificate. | |
enum | pn_tls_hash_alg { PN_TLS_SHA1 , PN_TLS_SHA256 , PN_TLS_SHA512 , PN_TLS_MD5 } |
Enumeration identifying hashing algorithm. | |
Functions | |
PN_TLS_EXTERN pn_tls_config_t * | pn_tls_config (pn_tls_mode_t mode) |
Create an TLS configuration domain. | |
PN_TLS_EXTERN void | pn_tls_config_free (pn_tls_config_t *domain) |
Release an TLS configuration domain. | |
PN_TLS_EXTERN int | pn_tls_config_set_credentials (pn_tls_config_t *domain, const char *credential_1, const char *credential_2, const char *password) |
Set the certificate that identifies the local node to the remote. | |
PN_TLS_EXTERN int | pn_tls_config_set_trusted_certs (pn_tls_config_t *domain, const char *certificate_db) |
Configure the set of trusted CA certificates used by this domain to verify peers. | |
PN_TLS_EXTERN int | pn_tls_config_set_peer_authentication (pn_tls_config_t *domain, const pn_tls_verify_mode_t mode, const char *trusted_CAs) |
Configure the level of verification used on the peer certificate. | |
PN_TLS_EXTERN int | pn_tls_config_set_impl_ciphers (pn_tls_config_t *domain, const char *ciphers) |
Configure the list of permitted ciphers. | |
PN_TLS_EXTERN pn_tls_t * | pn_tls (pn_tls_config_t *domain) |
Create a new TLS session object derived from a domain. | |
PN_TLS_EXTERN int | pn_tls_start (pn_tls_t *tls) |
Start a TLS session. | |
PN_TLS_EXTERN void | pn_tls_free (pn_tls_t *tls) |
PN_TLS_EXTERN bool | pn_tls_get_cipher (pn_tls_t *tls, const char **cipher, size_t *size) |
Get the name of the Cipher that is currently in use. | |
PN_TLS_EXTERN int | pn_tls_get_ssf (pn_tls_t *tls) |
Get the SSF (security strength factor) of the Cipher that is currently in use. | |
PN_TLS_EXTERN bool | pn_tls_get_protocol_version (pn_tls_t *tls, const char **version, size_t *size) |
Get the name of the TLS protocol that is currently in use. | |
PN_TLS_EXTERN int | pn_tls_set_peer_hostname (pn_tls_t *tls, const char *hostname) |
Set the expected identity of the remote peer. | |
PN_TLS_EXTERN int | pn_tls_get_peer_hostname (pn_tls_t *tls, char *hostname, size_t *bufsize) |
Access the configured peer identity. | |
PN_TLS_EXTERN const char * | pn_tls_get_remote_subject (pn_tls_t *tls) |
Get the subject from the peers certificate. | |
PN_TLS_EXTERN int | pn_tls_get_cert_fingerprint (pn_tls_t *tls0, char *fingerprint, size_t fingerprint_length, pn_tls_hash_alg hash_alg) |
Get the fingerprint of the certificate. | |
PN_TLS_EXTERN const char * | pn_tls_get_remote_subject_subfield (pn_tls_t *tls, pn_tls_cert_subject_subfield field) |
Returns a char pointer that contains the value of the sub field of the subject field in the tls certificate. | |
PN_TLS_EXTERN bool | pn_tls_is_encrypt_output_pending (pn_tls_t *tls) |
PN_TLS_EXTERN bool | pn_tls_is_decrypt_output_pending (pn_tls_t *tls) |
PN_TLS_EXTERN bool | pn_tls_is_secure (pn_tls_t *tls) |
PN_TLS_EXTERN size_t | pn_tls_give_encrypt_output_buffers (pn_tls_t *, pn_raw_buffer_t const *, size_t count) |
PN_TLS_EXTERN size_t | pn_tls_give_decrypt_output_buffers (pn_tls_t *, pn_raw_buffer_t const *, size_t count) |
PN_TLS_EXTERN size_t | pn_tls_take_decrypt_output_buffers (pn_tls_t *, pn_raw_buffer_t *, size_t count) |
PN_TLS_EXTERN size_t | pn_tls_take_encrypt_output_buffers (pn_tls_t *, pn_raw_buffer_t *, size_t count) |
PN_TLS_EXTERN size_t | pn_tls_give_encrypt_input_buffers (pn_tls_t *, pn_raw_buffer_t const *bufs, size_t count_bufs) |
PN_TLS_EXTERN size_t | pn_tls_give_decrypt_input_buffers (pn_tls_t *, pn_raw_buffer_t const *bufs, size_t count_bufs) |
PN_TLS_EXTERN size_t | pn_tls_take_encrypt_input_buffers (pn_tls_t *, pn_raw_buffer_t *, size_t count) |
PN_TLS_EXTERN size_t | pn_tls_take_decrypt_input_buffers (pn_tls_t *, pn_raw_buffer_t *, size_t count) |
PN_TLS_EXTERN size_t | pn_tls_get_encrypt_input_buffer_capacity (pn_tls_t *) |
PN_TLS_EXTERN size_t | pn_tls_get_decrypt_input_buffer_capacity (pn_tls_t *) |
PN_TLS_EXTERN bool | pn_tls_need_encrypt_output_buffers (pn_tls_t *) |
PN_TLS_EXTERN bool | pn_tls_need_decrypt_output_buffers (pn_tls_t *) |
PN_TLS_EXTERN size_t | pn_tls_get_encrypt_output_buffer_capacity (pn_tls_t *) |
PN_TLS_EXTERN size_t | pn_tls_get_decrypt_output_buffer_capacity (pn_tls_t *) |
PN_TLS_EXTERN size_t | pn_tls_get_decrypt_output_buffer_count (pn_tls_t *) |
PN_TLS_EXTERN size_t | pn_tls_get_encrypt_output_buffer_count (pn_tls_t *) |
PN_TLS_EXTERN uint32_t | pn_tls_get_last_decrypt_output_buffer_size (pn_tls_t *) |
PN_TLS_EXTERN uint32_t | pn_tls_get_last_encrypt_output_buffer_size (pn_tls_t *) |
PN_TLS_EXTERN void | pn_tls_set_encrypt_input_buffer_max_capacity (pn_tls_t *, size_t s) |
PN_TLS_EXTERN void | pn_tls_set_decrypt_input_buffer_max_capacity (pn_tls_t *, size_t s) |
PN_TLS_EXTERN void | pn_tls_set_encrypt_output_buffer_max_capacity (pn_tls_t *, size_t s) |
PN_TLS_EXTERN void | pn_tls_set_decrypt_output_buffer_max_capacity (pn_tls_t *, size_t s) |
PN_TLS_EXTERN int | pn_tls_process (pn_tls_t *tls) |
PN_TLS_EXTERN int | pn_tls_stop (pn_tls_t *tls) |
PN_TLS_EXTERN bool | pn_tls_is_input_closed (pn_tls_t *tls) |
PN_TLS_EXTERN void | pn_tls_close_output (pn_tls_t *tls) |
PN_TLS_EXTERN int | pn_tls_get_session_error (pn_tls_t *tls) |
PN_TLS_EXTERN size_t | pn_tls_get_session_error_string (pn_tls_t *tls, char *buf, size_t buf_len) |
PN_TLS_EXTERN int | pn_tls_config_set_alpn_protocols (pn_tls_config_t *domain, const char **protocols, size_t protocol_count) |
Provide an ordered list of application protols for RFC 7301 negotiation. | |
PN_TLS_EXTERN bool | pn_tls_get_alpn_protocol (pn_tls_t *tls, const char **protocol_name, size_t *size) |
Get the name of the negotiated application protocol. | |
#define PN_TLS_OK |
Error codes.
No error
typedef struct pn_tls_config_t pn_tls_config_t |
API for using TLS separate from AMQP connections.
This API is currently unsettled and subject to significant change and improvement.
Based heavily on the original Proton SSL API for configuring TLS over AMQP connections, this implementation separates the encryption/decryption of data from the network IO operations.
A Transport can be configured as either an "TLS client" or an "TLS server". An TLS client is the party that proactively establishes a connection to an TLS server. An TLS server is the party that accepts a connection request from a remote TLS client.
This TLS implementation defines the following objects:
The pn_tls_config_t is used to construct an TLS session (pn_tls_t). The session "adopts" its configuration from the pn_tls_config_t that was used to create it. For example, pn_tls_config_t can be configured as either a "client" or a "server". TLS sessions constructed from this domain will perform the corresponding role (either client or server).
If an TLS session is created without a pn_tls_config_t object then a default will be used (see ::pn_tls_init()).
If either an TLS server or client needs to identify itself with the remote node, it must have its TLS certificate configured (see pn_tls_config_set_credentials()).
If either an TLS server or client needs to verify the identity of the remote node, it must have its database of trusted CAs configured. By default this will be set up to use the default system database of trusted CA. But this can be changed (see pn_tls_config_set_trusted_certs()).
The level of verification required of the remote may be configured (see pn_tls_config_set_peer_authentication)
enum pn_tls_mode_t |
enum pn_tls_verify_mode_t |
Determines the level of peer validation.
ANONYMOUS_PEER does not require a valid certificate, and permits use of ciphers that do not provide authentication.
VERIFY_PEER will only connect to those peers that provide a valid identifying certificate signed by a trusted CA and are using an authenticated cipher.
VERIFY_PEER_NAME is like VERIFY_PEER, but also requires the peer's identity as contained in the certificate to be valid (see pn_tls_set_peer_hostname).
VERIFY_PEER_NAME is configured by default.
PN_TLS_EXTERN pn_tls_config_t * pn_tls_config | ( | pn_tls_mode_t | mode | ) |
Create an TLS configuration domain.
This method allocates an TLS domain object. This object is used to hold the TLS configuration for one or more TLS sessions. The TLS session object (pn_tls_t) is allocated from this object.
[in] | mode | the role, client or server, assumed by all TLS sessions created with this domain. |
PN_TLS_EXTERN void pn_tls_config_free | ( | pn_tls_config_t * | domain | ) |
Release an TLS configuration domain.
This method frees an TLS domain object allocated by pn_tls_config.
[in] | domain | the domain to destroy. |
PN_TLS_EXTERN int pn_tls_config_set_credentials | ( | pn_tls_config_t * | domain, |
const char * | credential_1, | ||
const char * | credential_2, | ||
const char * | password | ||
) |
Set the certificate that identifies the local node to the remote.
This certificate establishes the identity for the local node for all TLS sessions created from this domain. It will be sent to the remote if the remote needs to verify the identity of this node. This may be used for both TLS servers and TLS clients (if client authentication is required by the server).
[in] | domain | the tls domain that will use this certificate. |
[in] | credential_1 | specifier for the file/database containing the identifying certificate. For Openssl users, this is a PEM file. For Windows SChannel users, this is the PKCS#12 file or system store. |
[in] | credential_2 | an optional key to access the identifying certificate. For Openssl users, this is an optional PEM file containing the private key used to sign the certificate. For Windows SChannel users, this is the friendly name of the self-identifying certificate if there are multiple certificates in the store. |
[in] | password | the password used to sign the key, else NULL if key is not protected. |
PN_TLS_EXTERN int pn_tls_config_set_trusted_certs | ( | pn_tls_config_t * | domain, |
const char * | certificate_db | ||
) |
Configure the set of trusted CA certificates used by this domain to verify peers.
If the local TLS client/server needs to verify the identity of the remote, it must validate the signature of the remote's certificate. This function sets the database of trusted CAs that will be used to verify the signature of the remote's certificate.
[in] | domain | the tls domain that will use the database. |
[in] | certificate_db | database of trusted CAs, used to authenticate the peer. |
PN_TLS_EXTERN int pn_tls_config_set_peer_authentication | ( | pn_tls_config_t * | domain, |
const pn_tls_verify_mode_t | mode, | ||
const char * | trusted_CAs | ||
) |
Configure the level of verification used on the peer certificate.
This method controls how the peer's certificate is validated, if at all. By default, servers do not attempt to verify their peers (PN_TLS_ANONYMOUS_PEER) but clients attempt to verify both the certificate and peer name (PN_TLS_VERIFY_PEER_NAME). Once certificates and trusted CAs are configured, peer verification can be enabled.
[in] | domain | the tls domain to configure. |
[in] | mode | the level of validation to apply to the peer |
[in] | trusted_CAs | path to a database of trusted CAs that the server will advertise to the peer client if the server has been configured to verify its peer. |
PN_TLS_EXTERN int pn_tls_config_set_impl_ciphers | ( | pn_tls_config_t * | domain, |
const char * | ciphers | ||
) |
Configure the list of permitted ciphers.
[in] | domain | the tls domain to configure. |
[in] | ciphers | string representing the cipher list |
PN_TLS_EXTERN pn_tls_t * pn_tls | ( | pn_tls_config_t * | domain | ) |
Create a new TLS session object derived from a domain.
[in] | domain | the domain that configures the TLS session. |
PN_TLS_EXTERN int pn_tls_start | ( | pn_tls_t * | tls | ) |
Start a TLS session.
This method starts the operation of a TLS session based on the object's configuration. Subsequent configuration steps will have no effect. A client TLS session will generate one or more result buffers for the clienthello handshake.
[in] | tls | the tls session to configured. |
PN_TLS_EXTERN bool pn_tls_get_cipher | ( | pn_tls_t * | tls, |
const char ** | cipher, | ||
size_t * | size | ||
) |
Get the name of the Cipher that is currently in use.
Gets a text description of the cipher that is currently active, or returns FALSE if TLS is not active (no cipher). Note that the cipher in use may change over time due to renegotiation or other changes to the TLS state. The cipher is not null terminated.
[in] | tls | the tls client/server to query. |
[out] | cipher | set to a pointer to the current cipher description or NULL if no cipher. |
[out] | size | set to the cipher or 0 if no cipher. |
PN_TLS_EXTERN int pn_tls_get_ssf | ( | pn_tls_t * | tls | ) |
Get the SSF (security strength factor) of the Cipher that is currently in use.
[in] | tls | the tls client/server to query. |
PN_TLS_EXTERN bool pn_tls_get_protocol_version | ( | pn_tls_t * | tls, |
const char ** | version, | ||
size_t * | size | ||
) |
Get the name of the TLS protocol that is currently in use.
Gets a text description of the TLS protocol that is currently active, or returns FALSE if TLS is not active. Note that the protocol may change over time due to renegotiation.
[in] | tls | the tls client/server to query. |
[out] | version | set to a pointer to the current protocol version or NULL if not active. |
[out] | size | set to the length of the version or zero if not active. |
PN_TLS_EXTERN int pn_tls_set_peer_hostname | ( | pn_tls_t * | tls, |
const char * | hostname | ||
) |
Set the expected identity of the remote peer.
By default, TLS will use the hostname associated with the connection that the transport is bound to (see pn_connection_set_hostname). This method allows the caller to override that default.
The hostname is used for two purposes: 1) when set on an TLS client, it is sent to the server during the handshake (if Server Name Indication is supported), and 2) it is used to check against the identifying name provided in the peer's certificate. If the supplied name does not exactly match a SubjectAltName (type DNS name), or the CommonName entry in the peer's certificate, the peer is considered unauthenticated (potential imposter), and the TLS connection is aborted.
[in] | tls | the tls session. |
[in] | hostname | the expected identity of the remote. Must conform to the syntax as given in RFC1034, Section 3.5. |
PN_TLS_EXTERN int pn_tls_get_peer_hostname | ( | pn_tls_t * | tls, |
char * | hostname, | ||
size_t * | bufsize | ||
) |
Access the configured peer identity.
Return the expected identity of the remote peer, as set by pn_tls_set_peer_hostname.
[in] | tls | the tls session. |
[out] | hostname | buffer to hold the null-terminated name string. If null, no string is written. |
[in,out] | bufsize | on input set to the number of octets in hostname. On output, set to the number of octets needed to hold the value of hostname plus a null byte. Zero if no hostname set. |
PN_TLS_EXTERN const char * pn_tls_get_remote_subject | ( | pn_tls_t * | tls | ) |
Get the subject from the peers certificate.
[in] | tls | the tls client/server to query. |
PN_TLS_EXTERN int pn_tls_get_cert_fingerprint | ( | pn_tls_t * | tls0, |
char * | fingerprint, | ||
size_t | fingerprint_length, | ||
pn_tls_hash_alg | hash_alg | ||
) |
Get the fingerprint of the certificate.
The certificate fingerprint (as displayed in the Fingerprints section when looking at a certificate with say the Firefox browser) is the hexadecimal hash of the entire certificate. The fingerprint is not part of the certificate, rather it is computed from the certificate and can be used to uniquely identify a certificate.
[in] | tls0 | the tls client/server to query |
[in] | fingerprint | char pointer. The certificate fingerprint (in hex format) will be populated in this array. If sha1 is the digest name, the fingerprint is 41 characters long (40 + 1 '\0' character), 65 characters long for sha256 and 129 characters long for sha512 and 33 characters for md5. |
[in] | fingerprint_length | - Must be at >= 33 for md5, >= 41 for sha1, >= 65 for sha256 and >=129 for sha512. |
[in] | hash_alg | the hash algorithm to use. Must be of type pn_tls_hash_alg (currently supports sha1, sha256, sha512 and md5) |
PN_TLS_EXTERN const char * pn_tls_get_remote_subject_subfield | ( | pn_tls_t * | tls, |
pn_tls_cert_subject_subfield | field | ||
) |
Returns a char pointer that contains the value of the sub field of the subject field in the tls certificate.
The subject field usually contains the following sub fields - C = ISO3166 two character country code ST = state or province L = Locality; generally means city O = Organization - Company Name OU = Organization Unit - division or unit CN = CommonName
[in] | tls0 | the tls client/server to query |
[in] | field | The enumeration pn_tls_cert_subject_subfield representing the required sub field. |
PN_TLS_EXTERN int pn_tls_config_set_alpn_protocols | ( | pn_tls_config_t * | domain, |
const char ** | protocols, | ||
size_t | protocol_count | ||
) |
Provide an ordered list of application protols for RFC 7301 negotiation.
List ordered in descending preference for the caller.
Each protocol name must be provided as its well known octet sequence in UTF-8, null terminated. For the client, the order is preserved in the client_hello to the server, but the server will not usually take that ordering into account.
For the server, protocol selection follows the standard mechanism in RFC 7301: the first item in the server list that matches an item in the client list is selected. No match will result in a failed TLS handshake.
ALPN processing can be turned off by setting protocols to NULL and protocol_count to zero.
[in] | tls | the tls client/server to query. |
[in] | protocols | the array of pointers the protocol names in the list. |
[in] | count | the size of the protocols array. |
PN_TLS_EXTERN bool pn_tls_get_alpn_protocol | ( | pn_tls_t * | tls, |
const char ** | protocol_name, | ||
size_t * | size | ||
) |
Get the name of the negotiated application protocol.
Gets the name of the negotiated application protocol or returns FALSE if the negotiation failed, is not yet complete, or was never requested by the client. The protocol name is not a null terminated string.
[in] | tls | the tls client/server to query. |
[out] | protocol_name | set to a pointer to the application protocol name or NULL if not negotiated. |
[out] | size | set to the length of the protocol name or zero if not negotiated. |