HP Open Source Security for OpenVMS Volume 2:...

SSL Programming Concepts

Certificates for SSL Applications

HP SSL 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.

APIs for Data Structure Creation and Deallocation shows the APIs commonly used for creating and deallocating data structures.

Table 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()

Relationship Between SSL_CTX and SSL shows the relationship between the SSL_CTX and SSL data structures.  

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

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)

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

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.

Certificates for SSL Applications