diff options
Diffstat (limited to 'docs/en/ranch/1.2/manual/ranch_ssl/index.html')
| -rw-r--r-- | docs/en/ranch/1.2/manual/ranch_ssl/index.html | 479 |
1 files changed, 145 insertions, 334 deletions
diff --git a/docs/en/ranch/1.2/manual/ranch_ssl/index.html b/docs/en/ranch/1.2/manual/ranch_ssl/index.html index f310db81..7ea56fa3 100644 --- a/docs/en/ranch/1.2/manual/ranch_ssl/index.html +++ b/docs/en/ranch/1.2/manual/ranch_ssl/index.html @@ -62,349 +62,158 @@ <h1 class="lined-header"><span>ranch_ssl(3)</span></h1> -<div class="sect1"> <h2 id="_name">Name</h2> -<div class="sectionbody"> -<div class="paragraph"><p>ranch_ssl - SSL transport module</p></div> -</div> -</div> -<div class="sect1"> +<p>ranch_ssl - SSL transport module</p> <h2 id="_description">Description</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The <code>ranch_ssl</code> module implements an SSL Ranch transport.</p></div> -</div> -</div> -<div class="sect1"> +<p>The <code>ranch_ssl</code> module implements an SSL Ranch transport.</p> <h2 id="_types">Types</h2> -<div class="sectionbody"> -<div class="sect2"> <h3 id="_ssl_opt">ssl_opt()</h3> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">alpn_preferred_protocols</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]} - | {<span style="color: #FF6600">cacertfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} - | {<span style="color: #FF6600">cacerts</span>, [<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]} - | {<span style="color: #FF6600">cert</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} - | {<span style="color: #FF6600">certfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} - | {<span style="color: #FF6600">ciphers</span>, [<span style="font-weight: bold"><span style="color: #000000">ssl:erl_cipher_suite</span></span>()] | <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} - | {<span style="color: #FF6600">client_renegotiation</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">crl_cache</span>, {<span style="font-weight: bold"><span style="color: #000000">module</span></span>(), {<span style="color: #FF6600">internal</span> | <span style="font-weight: bold"><span style="color: #000000">any</span></span>(), <span style="font-weight: bold"><span style="color: #000080">list</span></span>()}}} - | {<span style="color: #FF6600">crl_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() | <span style="color: #FF6600">peer</span> | <span style="color: #FF6600">best_effort</span>} - | {<span style="color: #FF6600">depth</span>, <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">255</span>} - | {<span style="color: #FF6600">dh</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} - | {<span style="color: #FF6600">dhfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} - | {<span style="color: #FF6600">fail_if_no_peer_cert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">hibernate_after</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>() | <span style="color: #000080">undefined</span>} - | {<span style="color: #FF6600">honor_cipher_order</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">key</span>, {<span style="color: #FF6600">'RSAPrivateKey'</span> | <span style="color: #FF6600">'DSAPrivateKey'</span> | <span style="color: #FF6600">'PrivateKeyInfo'</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}} - | {<span style="color: #FF6600">keyfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} - | {<span style="color: #FF6600">log_alert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">next_protocols_advertised</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]} - | {<span style="color: #FF6600">partial_chain</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(([<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]) <span style="color: #990000">-></span> {<span style="color: #FF6600">trusted_ca</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} | <span style="color: #FF6600">unknown_ca</span>)} - | {<span style="color: #FF6600">password</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} - | {<span style="color: #FF6600">psk_identity</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} - | {<span style="color: #FF6600">reuse_session</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()} - | {<span style="color: #FF6600">reuse_sessions</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">secure_renegotiate</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} - | {<span style="color: #FF6600">sni_fun</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()} - | {<span style="color: #FF6600">sni_hosts</span>, [{<span style="font-weight: bold"><span style="color: #000000">string</span></span>(), <span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>()}]} - | {<span style="color: #FF6600">user_lookup_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}} - | {<span style="color: #FF6600">verify</span>, <span style="font-weight: bold"><span style="color: #000000">ssl:verify_type</span></span>()} - | {<span style="color: #FF6600">verify_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}} - | {<span style="color: #FF6600">versions</span>, [<span style="font-weight: bold"><span style="color: #000080">atom</span></span>()]}<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>SSL-specific listen options.</p></div> -</div> -<div class="sect2"> -<h3 id="_opt_ranch_tcp_opt_ssl_opt">opt() = ranch_tcp:opt() | ssl_opt()</h3> -<div class="paragraph"><p>Listen options.</p></div> -</div> -<div class="sect2"> -<h3 id="_opts_opt">opts() = [opt()]</h3> -<div class="paragraph"><p>List of listen options.</p></div> -</div> -</div> -</div> -<div class="sect1"> +<pre><tt><b><font color="#000000">ssl_opt</font></b>() <font color="#990000">=</font> {<font color="#FF6600">alpn_preferred_protocols</font>, [<b><font color="#000080">binary</font></b>()]} + | {<font color="#FF6600">cacertfile</font>, <b><font color="#000000">string</font></b>()} + | {<font color="#FF6600">cacerts</font>, [<b><font color="#000000">public_key:der_encoded</font></b>()]} + | {<font color="#FF6600">cert</font>, <b><font color="#000000">public_key:der_encoded</font></b>()} + | {<font color="#FF6600">certfile</font>, <b><font color="#000000">string</font></b>()} + | {<font color="#FF6600">ciphers</font>, [<b><font color="#000000">ssl:erl_cipher_suite</font></b>()] | <b><font color="#000000">string</font></b>()} + | {<font color="#FF6600">client_renegotiation</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">crl_cache</font>, {<b><font color="#000000">module</font></b>(), {<font color="#FF6600">internal</font> | <b><font color="#000000">any</font></b>(), <b><font color="#000080">list</font></b>()}}} + | {<font color="#FF6600">crl_check</font>, <b><font color="#000000">boolean</font></b>() | <font color="#FF6600">peer</font> | <font color="#FF6600">best_effort</font>} + | {<font color="#FF6600">depth</font>, <font color="#993399">0</font><font color="#990000">..</font><font color="#993399">255</font>} + | {<font color="#FF6600">dh</font>, <b><font color="#000000">public_key:der_encoded</font></b>()} + | {<font color="#FF6600">dhfile</font>, <b><font color="#000000">string</font></b>()} + | {<font color="#FF6600">fail_if_no_peer_cert</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">hibernate_after</font>, <b><font color="#000080">integer</font></b>() | <font color="#000080">undefined</font>} + | {<font color="#FF6600">honor_cipher_order</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">key</font>, {<font color="#FF6600">'RSAPrivateKey'</font> | <font color="#FF6600">'DSAPrivateKey'</font> | <font color="#FF6600">'PrivateKeyInfo'</font>, <b><font color="#000000">public_key:der_encoded</font></b>()}} + | {<font color="#FF6600">keyfile</font>, <b><font color="#000000">string</font></b>()} + | {<font color="#FF6600">log_alert</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">next_protocols_advertised</font>, [<b><font color="#000080">binary</font></b>()]} + | {<font color="#FF6600">partial_chain</font>, <b><font color="#0000FF">fun</font></b>(([<b><font color="#000000">public_key:der_encoded</font></b>()]) <font color="#990000">-></font> {<font color="#FF6600">trusted_ca</font>, <b><font color="#000000">public_key:der_encoded</font></b>()} | <font color="#FF6600">unknown_ca</font>)} + | {<font color="#FF6600">password</font>, <b><font color="#000000">string</font></b>()} + | {<font color="#FF6600">psk_identity</font>, <b><font color="#000000">string</font></b>()} + | {<font color="#FF6600">reuse_session</font>, <b><font color="#0000FF">fun</font></b>()} + | {<font color="#FF6600">reuse_sessions</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">secure_renegotiate</font>, <b><font color="#000000">boolean</font></b>()} + | {<font color="#FF6600">sni_fun</font>, <b><font color="#0000FF">fun</font></b>()} + | {<font color="#FF6600">sni_hosts</font>, [{<b><font color="#000000">string</font></b>(), <b><font color="#000000">ssl_opt</font></b>()}]} + | {<font color="#FF6600">user_lookup_fun</font>, {<b><font color="#0000FF">fun</font></b>(), <b><font color="#000000">any</font></b>()}} + | {<font color="#FF6600">verify</font>, <b><font color="#000000">ssl:verify_type</font></b>()} + | {<font color="#FF6600">verify_fun</font>, {<b><font color="#0000FF">fun</font></b>(), <b><font color="#000000">any</font></b>()}} + | {<font color="#FF6600">versions</font>, [<b><font color="#000080">atom</font></b>()]}<font color="#990000">.</font></tt></pre> +</div></div> +<p>SSL-specific listen options.</p> +<h3 id="_opt_____ranch_tcp_opt_____ssl_opt">opt() = ranch_tcp:opt() | ssl_opt()</h3> +<p>Listen options.</p> +<h3 id="_opts______opt">opts() = [opt()]</h3> +<p>List of listen options.</p> <h2 id="_option_descriptions">Option descriptions</h2> -<div class="sectionbody"> -<div class="paragraph"><p>Specifying a certificate is mandatory, either through the <code>cert</code> -or the <code>certfile</code> option. None of the other options are required.</p></div> -<div class="paragraph"><p>The default value is given next to the option name.</p></div> -<div class="dlist"><dl> -<dt class="hdlist1"> -alpn_preferred_protocols -</dt> -<dd> -<p> - Perform Application-Layer Protocol Negotiation with the given list of preferred protocols. -</p> -</dd> -<dt class="hdlist1"> -cacertfile -</dt> -<dd> -<p> - Path to PEM encoded trusted certificates file used to verify peer certificates. -</p> -</dd> -<dt class="hdlist1"> -cacerts -</dt> -<dd> -<p> - List of DER encoded trusted certificates. -</p> -</dd> -<dt class="hdlist1"> -cert -</dt> -<dd> -<p> - DER encoded user certificate. -</p> -</dd> -<dt class="hdlist1"> -certfile -</dt> -<dd> -<p> - Path to the PEM encoded user certificate file. May also contain the private key. -</p> -</dd> -<dt class="hdlist1"> -ciphers -</dt> -<dd> -<p> - List of ciphers that clients are allowed to use. -</p> -</dd> -<dt class="hdlist1"> -client_renegotiation (true) -</dt> -<dd> -<p> - Whether to allow client-initiated renegotiation. -</p> -</dd> -<dt class="hdlist1"> -crl_cache ({ssl_crl_cache, {internal, []}}) -</dt> -<dd> -<p> - Customize the module used to cache Certificate Revocation Lists. -</p> -</dd> -<dt class="hdlist1"> -crl_check (false) -</dt> -<dd> -<p> - Whether to perform CRL check on all certificates in the chain during validation. -</p> -</dd> -<dt class="hdlist1"> -depth (1) -</dt> -<dd> -<p> - Maximum of intermediate certificates allowed in the certification path. -</p> -</dd> -<dt class="hdlist1"> -dh -</dt> -<dd> -<p> - DER encoded Diffie-Hellman parameters. -</p> -</dd> -<dt class="hdlist1"> -dhfile -</dt> -<dd> -<p> - Path to the PEM encoded Diffie-Hellman parameters file. -</p> -</dd> -<dt class="hdlist1"> -fail_if_no_peer_cert (false) -</dt> -<dd> -<p> - Whether to refuse the connection if the client sends an empty certificate. -</p> -</dd> -<dt class="hdlist1"> -hibernate_after (undefined) -</dt> -<dd> -<p> - Time in ms after which SSL socket processes go into hibernation to reduce memory usage. -</p> -</dd> -<dt class="hdlist1"> -honor_cipher_order (false) -</dt> -<dd> -<p> - If true, use the server’s preference for cipher selection. If false, use the client’s preference. -</p> -</dd> -<dt class="hdlist1"> -key -</dt> -<dd> -<p> - DER encoded user private key. -</p> -</dd> -<dt class="hdlist1"> -keyfile -</dt> -<dd> -<p> - Path to the PEM encoded private key file, if different than the certfile. -</p> -</dd> -<dt class="hdlist1"> -log_alert (true) -</dt> -<dd> -<p> - If false, error reports will not be displayed. -</p> -</dd> -<dt class="hdlist1"> -next_protocols_advertised -</dt> -<dd> -<p> - List of protocols to send to the client if it supports the Next Protocol extension. -</p> -</dd> -<dt class="hdlist1"> -nodelay (true) -</dt> -<dd> -<p> - Whether to enable TCP_NODELAY. -</p> -</dd> -<dt class="hdlist1"> -partial_chain -</dt> -<dd> -<p> - Claim an intermediate CA in the chain as trusted. -</p> -</dd> -<dt class="hdlist1"> -password -</dt> -<dd> -<p> - Password to the private key file, if password protected. -</p> -</dd> -<dt class="hdlist1"> -psk_identity -</dt> -<dd> -<p> - Provide the given PSK identity hint to the client during the handshake. -</p> -</dd> -<dt class="hdlist1"> -reuse_session -</dt> -<dd> -<p> - Custom policy to decide whether a session should be reused. -</p> -</dd> -<dt class="hdlist1"> -reuse_sessions (false) -</dt> -<dd> -<p> - Whether to allow session reuse. -</p> -</dd> -<dt class="hdlist1"> -secure_renegotiate (false) -</dt> -<dd> -<p> - Whether to reject renegotiation attempts that do not conform to RFC5746. -</p> -</dd> -<dt class="hdlist1"> -sni_fun -</dt> -<dd> -<p> - Function called when the client requests a host using Server Name Indication. Returns options to apply. -</p> -</dd> -<dt class="hdlist1"> -sni_hosts -</dt> -<dd> -<p> - Options to apply for the host that matches what the client requested with Server Name Indication. -</p> -</dd> -<dt class="hdlist1"> -user_lookup_fun -</dt> -<dd> -<p> - Function called to determine the shared secret when using PSK, or provide parameters when using SRP. -</p> -</dd> -<dt class="hdlist1"> -verify (verify_none) -</dt> -<dd> -<p> - Use <code>verify_peer</code> to request a certificate from the client. -</p> -</dd> -<dt class="hdlist1"> -verify_fun -</dt> -<dd> -<p> - Custom policy to decide whether a client certificate is valid. -</p> -</dd> -<dt class="hdlist1"> -versions -</dt> -<dd> -<p> - TLS protocol versions that will be supported. -</p> -</dd> -</dl></div> -<div class="paragraph"><p>Note that the client will not send a certificate unless the -value for the <code>verify</code> option is set to <code>verify_peer</code>. This -means that the <code>fail_if_no_peer_cert</code> only apply when combined -with the <code>verify</code> option. The <code>verify_fun</code> option allows -greater control over the client certificate validation.</p></div> -<div class="paragraph"><p>The options <code>sni_fun</code> and <code>sni_hosts</code> are mutually exclusive.</p></div> -</div> -</div> -<div class="sect1"> +<p>Specifying a certificate is mandatory, either through the <code>cert</code> or the <code>certfile</code> option. None of the other options are required.</p> +<p>The default value is given next to the option name.</p> +<dl><dt>alpn_preferred_protocols</dt> +<dd><p>Perform Application-Layer Protocol Negotiation with the given list of preferred protocols.</p> +</dd> +<dt>cacertfile</dt> +<dd><p>Path to PEM encoded trusted certificates file used to verify peer certificates.</p> +</dd> +<dt>cacerts</dt> +<dd><p>List of DER encoded trusted certificates.</p> +</dd> +<dt>cert</dt> +<dd><p>DER encoded user certificate.</p> +</dd> +<dt>certfile</dt> +<dd><p>Path to the PEM encoded user certificate file. May also contain the private key.</p> +</dd> +<dt>ciphers</dt> +<dd><p>List of ciphers that clients are allowed to use.</p> +</dd> +<dt>client_renegotiation (true)</dt> +<dd><p>Whether to allow client-initiated renegotiation.</p> +</dd> +<dt>crl_cache ({ssl_crl_cache, {internal, []}})</dt> +<dd><p>Customize the module used to cache Certificate Revocation Lists.</p> +</dd> +<dt>crl_check (false)</dt> +<dd><p>Whether to perform CRL check on all certificates in the chain during validation.</p> +</dd> +<dt>depth (1)</dt> +<dd><p>Maximum of intermediate certificates allowed in the certification path.</p> +</dd> +<dt>dh</dt> +<dd><p>DER encoded Diffie-Hellman parameters.</p> +</dd> +<dt>dhfile</dt> +<dd><p>Path to the PEM encoded Diffie-Hellman parameters file.</p> +</dd> +<dt>fail_if_no_peer_cert (false)</dt> +<dd><p>Whether to refuse the connection if the client sends an empty certificate.</p> +</dd> +<dt>hibernate_after (undefined)</dt> +<dd><p>Time in ms after which SSL socket processes go into hibernation to reduce memory usage.</p> +</dd> +<dt>honor_cipher_order (false)</dt> +<dd><p>If true, use the server's preference for cipher selection. If false, use the client's preference.</p> +</dd> +<dt>key</dt> +<dd><p>DER encoded user private key.</p> +</dd> +<dt>keyfile</dt> +<dd><p>Path to the PEM encoded private key file, if different than the certfile.</p> +</dd> +<dt>log_alert (true)</dt> +<dd><p>If false, error reports will not be displayed.</p> +</dd> +<dt>next_protocols_advertised</dt> +<dd><p>List of protocols to send to the client if it supports the Next Protocol extension.</p> +</dd> +<dt>nodelay (true)</dt> +<dd><p>Whether to enable TCP_NODELAY.</p> +</dd> +<dt>partial_chain</dt> +<dd><p>Claim an intermediate CA in the chain as trusted.</p> +</dd> +<dt>password</dt> +<dd><p>Password to the private key file, if password protected.</p> +</dd> +<dt>psk_identity</dt> +<dd><p>Provide the given PSK identity hint to the client during the handshake.</p> +</dd> +<dt>reuse_session</dt> +<dd><p>Custom policy to decide whether a session should be reused.</p> +</dd> +<dt>reuse_sessions (false)</dt> +<dd><p>Whether to allow session reuse.</p> +</dd> +<dt>secure_renegotiate (false)</dt> +<dd><p>Whether to reject renegotiation attempts that do not conform to RFC5746.</p> +</dd> +<dt>sni_fun</dt> +<dd><p>Function called when the client requests a host using Server Name Indication. Returns options to apply.</p> +</dd> +<dt>sni_hosts</dt> +<dd><p>Options to apply for the host that matches what the client requested with Server Name Indication.</p> +</dd> +<dt>user_lookup_fun</dt> +<dd><p>Function called to determine the shared secret when using PSK, or provide parameters when using SRP.</p> +</dd> +<dt>verify (verify_none)</dt> +<dd><p>Use <code>verify_peer</code> to request a certificate from the client.</p> +</dd> +<dt>verify_fun</dt> +<dd><p>Custom policy to decide whether a client certificate is valid.</p> +</dd> +<dt>versions</dt> +<dd><p>TLS protocol versions that will be supported.</p> +</dd> +</dl> +<p>Note that the client will not send a certificate unless the value for the <code>verify</code> option is set to <code>verify_peer</code>. This means that the <code>fail_if_no_peer_cert</code> only apply when combined with the <code>verify</code> option. The <code>verify_fun</code> option allows greater control over the client certificate validation.</p> +<p>The options <code>sni_fun</code> and <code>sni_hosts</code> are mutually exclusive.</p> <h2 id="_exports">Exports</h2> -<div class="sectionbody"> -<div class="paragraph"><p>None.</p></div> -</div> -</div> +<p>None.</p> + @@ -439,6 +248,8 @@ greater control over the client certificate validation.</p></div> + <li><a href="/docs/en/ranch/1.5/manual">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> |