Cipher Management Functions

SSL_CIPHER

Functions

SSL_CIPHER*

SSL_get_current_cipher (SSL *ssl)

Returns the current SSL_CIPHER structure for the specified ssl. More...

int

SSL_CIPHER_get_bits (SSL_CIPHER *cipher, int *alg_bits)

Returns the number of key bits for symmetric ciphers. More...

unsigned long

SSL_CIPHER_get_id (SSL_CIPHER *cipher)

Returns the unique numeric identifier of a cipher suite. More...

char*

SSL_CIPHER_get_version (SSL_CIPHER *cipher)

Returns the SSL protocol version of the cipher suite. More...

char*

SSL_CIPHER_get_name (SSL_CIPHER *cipher)

Returns a reference to the name of the cipher suite. More...

char*

SSL_CIPHER_description (SSL_CIPHER *cipher, char *buffer, int size)

Returns a text string describing a cipher suite. More...

Function Documentation

char* SSL_CIPHER_description	(	SSL_CIPHER *	cipher,
		char *	buf,
		int	len
	)	;

Returns a text string describing a cipher suite. The string includes the applicable SSL version(s), key exchange, authentication, encryption and message digest mechanisms, and the cipher strengths in bits.

Parameters:

cipher	[In] The SSL_CIPHER structure from which to retrieve the description.
buf	[Out] The output buffer for the cipher suite description. If buf is `NULL`, the function allocates memory to the space required.
len	[In] The length of the output buffer.

Returns:: The cipher suite description.

int SSL_CIPHER_get_bits	(	SSL_CIPHER *	cipher,
		int *	alg_bits
	)	;

Returns the number of key bits for symmetric ciphers. There are two key sizes returned by this function that represent the full key size and the effective key size. The full key size is determined by the algorithm. For example, RC4 always uses a 128-bit key. The effective key size is the important determiner of how much entropy the key contributes and therefore how much security the key provides. RC4 40 has an effective size of 40 bits within the 128-bit RC4 key.

Parameters:

cipher	[In] The SSL_CIPHER description.
alg_bits	[Out] The number of bits for the full key material. If passed as a `NULL` pointer then no return value is possible.

Returns:: The number of effective key bits for the cipher.

: The number of effective bits for a key may differ from the number of bits for the full key in the case of export ciphers (and will be less than or equal to the total key bits). For Data Encryption Standard (DES) algorithms the parity bits of the whole key and the effective key are not included in the returned values.

unsigned long SSL_CIPHER_get_id

(

SSL_CIPHER *

cipher

)

;

Returns the unique numeric identifier of a cipher suite. The first two hexadecimal digits hold the SSL protocol version (2 or 3). For SSLv2 the next two digits hold an index for the cipher and the last four hexadecimal digits hold the number of bits of the encryption cipher. For SSLv3 the remaining hexadecimal digits (six) hold an index for the cipher.

Parameters:

cipher

[In] The SSL_CIPHER reference from which to retrieve the numeric identifier.

Returns:: The unique cipher identifier.

Example:

SSL_CTX *ssl_ctx;
SSL *ssl;
int count;
int i, ok;
SSL_CIPHER *ciph;


/* SSL_CTX has a default cipher list - see ssl.h */
/* ssl_ctx = SSL_CTX_new(...); */

/* This SSL will pick up the default cipher list from the ctx */
ssl = SSL_new(ssl_ctx);

/* Set the cipher list - I don't want the default */
ok = SSL_set_cipher_list(ssl,"RSA+RC4");
if (!ok)
{
        /* Print and error and quit */
        printf("Unable to load the cipher list I want\n");
        exit(1);
}

/* Display all the identifying values for these ciphers */
count = SSL_get_ciphers_count();

for (i=0; i<count; i++)
{
        ciph = SSL_get_ciphers_item(ssl,i);
        printf("Cipher ID = %l\n",SSL_CIPHER_get_id(ciph));
}

/* .... */

char* SSL_CIPHER_get_name

(

SSL_CIPHER *

cipher

)

;

Returns a reference to the name of the cipher suite.

Parameters:

cipher

[In] The SSL_CIPHER reference from which to return the name.

Returns:: A reference to the name of the cipher suite.
If cipher is NULL, the return value is NONE.

See also:: SSL_CIPHER_description(), SSL_CIPHER_get_bits() and SSL_CIPHER_get_version().

Samples:: fips_client.c, and simple.c.

char* SSL_CIPHER_get_version

(

SSL_CIPHER *

cipher

)

;

Returns the SSL protocol version of the cipher suite.

Parameters:

cipher

[In] The SSL_CIPHER reference from which to retrieve the protocol version.

Returns:: The SSL protocol version of the cipher suite.
If cipher is NULL, the return value is NONE.

See also:: SSL_CIPHER_description(), SSL_CIPHER_get_bits() and SSL_CIPHER_get_name().

SSL_CIPHER* SSL_get_current_cipher

(

SSL *

ssl

)

;

Returns the current SSL_CIPHER structure for the specified ssl. For example, the current cipher may be RC4 used with SSLv3, 56-bit encryption, RSA key exchange and authentication and SHA-1 message authentication. Other functions can be used to extract these details from the returned SSL_CIPHER structure.

Parameters:

ssl

[In] The SSL structure reference from which to retrieve the current cipher.

Returns:: The SSL_CIPHER reference for the current cipher.
NULL indicates there is no session information or session cipher.

Samples:: fips_client.c, and simple.c.

	RSA BSAFE SSL-C	Security protocol components for C
		Search