ssl.h File Reference

API for using SSL with the Transport Layer. More...

`#include <proton/import_export.h>`
`#include <proton/type_compat.h>`
`#include <proton/types.h>`

Go to the source code of this file.

## 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. More...
PN_EXTERN pn_ssl_domain_t * | pn_ssl_domain (pn_ssl_mode_t mode)
| Create an SSL configuration domain. More...
PN_EXTERN void | pn_ssl_domain_free (pn_ssl_domain_t *domain)
| Release an SSL configuration domain. More...
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. More...
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. More...
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. More...
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. More...
PN_EXTERN pn_ssl_t * | pn_ssl (pn_transport_t *transport)
| Create a new SSL session object associated with a transport. More...
PN_EXTERN int | pn_ssl_init (pn_ssl_t *ssl, pn_ssl_domain_t *domain, const char *session_id)
| Initialize an SSL session. More...
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. More...
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. More...
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. More...
PN_EXTERN pn_ssl_resume_status_t | pn_ssl_resume_status (pn_ssl_t *ssl)
| Check whether the state has been resumed. More...
PN_EXTERN int | pn_ssl_set_peer_hostname (pn_ssl_t *ssl, const char *hostname)
| Set the expected identity of the remote peer. More...
PN_EXTERN int | pn_ssl_get_peer_hostname (pn_ssl_t *ssl, char *hostname, size_t *bufsize)
| Access the configured peer identity. More...
PN_EXTERN const char * | pn_ssl_get_remote_subject (pn_ssl_t *ssl)
| Get the subject from the peers certificate. More...
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. More...
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. More...

## Detailed Description

API for using SSL with the Transport Layer.

A Transport may be configured to use SSL for encryption and/or authentication. A Transport can be configured as either an "SSL client" or an "SSL server". An SSL client is the party that proactively establishes a connection to an SSL server. An SSL server is the party that accepts a connection request from a remote SSL client.

This SSL implementation defines the following objects:

- A top-level object that stores the configuration used by one or more SSL sessions (pn_ssl_domain_t).
- A per-connection SSL session object that performs the encryption/authentication associated with the transport (pn_ssl_t).
- The encryption parameters negotiated for the SSL session (pn_ssl_state_t).

A pn_ssl_domain_t object must be created and configured before an SSL session can be established. The pn_ssl_domain_t is used to construct an SSL session (pn_ssl_t). The session "adopts" its configuration from the pn_ssl_domain_t that was used to create it. For example, pn_ssl_domain_t can be configured as either a "client" or a "server". SSL sessions constructed from this domain will perform the corresponding role (either client or server).

If either an SSL server or client needs to identify itself with the remote node, it must have its SSL certificate configured (see pn_ssl_domain_set_credentials()).

If either an SSL server or client needs to verify the identity of the remote node, it must have its database of trusted CAs configured (see pn_ssl_domain_set_trusted_ca_db()).

An SSL server connection may allow the remote client to connect without SSL (eg. "in the clear"), see pn_ssl_domain_allow_unsecured_client().

The level of verification required of the remote may be configured (see pn_ssl_domain_set_peer_authentication)

Support for SSL Client Session resume is provided (see pn_ssl_init, pn_ssl_resume_status).