path: root/man/tip/nng_tls_options.5.html

---
version: tip
layout: manpage_v2
title: nng_tls_options(5)
---
<h1>nng_tls_options(5)</h1>
<div class="sect1">
<h2 id="_name">NAME</h2>
<div class="sectionbody">
<div class="paragraph">
<p>nng_tls_options - TLS-specific options</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_synopsis">SYNOPSIS</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nng/nng.h&gt;</span>

<span class="tok-cp">#define NNG_OPT_TLS_AUTH_MODE      &quot;tls-authmode&quot;</span>
<span class="tok-cp">#define NNG_OPT_TLS_CA_FILE        &quot;tls-ca-file&quot;</span>
<span class="tok-cp">#define NNG_OPT_TLS_CERT_KEY_FILE  &quot;tls-cert-key-file&quot;</span>
<span class="tok-cp">#define NNG_OPT_TLS_CONFIG         &quot;tls-config&quot;</span>
<span class="tok-cp">#define NNG_OPT_TLS_SERVER_NAME    &quot;tls-server-name&quot;</span>
<span class="tok-cp">#define NNG_OPT_TLS_VERIFIED       &quot;tls-verified&quot;</span>
<span class="tok-cp">#define NNG_OPT_TLS_PEER_CN        &quot;tls-peer-cn&quot;</span>
<span class="tok-cp">#define NNG_OPT_TLS_PEER_ALT_NAMES &quot;tls-peer-alt-names&quot;</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_description">DESCRIPTION</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This page documents the various standard options that can be set or
retrieved on objects using TLS.</p>
</div>
<div class="paragraph">
<p>The option names should always be used by their symbolic definitions.</p>
</div>
<div class="paragraph">
<p>In the following list of options, the name of the option is supplied,
along with the data type of the underlying value.</p>
</div>
<div class="paragraph">
<p>Some options are only meaningful or supported in certain contexts, or may
have other access restrictions.
An attempt has been made to include details about such restrictions in the
description of the option.</p>
</div>
<div class="sect2">
<h3 id="_tls_options">TLS Options</h3>
<div class="dlist">
<dl>
<dt class="hdlist1"><a id="NNG_OPT_TLS_AUTH_MODE"></a><code>NNG_OPT_TLS_AUTH_MODE</code></dt>
<dd>
<p>(<code>int</code>)
Write-only option used to configure the authentication mode used.
See <a href="nng_tls_config_auth_mode.3tls.html"><code>nng_tls_config_auth_mode()</code></a> for
more details.</p>
</dd>
<dt class="hdlist1"><a id="NNG_OPT_TLS_CA_FILE"></a><code>NNG_OPT_TLS_CA_FILE</code></dt>
<dd>
<p>(string) Write-only option naming a file containing certificates to
use for peer validation.
See <a href="nng_tls_config_ca_file.3tls.html"><code>nng_tls_config_ca_file()</code></a> for more
information.</p>
</dd>
<dt class="hdlist1"><a id="NNG_OPT_TLS_CERT_KEY_FILE"></a><code>NNG_OPT_TLS_CERT_KEY_FILE</code></dt>
<dd>
<p>(string) Write-only option naming a file containing the local certificate and
associated private key.
The private key used must be unencrypted.
See <a href="nng_tls_config_own_cert.3tls.html"><code>nng_tls_config_own_cert()</code></a> for more
information.</p>
</dd>
<dt class="hdlist1"><a id="NNG_OPT_TLS_CONFIG"></a><code>NNG_OPT_TLS_CONFIG</code></dt>
<dd>
<p>(<code>nng_tls_config *</code>)
This option references the underlying
<a href="nng_tls_config.5.html">TLS configuration object</a>.
A hold is placed on the underlying
configuration object before returning it.</p>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The caller should release the hold with
<a href="nng_tls_config_free.3tls.html"><code>nng_tls_config_free()</code></a> when it no
longer needs the TLS configuration object.
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Use this option when more advanced TLS configuration is required.
</td>
</tr>
</table>
</div>
</dd>
<dt class="hdlist1"><a id="NNG_OPT_TLS_SERVER_NAME"></a><code>NNG_OPT_TLS_SERVER_NAME</code></dt>
<dd>
<p>(string)
This write-only option is used to specify the name of the server.
When used with a dialer, this potentially configures SNI (server name
indication, which is used as a hint by a multihosting server to choose the
appropriate certificate to provide) and also is used to validate the
name presented in the server&#8217;s x509 certificate.</p>
</dd>
<dt class="hdlist1"><a id="NNG_OPT_TLS_VERIFIED"></a><code>NNG_OPT_TLS_VERIFIED</code></dt>
<dd>
<p>(<code>bool</code>)
This read-only option indicates whether the remote peer has been properly verified using TLS
authentication.
May return incorrect results if peer authentication is disabled.</p>
</dd>
<dt class="hdlist1"><a id="NNG_OPT_TLS_PEER_CN"></a><code>NNG_OPT_TLS_PEER_CN</code></dt>
<dd>
<p>(string)
This read-only option returns the common name of the peer certificate.
May return incorrect results if peer authentication is disabled.</p>
</dd>
<dt class="hdlist1"><a id="NNG_OPT_TLS_PEER_ALT_NAMES"></a><code>NNG_OPT_TLS_PEER_ALT_NAMES</code></dt>
<dd>
<p>(string)
This read-only option returns string list with the subject alternative names of the
peer certificate. May return incorrect results if peer authentication is disabled.</p>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="_inherited_options">Inherited Options</h3>
<div class="paragraph">
<p>Generally, the following option values are also available for TLS objects,
when appropriate for the context:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="nng_options.5.html#NNG_OPT_LOCADDR"><code>NNG_OPT_LOCADDR</code></a></p>
</li>
<li>
<p><a href="nng_options.5.html#NNG_OPT_REMADDR"><code>NNG_OPT_REMADDR</code></a></p>
</li>
<li>
<p><a href="nng_tcp_options.5.html#NNG_OPT_TCP_KEEPALIVE"><code>NNG_OPT_TCP_KEEPALIVE</code></a></p>
</li>
<li>
<p><a href="nng_tcp_options.5.html#NNG_OPT_TCP_NODELAY"><code>NNG_OPT_TCP_NODELAY</code></a></p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_see_also">SEE ALSO</h2>
<div class="sectionbody">
<div class="paragraph text-left">
<p><a href="nng_options.5.html">nng_options(5)</a>
<a href="nng_tcp_options.5.html">nng_tcp_options(5)</a>
<a href="nng_tls_config.5.html">nng_tls_config(5)</a>,
<a href="nng.7.html">nng(7)</a></p>
</div>
</div>
</div>