The Cafe SSL APIs allow an application to perform secure communication on a TCP/IP client socket. The application is responsible for creation and connection management of the socket. The SSL library performs the SSL handshake and encrypted data transfer on the socket. The application can specify the SSL version (SSLv3 or TLSv1.0) and the certificates to be used for secure communication.
Cafe provides a build-in certificate store with CA certificates and client certificates. Each of these certificates are identified using an integer ID. The applications can specify to use the build-in certificates and/or provide their own certificates to be used during SSL handshake. ID for the internal certificates are defined in
cafe/nssl/nsslclient.h and IDs for the internal certificate groups are defined in
This is a handle to a set of certificates and keys to be used for secure communication. A process can create multiple
NSSLCreateContext and associate with it:
This is a handle to the configuration and status of a single SSL connection. A process can create multiple
NSSLConnection is associated with an
NSSLContext and a TCP/IP client socket (which is created and connected by the application).
NSSLConnection uses the client and server certificates associated with the
NSSLContext during the SSL handshake.
An application should use the following APIs to perform secure communication over TCP/IP using SSL.
nn::ac::Initializeand wait till the network comes up using
NSSLSetClientPKIif the server performs client certificate verification. Only one client certificate can be specified for a context.
NSSLAddServerPKIGroupsto be used to verify the peer certificate. These functions can be called multiple times on a context to specify multiple trusted CA certificates.
NSSLAddCRLExternal. This function can be called multiple times on a context to specify multiple CRLs. Turn on CRL checking by setting the appropriate flags for the context using
NSSLContextand the TCP/IP socket.
NSSLContextSetMode. This will help prevent downgrade attacks.
The application can (optionally) resume a previously created SSL session with a server using the session resumption feature. To use session resumption feature, the application should use
NSSLGetSession to get a handle to the SSL session after
NSSLDoHandshake and cache the handle. When reconnecting to the same server again, the application should use
NSSLDoHandshake to request reuse of the previous session id. The session handles are reference-counted. Each call to
NSSLGetSession increments the reference count by one. The application should call
NSSLFreeSession for each call to
NSSLGetSession. Session data is maintained within a NSSLContext and a session id can be reused only for the NSSLConnections from the same NSSLContext. An application can completely remove the cached session data from the NSSLContext by calling
NSSLContextSetMode as optional step.
2014/06/02 Added details about CRL usage.
2012/08/16 Cleanup pass.