C AMQP Protocol Engine API  0.6
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
ssl.h File Reference
#include <proton/import_export.h>
#include <sys/types.h>
#include <stdbool.h>
#include <proton/engine.h>
Include dependency graph for ssl.h:
This graph shows which files directly or indirectly include this file:

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 }
 
enum  pn_ssl_resume_status_t { PN_SSL_RESUME_UNKNOWN, PN_SSL_RESUME_NEW, PN_SSL_RESUME_REUSED }
 
enum  pn_ssl_verify_mode_t { PN_SSL_VERIFY_NULL =0, PN_SSL_VERIFY_PEER, PN_SSL_ANONYMOUS_PEER, PN_SSL_VERIFY_PEER_NAME }
 

Functions

PN_EXTERN pn_ssl_domain_tpn_ssl_domain (pn_ssl_mode_t mode)
 
PN_EXTERN void pn_ssl_domain_free (pn_ssl_domain_t *domain)
 
PN_EXTERN int pn_ssl_domain_set_credentials (pn_ssl_domain_t *domain, const char *certificate_file, const char *private_key_file, const char *password)
 
PN_EXTERN int pn_ssl_domain_set_trusted_ca_db (pn_ssl_domain_t *domain, const char *certificate_db)
 
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)
 
PN_EXTERN int pn_ssl_domain_allow_unsecured_client (pn_ssl_domain_t *domain)
 
PN_EXTERN pn_ssl_tpn_ssl (pn_transport_t *transport)
 
PN_EXTERN int pn_ssl_init (pn_ssl_t *ssl, pn_ssl_domain_t *domain, const char *session_id)
 
PN_EXTERN bool pn_ssl_get_cipher_name (pn_ssl_t *ssl, char *buffer, size_t size)
 
PN_EXTERN bool pn_ssl_get_protocol_name (pn_ssl_t *ssl, char *buffer, size_t size)
 
PN_EXTERN pn_ssl_resume_status_t pn_ssl_resume_status (pn_ssl_t *ssl)
 
PN_EXTERN int pn_ssl_set_peer_hostname (pn_ssl_t *ssl, const char *hostname)
 
PN_EXTERN int pn_ssl_get_peer_hostname (pn_ssl_t *ssl, char *hostname, size_t *bufsize)
 

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

Some per-session attributes - such as peer verification mode - may be overridden on a per-session basis from the default provided by the parent pn_ssl_domain_t.

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

The level of verification required of the remote may be configured (see ::pn_ssl_domain_set_default_peer_authentication ::pn_ssl_set_peer_authentication, ::pn_ssl_get_peer_authentication).

Support for SSL Client Session resume is provided (see ::pn_ssl_get_state, ::pn_ssl_resume_state).

Typedef Documentation

typedef struct pn_ssl_t pn_ssl_t

Enumeration Type Documentation

Determines the type of SSL endpoint.

Enumerator
PN_SSL_MODE_CLIENT 

Local connection endpoint is an SSL client

PN_SSL_MODE_SERVER 

Local connection endpoint is an SSL server

Indicates whether an SSL session has been resumed.

Enumerator
PN_SSL_RESUME_UNKNOWN 

Session resume state unknown/not supported

PN_SSL_RESUME_NEW 

Session renegotiated - not resumed

PN_SSL_RESUME_REUSED 

Session resumed from previous session.

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.

Enumerator
PN_SSL_VERIFY_NULL 

internal use only

PN_SSL_VERIFY_PEER 

require peer to provide a valid identifying certificate

PN_SSL_ANONYMOUS_PEER 

do not require a certificate nor cipher authorization

PN_SSL_VERIFY_PEER_NAME 

require valid certificate and matching name

Function Documentation

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.

Parameters
[in]transportthe transport that will own the new SSL session.
Returns
a pointer to the SSL object configured for this transport. Returns NULL if no SSL session is associated with the transport.
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.

Parameters
[in]modethe role, client or server, assumed by all SSL sessions created with this domain.
Returns
a pointer to the SSL domain, if SSL support is present.
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.

Parameters
[in]domainthe domain (server) that will accept the client connections.
Returns
0 on success
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.

Parameters
[in]domainthe domain to destroy.
PN_EXTERN int pn_ssl_domain_set_credentials ( pn_ssl_domain_t domain,
const char *  certificate_file,
const char *  private_key_file,
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).

Note
This setting effects only those pn_ssl_t objects created after this call returns. pn_ssl_t objects created before invoking this method will use the domain's previous setting.
Parameters
[in]domainthe ssl domain that will use this certificate.
[in]certificate_filepath to file/database containing the identifying certificate.
[in]private_key_filepath to file/database containing the private key used to sign the certificate
[in]passwordthe password used to sign the key, else NULL if key is not protected.
Returns
0 on success
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.

Note
In order to verify a peer, a trusted CA must be configured. See ::pn_ssl_set_trusted_ca_db().
Servers must provide their own certificate when verifying a peer. See ::pn_ssl_set_credentials().
This setting effects only those pn_ssl_t objects created after this call returns. pn_ssl_t objects created before invoking this method will use the domain's previous setting.
Parameters
[in]domainthe ssl 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_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.

Note
This setting effects only those pn_ssl_t objects created after this call returns. pn_ssl_t objects created before invoking this method will use the domain's previous setting.
Parameters
[in]domainthe ssl domain that will use the database.
[in]certificate_dbdatabase of trusted CAs, used to authenticate the peer.
Returns
0 on success
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.

Parameters
[in]sslthe ssl client/server to query.
[in,out]bufferbuffer of size bytes to hold cipher name
[in]sizemaximum number of bytes in buffer.
Returns
True if cipher name written to buffer, False if no cipher in use.
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.

Parameters
[in]sslthe ssl 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_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.

Parameters
[in]sslthe ssl client/server to query.
[in,out]bufferbuffer of size bytes to hold the version identifier
[in]sizemaximum number of bytes in buffer.
Returns
True if the version information was written to buffer, False if SSL connection not ready.
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.

Parameters
[in]sslthe ssl session to configured.
[in]domainthe ssl domain used to configure the SSL session.
[in]session_idif supplied, attempt to resume a previous SSL session that used the same session_id. The resulting session will be identified by the given session_id and stored for future session restore.
Returns
0 on success, else an error code.
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.

Note
This is a best-effort service - there is no guarantee that the remote server will accept the resumed parameters. The remote server may choose to ignore these parameters, and request a re-negotiation instead.
Parameters
[in]sslthe ssl session to check
Returns
status code indicating whether or not the session 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.

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.

Note
Verification of the hostname is only done if PN_SSL_VERIFY_PEER_NAME is enabled. See ::pn_ssl_set_peer_authentication.
Parameters
[in]sslthe ssl session.
[in]hostnamethe expected identity of the remote. Must conform to the syntax as given in RFC1034, Section 3.5.
Returns
0 on success.