diff options
Diffstat (limited to 'security/nss/doc/rst/legacy/tls_cipher_suite_discovery/index.rst')
| -rw-r--r-- | security/nss/doc/rst/legacy/tls_cipher_suite_discovery/index.rst | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/security/nss/doc/rst/legacy/tls_cipher_suite_discovery/index.rst b/security/nss/doc/rst/legacy/tls_cipher_suite_discovery/index.rst new file mode 100644 index 0000000000..f9a3fc8515 --- /dev/null +++ b/security/nss/doc/rst/legacy/tls_cipher_suite_discovery/index.rst @@ -0,0 +1,114 @@ +.. _mozilla_projects_nss_tls_cipher_suite_discovery: + +TLS Cipher Suite Discovery +========================== + +.. container:: + + | + | In order to communicate securely, an TLS client and TLS server must agree on the cryptographic + algorithms and keys that they will both use on the secured connection. They must agree on these + items: + + - Key Establishment Algorithm (such as RSA, DH, or ECDH) + - Peer Authentication Algorithm (such as RSA, DSA, ECDSA) + - Bulk Data Encryption Algorithm (such as RC4, DES, AES) and key size + - Digest Algorithm for Message Authentication Checking (SHA1, SHA256) + + There are numerous available choices for each of those categories, and the number of possible + combinations of all those choices is large. TLS does not allow all possible combinations of + choices from those categories to be used. Instead, TLS allows only certain well-defined + combinations of those choices, known as Cipher Suites, defined in the IETF RFC standards. + + Each Cipher Suite is represented by a 16-bit number. The number of well-defined cipher suites + grows with time, and no TLS implementation offers all known cipher suites at all times. An + implementation that claimed to offer all defined Cipher Suites would only be able to make that + claim for a short time until another new Cipher Suite was defined. At any time, any real + implementation implements some subset of the complete set of well-defined cipher suites. + + Each new release of a TLS implementation may contain support for new Cipher Suites not supported + in previous versions. When a new version of a TLS Implementation is made available for use by + applications, those applications may wish to immediately use the newly supported Cipher Suites + found in the new version, without the application needing to be modified and re-released to know + about these new cipher suites. To that end, NSS's libSSL offers a way for applications to + discover at run time the set of Cipher Suites supported by that version of libSSL. libSSL + provides enough information about each of the supported cipher suites that the application can + construct a display of that information from which the user can choose which cipher suites his + application will attempt to use. + + Here are the details of how an NSS-based application learns what cipher suites are supported and + obtains the information to display to the user. + + libSSL offers a public table of well defined cipher suite numbers. The cipher suites are listed + in the table in order of preference, from the most preferred cipher suite to the least preferred. + The size of this table varies from release to release, and so libSSL makes the number of entries + in that table publicly available too. The table and the number of entries are declared in + "ssl.h", as follows: + + .. code:: + + /* constant table enumerating all implemented SSL 2 and 3 cipher suites. */ + SSL_IMPORT const PRUint16 SSL_ImplementedCiphers[]; + + /* number of entries in the above table. */ + SSL_IMPORT const PRUint16 SSL_NumImplementedCiphers; + + Of course, the raw integer numbers of the cipher suites are not likely to be known to most users, + so libSSL provides a function by which the application can obtain a wealth of information about + any supported cipher suite, by its number. This function is declared in "ssl.h" as follows: + + .. code:: + + SSL_IMPORT SECStatus + SSL_GetCipherSuiteInfo( + PRUint16 cipherSuite, + SSLCipherSuiteInfo *info, + PRUintn len); + + The application provides + + - the cipher suite number for which it wants information, + - the address of a block of memory allocated to receive that information, and + - the size in bytes of that block of memory. + + ``SSL_GetCipherSuiteInfo`` fills that caller-supplied memory with information from the + ``SSLCipherSuiteInfo`` structure for that cipher suite. The ``SSLCipherSuiteInfo`` structure + contains this information, declared in "sslt.h": + + .. code:: + + typedef struct SSLCipherSuiteInfoStr { + PRUint16 length; + PRUint16 cipherSuite; + + /* Cipher Suite Name */ + const char * cipherSuiteName; + + /* server authentication info */ + const char * authAlgorithmName; + SSLAuthType authAlgorithm; + + /* key exchange algorithm info */ + const char * keaTypeName; + SSLKEAType keaType; + + /* symmetric encryption info */ + const char * symCipherName; + SSLCipherAlgorithm symCipher; + PRUint16 symKeyBits; + PRUint16 symKeySpace; + PRUint16 effectiveKeyBits; + + /* MAC info */ + const char * macAlgorithmName; + SSLMACAlgorithm macAlgorithm; + PRUint16 macBits; + + PRUintn isFIPS : 1; + PRUintn isExportable : 1; + PRUintn nonStandard : 1; + PRUintn reservedBits :29; + + } SSLCipherSuiteInfo; + + (Unfinished, To be completed here)
\ No newline at end of file |