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

CHANGES

+4 −0

Original line number	Original line	Diff line number	Diff line
	@@ -4,6 +4,10 @@

	Changes between 1.0.2e and 1.1.0 [xx XXX xxxx]		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.		*) Support for RFC6698/RFC7671 DANE TLSA peer authentication.

	Obtaining and performing DNSSEC validation of TLSA records is		Obtaining and performing DNSSEC validation of TLSA records is

doc/apps/ciphers.pod

+3 −5

Original line number	Original line	Diff line number	Diff line
	@@ -41,14 +41,12 @@ When combined with B<-s> includes cipher suites which require PSK.

	=item B<-v>		=item B<-v>

	Verbose option. List ciphers with a complete description of		Verbose output: For each ciphersuite, list details as provided by
	protocol version, key exchange,		L<SSL_CIPHER_description(3)>.
	authentication, encryption and mac algorithms used along with any key size
	restrictions and whether the algorithm is classed as an "export" cipher.

	=item B<-V>		=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>		=item B<-ssl3>

doc/ssl/SSL_CIPHER_get_name.pod

+23 −61

Original line number	Original line	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		=head1 DESCRIPTION

	SSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the		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		B<cipher> is NULL, it returns "(NONE)".
	returned.

	SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>. If		SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>.
	B<alg_bits> is not NULL, it contains the number of bits processed by the		If B<cipher> is NULL, 0 is returned.
	chosen algorithm. If B<cipher> is NULL, 0 is returned.

	SSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol		SSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol
	version that first defined the cipher.		version that first defined the cipher. It returns "(NONE)" if B<cipher> is NULL.
	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.

	SSL_CIPHER_get_cipher_nid() returns the cipher NID corresponding to B<c>.		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		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		used by B<c>. If there is no digest (e.g. for AEAD ciphersuites) then
	B<NID_undef> is returned.		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
	The number of bits processed can be different from the secret bits. An		must be at least 128 bytes, otherwise a buffer will be allocated using
	export cipher like e.g. EXP-RC4-MD5 has only 40 secret bits. The algorithm		OPENSSL_malloc(). If the provided buffer is too small, or the allocation fails,
	does use the full 128 bits (which would be returned for B<alg_bits>), of		B<NULL> is returned.
	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		The string returned by SSL_CIPHER_description() consists of several fields
	of cleartext information separated by one or more blanks in the following		separated by whitespace:
	sequence:

	=over 4		=over 4

	@@ -66,62 +51,39 @@ Textual representation of the cipher name.

	=item <protocol version>		=item <protocol version>

	Protocol version: B<SSLv3>, B<TLSv1.2>. The TLSv1.0 ciphers are		Protocol version, such as B<TLSv1.2>, when the cipher was first defined.
	flagged with SSLv3. No new ciphers were added by TLSv1.1.

	=item Kx=<key exchange>		=item Kx=<key exchange>

	Key exchange method: B<RSA> (for export ciphers as B<RSA(512)> or		Key exchange method such as B<RSA>, B<ECDHE>, etc.
	B<RSA(1024)>), B<DH> (for export ciphers as B<DH(512)> or B<DH(1024)>),
	B<DH/RSA>, B<DH/DSS>, B<Fortezza>.

	=item Au=<authentication>		=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.		representation of anonymous ciphers.

	=item Enc=<symmetric encryption method>		=item Enc=<symmetric encryption method>

	Encryption method with number of secret bits: B<DES(40)>, B<DES(56)>,		Encryption method, with number of secret bits, such as B<AESGCM(128)>.
	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>.

	=item Mac=<message authentication code>		=item Mac=<message authentication code>

	Message digest: B<MD5>, B<SHA1>.		Message digest, such as B<SHA256>.

	=item <export flag>

	If the cipher is flagged exportable with respect to old US crypto
	regulations, the word "B<export>" is printed.

	=back		=back

	=head1 EXAMPLES

	Some examples for the output of SSL_CIPHER_description():		Some examples for the output of SSL_CIPHER_description():

	DHE-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1		ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD
	DHE-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1		RSA-PSK-AES256-CBC-SHA384 TLSv1.0 Kx=RSAPSK Au=RSA Enc=AES(256) Mac=SHA384
	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.

	If SSL_CIPHER_description() cannot handle a built-in cipher, the according		=head1 HISTORY
	description of the cipher property is B<unknown>. This case should not
	occur.

	=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		=head1 SEE ALSO

ssl/ssl_ciph.c

+21 −25

Original line number	Original line	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 *ver;
	const char kx, au, enc, mac;		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 =		static const char *format =
	"%-23s %s Kx=%-8s Au=%-4s Enc=%-9s Mac=%-4s\n";		"%-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_mkey = cipher->algorithm_mkey;
	alg_auth = cipher->algorithm_auth;		alg_auth = cipher->algorithm_auth;
	alg_enc = cipher->algorithm_enc;		alg_enc = cipher->algorithm_enc;
	alg_mac = cipher->algorithm_mac;		alg_mac = cipher->algorithm_mac;
	alg_ssl = cipher->algorithm_ssl;

	if (alg_ssl & SSL_SSLV3)		ver = SSL_CIPHER_get_version(cipher);
	ver = "SSLv3";
	else if (alg_ssl & SSL_TLSV1)
	ver = "TLSv1.0";
	else if (alg_ssl & SSL_TLSV1_2)
	ver = "TLSv1.2";
	else
	ver = "unknown";

	switch (alg_mkey) {		switch (alg_mkey) {
	case SSL_kRSA:		case SSL_kRSA:
	@@ -1768,14 +1768,6 @@ char SSL_CIPHER_description(const SSL_CIPHER cipher, char *buf, int len)
	break;		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);		BIO_snprintf(buf, len, format, cipher->name, ver, kx, au, enc, mac);

	return (buf);		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)		char SSL_CIPHER_get_version(const SSL_CIPHER c)
	{		{
	int i;		uint32_t alg_ssl;

	if (c == NULL)		if (c == NULL)
	return ("(NONE)");		return "(NONE)";
	i = (int)(c->id >> 24L);		alg_ssl = c->algorithm_ssl;
	if (i == 3)
	return ("TLSv1/SSLv3");		if (alg_ssl & SSL_SSLV3)
	else		return "SSLv3";
	return ("unknown");		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 */		/* return the actual cipher being used */