index.rst (5268B)
1 .. _mozilla_projects_nss_tls_cipher_suite_discovery: 2 3 TLS Cipher Suite Discovery 4 ========================== 5 6 .. container:: 7 8 | 9 | In order to communicate securely, an TLS client and TLS server must agree on the cryptographic 10 algorithms and keys that they will both use on the secured connection. They must agree on these 11 items: 12 13 - Key Establishment Algorithm (such as RSA, DH, or ECDH) 14 - Peer Authentication Algorithm (such as RSA, DSA, ECDSA) 15 - Bulk Data Encryption Algorithm (such as RC4, DES, AES) and key size 16 - Digest Algorithm for Message Authentication Checking (SHA1, SHA256) 17 18 There are numerous available choices for each of those categories, and the number of possible 19 combinations of all those choices is large. TLS does not allow all possible combinations of 20 choices from those categories to be used. Instead, TLS allows only certain well-defined 21 combinations of those choices, known as Cipher Suites, defined in the IETF RFC standards. 22 23 Each Cipher Suite is represented by a 16-bit number. The number of well-defined cipher suites 24 grows with time, and no TLS implementation offers all known cipher suites at all times. An 25 implementation that claimed to offer all defined Cipher Suites would only be able to make that 26 claim for a short time until another new Cipher Suite was defined. At any time, any real 27 implementation implements some subset of the complete set of well-defined cipher suites. 28 29 Each new release of a TLS implementation may contain support for new Cipher Suites not supported 30 in previous versions. When a new version of a TLS Implementation is made available for use by 31 applications, those applications may wish to immediately use the newly supported Cipher Suites 32 found in the new version, without the application needing to be modified and re-released to know 33 about these new cipher suites. To that end, NSS's libSSL offers a way for applications to 34 discover at run time the set of Cipher Suites supported by that version of libSSL. libSSL 35 provides enough information about each of the supported cipher suites that the application can 36 construct a display of that information from which the user can choose which cipher suites his 37 application will attempt to use. 38 39 Here are the details of how an NSS-based application learns what cipher suites are supported and 40 obtains the information to display to the user. 41 42 libSSL offers a public table of well defined cipher suite numbers. The cipher suites are listed 43 in the table in order of preference, from the most preferred cipher suite to the least preferred. 44 The size of this table varies from release to release, and so libSSL makes the number of entries 45 in that table publicly available too. The table and the number of entries are declared in 46 "ssl.h", as follows: 47 48 .. code:: 49 50 /* constant table enumerating all implemented SSL 2 and 3 cipher suites. */ 51 SSL_IMPORT const PRUint16 SSL_ImplementedCiphers[]; 52 53 /* number of entries in the above table. */ 54 SSL_IMPORT const PRUint16 SSL_NumImplementedCiphers; 55 56 Of course, the raw integer numbers of the cipher suites are not likely to be known to most users, 57 so libSSL provides a function by which the application can obtain a wealth of information about 58 any supported cipher suite, by its number. This function is declared in "ssl.h" as follows: 59 60 .. code:: 61 62 SSL_IMPORT SECStatus 63 SSL_GetCipherSuiteInfo( 64 PRUint16 cipherSuite, 65 SSLCipherSuiteInfo *info, 66 PRUintn len); 67 68 The application provides 69 70 - the cipher suite number for which it wants information, 71 - the address of a block of memory allocated to receive that information, and 72 - the size in bytes of that block of memory. 73 74 ``SSL_GetCipherSuiteInfo`` fills that caller-supplied memory with information from the 75 ``SSLCipherSuiteInfo`` structure for that cipher suite. The ``SSLCipherSuiteInfo`` structure 76 contains this information, declared in "sslt.h": 77 78 .. code:: 79 80 typedef struct SSLCipherSuiteInfoStr { 81 PRUint16 length; 82 PRUint16 cipherSuite; 83 84 /* Cipher Suite Name */ 85 const char * cipherSuiteName; 86 87 /* server authentication info */ 88 const char * authAlgorithmName; 89 SSLAuthType authAlgorithm; 90 91 /* key exchange algorithm info */ 92 const char * keaTypeName; 93 SSLKEAType keaType; 94 95 /* symmetric encryption info */ 96 const char * symCipherName; 97 SSLCipherAlgorithm symCipher; 98 PRUint16 symKeyBits; 99 PRUint16 symKeySpace; 100 PRUint16 effectiveKeyBits; 101 102 /* MAC info */ 103 const char * macAlgorithmName; 104 SSLMACAlgorithm macAlgorithm; 105 PRUint16 macBits; 106 107 PRUintn isFIPS : 1; 108 PRUintn isExportable : 1; 109 PRUintn nonStandard : 1; 110 PRUintn reservedBits :29; 111 112 } SSLCipherSuiteInfo; 113 114 (Unfinished, To be completed here)