From: Richard Levitte <levitte@openssl.org>
Date: Mon, 18 Sep 2000 16:42:30 +0000 (+0000)
Subject: New documentation about things related to SSL_CIPHER.  Submitted by Lutz Jaenicke... 
X-Git-Tag: OpenSSL_0_9_6-beta3~39
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=615513ba5294e03b451f33bc46c714c5efa28916;p=oweals%2Fopenssl.git

New documentation about things related to SSL_CIPHER.  Submitted by Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>
---

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