diff options
author | Richard Levitte <levitte@openssl.org> | 2000-09-18 16:42:30 +0000 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2000-09-18 16:42:30 +0000 |
commit | 615513ba5294e03b451f33bc46c714c5efa28916 (patch) | |
tree | fd5754778a19265f37e6d6be1b0056c55a516862 /doc | |
parent | 2bd8aaefa42a7f1449f06a6cf2beb7caa4b71c8d (diff) | |
download | openssl-615513ba5294e03b451f33bc46c714c5efa28916.tar.gz |
New documentation about things related to SSL_CIPHER. Submitted by Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ssl/SSL_CIPHER_get_name.pod | 57 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_cipher_list.pod | 43 | ||||
-rw-r--r-- | doc/ssl/SSL_get_ciphers.pod | 42 | ||||
-rw-r--r-- | doc/ssl/SSL_get_current_cipher.pod | 43 |
4 files changed, 185 insertions, 0 deletions
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 <openssl/ssl.h> + + 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<cipher>. 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<cipher>. If +B<alg_bits> is not NULL, it contains the number of bits processed by the +chosen algorithm. If B<cipher> is NULL, 0 is returned. + +SSL_CIPHER_get_version() returns the protocol version for B<cipher>, currently +"SSLv2", "SSLv3", or "TLSv1". If B<cipher> is NULL, "(NONE)" is returned. + +SSL_CIPHER_description() returns a textual description of the cipher used +into the buffer B<buf> of length B<len> provided. B<len> must be at least +128 bytes, otherwise the string "Buffer too small" is returned. If B<buf> +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<alg_bits>), of +which however 88bits are fixed. The search space is hence only 40 bits. + +=head1 BUGS + +If SSL_CIPHER_description() is called with B<cipher> being NULL, the +library crashes. + +=head1 RETURN VALUES + +See DESCRIPTION + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_get_current_cipher(3)|SSL_get_current_cipher(3)>, +L<SSL_get_ciphers(3)|SSL_get_ciphers(3)> + +=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 <openssl/ssl.h> + + 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<ctx> +using the control string B<str>. The format of the string is described +in L<ciphers(1)|ciphers(1)>. The list of ciphers is inherited by all +B<ssl> objects created from B<ctx>. + +SSL_set_cipher_list() sets the list of ciphers only for B<ssl>. + +=head1 NOTES + +The control string B<str> 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<ssl(3)|ssl(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, +L<ciphers(1)|ciphers(1)> + +=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 <openssl/ssl.h> + + 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<ssl>, +sorted by preference. If B<ssl> 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<ssl> with B<priority>. If B<ssl> is NULL, no ciphers are +available, or there are less ciphers than B<priority> available, NULL +is returned. + +=head1 NOTES + +The details of the ciphers obtained by SSL_get_ciphers() can be obtained using +the L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> family of functions. + +Call SSL_get_cipher_list() with B<priority> starting from 0 to obtain the +sorted list of available ciphers, until NULL is returned. + +=head1 RETURN VALUES + +See DESCRIPTION + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, +L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> + +=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 <openssl/ssl.h> + + 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<ssl> 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<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> 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<ssl(3)|ssl(3)>, L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> + +=cut |