=encoding utf-8

=head1 NAME

ngx_stream_ssl_module - Module ngx_stream_ssl_module




=head1



The C<ngx_stream_ssl_module> module (1.9.0)
provides the necessary support for a stream proxy server to work with
the SSLE<sol>TLS protocol.
This module is not built by default, it should be enabled with the
C<--with-stream_ssl_module>
configuration parameter.




=head1 Example Configuration



To reduce the processor load, it is recommended to

=over




=item *

set the number of worker processes equal to the number of processors,



=item *

enable the shared session cache,



=item *

disable the built-in session cache,



=item *

and possibly increase the session lifetime (by default, 5 minutes):



=back




    
    <emphasis>worker_processes auto;</emphasis>
    
    stream {
    
        ...
    
        server {
            listen              12345 ssl;
    
            ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
            ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
            ssl_certificate     /usr/local/nginx/conf/cert.pem;
            ssl_certificate_key /usr/local/nginx/conf/cert.key;
            <emphasis>ssl_session_cache   shared:SSL:10m;</emphasis>
            <emphasis>ssl_session_timeout 10m;</emphasis>
    
            ...
        }






=head1 Directives

=head2 ssl_certificate


B<syntax:> ssl_certificate I<I<C<file>>>



B<context:> I<stream>


B<context:> I<server>





Specifies a I<C<file>> with the certificate in the PEM format
for the given server.
If intermediate certificates should be specified in addition to a primary
certificate, they should be specified in the same file in the following
order: 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 times
to load certificates of different types, for example, RSA and ECDSA:

    
    server {
        listen              12345 ssl;
    
        ssl_certificate     example.com.rsa.crt;
        ssl_certificate_key example.com.rsa.key;
    
        ssl_certificate     example.com.ecdsa.crt;
        ssl_certificate_key example.com.ecdsa.key;
    
        ...
    }



B<NOTE>

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








=head2 ssl_certificate_key


B<syntax:> ssl_certificate_key I<I<C<file>>>



B<context:> I<stream>


B<context:> I<server>





Specifies a I<C<file>> with the secret key in the PEM format
for the given server.





The value
C<engine>:I<C<name>>:I<C<id>>
can be specified instead of the I<C<file>>,
which loads a secret key with a specified I<C<id>>
from the OpenSSL engine I<C<name>>.







=head2 ssl_ciphers


B<syntax:> ssl_ciphers I<I<C<ciphers>>>


B<default:> I<HIGH:!aNULL:!MD5>


B<context:> I<stream>


B<context:> I<server>





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

    
    ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;







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







=head2 ssl_dhparam


B<syntax:> ssl_dhparam I<I<C<file>>>



B<context:> I<stream>


B<context:> I<server>





Specifies a I<C<file>> with DH parameters for DHE ciphers.







=head2 ssl_ecdh_curve


B<syntax:> ssl_ecdh_curve I<I<C<curve>>>


B<default:> I<auto>


B<context:> I<stream>


B<context:> I<server>





Specifies a I<C<curve>> for ECDHE ciphers.





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

    
    ssl_ecdh_curve prime256v1:secp384r1;







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






B<NOTE>

Prior to version 1.11.0,
the C<prime256v1> curve was used by default.








=head2 ssl_handshake_timeout


B<syntax:> ssl_handshake_timeout I<I<C<time>>>


B<default:> I<60s>


B<context:> I<stream>


B<context:> I<server>





Specifies a timeout for the SSL handshake to complete.







=head2 ssl_password_file


B<syntax:> ssl_password_file I<I<C<file>>>



B<context:> I<stream>


B<context:> I<server>





Specifies a I<C<file>> with passphrases for
secret keys
where each passphrase is specified on a separate line.
Passphrases are tried in turn when loading the key.





Example:

    
    stream {
        ssl_password_file /etc/keys/global.pass;
        ...
    
        server {
            listen 127.0.0.1:12345;
            ssl_certificate_key /etc/keys/first.key;
        }
    
        server {
            listen 127.0.0.1:12346;
    
            # named pipe can also be used instead of a file
            ssl_password_file /etc/keys/fifo;
            ssl_certificate_key /etc/keys/second.key;
        }
    }









=head2 ssl_prefer_server_ciphers


B<syntax:> ssl_prefer_server_ciphers I<C<on> E<verbar> C<off>>


B<default:> I<off>


B<context:> I<stream>


B<context:> I<server>





Specifies that server ciphers should be preferred over client ciphers
when the SSLv3 and TLS protocols are used.







=head2 ssl_protocols


B<syntax:> ssl_protocols I<
    [C<SSLv2>]
    [C<SSLv3>]
    [C<TLSv1>]
    [C<TLSv1.1>]
    [C<TLSv1.2>]>


B<default:> I<TLSv1 TLSv1.1 TLSv1.2>


B<context:> I<stream>


B<context:> I<server>





Enables the specified protocols.
The C<TLSv1.1> and C<TLSv1.2> parameters work
only when the OpenSSL library of version 1.0.1 or higher is used.







=head2 ssl_session_cache


B<syntax:> ssl_session_cache I<
    C<off> E<verbar>
    C<none> E<verbar>
    [C<builtin>[:I<C<size>>]]
    [C<shared>:I<C<name>>:I<C<size>>]>


B<default:> I<none>


B<context:> I<stream>


B<context:> I<server>





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

=over



=item C<off>




the use of a session cache is strictly prohibited:
nginx explicitly tells a client that sessions may not be reused.



=item C<none>




the use of a session cache is gently disallowed:
nginx tells a client that sessions may be reused, but does not
actually store session parameters in the cache.



=item C<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.



=item C<shared>




a cache shared between all worker processes.
The cache size is specified in bytes; one megabyte can store
about 4000 sessions.
Each shared cache should have an arbitrary name.
A cache with the same name can be used in several
servers.




=back







Both cache types can be used simultaneously, for example:

    
    ssl_session_cache builtin:1000 shared:SSL:10m;


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







=head2 ssl_session_ticket_key


B<syntax:> ssl_session_ticket_key I<I<C<file>>>



B<context:> I<stream>


B<context:> I<server>





Sets a I<C<file>> with the secret key used to encrypt
and decrypt TLS session tickets.
The directive is necessary if the same key has to be shared between
multiple servers.
By default, a randomly generated key is used.





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

    
    ssl_session_ticket_key current.key;
    ssl_session_ticket_key previous.key;







The I<C<file>> must contain 48 bytes of random data and can
be created using the following command:

    
    openssl rand 48 > ticket.key









=head2 ssl_session_tickets


B<syntax:> ssl_session_tickets I<C<on> E<verbar> C<off>>


B<default:> I<on>


B<context:> I<stream>


B<context:> I<server>





Enables or disables session resumption through
L<TLS session tickets|http://tools.ietf.org/html/rfc5077>.







=head2 ssl_session_timeout


B<syntax:> ssl_session_timeout I<I<C<time>>>


B<default:> I<5m>


B<context:> I<stream>


B<context:> I<server>





Specifies a time during which a client may reuse the
session parameters stored in a cache.







=head1 Embedded Variables



The C<ngx_http_ssl_module> module supports variables
since 1.11.2.

=over



=item C<$ssl_cipher>




returns the string of ciphers used
for an established SSL connection;



=item C<$ssl_protocol>




returns the protocol of an established SSL connection;



=item C<$ssl_server_name>




returns the server name requested through
L<SNI|http://en.wikipedia.org/wiki/Server_Name_Indication>;



=item C<$ssl_session_id>




returns the session identifier of an established SSL connection;



=item C<$ssl_session_reused>




returns “C<r>” if an SSL session was reused,
or “C<.>” otherwise.




=back