generic-library/openssl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

GH528: "cipher -v" output is confusing.

Browse Source 
Fix the docs, and refactor some common code.

Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
This commit is contained in:
Rich Salz 2016-01-09 19:25:52 -05:00 committed by Rich Salz
parent 855eff54ec
commit baf245ec5f
4 changed files with 51 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
CHANGES
View File

@ -4,6 +4,10 @@
Changes between 1.0.2e and 1.1.0 [xx XXX xxxx]
*) The return value for SSL_CIPHER_description() for error conditions
has changed.
[Rich Salz]
*) Support for RFC6698/RFC7671 DANE TLSA peer authentication.
Obtaining and performing DNSSEC validation of TLSA records is

8
doc/apps/ciphers.pod
View File

@ -41,14 +41,12 @@ When combined with B<-s> includes cipher suites which require PSK.
=item B<-v>
Verbose option. List ciphers with a complete description of
protocol version, key exchange,
authentication, encryption and mac algorithms used along with any key size
restrictions and whether the algorithm is classed as an "export" cipher.
Verbose output: For each ciphersuite, list details as provided by
L<SSL_CIPHER_description(3)>.
=item B<-V>
Like B<-v>, but include cipher suite codes in output (hex format).
Like B<-v>, but include the official cipher suite values in hex.
=item B<-ssl3>

84
doc/ssl/SSL_CIPHER_get_name.pod
View File

@ -18,26 +18,13 @@ SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_des
=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.
B<cipher> is NULL, it returns "(NONE)".
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_bits() returns the number of secret bits used for B<cipher>.
If B<cipher> is NULL, 0 is returned.
SSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol
version that first defined the cipher.
This is currently B<TLSv1/SSLv3>.
In some cases it should possibly return "TLSv1.2" but does not;
use SSL_CIPHER_description() instead.
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 a pointer to 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, a pointer to the string
"OPENSSL_malloc Error" is returned.
version that first defined the cipher. It returns "(NONE)" if B<cipher> is NULL.
SSL_CIPHER_get_cipher_nid() returns the cipher NID corresponding to B<c>.
If there is no cipher (e.g. for ciphersuites with no encryption) then
@ -47,16 +34,14 @@ SSL_CIPHER_get_digest_nid() returns the digest NID corresponding to the MAC
used by B<c>. If there is no digest (e.g. for AEAD ciphersuites) then
B<NID_undef> is returned.
=head1 NOTES
SSL_CIPHER_description() returns a textual description of the cipher used
into the buffer B<buf> of length B<len> provided. If B<buf> is provided, it
must be at least 128 bytes, otherwise a buffer will be allocated using
OPENSSL_malloc(). If the provided buffer is too small, or the allocation fails,
B<NULL> is returned.
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.
The string returned by SSL_CIPHER_description() in case of success consists
of cleartext information separated by one or more blanks in the following
sequence:
The string returned by SSL_CIPHER_description() consists of several fields
separated by whitespace:
=over 4
@ -66,62 +51,39 @@ Textual representation of the cipher name.
=item <protocol version>
Protocol version: B<SSLv3>, B<TLSv1.2>. The TLSv1.0 ciphers are
flagged with SSLv3. No new ciphers were added by TLSv1.1.
Protocol version, such as B<TLSv1.2>, when the cipher was first defined.
=item Kx=<key exchange>
Key exchange method: B<RSA> (for export ciphers as B<RSA(512)> or
B<RSA(1024)>), B<DH> (for export ciphers as B<DH(512)> or B<DH(1024)>),
B<DH/RSA>, B<DH/DSS>, B<Fortezza>.
Key exchange method such as B<RSA>, B<ECDHE>, etc.
=item Au=<authentication>
Authentication method: B<RSA>, B<DSS>, B<DH>, B<None>. None is the
Authentication method such as B<RSA>, B<None>, etc.. None is the
representation of anonymous ciphers.
=item Enc=<symmetric encryption method>
Encryption method with number of secret bits: B<DES(40)>, B<DES(56)>,
B<3DES(168)>, B<RC4(40)>, B<RC4(56)>, B<RC4(64)>, B<RC4(128)>,
B<RC2(40)>, B<RC2(56)>, B<RC2(128)>, B<IDEA(128)>, B<Fortezza>, B<None>.
Encryption method, with number of secret bits, such as B<AESGCM(128)>.
=item Mac=<message authentication code>
Message digest: B<MD5>, B<SHA1>.
=item <export flag>
If the cipher is flagged exportable with respect to old US crypto
regulations, the word "B<export>" is printed.
Message digest, such as B<SHA256>.
=back
=head1 EXAMPLES
Some examples for the output of SSL_CIPHER_description():
DHE-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1
DHE-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1
RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5
EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD
RSA-PSK-AES256-CBC-SHA384 TLSv1.0 Kx=RSAPSK Au=RSA Enc=AES(256) Mac=SHA384
A comp[lete list can be retrieved by invoking the following command:
=head1 HISTORY
openssl ciphers -v ALL
SSL_CIPHER_get_version() was updated to always return the correct protocol
string in OpenSSL 1.1.
=head1 BUGS
If SSL_CIPHER_description() is called with B<cipher> being NULL, the
library crashes.
If SSL_CIPHER_description() cannot handle a built-in cipher, the according
description of the cipher property is B<unknown>. This case should not
occur.
=head1 RETURN VALUES
See DESCRIPTION
SSL_CIPHER_description() was changed to return B<NULL> on error,
rather than a fixed string, in OpenSSL 1.1
=head1 SEE ALSO

46
ssl/ssl_ciph.c
View File

@ -1581,24 +1581,24 @@ char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int len)
{
const char *ver;
const char *kx, *au, *enc, *mac;
uint32_t alg_mkey, alg_auth, alg_enc, alg_mac, alg_ssl;
uint32_t alg_mkey, alg_auth, alg_enc, alg_mac;
static const char *format =
"%-23s %s Kx=%-8s Au=%-4s Enc=%-9s Mac=%-4s\n";
if (buf == NULL) {
len = 128;
buf = OPENSSL_malloc(len);
if (buf == NULL)
return NULL;
} else if (len < 128)
return NULL;
alg_mkey = cipher->algorithm_mkey;
alg_auth = cipher->algorithm_auth;
alg_enc = cipher->algorithm_enc;
alg_mac = cipher->algorithm_mac;
alg_ssl = cipher->algorithm_ssl;
if (alg_ssl & SSL_SSLV3)
ver = "SSLv3";
else if (alg_ssl & SSL_TLSV1)
ver = "TLSv1.0";
else if (alg_ssl & SSL_TLSV1_2)
ver = "TLSv1.2";
else
ver = "unknown";
ver = SSL_CIPHER_get_version(cipher);
switch (alg_mkey) {
case SSL_kRSA:
@ -1768,14 +1768,6 @@ char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int len)
break;
}
if (buf == NULL) {
len = 128;
buf = OPENSSL_malloc(len);
if (buf == NULL)
return ("OPENSSL_malloc Error");
} else if (len < 128)
return ("Buffer too small");
BIO_snprintf(buf, len, format, cipher->name, ver, kx, au, enc, mac);
return (buf);
@ -1783,15 +1775,19 @@ char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int len)
char *SSL_CIPHER_get_version(const SSL_CIPHER *c)
{
int i;
uint32_t alg_ssl;
if (c == NULL)
return ("(NONE)");
i = (int)(c->id >> 24L);
if (i == 3)
return ("TLSv1/SSLv3");
else
return ("unknown");
return "(NONE)";
alg_ssl = c->algorithm_ssl;
if (alg_ssl & SSL_SSLV3)
return "SSLv3";
if (alg_ssl & SSL_TLSV1)
return "TLSv1.0";
if (alg_ssl & SSL_TLSV1_2)
return "TLSv1.2";
return "unknown";
}
/* return the actual cipher being used */