Qpid Proton C API  0.37.0
Tls

Macros

#define PN_TLS_OK
 Error codes. More...
 
#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. More...
 
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_tpn_tls_config (pn_tls_mode_t mode)
 Create an TLS configuration domain. More...
 
PN_TLS_EXTERN void pn_tls_config_free (pn_tls_config_t *domain)
 Release an TLS configuration domain. More...
 
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. More...
 
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. More...
 
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. More...
 
PN_TLS_EXTERN int pn_tls_config_set_impl_ciphers (pn_tls_config_t *domain, const char *ciphers)
 Configure the list of permitted ciphers. More...
 
PN_TLS_EXTERN pn_tls_tpn_tls (pn_tls_config_t *domain)
 Create a new TLS session object derived from a domain. More...
 
PN_TLS_EXTERN int pn_tls_start (pn_tls_t *tls)
 Start a TLS session. More...
 
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. More...
 
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. More...
 
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. More...
 
PN_TLS_EXTERN int pn_tls_set_peer_hostname (pn_tls_t *tls, const char *hostname)
 Set the expected identity of the remote peer. More...
 
PN_TLS_EXTERN int pn_tls_get_peer_hostname (pn_tls_t *tls, char *hostname, size_t *bufsize)
 Access the configured peer identity. More...
 
PN_TLS_EXTERN const char * pn_tls_get_remote_subject (pn_tls_t *tls)
 Get the subject from the peers certificate. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

Detailed Description

Macro Definition Documentation

◆ PN_TLS_OK

#define PN_TLS_OK

Error codes.

No error

Typedef Documentation

◆ 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:

  • A top-level object that stores the configuration used by one or more TLS sessions (pn_tls_config_t).
  • A per-connection TLS session object that performs the encryption/authentication associated with the transport (pn_tls_t).

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)

◆ pn_tls_t

typedef struct pn_tls_t pn_tls_t
See also
pn_tls

Enumeration Type Documentation

◆ pn_tls_mode_t

Determines the type of TLS endpoint.

Enumerator
PN_TLS_MODE_CLIENT 

Local connection endpoint is an TLS client.

PN_TLS_MODE_SERVER 

Local connection endpoint is an TLS server.

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

Enumerator
PN_TLS_VERIFY_NULL 

internal use only

PN_TLS_VERIFY_PEER 

require peer to provide a valid identifying certificate

PN_TLS_ANONYMOUS_PEER 

do not require a certificate nor cipher authorization

PN_TLS_VERIFY_PEER_NAME 

require valid certificate and matching name

Function Documentation

◆ pn_tls_config()

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.

Parameters
[in]modethe role, client or server, assumed by all TLS sessions created with this domain.
Returns
a pointer to the TLS domain, if TLS support is present.

◆ pn_tls_config_free()

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.

Parameters
[in]domainthe domain to destroy.

◆ pn_tls_config_set_credentials()

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

Note
This setting effects only those pn_tls_t objects created after this call returns. pn_tls_t objects created before invoking this method will use the domain's previous setting.
Parameters
[in]domainthe tls domain that will use this certificate.
[in]credential_1specifier 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_2an 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]passwordthe password used to sign the key, else NULL if key is not protected.
Returns
0 on success

◆ pn_tls_config_set_trusted_certs()

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.

Note
This setting effects only those pn_tls_t objects created after this call returns. pn_tls_t objects created before invoking this method will use the domain's previous setting.
By default the list of trusted CA certificates will be set to the system default. What this is is depends on the OS and the TLS implementation used: For OpenTLS the default will depend on how the OS is set up. When using the Windows SChannel implementation the default will be the users default trusted certificate store.
Parameters
[in]domainthe tls domain that will use the database.
[in]certificate_dbdatabase of trusted CAs, used to authenticate the peer.
Returns
0 on success

◆ pn_tls_config_set_peer_authentication()

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.

Note
In order to verify a peer, a trusted CA must be configured. See pn_tls_config_set_trusted_certs().
Servers must provide their own certificate when verifying a peer. See pn_tls_config_set_credentials().
This setting effects only those pn_tls_t objects created after this call returns. pn_tls_t objects created before invoking this method will use the domain's previous setting.
Parameters
[in]domainthe tls domain to configure.
[in]modethe level of validation to apply to the peer
[in]trusted_CAspath 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.
Returns
0 on success

◆ pn_tls_config_set_impl_ciphers()

PN_TLS_EXTERN int pn_tls_config_set_impl_ciphers ( pn_tls_config_t domain,
const char *  ciphers 
)

Configure the list of permitted ciphers.

Note
The syntax of the permitted list is undefined and will depend on the underlying TLS implementation.
Parameters
[in]domainthe tls domain to configure.
[in]ciphersstring representing the cipher list
Returns
0 on success

◆ pn_tls()

PN_TLS_EXTERN pn_tls_t* pn_tls ( pn_tls_config_t domain)

Create a new TLS session object derived from a domain.

Parameters
[in]domainthe domain that configures the TLS session.
Returns
a pointer to the TLS object. Returns NULL if memory allocation fails or if domain is NULL.

◆ pn_tls_start()

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.

Parameters
[in]tlsthe tls session to configured.
Returns
0 on success, else an error code.

◆ pn_tls_get_cipher()

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.

Parameters
[in]tlsthe tls client/server to query.
[out]cipherset to a pointer to the current cipher description or NULL if no cipher.
[out]sizeset to the cipher or 0 if no cipher.
Returns
True if cipher is non-null and size is not zero.

◆ pn_tls_get_ssf()

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.

Parameters
[in]tlsthe tls client/server to query.
Returns
the ssf, note that 0 means no security.

◆ pn_tls_get_protocol_version()

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.

Parameters
[in]tlsthe tls client/server to query.
[out]versionset to a pointer to the current protocol version or NULL if not active.
[out]sizeset to the length of the version or zero if not active.
Returns
True if version is non-null and size is not zero. not ready.

◆ pn_tls_set_peer_hostname()

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.

Note
Verification of the hostname is only done if PN_TLS_VERIFY_PEER_NAME is enabled. See pn_tls_config_set_peer_authentication.
Parameters
[in]tlsthe tls session.
[in]hostnamethe expected identity of the remote. Must conform to the syntax as given in RFC1034, Section 3.5.
Returns
0 on success.

◆ pn_tls_get_peer_hostname()

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.

Parameters
[in]tlsthe tls session.
[out]hostnamebuffer to hold the null-terminated name string. If null, no string is written.
[in,out]bufsizeon 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.
Returns
0 on success.

◆ pn_tls_get_remote_subject()

PN_TLS_EXTERN const char* pn_tls_get_remote_subject ( pn_tls_t tls)

Get the subject from the peers certificate.

Parameters
[in]tlsthe tls client/server to query.
Returns
A null terminated string representing the full subject, which is valid until the tls object is destroyed.

◆ pn_tls_get_cert_fingerprint()

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.

Parameters
[in]tls0the tls client/server to query
[in]fingerprintchar 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_algthe hash algorithm to use. Must be of type pn_tls_hash_alg (currently supports sha1, sha256, sha512 and md5)
Returns
error code - Returns 0 on success. Return a value less than zero if there were any errors. Upon execution of this function, char *fingerprint will contain the appropriate null terminated hex fingerprint

◆ pn_tls_get_remote_subject_subfield()

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

Parameters
[in]tls0the tls client/server to query
[in]fieldThe enumeration pn_tls_cert_subject_subfield representing the required sub field.
Returns
A null terminated string which contains the requested sub field value which is valid until the tls object is destroyed.

◆ pn_tls_config_set_alpn_protocols()

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.

Note
This setting effects only those pn_tls_t objects created after this call returns. pn_tls_t objects created before invoking this method will use the domain's previous setting.
Parameters
[in]tlsthe tls client/server to query.
[in]protocolsthe array of pointers the protocol names in the list.
[in]countthe size of the protocols array.
Returns
0 on success, PN_ARG_ERROR if any array pointers are null or any protocol names exceed 255 bytes in length. PN_OUT_OF_MEMORY if memory allocation fails.

◆ pn_tls_get_alpn_protocol()

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.

Parameters
[in]tlsthe tls client/server to query.
[out]protocol_nameset to a pointer to the application protocol name or NULL if not negotiated.
[out]sizeset to the length of the protocol name or zero if not negotiated.
Returns
True if the protocol_name is non-null and size is not zero.