1. TLS/SSL and crypto library. Contribute to openssl/openssl development by creating an account on GitHub.
  2. Building on Server Side Session Cache in OpenSSL we need to deal with the Client side. The OpenSSL documentation for SSLCTXsetsessioncachemode has an option for client caching. However, it states that, “the application must select the session to be reused by using the SSLsetsession(3) function.”.

The ticket mechanism is a TLS extension. The client can advertise its support by sending an empty “Session Ticket” extension in the “Client Hello” message. The server will answer with an empty “Session Ticket” extension in its “Server Hello” message if it supports it.

I have encountered a problem with EAP-FAST PACs when switching our implementation of OpenSSL from a context that supports TLSv1.0 only to a context that supports negotiation to the highest available TLS version.

For EAP-FAST the PAC opaque is loaded into the SSL tlsext_session_ticket using the SSL_set_session_ticket_ext method during initialization of the SSL connection.

When the SSL context is set using TLSV1_client_method (TLS v1.0), thessl3_client_hello method is invoked for the client hello message which calls ssl_get_new_session if SSL session is NULL. The ssl3_client_hello method eventually calls ssl_add_clienthello_tlsext which will initialize the SSL session tlsext_tick structure as long as the SSL structure contains a session that is not NULL.

When theSSL context is set using SSLv23_client_method, thessl23_client_hello method is invoked for the client hello message which does not call ssl_get_new_session (the call is commented out) before the ssl_add_clienthello_tlsext is called. In this scenario the SSL session is NULL, so when ssl_add_clienthello_tlsext is called it does not initialize the SSL session tlsext_tick structure. This results in the EAP-FAST PAC not being loaded into the TLS session ticket extension when using the methods that support negotiation of the highest available SSL/TLS version.

In order for TLS session ticket extension to work with the SSLv23_client_method's it seems that the ssl23_client_hello method should add a new session object to the SSL connection when there is none, similar to what is done in the ssl3_client_hello method.

Ian McFadries

Module ngx_http_ssl_module

Example Configuration
Directives
ssl
ssl_buffer_size
ssl_certificate
ssl_certificate_key
ssl_ciphers
ssl_client_certificate
ssl_conf_command
ssl_crl
ssl_dhparam
ssl_early_data
ssl_ecdh_curve
ssl_ocsp
ssl_ocsp_cache
ssl_ocsp_responder
ssl_password_file
ssl_prefer_server_ciphers
ssl_protocols
ssl_reject_handshake
ssl_session_cache
ssl_session_ticket_key
ssl_session_tickets
ssl_session_timeout
ssl_stapling
ssl_stapling_file
ssl_stapling_responder
ssl_stapling_verify
ssl_trusted_certificate
ssl_verify_client
ssl_verify_depth
Error Processing
Embedded Variables

The ngx_http_ssl_module module provides thenecessary support for HTTPS.

This module is not built by default, it should be enabled with the--with-http_ssl_moduleconfiguration parameter.

This module requires theOpenSSL library.

Example Configuration

To reduce the processor load it is recommended to

  • set the number ofworker processesequal to the number of processors,
  • enablekeep-aliveconnections,
  • enable the shared session cache,
  • disable the built-in session cache,
  • and possibly increase the session lifetime(by default, 5 minutes):

Directives

Syntax: sslonoff;
Default:
Context: http, server

This directive was made obsolete in version 1.15.0.The ssl parameterof the listen directiveshould be used instead.

Syntax: ssl_buffer_sizesize;
Default:
Context: http, server

This directive appeared in version 1.5.9.

Sets the size of the buffer used for sending data.

By default, the buffer size is 16k, which corresponds to minimaloverhead when sending big responses.To minimize Time To First Byte it may be beneficial to use smaller values,for example:

Syntax: ssl_certificatefile;
Default:
Context: http, server

Specifies a file with the certificate in the PEM formatfor the given virtual server.If intermediate certificates should be specified in addition to a primarycertificate, they should be specified in the same file in the followingorder: the primary certificate comes first, then the intermediate certificates.A secret key in the PEM format may be placed in the same file.

Since version 1.11.0,this directive can be specified multiple timesto load certificates of different types, for example, RSA and ECDSA:

Only OpenSSL 1.0.2 or higher supports separatecertificate chainsfor different certificates.With older versions, only one certificate chain can be used.

Since version 1.15.9, variables can be used in the file namewhen using OpenSSL 1.0.2 or higher:

Note that using variables implies thata certificate will be loaded for each SSL handshake,and this may have a negative impact on performance.

The valuedata:$variablecan be specified instead of the file (1.15.10),which loads a certificate from a variablewithout using intermediate files.Note that inappropriate use of this syntax may have its security implications,such as writing secret key data toerror log.

It should be kept in mind that due to the HTTPS protocol limitationsfor maximum interoperability virtual servers should listen ondifferentIP addresses.

Syntax: ssl_certificate_keyfile;
Default:
Context: http, server

Specifies a file with the secret key in the PEM formatfor the given virtual server.

The valueengine:name:idcan be specified instead of the file (1.7.9),which loads a secret key with a specified idfrom the OpenSSL engine name.

The valuedata:$variablecan be specified instead of the file (1.15.10),which loads a secret key from a variable without using intermediate files.Note that inappropriate use of this syntax may have its security implications,such as writing secret key data toerror log.

Since version 1.15.9, variables can be used in the file namewhen using OpenSSL 1.0.2 or higher.

Syntax: ssl_ciphersciphers;
Default:
Context: http, server

Specifies the enabled ciphers.The ciphers are specified in the format understood by theOpenSSL library, for example:

The full list can be viewed using the“openssl ciphers” command.

The previous versions of nginx useddifferentciphers by default.
Syntax: ssl_client_certificatefile;
Default:
Context: http, server

Specifies a file with trusted CA certificates in the PEM formatused to verify client certificates andOCSP responses if ssl_stapling is enabled.

The list of certificates will be sent to clients.If this is not desired, the ssl_trusted_certificatedirective can be used.

Syntax: ssl_conf_commandcommand;
Default:
Context: http, server

This directive appeared in version 1.19.4.

Sets arbitrary OpenSSL configurationcommands.

The directive is supported when using OpenSSL 1.0.2 or higher.

Several ssl_conf_command directivescan be specified on the same level:

These directives are inherited from the previous configuration levelif and only if there are no ssl_conf_command directivesdefined on the current level.

Note that configuring OpenSSL directlymight result in unexpected behavior.
Syntax: ssl_crlfile;
Default:
Context: http, server

This directive appeared in version 0.8.7.

Specifies a file with revoked certificates (CRL)in the PEM format used to verifyclient certificates.

Syntax: ssl_dhparamfile;
Default:
Context: http, server

This directive appeared in version 0.7.2.

Specifies a file with DH parameters for DHE ciphers.

By default no parameters are set,and therefore DHE ciphers will not be used.

Prior to version 1.11.0, builtin parameters were used by default.
Syntax: ssl_early_dataonoff;
Default:
Context: http, server

This directive appeared in version 1.15.3.

Enables or disables TLS 1.3early data.

Requests sent within early data are subject toreplay attacks.To protect against such attacks at the application layer,the $ssl_early_data variableshould be used.
The directive is supported when using OpenSSL 1.1.1 or higher (1.15.4) andBoringSSL.
Syntax: ssl_ecdh_curvecurve;
Default:
Context: http, server

This directive appeared in versions 1.1.0 and 1.0.6.

Specifies a curve for ECDHE ciphers.

When using OpenSSL 1.0.2 or higher,it is possible to specify multiple curves (1.11.0), for example:

The special value auto (1.11.0) instructs nginx to usea list built into the OpenSSL library when using OpenSSL 1.0.2 or higher,or prime256v1 with older versions.

Prior to version 1.11.0,the prime256v1 curve was used by default.
When using OpenSSL 1.0.2 or higher,this directive sets the list of curves supported by the server.Thus, in order for ECDSA certificates to work,it is important to include the curves used in the certificates.
Syntax: ssl_ocsponoffleaf;
Default:
Context: http, server

This directive appeared in version 1.19.0.

Enables OCSP validation of the client certificate chain.The leaf parameterenables validation of the client certificate only.

For the OCSP validation to work,the ssl_verify_client directive should be set toon or optional.

To resolve the OCSP responder hostname,the resolver directiveshould also be specified.

Ticket

Example:

Syntax: ssl_ocsp_cacheoff [shared:name:size];
Default:
Context: http, server

This directive appeared in version 1.19.0.

Sets name and size of the cachethat stores client certificates status for OCSP validation.The cache is shared between all worker processes.A cache with the same name can be used in several virtual servers.

The off parameter prohibits the use of the cache.

Syntax: ssl_ocsp_responderurl;
Default:
Context: http, server

This directive appeared in version 1.19.0.

Overrides the URL of the OCSP responder specified in the“AuthorityInformation Access” certificate extensionfor validation of client certificates.

Only “http://” OCSP responders are supported:

Syntax: ssl_password_filefile;
Default:
Context: http, server

This directive appeared in version 1.7.3.

Specifies a file with passphrases forsecret keyswhere each passphrase is specified on a separate line.Passphrases are tried in turn when loading the key.

Example:

Syntax: ssl_prefer_server_ciphersonoff;
Default:
Context: http, server

Specifies that server ciphers should be preferred over clientciphers when using the SSLv3 and TLS protocols.

Syntax: ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default:
Context: http, server

Enables the specified protocols.

The TLSv1.1 and TLSv1.2 parameters(1.1.13, 1.0.12) work only when OpenSSL 1.0.1 or higher is used.
The TLSv1.3 parameter (1.13.0) works only whenOpenSSL 1.1.1 built with TLSv1.3 support is used.

Openssl Session Ticket Maker

Session
Syntax: ssl_reject_handshakeonoff;
Default:
Context: http, server

This directive appeared in version 1.19.4.

Ticket

If enabled, SSL handshakes inthe server block will be rejected.

For example, in the following configuration, SSL handshakes withserver names other than example.com are rejected:

Syntax: ssl_session_cacheoffnone [builtin[:size]] [shared:name:size];
Default:
Context: http, server

Sets the types and sizes of caches that store session parameters.A cache can be of any of the following types:

off
the use of a session cache is strictly prohibited:nginx explicitly tells a client that sessions may not be reused.
none
the use of a session cache is gently disallowed:nginx tells a client that sessions may be reused, but does notactually store session parameters in the cache.
builtin
a cache built in OpenSSL; used by one worker process only.The cache size is specified in sessions.If size is not given, it is equal to 20480 sessions.Use of the built-in cache can cause memory fragmentation.
shared
a cache shared between all worker processes.The cache size is specified in bytes; one megabyte can storeabout 4000 sessions.Each shared cache should have an arbitrary name.A cache with the same name can be used in several virtual servers.

Both cache types can be used simultaneously, for example:

but using only shared cache without the built-in cache shouldbe more efficient.

Syntax: ssl_session_ticket_keyfile;
Default:
Context: http, server

This directive appeared in version 1.5.7.

Sets a file with the secret key used to encryptand decrypt TLS session tickets.The directive is necessary if the same key has to be shared betweenmultiple servers.By default, a randomly generated key is used.

If several keys are specified, only the first key isused to encrypt TLS session tickets.This allows configuring key rotation, for example:

The file must contain 80 or 48 bytesof random data and can be created using the following command:

Depending on the file size either AES256 (for 80-byte keys, 1.11.8)or AES128 (for 48-byte keys) is used for encryption.

Syntax: ssl_session_ticketsonoff;
Default:
Context: http, server

This directive appeared in version 1.5.9.

Enables or disables session resumption throughTLS session tickets.

Syntax: ssl_session_timeouttime;
Default:
Context: http, server

Specifies a time during which a client may reuse thesession parameters.

Syntax: ssl_staplingonoff;
Default:
Context: http, server

This directive appeared in version 1.3.7.

Enables or disablesstaplingof OCSP responses by the server.Example:

For the OCSP stapling to work, the certificate of the server certificateissuer should be known.If the ssl_certificate file doesnot contain intermediate certificates,the certificate of the server certificate issuer should bepresent in thessl_trusted_certificate file.

For a resolution of the OCSP responder hostname,the resolver directiveshould also be specified.

Syntax: ssl_stapling_filefile;
Default:
Context: http, server

This directive appeared in version 1.3.7.

When set, the stapled OCSP response will be taken from thespecified file instead of queryingthe OCSP responder specified in the server certificate.

The file should be in the DER format as produced by the“openssl ocsp” command.

Syntax: ssl_stapling_responderurl;
Default:
Context: http, server

This directive appeared in version 1.3.7.

Overrides the URL of the OCSP responder specified in the“AuthorityInformation Access” certificate extension.

Openssl Session Ticket

Only “http://” OCSP responders are supported:

Syntax: ssl_stapling_verifyonoff;
Default:
Context: http, server

This directive appeared in version 1.3.7.

Enables or disables verification of OCSP responses by the server.

For verification to work, the certificate of the server certificateissuer, the root certificate, and all intermediate certificatesshould be configured as trusted using thessl_trusted_certificate directive.

Syntax: ssl_trusted_certificatefile;
Default:
Context: http, server

This directive appeared in version 1.3.7.

Specifies a file with trusted CA certificates in the PEM formatused to verify client certificates andOCSP responses if ssl_stapling is enabled.

In contrast to the certificate set by ssl_client_certificate,the list of these certificates will not be sent to clients.

Syntax: ssl_verify_clientonoffoptionaloptional_no_ca;
Default:
Context: http, server

Enables verification of client certificates.The verification result is stored in the$ssl_client_verify variable.

Openssl Session Ticketmaster

The optional parameter (0.8.7+) requests the clientcertificate and verifies it if the certificate is present.

The optional_no_ca parameter (1.3.8, 1.2.5)requests the clientcertificate but does not require it to be signed by a trusted CA certificate.This is intended for the use in cases when a service that is external to nginxperforms the actual certificate verification.The contents of the certificate is accessible through the$ssl_client_cert variable.

Syntax: ssl_verify_depthnumber;
Default:
Context: http, server

Sets the verification depth in the client certificates chain.

Error Processing

The ngx_http_ssl_module module supports severalnon-standard error codes that can be used for redirects using theerror_page directive:

495
an error has occurred during the client certificate verification;
496
a client has not presented the required certificate;
497
a regular request has been sent to the HTTPS port.

The redirection happens after the request is fully parsed andthe variables, such as $request_uri,$uri, $args and others, are available.

Embedded Variables

The ngx_http_ssl_module module supportsembedded variables:

$ssl_cipher
returns the name of the cipher usedfor an established SSL connection;
$ssl_ciphers
returns the list of ciphers supported by the client (1.11.7).Known ciphers are listed by names, unknown are shown in hexadecimal,for example:
The variable is fully supported only when using OpenSSL version 1.0.2 or higher.With older versions, the variable is availableonly for new sessions and lists only known ciphers.
$ssl_client_escaped_cert
returns the client certificate in the PEM format (urlencoded)for an established SSL connection (1.13.5);
$ssl_client_cert
returns the client certificate in the PEM formatfor an established SSL connection, with each line except the firstprepended with the tab character;this is intended for the use in theproxy_set_header directive;
The variable is deprecated,the $ssl_client_escaped_cert variable should be used instead.
$ssl_client_fingerprint
returns the SHA1 fingerprint of the client certificatefor an established SSL connection (1.7.1);
$ssl_client_i_dn
returns the “issuer DN” string of the client certificatefor an established SSL connection according toRFC 2253 (1.11.6);
$ssl_client_i_dn_legacy
returns the “issuer DN” string of the client certificatefor an established SSL connection;
Prior to version 1.11.6, the variable name was $ssl_client_i_dn.
$ssl_client_raw_cert
returns the client certificate in the PEM formatfor an established SSL connection;
$ssl_client_s_dn
returns the “subject DN” string of the client certificatefor an established SSL connection according toRFC 2253 (1.11.6);
$ssl_client_s_dn_legacy
returns the “subject DN” string of the client certificatefor an established SSL connection;
Prior to version 1.11.6, the variable name was $ssl_client_s_dn.
$ssl_client_serial
returns the serial number of the client certificatefor an established SSL connection;
$ssl_client_v_end
returns the end date of the client certificate (1.11.7);
$ssl_client_v_remain
returns the number of daysuntil the client certificate expires (1.11.7);
$ssl_client_v_start
returns the start date of the client certificate (1.11.7);
$ssl_client_verify
returns the result of client certificate verification:“SUCCESS”, “FAILED:reason”,and “NONE” if a certificate was not present;
Prior to version 1.11.7, the “FAILED” resultdid not contain the reason string.
$ssl_curves
returns the list of curves supported by the client (1.11.7).Known curves are listed by names, unknown are shown in hexadecimal,for example:
The variable is supported only when using OpenSSL version 1.0.2 or higher.With older versions, the variable value will be an empty string.
The variable is available only for new sessions.
$ssl_early_data
returns “1” ifTLS 1.3 early data is usedand the handshake is not complete, otherwise “” (1.15.3).
$ssl_protocol
returns the protocol of an established SSL connection;
$ssl_server_name
returns the server name requested throughSNI(1.7.0);
$ssl_session_id
returns the session identifier of an established SSL connection;
$ssl_session_reused
returns “r” if an SSL session was reused,or “.” otherwise (1.5.11).
Coments are closed

Most Viewed Posts

  • My Tableau Repository
  • Marbas Sigil
  • Microsoft Teams Kamera
  • Amazon Prime Direct
  • Engine_pkcs11

Scroll to top