Transport Layer Security (TLS, formerly Secure Sockets Layer/SSL) is the recommended way to to protect integrity and confidentiality while data is transferred over an untrusted network connection, and to identify the endpoint. At this chapter we describe the available libraries in Fedora as well as known pitfalls, and safe ways to write applications with them. When using any library, in addition to this guide, it is recommended to consult the library' documentation. NSS documentation GNUTLS documentation OpenSSL documentation OpenJDK documentation

TLS implementations are difficult to use, and most of them lack a clean API design. The following sections contain implementation-specific advice, and some generic pitfalls are mentioned below. Most TLS implementations have questionable default TLS cipher suites. Most of them enable anonymous Diffie-Hellman key exchange (but we generally want servers to authenticate themselves). Many do not disable ciphers which are subject to brute-force attacks because of restricted key lengths. Some even disable all variants of AES in the default configuration. When overriding the cipher suite defaults, it is recommended to disable all cipher suites which are not present on a whitelist, instead of simply enabling a list of cipher suites. This way, if an algorithm is disabled by default in the TLS implementation in a future security update, the application will not re-enable it. The name which is used in certificate validation must match the name provided by the user or configuration file. No host name canonicalization or IP address lookup must be performed. The TLS handshake has very poor performance if the TCP Nagle algorithm is active. You should switch on the TCP_NODELAY socket option (at least for the duration of the handshake), or use the Linux-specific TCP_CORK option. Implementing proper session resumption decreases handshake overhead considerably. This is important if the upper-layer protocol uses short-lived connections (like most application of HTTPS). Both client and server should work towards an orderly connection shutdown, that is send close_notify alerts and respond to them. This is especially important if the upper-layer protocol does not provide means to detect connection truncation (like some uses of HTTP). When implementing a server using event-driven programming, it is important to handle the TLS handshake properly because it includes multiple network round-trips which can block when an ordinary TCP accept would not. Otherwise, a client which fails to complete the TLS handshake for some reason will prevent the server from handling input from other clients. Unlike regular file descriptors, TLS connections cannot be passed between processes. Some TLS implementations add additional restrictions, and TLS connections generally cannot be used across fork function calls (see ).

Some OpenSSL function use tri-state return values. Correct error checking is extremely important. Several functions return int values with the following meaning: The value 1 indicates success (for example, a successful signature verification). The value 0 indicates semantic failure (for example, a signature verification which was unsuccessful because the signing certificate was self-signed). The value -1 indicates a low-level error in the system, such as failure to allocate memory using malloc. Treating such tri-state return values as booleans can lead to security vulnerabilities. Note that some OpenSSL functions return boolean results or yet another set of status indicators. Each function needs to be checked individually. Recovering precise error information is difficult. shows how to obtain a more precise error code after a function call on an SSL object has failed. However, there are still cases where no detailed error information is available (e.g., if SSL_shutdown fails due to a connection teardown by the other end). The OPENSSL_config function is documented to never fail. In reality, it can terminate the entire process if there is a failure accessing the configuration file. An error message is written to standard error, but which might not be visible if the function is called from a daemon process. OpenSSL contains two separate ASN.1 DER decoders. One set of decoders operate on BIO handles (the input/output stream abstraction provided by OpenSSL); their decoder function names start with d2i_ and end in _fp or _bio (e.g., d2i_X509_fp or d2i_X509_bio). These decoders must not be used for parsing data from untrusted sources; instead, the variants without the _fp and _bio (e.g., d2i_X509) shall be used. The BIO variants have received considerably less testing and are not very robust. For the same reason, the OpenSSL command line tools (such as openssl x509) are generally generally less robust than the actual library code. They use the BIO functions internally, and not the more robust variants. The command line tools do not always indicate failure in the exit status of the openssl process. For instance, a verification failure in openssl verify result in an exit status of zero. OpenSSL command-line commands, such as openssl genrsa, do not ensure that physical entropy is used for key generation—they obtain entropy from /dev/urandom and other sources, but not from /dev/random. This can result in weak keys if the system lacks a proper entropy source (e.g., a virtual machine with solid state storage). Depending on local policies, keys generated by these OpenSSL tools should not be used in high-value, critical functions. The OpenSSL server and client applications (openssl s_client and openssl s_server) are debugging tools and should never be used as generic clients. For instance, the s_client tool reacts in a surprising way to lines starting with R and Q. OpenSSL allows application code to access private key material over documented interfaces. This can significantly increase the part of the code base which has to undergo security certification.

Older versions of GNUTLS had several peculiarities described in previous versions of this guide; as of GNUTLS 3.3.10, these issues are no longer applicable.

The Java cryptographic framework is highly modular. As a result, when you request an object implementing some cryptographic functionality, you cannot be completely sure that you end up with the well-tested, reviewed implementation in OpenJDK. OpenJDK (in the source code as published by Oracle) and other implementations of the Java platform require that the system administrator has installed so-called unlimited strength jurisdiction policy files. Without this step, it is not possible to use the secure algorithms which offer sufficient cryptographic strength. Most downstream redistributors of OpenJDK remove this requirement. Some versions of OpenJDK use /dev/random as the randomness source for nonces and other random data which is needed for TLS operation, but does not actually require physical randomness. As a result, TLS applications can block, waiting for more bits to become available in /dev/random.

NSS was not designed to be used by other libraries which can be linked into applications without modifying them. There is a lot of global state. There does not seem to be a way to perform required NSS initialization without race conditions. If the NSPR descriptor is in an unexpected state, the SSL_ForceHandshake function can succeed, but no TLS handshake takes place, the peer is not authenticated, and subsequent data is exchanged in the clear. NSS disables itself if it detects that the process underwent a fork after the library has been initialized. This behavior is required by the PKCS#11 API specification.

Secure use of TLS in a client generally involves all of the following steps. (Individual instructions for specific TLS implementations follow in the next sections.) The client must configure the TLS library to use a set of trusted root certificates. These certificates are provided by the system in various formats and files. These are documented in update-ca-trust man page in Fedora. Portable applications should not hard-code any paths; they should rely on APIs which set the default for the system trust store. The client selects sufficiently strong cryptographic primitives and disables insecure ones (such as no-op encryption). Compression support and SSL version 3 or lower must be disabled (including the SSLv2-compatible handshake). The client initiates the TLS connection. The Server Name Indication extension should be used if supported by the TLS implementation. Before switching to the encrypted connection state, the contents of all input and output buffers must be discarded. The client needs to validate the peer certificate provided by the server, that is, the client must check that there is a cryptographically protected chain from a trusted root certificate to the peer certificate. (Depending on the TLS implementation, a TLS handshake can succeed even if the certificate cannot be validated.) The client must check that the configured or user-provided server name matches the peer certificate provided by the server. It is safe to provide users detailed diagnostics on certificate validation failures. Other causes of handshake failures and, generally speaking, any details on other errors reported by the TLS implementation (particularly exception tracebacks), must not be divulged in ways that make them accessible to potential attackers. Otherwise, it is possible to create decryption oracles. Depending on the application, revocation checking (against certificate revocations lists or via OCSP) and session resumption are important aspects of production-quality client. These aspects are not yet covered.

In the following code, the error handling is only exploratory. Proper error handling is required for production use, especially in libraries. The OpenSSL library needs explicit initialization (see ). After that, a context object has to be created, which acts as a factory for connection objects (). We use an explicit cipher list so that we do not pick up any strange ciphers when OpenSSL is upgraded. The actual version requested in the client hello depends on additional restrictions in the OpenSSL library. If possible, you should follow the example code and use the default list of trusted root certificate authorities provided by the system because you would have to maintain your own set otherwise, which can be cumbersome. A single context object can be used to create multiple connection objects. It is safe to use the same SSL_CTX object for creating connections concurrently from multiple threads, provided that the SSL_CTX object is not modified (e.g., callbacks must not be changed). After creating the TCP socket and disabling the Nagle algorithm (per ), the actual connection object needs to be created, as show in . If the handshake started by SSL_connect fails, the ssl_print_error_and_exit function from is called. The certificate_validity_override function provides an opportunity to override the validity of the certificate in case the OpenSSL check fails. If such functionality is not required, the call can be removed, otherwise, the application developer has to implement it. The host name passed to the functions SSL_set_tlsext_host_name and X509_check_host must be the name that was passed to getaddrinfo or a similar name resolution function. No host name canonicalization must be performed. The X509_check_host function used in the final step for host name matching is currently only implemented in OpenSSL 1.1, which is not released yet. In case host name matching fails, the function certificate_host_name_override is called. This function should check user-specific certificate store, to allow a connection even if the host name does not match the certificate. This function has to be provided by the application developer. Note that the override must be keyed by both the certificate and the host name. The connection object can be used for sending and receiving data, as in . It is also possible to create a BIO object and use the SSL object as the underlying transport, using BIO_set_ssl. When it is time to close the connection, the SSL_shutdown function needs to be called twice for an orderly, synchronous connection termination (). This exchanges close_notify alerts with the server. The additional logic is required to deal with an unexpected close_notify from the server. Note that is necessary to explicitly close the underlying socket after the connection object has been freed. shows how to deallocate the context object when it is no longer needed because no further TLS connections will be established.

This section describes how to implement a TLS client with full certificate validation (but without certificate revocation checking). Note that the error handling in is only exploratory and needs to be replaced before production use. Before setting up TLS connections, a credentials objects has to be allocated and initialized with the set of trusted root CAs (). After the last TLS connection has been closed, this credentials object should be freed: During its lifetime, the credentials object can be used to initialize TLS session objects from multiple threads, provided that it is not changed. Once the TCP connection has been established, the Nagle algorithm should be disabled (see ). After that, the socket can be associated with a new GNUTLS session object. The previously allocated credentials object provides the set of root CAs. Then the TLS handshake must be initiated. This is shown in . After the handshake has been completed, the server certificate needs to be verified against the server's hostname (). In the example, the user-defined certificate_validity_override function is called if the verification fails, so that a separate, user-specific trust store can be checked. This function call can be omitted if the functionality is not needed. An established TLS session can be used for sending and receiving data, as in . In order to shut down a connection in an orderly manner, you should call the gnutls_bye function. Finally, the session object can be deallocated using gnutls_deinit (see ).

The examples below use the following cryptographic-related classes: If compatibility with OpenJDK 6 is required, it is necessary to use the internal class sun.security.util.HostnameChecker. (The public OpenJDK API does not provide any support for dissecting the subject distinguished name of an X.509 certificate, so a custom-written DER parser is needed—or we have to use an internal class, which we do below.) In OpenJDK 7, the setEndpointIdentificationAlgorithm method was added to the javax.net.ssl.SSLParameters class, providing an official way to implement host name checking. TLS connections are established using an SSLContext instance. With a properly configured OpenJDK installation, the SunJSSE provider uses the system-wide set of trusted root certificate authorities, so no further configuration is necessary. For backwards compatibility with OpenJDK 6, the TLSv1 provider has to be supported as a fall-back option. This is shown in . In addition to the context, a TLS parameter object will be needed which adjusts the cipher suites and protocols (). Like the context, these parameters can be reused for multiple TLS connections. As initialized above, the parameter object does not yet require host name checking. This has to be enabled separately, and this is only supported by OpenJDK 7 and later: All application protocols can use the "HTTPS" algorithm. (The algorithms have minor differences with regard to wildcard handling, which should not matter in practice.) shows how to establish the connection. Before the handshake is initialized, the protocol and cipher configuration has to be performed, by applying the parameter object params. (After this point, changes to params will not affect this TLS socket.) As mentioned initially, host name checking requires using an internal API on OpenJDK 6. Starting with OpenJDK 7, the last lines can be omitted, provided that host name verification has been enabled by calling the setEndpointIdentificationAlgorithm method on the params object (before it was applied to the socket). The TLS socket can be used as a regular socket, as shown in .

Overriding certificate validation requires a custom trust manager. With OpenJDK 6, the trust manager lacks information about the TLS session, and to which server the connection is made. Certificate overrides have to be tied to specific servers (host names). Consequently, different TrustManager and SSLContext objects have to be used for different servers. In the trust manager shown in , the server certificate is identified by its SHA-256 hash. This trust manager has to be passed to the init method of the SSLContext object, as show in . When certificate overrides are in place, host name verification should not be performed because there is no security requirement that the host name in the certificate matches the host name used to establish the connection (and it often will not). However, without host name verification, it is not possible to perform transparent fallback to certification validation using the system certificate store. The approach described above works with OpenJDK 6 and later versions. Starting with OpenJDK 7, it is possible to use a custom subclass of the javax.net.ssl.X509ExtendedTrustManager class. The OpenJDK TLS implementation will call the new methods, passing along TLS session information. This can be used to implement certificate overrides as a fallback (if certificate or host name verification fails), and a trust manager object can be used for multiple servers because the server address is available to the trust manager.

The following code shows how to implement a simple TLS client using NSS. These instructions apply to NSS version 3.14 and later. Versions before 3.14 need different initialization code. Keep in mind that the error handling needs to be improved before the code can be used in production. Using NSS needs several header files, as shown in . Initializing the NSS library is shown in . This initialization procedure overrides global state. We only call NSS_SetDomesticPolicy if there are no strong ciphers available, assuming that it has already been called otherwise. This avoids overriding the process-wide cipher suite policy unnecessarily. The simplest way to configured the trusted root certificates involves loading the libnssckbi.so NSS module with a call to the SECMOD_LoadUserModule function. The root certificates are compiled into this module. (The PEM module for NSS, libnsspem.so, offers a way to load trusted CA certificates from a file.) Some of the effects of the initialization can be reverted with the following function calls: After NSS has been initialized, the TLS connection can be created (). The internal PR_ImportTCPSocket function is used to turn the POSIX file descriptor sockfd into an NSPR file descriptor. (This function is de-facto part of the NSS public ABI, so it will not go away.) Creating the TLS-capable file descriptor requires a model descriptor, which is configured with the desired set of protocols. The model descriptor is not needed anymore after TLS support has been activated for the existing connection descriptor. The call to SSL_BadCertHook can be omitted if no mechanism to override certificate verification is needed. The bad_certificate function must check both the host name specified for the connection and the certificate before granting the override. Triggering the actual handshake requires three function calls, SSL_ResetHandshake, SSL_SetURL, and SSL_ForceHandshake. (If SSL_ResetHandshake is omitted, SSL_ForceHandshake will succeed, but the data will not be encrypted.) During the handshake, the certificate is verified and matched against the host name. After the connection has been established, shows how to use the NSPR descriptor to communicate with the server. shows how to close the connection.

The Python distribution provides a TLS implementation in the ssl module (actually a wrapper around OpenSSL). The exported interface is somewhat restricted, so that the client code shown below does not fully implement the recommendations in . Currently, most Python function which accept https:// URLs or otherwise implement HTTPS support do not perform certificate validation at all. (For example, this is true for the httplib and xmlrpclib modules.) If you use HTTPS, you should not use the built-in HTTP clients. The Curl class in the curl module, as provided by the python-pycurl package implements proper certificate validation. The ssl module currently does not perform host name checking on the server certificate. shows how to implement certificate matching, using the parsed certificate returned by getpeercert. To turn a regular, connected TCP socket into a TLS-enabled socket, use the ssl.wrap_socket function. The function call in provides additional arguments to override questionable defaults in OpenSSL and in the Python module. ciphers="HIGH:-aNULL:-eNULL:-PSK:RC4-SHA:RC4-MD5" selects relatively strong cipher suites with certificate-based authentication. (The call to check_host_name function provides additional protection against anonymous cipher suites.) ssl_version=ssl.PROTOCOL_TLSv1 disables SSL 2.0 support. By default, the ssl module sends an SSL 2.0 client hello, which is rejected by some servers. Ideally, we would request OpenSSL to negotiated the most recent TLS version supported by the server and the client, but the Python module does not allow this. cert_reqs=ssl.CERT_REQUIRED turns on certificate validation. ca_certs='/etc/ssl/certs/ca-bundle.crt' initializes the certificate store with a set of trusted root CAs. Unfortunately, it is necessary to hard-code this path into applications because the default path in OpenSSL is not available through the Python ssl module. The ssl module (and OpenSSL) perform certificate validation, but the certificate must be compared manually against the host name, by calling the check_host_name defined above. After the connection has been established, the TLS socket can be used like a regular socket: Closing the TLS socket is straightforward as well: