HP SSL Data Structures

Before you start SSL application development, you should understand the data structures used for SSL APIs, and the relationships between the data structures.

SSL APIs use data structures to hold various types of information about SSL sessions and connections. The most important structures are SSL_CTX and SSL. Usually, one SSL_CTX structure exists per SSL application program, and an SSL structure is created every time a new SSL connection is created. An SSL structure inherits configuration information from the SSL_CTX structure when it is created.

Table 4-1 “APIs for Data Structure Creation and Deallocation” shows the APIs commonly used for creating and deallocating data structures.

Table 4-1 APIs for Data Structure Creation and Deallocation

Data Structure	API for Creation	API for Deallocation
SSL_CTX	`SSL_CTX_new`()	`SSL_CTX_free`()
SSL	`SSL_new`()	`SSL_free`()
SSL_SESSION	`SSL_SESSION_new`()	`SSL_SESSION_free`()
BIO	`BIO_new`()	`BIO_free`()
X509	`X509_new`()	`X509_free`()
RSA	`RSA_new`()	`RSA_free`()
DH	`DH_new`()	`DH_free`()

Figure 4-1 “ Relationship Between SSL_CTX and SSL” shows the relationship between the SSL_CTX and SSL data structures.

Figure 4-1 Relationship Between SSL_CTX and SSL

SSL_CTX Structure

The SSL_CTX structure is defined in ssl.h. An SSL_CTX structure stores default values for SSL structures. (The SSL structures are created after the SSL_CTX structure is created and configured.) The SSL_CTX structure also holds information about SSL connections and sessions (the numbers of new SSL connections, renegotiations, session resumptions, and so on).

Each SSL client or server program creates and keeps only one SSL_CTX structure. The SSL_CTX structure is created at the beginning of the SSL application program. The SSL_CTX structure is configured with the default values that will be inherited by the SSL structures. For example, a CA certificate loaded in the SSL_CTX structure is also loaded into an SSL structure when that SSL structure is created.




	NOTE: Data structure definitions are subject to change in future releases of HP SSL for OpenVMS.

SSL Structure

An SSL structure is created for every SSL connection in the SSL client or server program. You create the SSL structure after creating and configuring the SSL_CTX structure because the SSL structure inherits default values from the SSL_CTX structure. The inheritance of the default values enables the SSL structure to be used without explicit configuration. However, it is possible to change the inherited values in a specific SSL structure.

An SSL structure saves the addresses of data structures that store information about SSL connections and sessions. These data structures are as follows:

The SSL_CTX structure from which the SSL structure is created
SSL_METHOD (SSL protocol version)
SSL_SESSION
SSL_CIPHER
CERT (certificate information extracted from an X.509 structure)
BIO (an SSL connection is performed via BIO)

The SSL information (protocol version, connection status values, and so on) in the SSL structure is used for the SSL connection. Figure 4-2 “ Structures Associated with SSL Structure” shows the structures associated with the SSL structure.

Figure 4-2 Structures Associated with SSL Structure

SSL_METHOD Structure

The SSL_METHOD structure is defined in ssl.h. An SSL_METHOD structure contains pointers to the functions that implement the SSL protocol version specified. This structure must be created before creation of the SSL_CTX structure.

SSL_CIPHER Structure

The SSL_CIPHER structure is defined in the ssl.h header file. An SSL_CIPHER structure holds information about the cipher suite used for SSL connections and sessions.

CERT/X509 Structure

In OpenSSL application programs, an X.509 certificate is stored as an X509 structure. However, after loading an X509 structure into an SSL_CTX or SSL structure, the X.509 certificate information is extracted from the X509 structure and stored in a CERT structure associated with the SSL_CTX or SSL structure. The X509 and CERT structures are defined in x509.h and ssl_locl.h, respectively.




	NOTE: The `ssl_locl.h` header file is not used for SSL application programs because it defines only internal functions and structures, such as the `CERT` structure. In SSL application programs, a certificate is stored in an `X509` structure, not in a `CERT` structure. An SSL application developer does not need to know the definition of the `CERT` structure and `ssl_locl.h`.

BIO Structure

A BIO structure is an I/O abstraction in an SSL application with SSL APIs. The BIO structure encapsulates an underlying I/O secured by SSL, and all the communication between the client and server is conducted through this structure. The BIO structure is defined in bio.h.

HP OpenVMS Systems Documentation