Typedefs | |
typedef struct pn_ssl_domain_t | pn_ssl_domain_t |
typedef struct pn_ssl_t | pn_ssl_t |
Enumerations | |
enum | pn_ssl_mode_t { PN_SSL_MODE_CLIENT = 1, PN_SSL_MODE_SERVER } |
Determines the type of SSL endpoint. More... | |
enum | pn_ssl_resume_status_t { PN_SSL_RESUME_UNKNOWN, PN_SSL_RESUME_NEW, PN_SSL_RESUME_REUSED } |
Indicates whether an SSL session has been resumed. More... | |
enum | pn_ssl_verify_mode_t { PN_SSL_VERIFY_NULL = 0, PN_SSL_VERIFY_PEER, PN_SSL_ANONYMOUS_PEER, PN_SSL_VERIFY_PEER_NAME } |
Determines the level of peer validation. More... | |
enum | pn_ssl_cert_subject_subfield { PN_SSL_CERT_SUBJECT_COUNTRY_NAME, PN_SSL_CERT_SUBJECT_STATE_OR_PROVINCE, PN_SSL_CERT_SUBJECT_CITY_OR_LOCALITY, PN_SSL_CERT_SUBJECT_ORGANIZATION_NAME, PN_SSL_CERT_SUBJECT_ORGANIZATION_UNIT, PN_SSL_CERT_SUBJECT_COMMON_NAME } |
Enumeration identifying the sub fields of the subject field in the ssl certificate. More... | |
enum | pn_ssl_hash_alg { PN_SSL_SHA1, PN_SSL_SHA256, PN_SSL_SHA512, PN_SSL_MD5 } |
Enumeration identifying hashing algorithm. More... | |
Functions | |
PN_EXTERN bool | pn_ssl_present (void) |
Tests for SSL implementation present. | |
PN_EXTERN pn_ssl_domain_t * | pn_ssl_domain (pn_ssl_mode_t mode) |
Create an SSL configuration domain. | |
PN_EXTERN void | pn_ssl_domain_free (pn_ssl_domain_t *domain) |
Release an SSL configuration domain. | |
PN_EXTERN int | pn_ssl_domain_set_credentials (pn_ssl_domain_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_EXTERN int | pn_ssl_domain_set_trusted_ca_db (pn_ssl_domain_t *domain, const char *certificate_db) |
Configure the set of trusted CA certificates used by this domain to verify peers. | |
PN_EXTERN int | pn_ssl_domain_set_peer_authentication (pn_ssl_domain_t *domain, const pn_ssl_verify_mode_t mode, const char *trusted_CAs) |
Configure the level of verification used on the peer certificate. | |
PN_EXTERN int | pn_ssl_domain_allow_unsecured_client (pn_ssl_domain_t *domain) |
Permit a server to accept connection requests from non-SSL clients. | |
PN_EXTERN pn_ssl_t * | pn_ssl (pn_transport_t *transport) |
Create a new SSL session object associated with a transport. | |
PN_EXTERN int | pn_ssl_init (pn_ssl_t *ssl, pn_ssl_domain_t *domain, const char *session_id) |
Initialize an SSL session. | |
PN_EXTERN bool | pn_ssl_get_cipher_name (pn_ssl_t *ssl, char *buffer, size_t size) |
Get the name of the Cipher that is currently in use. | |
PN_EXTERN int | pn_ssl_get_ssf (pn_ssl_t *ssl) |
Get the SSF (security strength factor) of the Cipher that is currently in use. | |
PN_EXTERN bool | pn_ssl_get_protocol_name (pn_ssl_t *ssl, char *buffer, size_t size) |
Get the name of the SSL protocol that is currently in use. | |
PN_EXTERN pn_ssl_resume_status_t | pn_ssl_resume_status (pn_ssl_t *ssl) |
Check whether the state has been resumed. | |
PN_EXTERN int | pn_ssl_set_peer_hostname (pn_ssl_t *ssl, const char *hostname) |
Set the expected identity of the remote peer. | |
PN_EXTERN int | pn_ssl_get_peer_hostname (pn_ssl_t *ssl, char *hostname, size_t *bufsize) |
Access the configured peer identity. | |
PN_EXTERN const char * | pn_ssl_get_remote_subject (pn_ssl_t *ssl) |
Get the subject from the peers certificate. | |
PN_EXTERN int | pn_ssl_get_cert_fingerprint (pn_ssl_t *ssl0, char *fingerprint, size_t fingerprint_length, pn_ssl_hash_alg hash_alg) |
Get the fingerprint of the certificate. | |
PN_EXTERN const char * | pn_ssl_get_remote_subject_subfield (pn_ssl_t *ssl0, pn_ssl_cert_subject_subfield field) |
Returns a char pointer that contains the value of the sub field of the subject field in the ssl certificate. |
typedef struct pn_ssl_domain_t pn_ssl_domain_t |
Enumeration identifying the sub fields of the subject field in the ssl certificate.
enum pn_ssl_hash_alg |
enum pn_ssl_mode_t |
enum pn_ssl_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_ssl_set_peer_hostname).
ANONYMOUS_PEER is configured by default.
PN_EXTERN pn_ssl_t* pn_ssl | ( | pn_transport_t * | transport | ) |
Create a new SSL session object associated with a transport.
A transport must have an SSL object in order to "speak" SSL over its connection. This method allocates an SSL object associates it with the transport.
[in] | transport | the transport that will own the new SSL session. |
PN_EXTERN pn_ssl_domain_t* pn_ssl_domain | ( | pn_ssl_mode_t | mode | ) |
Create an SSL configuration domain.
This method allocates an SSL domain object. This object is used to hold the SSL configuration for one or more SSL sessions. The SSL session object (pn_ssl_t) is allocated from this object.
[in] | mode | the role, client or server, assumed by all SSL sessions created with this domain. |
PN_EXTERN int pn_ssl_domain_allow_unsecured_client | ( | pn_ssl_domain_t * | domain | ) |
Permit a server to accept connection requests from non-SSL clients.
This configures the server to "sniff" the incoming client data stream, and dynamically determine whether SSL/TLS is being used. This option is disabled by default: only clients using SSL/TLS are accepted.
[in] | domain | the domain (server) that will accept the client connections. |
PN_EXTERN void pn_ssl_domain_free | ( | pn_ssl_domain_t * | domain | ) |
Release an SSL configuration domain.
This method frees an SSL domain object allocated by pn_ssl_domain.
[in] | domain | the domain to destroy. |
PN_EXTERN int pn_ssl_domain_set_credentials | ( | pn_ssl_domain_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 SSL 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 SSL servers and SSL clients (if client authentication is required by the server).
[in] | domain | the ssl 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_EXTERN int pn_ssl_domain_set_peer_authentication | ( | pn_ssl_domain_t * | domain, | |
const pn_ssl_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, neither servers nor clients attempt to verify their peers (PN_SSL_ANONYMOUS_PEER). Once certificates and trusted CAs are configured, peer verification can be enabled.
[in] | domain | the ssl 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_EXTERN int pn_ssl_domain_set_trusted_ca_db | ( | pn_ssl_domain_t * | domain, | |
const char * | certificate_db | |||
) |
Configure the set of trusted CA certificates used by this domain to verify peers.
If the local SSL 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 ssl domain that will use the database. |
[in] | certificate_db | database of trusted CAs, used to authenticate the peer. |
PN_EXTERN int pn_ssl_get_cert_fingerprint | ( | pn_ssl_t * | ssl0, | |
char * | fingerprint, | |||
size_t | fingerprint_length, | |||
pn_ssl_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] | ssl0 | the ssl 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 '' 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_ssl_hash_alg (currently supports sha1, sha256, sha512 and md5) |
PN_EXTERN bool pn_ssl_get_cipher_name | ( | pn_ssl_t * | ssl, | |
char * | buffer, | |||
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 SSL is not active (no cipher). Note that the cipher in use may change over time due to renegotiation or other changes to the SSL state.
[in] | ssl | the ssl client/server to query. |
[in,out] | buffer | buffer of size bytes to hold cipher name |
[in] | size | maximum number of bytes in buffer. |
PN_EXTERN int pn_ssl_get_peer_hostname | ( | pn_ssl_t * | ssl, | |
char * | hostname, | |||
size_t * | bufsize | |||
) |
Access the configured peer identity.
Return the expected identity of the remote peer, as set by pn_ssl_set_peer_hostname.
[in] | ssl | the ssl 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_EXTERN bool pn_ssl_get_protocol_name | ( | pn_ssl_t * | ssl, | |
char * | buffer, | |||
size_t | size | |||
) |
Get the name of the SSL protocol that is currently in use.
Gets a text description of the SSL protocol that is currently active, or returns FALSE if SSL is not active. Note that the protocol may change over time due to renegotiation.
[in] | ssl | the ssl client/server to query. |
[in,out] | buffer | buffer of size bytes to hold the version identifier |
[in] | size | maximum number of bytes in buffer. |
PN_EXTERN const char* pn_ssl_get_remote_subject | ( | pn_ssl_t * | ssl | ) |
Get the subject from the peers certificate.
[in] | ssl | the ssl client/server to query. |
PN_EXTERN const char* pn_ssl_get_remote_subject_subfield | ( | pn_ssl_t * | ssl0, | |
pn_ssl_cert_subject_subfield | field | |||
) |
Returns a char pointer that contains the value of the sub field of the subject field in the ssl 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] | ssl0 | the ssl client/server to query |
[in] | field | The enumeration pn_ssl_cert_subject_subfield representing the required sub field. |
PN_EXTERN int pn_ssl_get_ssf | ( | pn_ssl_t * | ssl | ) |
Get the SSF (security strength factor) of the Cipher that is currently in use.
[in] | ssl | the ssl client/server to query. |
PN_EXTERN int pn_ssl_init | ( | pn_ssl_t * | ssl, | |
pn_ssl_domain_t * | domain, | |||
const char * | session_id | |||
) |
Initialize an SSL session.
This method configures an SSL object using the configuration provided by the given domain.
[in] | ssl | the ssl session to configured. |
[in] | domain | the ssl domain used to configure the SSL session. |
[in] | session_id | if supplied, attempt to resume a previous SSL session that used the same session_id. If no previous SSL session is available, a new session will be created using the session_id and stored for future session restore (see ::pn_ssl_resume_status). |
PN_EXTERN bool pn_ssl_present | ( | void | ) |
Tests for SSL implementation present.
PN_EXTERN pn_ssl_resume_status_t pn_ssl_resume_status | ( | pn_ssl_t * | ssl | ) |
Check whether the state has been resumed.
Used for client session resume. When called on an active session, indicates whether the state has been resumed from a previous session.
[in] | ssl | the ssl session to check |
PN_EXTERN int pn_ssl_set_peer_hostname | ( | pn_ssl_t * | ssl, | |
const char * | hostname | |||
) |
Set the expected identity of the remote peer.
By default, SSL 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 SSL 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 SSL connection is aborted.
[in] | ssl | the ssl session. |
[in] | hostname | the expected identity of the remote. Must conform to the syntax as given in RFC1034, Section 3.5. |