Cafe SSL Data Structures and API overview

Introduction

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 cafe/nssl/certstore.h.

Data Structures


NSSLContext

This is a handle to a set of certificates and keys to be used for secure communication. A process can create multiple NSSLContexts using NSSLCreateContext and associate with it:


NSSLConnection

This is a handle to the configuration and status of a single SSL connection. A process can create multiple NSSLConnections using NSSLCreateContext. An 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.

SSL API usage

An application should use the following APIs to perform secure communication over TCP/IP using SSL.

  1. Initialize the auto connection library using nn::ac::Initialize and wait till the network comes up using nn::ac::Connect.
  2. After the network is UP, initialize the socket library using SOInit.
  3. Initialize the SSL Library using NSSLInit
  4. Create an NSSLContext using NSSLCreateContext.
    • Optionally specify a client certificate and private key using NSSLSetClientPKIExternal or NSSLSetClientPKI if the server performs client certificate verification. Only one client certificate can be specified for a context.
    • Optionally specify the trusted CA certificates using NSSLAddServerPKIExternal and/or NSSLAddServerPKI and/or NSSLAddServerPKIGroups to be used to verify the peer certificate. These functions can be called multiple times on a context to specify multiple trusted CA certificates.
    • Optionally specify the Certificate Revocation List (CRL) using 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 NSSLContextSetFlags.
  5. Create a TCP/IP client socket and connect it to the server.
  6. Create an NSSLConnection by using NSSLCreateConnection specifying the NSSLContext and the TCP/IP socket.
  7. Optionally set SSL context mode using NSSLContextSetMode.
  8. Perform SSL handshake using NSSLDoHandshake.
  9. Perform secure data transfer using NSSLRead and NSSLWrite.
  10. Terminate SSL connection using NSSLDestroyConnection.
  11. Close the socket to terminate the TCP/IP connection.
  12. Clean up

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 NSSLSetSession before 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 NSSLRemoveSession.

See Also

Cafe SSL Overview

Revision History

2015/04/09 Added NSSLContextSetMode as optional step.
2014/06/02 Added details about CRL usage.
2012/08/16 Cleanup pass.


CONFIDENTIAL