ag/cpython-source-deps
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Import OpenSSL 1.1.0f

Browse Source
This commit is contained in:
Steve Dower
2017-09-07 16:27:43 -07:00
committed by Steve Dower
parent ccd3ab4aff
commit f4b81cb7c9
3340 changed files with 325158 additions and 557542 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
doc/ssl/SSL_CIPHER_get_name.pod
View File

@@ -2,7 +2,11 @@
=head1 NAME
SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_description - get SSL_CIPHER properties
SSL_CIPHER_get_cipher_nid, SSL_CIPHER_get_digest_nid, SSL_CIPHER_get_kx_nid,
SSL_CIPHER_get_auth_nid, SSL_CIPHER_is_aead,
SSL_CIPHER_get_name, SSL_CIPHER_get_bits,
SSL_CIPHER_get_version, SSL_CIPHER_description
- get SSL_CIPHER properties
=head1 SYNOPSIS
@@ -12,41 +16,58 @@ SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_des
int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits);
char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher);
char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size);
int SSL_CIPHER_get_cipher_nid(const SSL_CIPHER *c);
int SSL_CIPHER_get_digest_nid(const SSL_CIPHER *c);
int SSL_CIPHER_get_kx_nid(const SSL_CIPHER *c);
int SSL_CIPHER_get_auth_nid(const SSL_CIPHER *c);
int SSL_CIPHER_is_aead(const SSL_CIPHER *c);
=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<SSLv2> or 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.
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
B<NID_undef> is returned.
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.
SSL_CIPHER_get_kx_nid() returns the key exchange NID corresponding to the method
used by B<c>. If there is no key exchange, then B<NID_undef> is returned. Examples (not comprehensive):
NID_kx_rsa
NID_kx_ecdhe
NID_kx_dhe
NID_kx_psk
SSL_CIPHER_get_auth_nid() returns the authentication NID corresponding to the method
used by B<c>. If there is no authentication, then B<NID_undef> is returned.
Examples (not comprehensive):
NID_auth_rsa
NID_auth_ecdsa
NID_auth_psk
SSL_CIPHER_is_aead() returns 1 if the cipher B<c> is AEAD (e.g. GCM or
ChaCha20/Poly1305), and 0 if it is not AEAD.
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.
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.
=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.
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
@@ -56,77 +77,52 @@ Textual representation of the cipher name.
=item <protocol version>
Protocol version: B<SSLv2>, 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():
EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1
EDH-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.
The standard terminology for ephemeral Diffie-Hellman schemes is DHE
(finite field) or ECDHE (elliptic curve). This version of OpenSSL
idiosyncratically reports these schemes as EDH and EECDH, even though
it also accepts the standard terminology.
It is recommended to use the standard terminology (DHE and ECDHE)
during configuration (e.g. via SSL_CTX_set_cipher_list) for clarity of
configuration. OpenSSL versions after 1.0.2 will report the standard
terms via SSL_CIPHER_get_name and SSL_CIPHER_description.
=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
L<ssl(3)|ssl(3)>, L<SSL_get_current_cipher(3)|SSL_get_current_cipher(3)>,
L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, L<ciphers(1)|ciphers(1)>,
L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>
L<ssl(3)>, L<SSL_get_current_cipher(3)>,
L<SSL_get_ciphers(3)>, L<ciphers(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut