From baf245ec5fe969f115e0e556bf0da6bf7e960847 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Sat, 9 Jan 2016 19:25:52 -0500 Subject: [PATCH] GH528: "cipher -v" output is confusing. Fix the docs, and refactor some common code. Reviewed-by: Viktor Dukhovni --- CHANGES | 4 ++ doc/apps/ciphers.pod | 8 ++-- doc/ssl/SSL_CIPHER_get_name.pod | 84 +++++++++------------------------ ssl/ssl_ciph.c | 46 +++++++++--------- 4 files changed, 51 insertions(+), 91 deletions(-) diff --git a/CHANGES b/CHANGES index 4e305721e3..ffb89904cc 100644 --- a/CHANGES +++ b/CHANGES @@ -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 diff --git a/doc/apps/ciphers.pod b/doc/apps/ciphers.pod index 43bfd942ef..0238db3f2d 100644 --- a/doc/apps/ciphers.pod +++ b/doc/apps/ciphers.pod @@ -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. =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> diff --git a/doc/ssl/SSL_CIPHER_get_name.pod b/doc/ssl/SSL_CIPHER_get_name.pod index 3ea94b849e..db0ddaa348 100644 --- a/doc/ssl/SSL_CIPHER_get_name.pod +++ b/doc/ssl/SSL_CIPHER_get_name.pod @@ -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. If the -argument is the NULL pointer, a pointer to the constant value "NONE" is -returned. +B is NULL, it returns "(NONE)". -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_bits() returns the number of secret bits used for B. +If B 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. -In some cases it should possibly return "TLSv1.2" but does not; -use SSL_CIPHER_description() instead. -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 a pointer to 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, a pointer to the string -"OPENSSL_malloc Error" is returned. +version that first defined the cipher. It returns "(NONE)" if B is NULL. SSL_CIPHER_get_cipher_nid() returns the cipher NID corresponding to B. 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. If there is no digest (e.g. for AEAD ciphersuites) then B 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. +SSL_CIPHER_description() returns a textual description of the cipher used +into the buffer B of length B provided. If B 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 is returned. -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: B, B. The TLSv1.0 ciphers are -flagged with SSLv3. No new ciphers were added by TLSv1.1. +Protocol version, such as B, when the cipher was first defined. =item Kx= -Key exchange method: B (for export ciphers as B or -B), B (for export ciphers as B or B), -B, B, B. +Key exchange method such as B, B, etc. =item Au= -Authentication method: B, B, B, B. None is the +Authentication method such as B, B, etc.. None is the representation of anonymous ciphers. =item Enc= -Encryption method with number of secret bits: B, B, -B<3DES(168)>, B, B, B, B, -B, B, B, B, B, B. +Encryption method, with number of secret bits, such as B. =item Mac= -Message digest: B, B. - -=item - -If the cipher is flagged exportable with respect to old US crypto -regulations, the word "B" is printed. +Message digest, such as B. =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 - -A comp[lete list can be retrieved by invoking the following command: - - openssl ciphers -v ALL - -=head1 BUGS - -If SSL_CIPHER_description() is called with B being NULL, the -library crashes. + 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 -If SSL_CIPHER_description() cannot handle a built-in cipher, the according -description of the cipher property is B. This case should not -occur. +=head1 HISTORY -=head1 RETURN VALUES +SSL_CIPHER_get_version() was updated to always return the correct protocol +string in OpenSSL 1.1. -See DESCRIPTION +SSL_CIPHER_description() was changed to return B on error, +rather than a fixed string, in OpenSSL 1.1 =head1 SEE ALSO diff --git a/ssl/ssl_ciph.c b/ssl/ssl_ciph.c index 44d0e7fa0f..9234364d35 100644 --- a/ssl/ssl_ciph.c +++ b/ssl/ssl_ciph.c @@ -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 */ -- 2.34.1