defensive-coding-guide/defensive-coding/bo/Features/TLS.po

# AUTHOR <EMAIL@ADDRESS>, YEAR.
# 
# Translators:
msgid ""
msgstr ""
"Project-Id-Version: Defensive Coding Guide\n"
"POT-Creation-Date: 2013-03-12T03:19:44\n"
"PO-Revision-Date: 2013-03-19 15:31+0000\n"
"Last-Translator: Automatically generated\n"
"Language-Team: Tibetan <trans-bo@lists.fedoraproject.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Language: bo\n"
"Plural-Forms: nplurals=1; plural=0;\n"

#. Tag: title
#, no-c-format
msgid "Transport Layer Security"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Common Pitfalls"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The TLS handshake has very poor performance if the TCP Nagle algorithm is "
"active. You should switch on the <literal>TCP_NODELAY</literal> socket "
"option (at least for the duration of the handshake), or use the Linux-"
"specific <literal>TCP_CORK</literal> option."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Deactivating the TCP Nagle algorithm"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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)."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"Both client and server should work towards an orderly connection shutdown, "
"that is send <literal>close_notify</literal> 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)."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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 <function>accept</function>"
" 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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 <function>fork</function> "
"function calls (see <xref linkend=\"sect-Defensive_Coding-Tasks-Processes-"
"Fork-Parallel\" />)."
msgstr ""

#. Tag: title
#, no-c-format
msgid "OpenSSL Pitfalls"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"Some OpenSSL function use <emphasis>tri-state return values</emphasis>. "
"Correct error checking is extremely important. Several functions return "
"<literal>int</literal> values with the following meaning:"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The value <literal>1</literal> indicates success (for example, a successful "
"signature verification)."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The value <literal>0</literal> indicates semantic failure (for example, a "
"signature verification which was unsuccessful because the signing "
"certificate was self-signed)."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The value <literal>-1</literal> indicates a low-level error in the system, "
"such as failure to allocate memory using <function>malloc</function>."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"Recovering precise error information is difficult. <xref linkend=\"ex-"
"Defensive_Coding-TLS-OpenSSL-Errors\" /> shows how to obtain a more precise "
"error code after a function call on an <literal>SSL</literal> object has "
"failed. However, there are still cases where no detailed error information "
"is available (e.g., if <function>SSL_shutdown</function> fails due to a "
"connection teardown by the other end)."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Obtaining OpenSSL error codes"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The <function>OPENSSL_config</function> 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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 <literal>d2i_</literal> "
"and end in <literal>_fp</literal> or <literal>_bio</literal> (e.g., "
"<function>d2i_X509_fp</function> or <function>d2i_X509_bio</function>). "
"These decoders must not be used for parsing data from untrusted sources; "
"instead, the variants without the <literal>_fp</literal> and "
"<literal>_bio</literal> (e.g., <function>d2i_X509</function>) shall be used."
" The BIO variants have received considerably less testing and are not very "
"robust."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"For the same reason, the OpenSSL command line tools (such as "
"<command>openssl x509</command>) are generally generally less robust than "
"the actual library code. They use the BIO functions internally, and not the "
"more robust variants."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The command line tools do not always indicate failure in the exit status of "
"the <application>openssl</application> process. For instance, a verification"
" failure in <command>openssl verify</command> result in an exit status of "
"zero."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The OpenSSL server and client applications (<command>openssl "
"s_client</command> and <command>openssl s_server</command>) are debugging "
"tools and should <emphasis>never</emphasis> be used as generic clients. For "
"instance, the <application>s_client</application> tool reacts in a "
"surprisign way to lines starting with <literal>R</literal> and "
"<literal>Q</literal>."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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."
msgstr ""

#. Tag: title
#, no-c-format
msgid "GNUTLS Pitfalls"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"<filename>libgnutls.so.26</filename> links to "
"<filename>libpthread.so.0</filename>. Loading the threading library too late"
" causes problems, so the main program should be linked with "
"<literal>-lpthread</literal> as well. As a result, it can be difficult to "
"use GNUTLS in a plugin which is loaded with the <function>dlopen</function> "
"function. Another side effect is that applications which merely link against"
" GNUTLS (even without actually using it) may incur a substantial overhead "
"because other libraries automatically switch to thread-safe algorithms."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The <function>gnutls_global_init</function> function must be called before "
"using any functionality provided by the library. This function is not "
"thread-safe, so external locking is required, but it is not clear which lock"
" should be used. Omitting the synchronization does not just lead to a memory"
" leak, as it is suggested in the GNUTLS documentation, but to undefined "
"behavior because there is no barrier that would enforce memory ordering."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The <function>gnutls_global_deinit</function> function does not actually "
"deallocate all resources allocated by "
"<function>gnutls_global_init</function>. It is currently not thread-safe. "
"Therefore, it is best to avoid calling it altogether."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The X.509 implementation in GNUTLS is rather lenient. For example, it is "
"possible to create and process X.509 version&nbsp;1 certificates which carry"
" extensions. These certificates are (correctly) rejected by other "
"implementations."
msgstr ""

#. Tag: title
#, no-c-format
msgid "OpenJDK Pitfalls"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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 <emphasis>unlimited strength jurisdiction policy "
"files</emphasis>. 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"Some versions of OpenJDK use <filename>/dev/random</filename> 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 "
"<filename>/dev/random</filename>."
msgstr ""

#. Tag: title
#, no-c-format
msgid "NSS Pitfalls"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"If the NSPR descriptor is in an unexpected state, the "
"<function>SSL_ForceHandshake</function> function can succeed, but no TLS "
"handshake takes place, the peer is not authenticated, and subsequent data is"
" exchanged in the clear."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"NSS disables itself if it detects that the process underwent a "
"<function>fork</function> after the library has been initialized. This "
"behavior is required by the PKCS#11 API specification."
msgstr ""

#. Tag: title
#, no-c-format
msgid "TLS Clients"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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.)"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The client must configure the TLS library to use a set of trusted root "
"certificates. These certificates are provided by the system in <filename "
"class=\"directory\">/etc/ssl/certs</filename> or files derived from it."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The client selects sufficiently strong cryptographic primitives and disables"
" insecure ones (such as no-op encryption). Compression and SSL version 2 "
"support must be disabled (including the SSLv2-compatible handshake)."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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.)"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The client must check that the configured or user-provided server name "
"matches the peer certificate provided by the server."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Implementation TLS Clients With OpenSSL"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"In the following code, the error handling is only exploratory. Proper error "
"handling is required for production use, especially in libraries."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The OpenSSL library needs explicit initialization (see <xref linkend=\"ex-"
"Defensive_Coding-TLS-OpenSSL-Init\" />)."
msgstr ""

#. Tag: title
#, no-c-format
msgid "OpenSSL library initialization"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"After that, a context object has to be created, which acts as a factory for "
"connection objects (<xref linkend=\"ex-Defensive_Coding-TLS-Client-OpenSSL-"
"CTX\" />). 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."
msgstr ""

#. Tag: title
#, no-c-format
msgid "OpenSSL client context creation"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"A single context object can be used to create multiple connection objects. "
"It is safe to use the same <literal>SSL_CTX</literal> object for creating "
"connections concurrently from multiple threads, provided that the "
"<literal>SSL_CTX</literal> object is not modified (e.g., callbacks must not "
"be changed)."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"After creating the TCP socket and disabling the Nagle algorithm (per <xref "
"linkend=\"ex-Defensive_Coding-TLS-Nagle\" />), the actual connection object "
"needs to be created, as show in <xref linkend=\"ex-Defensive_Coding-TLS-"
"Client-OpenSSL-CTX\" />. If the handshake started by "
"<function>SSL_connect</function> fails, the "
"<function>ssl_print_error_and_exit</function> function from <xref linkend"
"=\"ex-Defensive_Coding-TLS-OpenSSL-Errors\" /> is called."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The <function>certificate_validity_override</function> 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The host name passed to the functions "
"<function>SSL_set_tlsext_host_name</function> and "
"<function>X509_check_host</function> must be the name that was passed to "
"<function>getaddrinfo</function> or a similar name resolution function. No "
"host name canonicalization must be performed. The "
"<function>X509_check_host</function> 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 "
"<function>certificate_host_name_override</function> 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 <emphasis>and</emphasis> the host name."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Creating a client connection using OpenSSL"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The connection object can be used for sending and receiving data, as in "
"<xref linkend=\"ex-Defensive_Coding-TLS-OpenSSL-Connection-Use\" />. It is "
"also possible to create a <literal>BIO</literal> object and use the "
"<literal>SSL</literal> object as the underlying transport, using "
"<function>BIO_set_ssl</function>."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Using an OpenSSL connection to send and receive data"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"When it is time to close the connection, the "
"<function>SSL_shutdown</function> function needs to be called twice for an "
"orderly, synchronous connection termination (<xref linkend=\"ex-"
"Defensive_Coding-TLS-OpenSSL-Connection-Close\" />). This exchanges "
"<literal>close_notify</literal> alerts with the server. The additional logic"
" is required to deal with an unexpected <literal>close_notify</literal> from"
" the server. Note that is necessary to explicitly close the underlying "
"socket after the connection object has been freed."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Closing an OpenSSL connection in an orderly fashion"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"<xref linkend=\"ex-Defensive_Coding-TLS-OpenSSL-Context-Close\" /> shows how"
" to deallocate the context object when it is no longer needed because no "
"further TLS connections will be established."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Implementation TLS Clients With GNUTLS"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "The GNUTLS library needs explicit initialization:"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"Failing to do so can result in obscure failures in Base64 decoding. See "
"<xref linkend=\"sect-Defensive_Coding-TLS-Pitfalls-GNUTLS\" /> for "
"additional aspects of initialization."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"Before setting up TLS connections, a credentials objects has to be allocated"
" and initialized with the set of trusted root CAs (<xref linkend=\"ex-"
"Defensive_Coding-TLS-Client-GNUTLS-Credentials\" />)."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Initializing a GNUTLS credentials structure"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"After the last TLS connection has been closed, this credentials object "
"should be freed:"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"During its lifetime, the credentials object can be used to initialize TLS "
"session objects from multiple threads, provided that it is not changed."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"Once the TCP connection has been established, the Nagle algorithm should be "
"disabled (see <xref linkend=\"ex-Defensive_Coding-TLS-Nagle\" />). After "
"that, the socket can be associated with a new GNUTLS session object. The "
"previously allocated credentials object provides the set of root CAs. The "
"<literal>NORMAL</literal> set of cipher suites and protocols provides a "
"reasonable default. Then the TLS handshake must be initiated. This is shown "
"in <xref linkend=\"ex-Defensive_Coding-TLS-Client-GNUTLS-Connect\" />."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Establishing a TLS client connection using GNUTLS"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"After the handshake has been completed, the server certificate needs to be "
"verified (<xref linkend=\"ex-Defensive_Coding-TLS-Client-GNUTLS-Verify\" "
"/>). In the example, the user-defined "
"<function>certificate_validity_override</function> 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."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Verifying a server certificate using GNUTLS"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"In the next step (<xref linkend=\"ex-Defensive_Coding-TLS-Client-GNUTLS-"
"Match\" />, the certificate must be matched against the host name (note the "
"unusual return value from "
"<function>gnutls_x509_crt_check_hostname</function>). Again, an override "
"function <function>certificate_host_name_override</function> is called. Note"
" that the override must be keyed to the certificate <emphasis>and</emphasis>"
" the host name. The function call can be omitted if the override is not "
"needed."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Matching the server host name and certificate in a GNUTLS client"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"In newer GNUTLS versions, certificate checking and host name validation can "
"be combined using the <function>gnutls_certificate_verify_peers3</function> "
"function."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"An established TLS session can be used for sending and receiving data, as in"
" <xref linkend=\"ex-Defensive_Coding-TLS-GNUTLS-Use\" />."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Using a GNUTLS session"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"In order to shut down a connection in an orderly manner, you should call the"
" <function>gnutls_bye</function> function. Finally, the session object can "
"be deallocated using <function>gnutls_deinit</function> (see <xref linkend"
"=\"ex-Defensive_Coding-TLS-GNUTLS-Disconnect\" />)."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Implementing TLS Clients With OpenJDK"
msgstr ""

#. Tag: para
#, no-c-format
msgid "The examples below use the following cryptographic-related classes:"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"If compatibility with OpenJDK 6 is required, it is necessary to use the "
"internal class <literal>sun.security.util.HostnameChecker</literal>. (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 <function>setEndpointIdentificationAlgorithm</function> "
"method was added to the <literal>javax.net.ssl.SSLParameters</literal> "
"class, providing an official way to implement host name checking."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"TLS connections are established using an <literal>SSLContext</literal> "
"instance. With a properly configured OpenJDK installation, the "
"<literal>SunJSSE</literal> provider uses the system-wide set of trusted root"
" certificate authorities, so no further configuration is necessary. For "
"backwards compatibility with OpenJDK&nbsp;6, the <literal>TLSv1</literal> "
"provider has to be supported as a fall-back option. This is shown in <xref "
"linkend=\"ex-Defensive_Coding-TLS-Client-OpenJDK-Context\" />."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Setting up an <literal>SSLContext</literal> for OpenJDK TLS clients"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"In addition to the context, a TLS parameter object will be needed which "
"adjusts the cipher suites and protocols (<xref linkend=\"ex-"
"Defensive_Coding-TLS-OpenJDK-Parameters\" />). Like the context, these "
"parameters can be reused for multiple TLS connections."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Setting up <literal>SSLParameters</literal> for TLS use with OpenJDK"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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:"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"All application protocols can use the <literal>\"HTTPS\"</literal> "
"algorithm. (The algorithms have minor differences with regard to wildcard "
"handling, which should not matter in practice.)"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"<xref linkend=\"ex-Defensive_Coding-TLS-Client-OpenJDK-Connect\" /> 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 <literal>params</literal>. (After this point, changes to "
"<literal>params</literal> will not affect this TLS socket.) As mentioned "
"initially, host name checking requires using an internal API on OpenJDK 6."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Establishing a TLS connection with OpenJDK"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"Starting with OpenJDK 7, the last lines can be omitted, provided that host "
"name verification has been enabled by calling the "
"<function>setEndpointIdentificationAlgorithm</function> method on the "
"<literal>params</literal> object (before it was applied to the socket)."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The TLS socket can be used as a regular socket, as shown in <xref linkend"
"=\"ex-Defensive_Coding-TLS-Client-OpenJDK-Use\" />."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Using a TLS client socket in OpenJDK"
msgstr ""

#. Tag: title
#, no-c-format
msgid "Overriding server certificate validation with OpenJDK 6"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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 "
"<literal>TrustManager</literal> and <literal>SSLContext</literal> objects "
"have to be used for different servers."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"In the trust manager shown in <xref linkend=\"ex-Defensive_Coding-TLS-"
"Client-MyTrustManager\" />, the server certificate is identified by its "
"SHA-256 hash."
msgstr ""

#. Tag: title
#, no-c-format
msgid "A customer trust manager for OpenJDK TLS clients"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"This trust manager has to be passed to the <literal>init</literal> method of"
" the <literal>SSLContext</literal> object, as show in <xref linkend=\"ex-"
"Defensive_Coding-TLS-Client-Context_For_Cert\" />."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Using a custom TLS trust manager with OpenJDK"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"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 "
"<literal>javax.net.ssl.X509ExtendedTrustManager</literal> 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."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Implementing TLS Clients With NSS"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The following code shows how to implement a simple TLS client using NSS. "
"Note that the error handling needs replacing before production use."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"Using NSS needs several header files, as shown in <xref linkend=\"ex-"
"Defensive_Coding-TLS-NSS-Includes\" />."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Include files for NSS"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"Initializing the NSS library is a complex task (<xref linkend=\"ex-"
"Defensive_Coding-TLS-NSS-Init\" />). It is not thread-safe. By default, the "
"library is in export mode, and all strong ciphers are disabled. Therefore, "
"after creating the <literal>NSSInitCContext</literal> object, we probe all "
"the strong ciphers we want to use, and check if at least one of them is "
"available. If not, we call <function>NSS_SetDomesticPolicy</function> to "
"switch to unrestricted policy mode. This function replaces the existing "
"global cipher suite policy, that is why we avoid calling it unless "
"absolutely necessary."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The simplest way to configured the trusted root certificates involves "
"loading the <filename>libnssckbi.so</filename> NSS module with a call to the"
" <function>SECMOD_LoadUserModule</function> function. The root certificates "
"are compiled into this module. (The PEM module for NSS, "
"<filename>libnsspem.so</filename>, offers a way to load trusted CA "
"certificates from a file.)"
msgstr ""

#. Tag: title
#, no-c-format
msgid "Initializing the NSS library"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"Some of the effects of the initialization can be reverted with the following"
" function calls:"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"After NSS has been initialized, the TLS connection can be created (<xref "
"linkend=\"ex-Defensive_Coding-TLS-Client-NSS-Connect\" />). The internal "
"<function>PR_ImportTCPSocket</function> function is used to turn the POSIX "
"file descriptor <literal>sockfd</literal> 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 "
"<emphasis>model</emphasis> descriptor, which is configured with the desired "
"set of protocols and ciphers. (The <literal>good_ciphers</literal> variable "
"is part of <xref linkend=\"ex-Defensive_Coding-TLS-NSS-Init\" />.) We cannot"
" resort to disabling ciphers not on a whitelist because by default, the AES "
"cipher suites are disabled. The model descriptor is not needed anymore after"
" TLS support has been activated for the existing connection descriptor."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The call to <function>SSL_BadCertHook</function> can be omitted if no "
"mechanism to override certificate verification is needed. The "
"<literal>bad_certificate</literal> function must check both the host name "
"specified for the connection and the certificate before granting the "
"override."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"Triggering the actual handshake requires three function calls, "
"<function>SSL_ResetHandshake</function>, <function>SSL_SetURL</function>, "
"and <function>SSL_ForceHandshake</function>. (If "
"<function>SSL_ResetHandshake</function> is omitted, "
"<function>SSL_ForceHandshake</function> will succeed, but the data will not "
"be encrypted.) During the handshake, the certificate is verified and matched"
" against the host name."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Creating a TLS connection with NSS"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"After the connection has been established, <xref linkend=\"ex-"
"Defensive_Coding-TLS-NSS-Use\" /> shows how to use the NSPR descriptor to "
"communicate with the server."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Using NSS for sending and receiving data"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"<xref linkend=\"ex-Defensive_Coding-TLS-Client-NSS-Close\" /> shows how to "
"close the connection."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Closing NSS client connections"
msgstr ""

#. Tag: title
#, no-c-format
msgid "Implementing TLS Clients With Python"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The Python distribution provides a TLS implementation in the "
"<literal>ssl</literal> 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 <xref linkend=\"sect-"
"Defensive_Coding-TLS-OpenSSL\" />."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"Currently, most Python function which accept <literal>https://</literal> "
"URLs or otherwise implement HTTPS support do not perform certificate "
"validation at all. (For example, this is true for the "
"<literal>httplib</literal> and <literal>xmlrpclib</literal> modules.) If you"
" use HTTPS, you should not use the built-in HTTP clients. The "
"<literal>Curl</literal> class in the <literal>curl</literal> module, as "
"provided by the <literal>python-pycurl</literal> package implements proper "
"certificate validation."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The <literal>ssl</literal> module currently does not perform host name "
"checking on the server certificate. <xref linkend=\"ex-Defensive_Coding-TLS-"
"Client-Python-check_host_name\" /> shows how to implement certificate "
"matching, using the parsed certificate returned by "
"<function>getpeercert</function>."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Implementing TLS host name checking Python (without wildcard support)"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"To turn a regular, connected TCP socket into a TLS-enabled socket, use the "
"<function>ssl.wrap_socket</function> function. The function call in <xref "
"linkend=\"ex-Defensive_Coding-TLS-Client-Python-Connect\" /> provides "
"additional arguments to override questionable defaults in OpenSSL and in the"
" Python module."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"<literal>ciphers=\"HIGH:-aNULL:-eNULL:-PSK:RC4-SHA:RC4-MD5\"</literal> "
"selects relatively strong cipher suites with certificate-based "
"authentication. (The call to <function>check_host_name</function> function "
"provides additional protection against anonymous cipher suites.)"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"<literal>ssl_version=ssl.PROTOCOL_TLSv1</literal> disables SSL 2.0 support. "
"By default, the <literal>ssl</literal> 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"<literal>cert_reqs=ssl.CERT_REQUIRED</literal> turns on certificate "
"validation."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"<literal>ca_certs='/etc/ssl/certs/ca-bundle.crt'</literal> 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 <literal>ssl</literal> "
"module."
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"The <literal>ssl</literal> module (and OpenSSL) perform certificate "
"validation, but the certificate must be compared manually against the host "
"name, by calling the <function>check_host_name</function> defined above."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Establishing a TLS client connection with Python"
msgstr ""

#. Tag: para
#, no-c-format
msgid ""
"After the connection has been established, the TLS socket can be used like a"
" regular socket:"
msgstr ""

#. Tag: para
#, no-c-format
msgid "Closing the TLS socket is straightforward as well:"
msgstr ""