# 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: None\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Language: en_US\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"

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

#. 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 "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."

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

#. 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 "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."

#. 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 "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."

#. 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 "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."

#. 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 "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."

#. 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 "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."

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

#. 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 "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)."

#. 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 "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)."

#. 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 "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."

#. 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 "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\" />)."

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

#. 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 "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:"

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

#. 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 "The value <literal>0</literal> indicates semantic failure (for example, a signature verification which was unsuccessful because the signing certificate was self-signed)."

#. 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 "The value <literal>-1</literal> indicates a low-level error in the system, such as failure to allocate memory using <function>malloc</function>."

#. 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 "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."

#. 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 "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)."

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

#. 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 "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."

#. 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 "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."

#. 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 "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."

#. 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 "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."

#. 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 "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>."

#. 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 "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."

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

#. 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 "<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."

#. 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 "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."

#. 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 "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."

#. 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 "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."

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

#. 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 "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."

#. 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 "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."

#. 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 "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>."

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

#. 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 "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."

#. 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 "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."

#. 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 "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."

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

#. 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 "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.)"

#. 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 "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."

#. 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 "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)."

#. 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 "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."

#. 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 "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.)"

#. 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 "The client must check that the configured or user-provided server name matches the peer certificate provided by the server."

#. 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 "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."

#. 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 "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."

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

#. 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 "In the following code, the error handling is only exploratory. Proper error handling is required for production use, especially in libraries."

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

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

#. 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 "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."

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

#. 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 "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)."

#. 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 "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."

#. 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 "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."

#. 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 "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."

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

#. 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 "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>."

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

#. 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 "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."

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

#. 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 "<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."

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

#. 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 "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."

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

#. 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 "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."

#. 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 "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\" />)."

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

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

#. 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 "During its lifetime, the credentials object can be used to initialize TLS session objects from multiple threads, provided that it is not changed."

#. 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 "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\" />."

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

#. 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 "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."

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

#. 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 "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."

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

#. 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 "In newer GNUTLS versions, certificate checking and host name validation can be combined using the <function>gnutls_certificate_verify_peers3</function> function."

#. 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 "An established TLS session can be used for sending and receiving data, as in <xref linkend=\"ex-Defensive_Coding-TLS-GNUTLS-Use\" />."

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

#. 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 "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\" />)."

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

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

#. 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 "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."

#. 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 "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\" />."

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

#. 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 "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."

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

#. 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 "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:"

#. 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 "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.)"

#. 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 "<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."

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

#. 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 "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)."

#. 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 "The TLS socket can be used as a regular socket, as shown in <xref linkend=\"ex-Defensive_Coding-TLS-Client-OpenJDK-Use\" />."

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

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

#. 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 "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."

#. 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 "In the trust manager shown in <xref linkend=\"ex-Defensive_Coding-TLS-Client-MyTrustManager\" />, the server certificate is identified by its SHA-256 hash."

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

#. 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 "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\" />."

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

#. 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 "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."

#. 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 "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."

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

#. 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 "The following code shows how to implement a simple TLS client using NSS. Note that the error handling needs replacing before production use."

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

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

#. 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 "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."

#. 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 "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.)"

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

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

#. 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 "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."

#. 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 "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."

#. 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 "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."

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

#. 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 "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."

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

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

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

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

#. 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 "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\" />."

#. 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 "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."

#. 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 "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>."

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

#. 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 "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."

#. 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 "<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.)"

#. 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 "<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."

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

#. 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 "<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."

#. 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 "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."

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

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

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