168651Skris=pod 268651Skris 368651Skris=head1 NAME 468651Skris 572613SkrisSSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_description - get SSL_CIPHER properties 668651Skris 768651Skris=head1 SYNOPSIS 868651Skris 968651Skris #include <openssl/ssl.h> 1068651Skris 11160814Ssimon const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher); 12160814Ssimon int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits); 13160814Ssimon char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher); 14205128Ssimon char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size); 1568651Skris 1668651Skris=head1 DESCRIPTION 1768651Skris 1868651SkrisSSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the 1968651Skrisargument is the NULL pointer, a pointer to the constant value "NONE" is 2068651Skrisreturned. 2168651Skris 2268651SkrisSSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>. If 2368651SkrisB<alg_bits> is not NULL, it contains the number of bits processed by the 2468651Skrischosen algorithm. If B<cipher> is NULL, 0 is returned. 2568651Skris 26269682SjkimSSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol 27269682Sjkimversion that first defined the cipher. 28269682SjkimThis is currently B<SSLv2> or B<TLSv1/SSLv3>. 29269682SjkimIn some cases it should possibly return "TLSv1.2" but does not; 30269682Sjkimuse SSL_CIPHER_description() instead. 31269682SjkimIf B<cipher> is NULL, "(NONE)" is returned. 3268651Skris 3368651SkrisSSL_CIPHER_description() returns a textual description of the cipher used 3468651Skrisinto the buffer B<buf> of length B<len> provided. B<len> must be at least 35194206Ssimon128 bytes, otherwise a pointer to the string "Buffer too small" is 3672613Skrisreturned. If B<buf> is NULL, a buffer of 128 bytes is allocated using 3772613SkrisOPENSSL_malloc(). If the allocation fails, a pointer to the string 3872613Skris"OPENSSL_malloc Error" is returned. 3968651Skris 4068651Skris=head1 NOTES 4168651Skris 4268651SkrisThe number of bits processed can be different from the secret bits. An 4368651Skrisexport cipher like e.g. EXP-RC4-MD5 has only 40 secret bits. The algorithm 4468651Skrisdoes use the full 128 bits (which would be returned for B<alg_bits>), of 4568651Skriswhich however 88bits are fixed. The search space is hence only 40 bits. 4668651Skris 4772613SkrisThe string returned by SSL_CIPHER_description() in case of success consists 4876866Skrisof cleartext information separated by one or more blanks in the following 4972613Skrissequence: 5072613Skris 5172613Skris=over 4 5272613Skris 5372613Skris=item <ciphername> 5472613Skris 5572613SkrisTextual representation of the cipher name. 5672613Skris 5772613Skris=item <protocol version> 5872613Skris 59269682SjkimProtocol version: B<SSLv2>, B<SSLv3>, B<TLSv1.2>. The TLSv1.0 ciphers are 60269682Sjkimflagged with SSLv3. No new ciphers were added by TLSv1.1. 6172613Skris 6272613Skris=item Kx=<key exchange> 6372613Skris 6472613SkrisKey exchange method: B<RSA> (for export ciphers as B<RSA(512)> or 6572613SkrisB<RSA(1024)>), B<DH> (for export ciphers as B<DH(512)> or B<DH(1024)>), 6672613SkrisB<DH/RSA>, B<DH/DSS>, B<Fortezza>. 6772613Skris 6872613Skris=item Au=<authentication> 6972613Skris 7072613SkrisAuthentication method: B<RSA>, B<DSS>, B<DH>, B<None>. None is the 7172613Skrisrepresentation of anonymous ciphers. 7272613Skris 7376866Skris=item Enc=<symmetric encryption method> 7472613Skris 7572613SkrisEncryption method with number of secret bits: B<DES(40)>, B<DES(56)>, 7672613SkrisB<3DES(168)>, B<RC4(40)>, B<RC4(56)>, B<RC4(64)>, B<RC4(128)>, 7772613SkrisB<RC2(40)>, B<RC2(56)>, B<RC2(128)>, B<IDEA(128)>, B<Fortezza>, B<None>. 7872613Skris 7972613Skris=item Mac=<message authentication code> 8072613Skris 8172613SkrisMessage digest: B<MD5>, B<SHA1>. 8272613Skris 8372613Skris=item <export flag> 8472613Skris 8572613SkrisIf the cipher is flagged exportable with respect to old US crypto 8672613Skrisregulations, the word "B<export>" is printed. 8772613Skris 8872613Skris=back 8972613Skris 9072613Skris=head1 EXAMPLES 9172613Skris 9272613SkrisSome examples for the output of SSL_CIPHER_description(): 9372613Skris 9472613Skris EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1 9572613Skris EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1 9672613Skris RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5 9772613Skris EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export 9872613Skris 99269682SjkimA comp[lete list can be retrieved by invoking the following command: 100269682Sjkim 101269682Sjkim openssl ciphers -v ALL 102269682Sjkim 10368651Skris=head1 BUGS 10468651Skris 10568651SkrisIf SSL_CIPHER_description() is called with B<cipher> being NULL, the 10668651Skrislibrary crashes. 10768651Skris 10872613SkrisIf SSL_CIPHER_description() cannot handle a built-in cipher, the according 10972613Skrisdescription of the cipher property is B<unknown>. This case should not 11072613Skrisoccur. 11172613Skris 112290207SjkimThe standard terminology for ephemeral Diffie-Hellman schemes is DHE 113290207Sjkim(finite field) or ECDHE (elliptic curve). This version of OpenSSL 114290207Sjkimidiosyncratically reports these schemes as EDH and EECDH, even though 115290207Sjkimit also accepts the standard terminology. 116290207Sjkim 117290207SjkimIt is recommended to use the standard terminology (DHE and ECDHE) 118290207Sjkimduring configuration (e.g. via SSL_CTX_set_cipher_list) for clarity of 119290207Sjkimconfiguration. OpenSSL versions after 1.0.2 will report the standard 120290207Sjkimterms via SSL_CIPHER_get_name and SSL_CIPHER_description. 121290207Sjkim 12268651Skris=head1 RETURN VALUES 12368651Skris 12468651SkrisSee DESCRIPTION 12568651Skris 12668651Skris=head1 SEE ALSO 12768651Skris 12868651SkrisL<ssl(3)|ssl(3)>, L<SSL_get_current_cipher(3)|SSL_get_current_cipher(3)>, 129290207SjkimL<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, L<ciphers(1)|ciphers(1)>, 130290207SjkimL<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)> 13168651Skris 13268651Skris=cut 133