From 615513ba5294e03b451f33bc46c714c5efa28916 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Mon, 18 Sep 2000 16:42:30 +0000 Subject: [PATCH] New documentation about things related to SSL_CIPHER. Submitted by Lutz Jaenicke --- doc/ssl/SSL_CIPHER_get_name.pod | 57 +++++++++++++++++++++++++++++ doc/ssl/SSL_CTX_set_cipher_list.pod | 43 ++++++++++++++++++++++ doc/ssl/SSL_get_ciphers.pod | 42 +++++++++++++++++++++ doc/ssl/SSL_get_current_cipher.pod | 43 ++++++++++++++++++++++ 4 files changed, 185 insertions(+) create mode 100644 doc/ssl/SSL_CIPHER_get_name.pod create mode 100644 doc/ssl/SSL_CTX_set_cipher_list.pod create mode 100644 doc/ssl/SSL_get_ciphers.pod create mode 100644 doc/ssl/SSL_get_current_cipher.pod diff --git a/doc/ssl/SSL_CIPHER_get_name.pod b/doc/ssl/SSL_CIPHER_get_name.pod new file mode 100644 index 0000000000..7fea14ee68 --- /dev/null +++ b/doc/ssl/SSL_CIPHER_get_name.pod @@ -0,0 +1,57 @@ +=pod + +=head1 NAME + +SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, +SSL_CIPHER_description - get SSL_CIPHER properties + +=head1 SYNOPSIS + + #include + + const char *SSL_CIPHER_get_name(SSL_CIPHER *cipher); + int SSL_CIPHER_get_bits(SSL_CIPHER *cipher, int *alg_bits); + char *SSL_CIPHER_get_version(SSL_CIPHER *cipher); + char *SSL_CIPHER_description(SSL_CIPHER *cipher, char *buf, int size); + +=head1 DESCRIPTION + +SSL_CIPHER_get_name() returns a pointer to the name of B. If the +argument is the NULL pointer, a pointer to the constant value "NONE" is +returned. + +SSL_CIPHER_get_bits() returns the number of secret bits used for B. If +B is not NULL, it contains the number of bits processed by the +chosen algorithm. If B is NULL, 0 is returned. + +SSL_CIPHER_get_version() returns the protocol version for B, currently +"SSLv2", "SSLv3", or "TLSv1". If B is NULL, "(NONE)" is returned. + +SSL_CIPHER_description() returns a textual description of the cipher used +into the buffer B of length B provided. B must be at least +128 bytes, otherwise the string "Buffer too small" is returned. If B +is NULL, a buffer of 128 bytes is allocated using OPENSSL_malloc(). If the +allocation fails, the string "OPENSSL_malloc Error" is returned. + +=head1 NOTES + +The number of bits processed can be different from the secret bits. An +export cipher like e.g. EXP-RC4-MD5 has only 40 secret bits. The algorithm +does use the full 128 bits (which would be returned for B), of +which however 88bits are fixed. The search space is hence only 40 bits. + +=head1 BUGS + +If SSL_CIPHER_description() is called with B being NULL, the +library crashes. + +=head1 RETURN VALUES + +See DESCRIPTION + +=head1 SEE ALSO + +L, L, +L + +=cut diff --git a/doc/ssl/SSL_CTX_set_cipher_list.pod b/doc/ssl/SSL_CTX_set_cipher_list.pod new file mode 100644 index 0000000000..1f0daa5de8 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_cipher_list.pod @@ -0,0 +1,43 @@ +=pod + +=head1 NAME + +SSL_CTX_set_cipher_list, SSL_set_cipher_list +- choose list of available SSL_CIPHERs + +=head1 SYNOPSIS + + #include + + int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str); + int SSL_set_cipher_list(SSL *ssl, const char *str); + +=head1 DESCRIPTION + +SSL_CTX_set_cipher_list() sets the list of available ciphers for B +using the control string B. The format of the string is described +in L. The list of ciphers is inherited by all +B objects created from B. + +SSL_set_cipher_list() sets the list of ciphers only for B. + +=head1 NOTES + +The control string B should be universally useable and not depend +on details of the library configuration (ciphers compiled in). Thus no +syntax checking takes place. Items that are not recognized, because the +corrensponding ciphers are not compiled in or because they are mistyped, +are simply ignored. Failure is only flagged if no ciphers could be collected +at all. + +=head1 RETURN VALUES + +SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher +could be selected and 0 on complete failure. + +=head1 SEE ALSO + +L, L, +L + +=cut diff --git a/doc/ssl/SSL_get_ciphers.pod b/doc/ssl/SSL_get_ciphers.pod new file mode 100644 index 0000000000..2a57455c23 --- /dev/null +++ b/doc/ssl/SSL_get_ciphers.pod @@ -0,0 +1,42 @@ +=pod + +=head1 NAME + +SSL_get_ciphers, SSL_get_cipher_list - get list of available SSL_CIPHERs + +=head1 SYNOPSIS + + #include + + STACK_OF(SSL_CIPHER) *SSL_get_ciphers(SSL *ssl); + const char *SSL_get_cipher_list(SSL *ssl, int priority); + +=head1 DESCRIPTION + +SSL_get_ciphers() returns the stack of available SSL_CIPHERs for B, +sorted by preference. If B is NULL or no ciphers are available, NULL +is returned. + +SSL_get_cipher_list() returns a pointer to the name of the SSL_CIPHER +listed for B with B. If B is NULL, no ciphers are +available, or there are less ciphers than B available, NULL +is returned. + +=head1 NOTES + +The details of the ciphers obtained by SSL_get_ciphers() can be obtained using +the L family of functions. + +Call SSL_get_cipher_list() with B starting from 0 to obtain the +sorted list of available ciphers, until NULL is returned. + +=head1 RETURN VALUES + +See DESCRIPTION + +=head1 SEE ALSO + +L, L, +L + +=cut diff --git a/doc/ssl/SSL_get_current_cipher.pod b/doc/ssl/SSL_get_current_cipher.pod new file mode 100644 index 0000000000..2dd7261d89 --- /dev/null +++ b/doc/ssl/SSL_get_current_cipher.pod @@ -0,0 +1,43 @@ +=pod + +=head1 NAME + +SSL_get_current_cipher, SSL_get_cipher, SSL_get_cipher_name, +SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection + +=head1 SYNOPSIS + + #include + + SSL_CIPHER *SSL_get_current_cipher(SSL *ssl); + #define SSL_get_cipher(s) \ + SSL_CIPHER_get_name(SSL_get_current_cipher(s)) + #define SSL_get_cipher_name(s) \ + SSL_CIPHER_get_name(SSL_get_current_cipher(s)) + #define SSL_get_cipher_bits(s,np) \ + SSL_CIPHER_get_bits(SSL_get_current_cipher(s),np) + #define SSL_get_cipher_version(s) \ + SSL_CIPHER_get_version(SSL_get_current_cipher(s)) + +=head1 DESCRIPTION + +SSL_get_current_cipher() returns a pointer to an SSL_CIPHER object containing +the description of the actually used cipher of a connection established with +the B object. + +SSL_get_cipher() and SSL_get_cipher_name() are identical macros to obtain the +name of the currently used cipher. SSL_get_cipher_bits() is a +macro to obtain the number of secret/algorithm bits used and +SSL_get_cipher_version() returns the protocol name. +See L for more details. + +=head1 RETURN VALUES + +SSL_get_current_cipher() returns the cipher actually used or NULL, when +no session has been established. + +=head1 SEE ALSO + +L, L + +=cut -- 2.34.1