NAME

SSL/TLS security library

SYNOPSIS

#include <ssl/ssltls.h>

DESCRIPTION

The SSL/TLS library implements the Secure Sockets Layer (SSL v3) and Transport Layer Security (TLS v1) protocols. Current library version supports only TLS protocols v1.0 and v1.1.

For more portability library ssltls has API functions based on the OpenSSL API functions. But for more usability ssltls has several self-format API functions (non OpenSSL). All API are documented here.

Algorithms

ssltls supports a number of the most commonly used cryptographic algorithms:

Ciphers
AES128, AES256, RC4

Cryptographic hash functions
SHA, MD5

Key cryptography
RSA

API functions

SSL/TLS library initial functions

int SSL_library_init(void);
int OpenSSL_add_ssl_algorithms(void);

Description
Registers the available SSL/TLS ciphers and digests.
Return values
Always returns “1” – indicates that the function was successful.
NOTE! These functions are empty – only for OpenSSL more portability!

void SSL_load_error_strings(void);

Description
Registers the error strings for all ssltls functions.
Return values
None.
NOTE! This function is empty – only for OpenSSL more portability!

Key and certificate functions

void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u);

Description
Sets the password that is used to access data in a private key file that is in PEM format.
Parameters
*ctx – a pointer to a token returned on the SSL_CTX_new() call.
*u – a pointer to the password. The maximum length is 255 characters.
Return values
None.

int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type);
int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type);

Description
Loads the RSA private key for use with a SSL session using a specific CTX structure.
Parameters
*ctx – a pointer to a token returned on the SSL_CTX_new() call.
*file – a pointer to the name of the file that contains the RSA private key.
type – the file type, which is one of the following:
SSL_FILETYPE_ASN1 – the file is in ASN.1 format
SSL_FILETYPE_PEM – the file is in PEM format
Return values
Return code “1” indicates that the function was successful.

int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len);

Description
Loads the RSA private key stored in memory for use with a SSL session using a specific context CTX structure.
Parameters
*ctx – a pointer to a token returned on the SSL_CTX_new() call.
*d – a pointer to the memory location that contains the RSA private key.
len – RSA private key length.
Return values
Return code “1” indicates that the function was successful.

int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type);

Description
Loads the certificate for use with SSL sessions using a specific CTX structure.
Parameters
*ctx – a pointer to a token returned on the SSL_CTX_new() call.
*file – a pointer to the name of the file that contains the certificate.
type – the file type, which is one of the following:
SSL_FILETYPE_ASN1 – the file is in ASN.1 format
SSL_FILETYPE_PEM – the file is in PEM format
Return values
Return code “1” indicates that the function was successful.

int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d);

Description
Loads the certificate stored in memory for use with a SSL session using a specific CTX structure.
Parameters
*ctx – a pointer to a token returned on the SSL_CTX_new() call.
len – certificate length.
*d – a pointer to the memory location that contains the certificate.
Return values
Return code “1” indicates that the function was successful.

int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile, const char *CApath);

Description
Loads the certificate of the CA that is trusted by this application and that will be used to verify certificates that are received from remote applications.
Parameters
*ctx – a pointer to a token returned on the SSL_CTX_new() call.
*CAfile – a pointer to the name of the file that contain the certificate of the trusted CA. The file must be in PEM format.
*CApath – a pointer to the name of the directory that contains the certificates of the trusted CAs. This parameter must be NULL.
Return values
Return code “1” indicates that the function was successful.

int SSL_CTX_load_verify_ASN1(SSL_CTX *ctx, unsigned char *d, long len);

Description
Loads the certificate stored in memory of the CA that is trusted by this application and that will be used to verify certificates that are received from remote applications.
Parameters
*ctx – a pointer to a token returned on the SSL_CTX_new() call.
*d – a pointer to the memory location that contains the certificate.
len – CA certificate length.
Return values
Return code “1” indicates that the function was successful.

Peer verification functions

void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, int (*verify_callback)(int, X509_STORE_CTX *));
void SSL_set_verify(SSL *s, int mode, int (*verify_callback)(int, X509_STORE_CTX *));

Description
Indicates whether to verify the identity of the remote peer or not when the SSL session is started.
Parameters
*ctx / *s – a pointer to a token returned on the SSL_CTX_new() / SSL_new() call.
mode – one of the following verify options:
SSL_VERIFY_NONE – use this option if you do not want to verify the identity of the remote peer. Consider the following when using this option:

• If the application is a server, the application will not request the certificate for the remote client.
• If the application is a client, the certificate for the remote server application will be validated; however, the SSL session will be started regardless of whether or not the certificate for the remote server application is valid.

SSL_VERIFY_PEER – use this option to verify the identify of the remote peer when the SSL session is started. Consider the following when using this option:

• If the application is a server, the application will request and verify the certificate for the remote client application. If the remote client application provides a certificate that is not valid, the SSL session fails.
• If the application is a client, the certificate for the remote server application will be validated. If the certificate for the remote server application is not valid, the SSL session fails.

*verify_callback – callback function. This parameter must be NULL.
Return values
None.

int SSL_CTX_get_verify_mode(const SSL_CTX *ctx);
int SSL_get_verify_mode(const SSL *ssl);

Description
Returns the verification mode currently set in CTX structure or SSL session.
Parameters
*ctx / *s – a pointer to a token returned on the SSL_CTX_new() / SSL_new() call.
Return values
Returns current verify mode for CTX structure or SSL session. See description for functions SSL_CTX_set_verify() and SSL_set_verify().

long SSL_get_verify_result(const SSL *ssl);

Description
Returns the result of the remote peer certificate validation.
Parameters
*ssl – a pointer to a token returned on the SSL_new() call.
Return values
See “X.509 verify errors” section in file “ssltls.h”.

void SSL_CTX_set_verify_depth(SSL_CTX *ctx, int depth);
void SSL_set_verify_depth(SSL *s, int depth);

Description
Sets the maximum depth for the certificate chain verification.
Parameters
*ctx / *s – a pointer to a token returned on the SSL_CTX_new() / SSL_new() call.
depth – verification depth.
Return values
None.
NOTE! These functions are empty – only for OpenSSL more portability!

int SSL_CTX_get_verify_depth(const SSL_CTX *ctx);
int SSL_get_verify_depth(const SSL *ssl);

Description
Returns current maximum depth for the certificate chain verification.
Parameters
*ctx / *s – a pointer to a token returned on the SSL_CTX_new() / SSL_new() call.
Return values
Always returns (-1) – no limit depth.
NOTE! These functions are empty – only for OpenSSL more portability!

Methods functions

const SSL_METHOD *TLSv1_server_method(void);

Description
Function indicates that the application is a server and supports TLSv1.0.
Return values
A pointer to the appropriate connection method.

const SSL_METHOD *TLSv1_client_method(void);

Description
Function indicates that the application is a client and supports TLSv1.0.
Return values
A pointer to the appropriate connection method.

const SSL_METHOD *TLSv1_1_server_method(void);

Description
Function indicates that the application is a server and supports TLSv1.1.
Return values
A pointer to the appropriate connection method.

const SSL_METHOD *TLSv1_1_client_method(void);

Description
Function indicates that the application is a client and supports TLSv1.1.
Return values
A pointer to the appropriate connection method.

Context create and delete functions

SSL_CTX *SSL_CTX_new(const SSL_METHOD *method);

Description
Creates a new context structure.
Parameters
*method – a pointer to the connection method that indicates which SSL/TLS versions are supported and whether the new CTX structure is for a client application or a server application.
Return values
Pointer to an SSL_CTX object. A NULL pointer indicates an error.

void SSL_CTX_free(SSL_CTX *ctx);

Description
Free an allocated context object.
Parameters
*ctx – a pointer to a token returned on the SSL_CTX_new() call.
Return values
None.

long SSL_CTX_get_timeout(const SSL_CTX *ctx);

Description
Returns the timeout value for context object. Whenever a new SSL session is created, it is assigned a maximum lifetime – expiration time.
Parameters
*ctx – a pointer to a token returned on the SSL_CTX_new() call.
Return values
Timeout value.

SSL session functions

SSL *SSL_new(SSL_CTX *ctx);

Description
Creates a new structure for use with an SSL session.
Parameters
*ctx – a pointer to a token returned on the SSL_CTX_new() call.
Return values
Pointer to an SSL structure. A NULL pointer indicates an error.

void SSL_free(SSL *ssl);

Description
Free an allocated session object.
Parameters
*ssl – a pointer to a token returned on the SSL_new() call.
Return values
None.

int SSL_set_fd(SSL *ssl, int fd);

Description
Assigns a socket to a SSL session.
Parameters
*ssl – a pointer to a token returned on the SSL_new() call.
fd – the file descriptor of the socket.
Return values
Always return “1” – the function was successful.

int SSL_shutdown(SSL *ssl);

Description
Shuts down data flow for a SSL session.
Parameters
*ssl – a pointer to a token returned on the SSL_new() call.
Return values
Always return “1” – the function was successful.
NOTE! This function is empty – only for OpenSSL more portability!

int SSL_state(SSL *ssl);

Description
Returns state code for a SSL session.
Parameters
*ssl – a pointer to a token returned on the SSL_new() call.
Return values
Always returns 0x03 – OK state.
NOTE! This function is empty – only for OpenSSL more portability!

int SSL_connect(SSL *ssl);

Description
Starts a SSL session with a remote server application.
Parameters
*ssl – a pointer to a token returned on the SSL_new() call.
Return values
Return code “1” indicates that the function was successful.

int SSL_accept(SSL *ssl);

Description
Accepts a SSL session connection request from a remote client application.
Parameters
*ssl – a pointer to a token returned on the SSL_new() call.
Return values
Return code “1” indicates that the function was successful.

int SSL_read(SSL *ssl, void *buf, int num);

Description
Reads application data from a SSL session.
Parameters
*ssl – a pointer to a token returned on the SSL_new() call.
*buf – a pointer to the buffer into which to read the data.
num – the maximum number of bytes of data that the application can read.
Return values
Returns the number of bytes of data that are read. A return code equal to 0 or a negative number indicates an error.

int SSL_write(SSL *ssl, const void *buf, int num);

Description
Writes application data across a SSL session.
Parameters
*ssl – a pointer to a token returned on the SSL_new() call.
*buf – a pointer to the data to send.
num – the number of bytes of data to send.
Return values
Returns the number of bytes of data sent. A return code equal to 0 or a negative number indicates an error.

int SSL_get_error(const SSL *ssl, int ret);

Description
Returns information about why the previous SSL API call resulted in an error return code.
Parameters
*ssl – a pointer to a token returned on the SSL_new() call.
ret – the return code from the previous SSL API call.
Return values
Returns one of the following values:

• SSL_ERROR_NONE – No error to report. This is set when the value of the ret parameter is greater than 0.
• SSL_ERROR_SYSCALL – An I/O error occurred.
• SSL_ERROR_ZERO_RETURN – The remote application shut down the SSL connection normally.

const char *SSL_get_version(const SSL *ssl);

Description
Returns the protocol version of the current SSL connection.
Parameters
*ssl – a pointer to a token returned on the SSL_new() call.
Return values
Returns a character pointer to the name of the protocol version in use. Possible values are:

• TLSv1.0 – The connection uses the TLS v1.0 protocol.
• TLSv1.1 – The connection uses the TLS v1.1 protocol.
• unknown – This indicates that no version has been set (no connection established).

const char *SSL_get_cipher(const SSL *ssl);
const char *SSL_get_cipher_name(const SSL *ssl);

Description
Returns the name of the cipher associated with a specific SSL session.
Parameters
*ssl – a pointer to a token returned on the SSL_new() call.
Return values
Returns a pointer to the cipher name. Possible values are:

• AES128-SHA – AES128 (128-bit key) for data encryption; SHA for message integrity.
• AES256-SHA – AES256 (256-bit key) for data encryption; SHA for message integrity.
• RC4-SHA – RC4 (128-bit key) for data encryption; SHA for message integrity.
• RC4-MD5 – RC4 (128-bit key) for data encryption; MD5 for message integrity.
• unknown – This indicates error.

Non OpenSSL functions

void SSL_CTX_debug(SSL_CTX *ctx, int debug);

Description
Set debug output parameters.
Parameters
*ctx – a pointer to a token returned on the SSL_CTX_new() call.
debug – one or more of the following verify options:

• DBG_DISPLAY_STATES – display the state changes during the handshake.
• DBG_DISPLAY_BYTES – display the byte sequences during the handshake.
• DBG_DISPLAY_CERTS – display the certificates that are passed during a handshake.
• DBG_DISPLAY_RSA – display the RSA key details that are passed during a handshake.

Return values
None.

int SSL_CTX_use_PKCS8_file(SSL_CTX *ctx, const char *file, char *password);

Description
Loads encrypted key in PKCS#8 format from file for use with a SSL session using a specific CTX structure.
Parameters
*ctx – a pointer to a token returned on the SSL_CTX_new() call.
*file – a pointer to the name of the file that contains the key.
*password – a pointer to the password. The maximum length is 255 characters.
Return values
Return code “1” indicates that the function was successful.

int SSL_CTX_use_PKCS8_memory(SSL_CTX *ctx, unsigned char *d, long len, char *password);

Description
Loads encrypted key in PKCS#8 format stored in memory for use with a SSL session using a specific CTX structure.
Parameters
*ctx – a pointer to a token returned on the SSL_CTX_new() call.
*d – a pointer to the memory location that contains the key.
len – key length.
*password – a pointer to the password. The maximum length is 255 characters.
Return values
Return code “1” indicates that the function was successful.

int SSL_CTX_use_PKCS12_file(SSL_CTX *ctx, const char *file, char *password);

Description
Loads encrypted key and certificate in PKCS#12 format from file for use with a SSL session using a specific CTX structure.
Parameters
*ctx – a pointer to a token returned on the SSL_CTX_new() call.
*file – a pointer to the name of the file that contains the key and certificate.
*password – a pointer to the password. The maximum length is 255 characters.
Return values
Return code “1” indicates that the function was successful.

int SSL_CTX_use_PKCS12_memory(SSL_CTX *ctx, unsigned char *d, long len, char *password);

Description
Loads encrypted key and certificate in PKCS#12 format stored in memory for use with a SSL session using a specific CTX structure.
Parameters
*ctx – a pointer to a token returned on the SSL_CTX_new() call.
*d – a pointer to the memory location that contains the key and certificate.
len – key and certificate length.
*password – a pointer to the password. The maximum length is 255 characters.
Return values
Return code “1” indicates that the function was successful.

Library options

Library ssltls has a number of compilation options. These options allow switch-off some features, change some behaviour and debug messages control. All options are in the file “ssltls_config.h” in the library directory.

SSL_CLIENT_SUPPORT – control client functions
0 – library not contains SSL/TLS client capability
1 – library contains SSL/TLS client capability
Default value:
#define SSL_CLIENT_SUPPORT 1

SSL_SERVER_SUPPORT – control server functions
0 – library not contains SSL/TLS server capability
1 – library contains SSL/TLS server capability
Default value:
#define SSL_SERVER_SUPPORT 1

SSL_CERT_VERIFICATION – control certificate verification
0 – library not contains SSL/TLS certificate verification capability
1 – library contaisn SSL/TLS certificate verification capability
NOTE! This parameter can’t be disabled if client features are using!
Default value:
#define SSL_CERT_VERIFICATION 1

CONFIG_SSL_PROT_LOW – cipher order: RC4-SHA, AES128-SHA, AES256-SHA, RC4-MD5
CONFIG_SSL_PROT_MEDIUM – cipher order: AES128-SHA, AES256-SHA, RC4-SHA, RC4-MD5
CONFIG_SSL_PROT_HIGH – cipher order: AES256-SHA, AES128-SHA, RC4-SHA, RC4-MD5
These options allow to set cipher protocol preference. Selected order using during peers negotiate about work cipher algorithms.
Preference description:
LOW – the fastest cipher(s) but at the expense of security
MEDIUM – balance between speed and security
HIGH – the strongest cipher(s) at the cost of speed
NOTE! You have to select only one preference!
Default value:
//#define CONFIG_SSL_PROT_LOW
#define CONFIG_SSL_PROT_MEDIUM
//#define CONFIG_SSL_PROT_HIGH

DEBUG_DISPLAY – debug flags control
0 – disable debug flags control
1 – enable debug flags control
This parameter allow to control debug messages with help of function SSL_CTX_debug()
Default value:
#define DEBUG_DISPLAY 1

DEBUG_MSG – misc warnings and notifies
0 – disable misc warnings and notifies
1 – enable misc warnings and notifies
This parameter add output extra warnings and notifies.
Default value:
#define DEBUG_MSG 0

DEBUG_BIGINT – big integer debug
0 – disable big integer debug
1 – enable big integer debug
This parameter add output extra messages for big integer debug.
Default value:
#define DEBUG_BIGINT 0

NOTES

There are a SSL/TLS demo projects available for the Unison and DSPnano which is found in installdir/demo.

SEE ALSO

tcpd