GH528: "cipher -v" output is confusing. (baf245ec) · Commits · CYBER - Cyber Security / TS 103 523 MSP / TLMSP / TLMSP OpenSSL

CHANGES

+4 −0

Original line number	Diff line number	Diff line
		@@ -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

doc/apps/ciphers.pod

+3 −5

Original line number	Diff line number	Diff line
		@@ -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>

doc/ssl/SSL_CIPHER_get_name.pod

+23 −61

Original line number	Diff line number	Diff line
		@@ -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

		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.
		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 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

		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<cipher> 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<unknown>. 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<NULL> on error,
		rather than a fixed string, in OpenSSL 1.1

		=head1 SEE ALSO

ssl/ssl_ciph.c

+21 −25

Original line number	Diff line number	Diff line
		@@ -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 */