deploy: d50c3cc944

branch/main/get_certificate_module.html

@@ -213,7 +213,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-ge
 <span id="ansible-collections-community-crypto-get-certificate-module-requirements"></span><h2><a class="toc-backref" href="#id2" role="doc-backlink">Requirements</a><a class="headerlink" href="#requirements" title="Link to this heading"></a></h2>
 <p>The below requirements are needed on the host that executes this module.</p>
 <ul class="simple">
-<li><p>Python &gt;= 2.7 when using <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-get-certificate-module-parameter-proxy-host"><span class="std std-ref"><span class="pre">proxy_host</span></span></a></strong></code></p></li>
+<li><p>Python &gt;= 2.7 when using <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-get-certificate-module-parameter-proxy-host"><span class="std std-ref"><span class="pre">proxy_host</span></span></a></strong></code>, and Python &gt;= 3.10 when <code class="ansible-option-value docutils literal notranslate"><a class="reference internal" href="#ansible-collections-community-crypto-get-certificate-module-parameter-get-certificate-chain"><span class="std std-ref"><span class="pre">get_certificate_chain=true</span></span></a></code></p></li>
 <li><p>cryptography &gt;= 1.6</p></li>
 </ul>
 </section>
@@ -261,27 +261,42 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-ge
 </div></td>
 </tr>
 <tr class="row-odd"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="parameter-get_certificate_chain"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-get-certificate-module-parameter-get-certificate-chain"><strong>get_certificate_chain</strong></p>
+<a class="ansibleOptionLink" href="#parameter-get_certificate_chain" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
+<p><em class="ansible-option-versionadded">added in community.crypto 2.21.0</em></p>
+</div></td>
+<td><div class="ansible-option-cell"><p>If set to <code class="ansible-value docutils literal notranslate"><span class="pre">true</span></code>, will obtain the certificate chain next to the certificate itself.</p>
+<p>The chain as returned by the server can be found in <code class="ansible-return-value docutils literal notranslate"><a class="reference internal" href="#ansible-collections-community-crypto-get-certificate-module-return-unverified-chain"><span class="std std-ref"><span class="pre">unverified_chain</span></span></a></code>, and the chain that passed validation in <code class="ansible-return-value docutils literal notranslate"><a class="reference internal" href="#ansible-collections-community-crypto-get-certificate-module-return-verified-chain"><span class="std std-ref"><span class="pre">verified_chain</span></span></a></code>.</p>
+<p><strong>Note</strong> that this needs <strong>Python 3.10 or newer</strong>. Also note that only Python 3.13 or newer officially supports this. The module uses internal APIs of Python 3.10, 3.11, and 3.12 to achieve the same. It can be that future versions of Python 3.10, 3.11, or 3.12 break this.</p>
+<p class="ansible-option-line"><strong class="ansible-option-choices">Choices:</strong></p>
+<ul class="simple">
+<li><p><code class="ansible-option-default-bold docutils literal notranslate"><strong><span class="pre">false</span></strong></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
+<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">true</span></code></p></li>
+</ul>
+</div></td>
+</tr>
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-host"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-get-certificate-module-parameter-host"><strong>host</strong></p>
 <a class="ansibleOptionLink" href="#parameter-host" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span> / <span class="ansible-option-required">required</span></p>
 </div></td>
 <td><div class="ansible-option-cell"><p>The host to get the cert for (IP is fine).</p>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-port"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-get-certificate-module-parameter-port"><strong>port</strong></p>
 <a class="ansibleOptionLink" href="#parameter-port" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">integer</span> / <span class="ansible-option-required">required</span></p>
 </div></td>
 <td><div class="ansible-option-cell"><p>The port to connect to.</p>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-proxy_host"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-get-certificate-module-parameter-proxy-host"><strong>proxy_host</strong></p>
 <a class="ansibleOptionLink" href="#parameter-proxy_host" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
 </div></td>
 <td><div class="ansible-option-cell"><p>Proxy host used when get a certificate.</p>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-proxy_port"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-get-certificate-module-parameter-proxy-port"><strong>proxy_port</strong></p>
 <a class="ansibleOptionLink" href="#parameter-proxy_port" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">integer</span></p>
 </div></td>
@@ -289,7 +304,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-ge
 <p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-option-default docutils literal notranslate"><span class="pre">8080</span></code></p>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-select_crypto_backend"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-get-certificate-module-parameter-select-crypto-backend"><strong>select_crypto_backend</strong></p>
 <a class="ansibleOptionLink" href="#parameter-select_crypto_backend" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
 </div></td>
@@ -303,7 +318,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-ge
 </ul>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-server_name"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-get-certificate-module-parameter-server-name"><strong>server_name</strong></p>
 <a class="ansibleOptionLink" href="#parameter-server_name" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
 <p><em class="ansible-option-versionadded">added in community.crypto 1.4.0</em></p>
@@ -311,7 +326,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-ge
 <td><div class="ansible-option-cell"><p>Server name used for SNI (<a class="reference external" href="https://en.wikipedia.org/wiki/Server_Name_Indication">Server Name Indication</a>) when hostname is an IP or is different from server name.</p>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-starttls"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-get-certificate-module-parameter-starttls"><strong>starttls</strong></p>
 <a class="ansibleOptionLink" href="#parameter-starttls" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
 <p><em class="ansible-option-versionadded">added in community.crypto 1.9.0</em></p>
@@ -324,7 +339,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-ge
 </ul>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-timeout"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-get-certificate-module-parameter-timeout"><strong>timeout</strong></p>
 <a class="ansibleOptionLink" href="#parameter-timeout" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">integer</span></p>
 </div></td>
@@ -332,7 +347,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-ge
 <p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-option-default docutils literal notranslate"><span class="pre">10</span></code></p>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-tls_ctx_options"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-get-certificate-module-parameter-tls-ctx-options"><strong>tls_ctx_options</strong></p>
 <a class="ansibleOptionLink" href="#parameter-tls_ctx_options" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">list</span> / <span class="ansible-option-elements">elements=any</span></p>
 <p><em class="ansible-option-versionadded">added in community.crypto 2.21.0</em></p>
@@ -553,6 +568,28 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-ge
 </div></td>
 </tr>
 <tr class="row-even"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="return-unverified_chain"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-get-certificate-module-return-unverified-chain"><strong>unverified_chain</strong></p>
+<a class="ansibleOptionLink" href="#return-unverified_chain" title="Permalink to this return value"></a><p class="ansible-option-type-line"><span class="ansible-option-type">list</span> / <span class="ansible-option-elements">elements=string</span></p>
+<p><em class="ansible-option-versionadded">added in community.crypto 2.21.0</em></p>
+</div></td>
+<td><div class="ansible-option-cell"><p>The certificate chain retrieved from the port.</p>
+<p>The first entry is always <code class="ansible-return-value docutils literal notranslate"><a class="reference internal" href="#ansible-collections-community-crypto-get-certificate-module-return-cert"><span class="std std-ref"><span class="pre">cert</span></span></a></code>.</p>
+<p class="ansible-option-line"><strong class="ansible-option-returned-bold">Returned:</strong> success and <code class="ansible-option-value docutils literal notranslate"><a class="reference internal" href="#ansible-collections-community-crypto-get-certificate-module-parameter-get-certificate-chain"><span class="std std-ref"><span class="pre">get_certificate_chain=true</span></span></a></code></p>
+</div></td>
+</tr>
+<tr class="row-odd"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="return-verified_chain"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-get-certificate-module-return-verified-chain"><strong>verified_chain</strong></p>
+<a class="ansibleOptionLink" href="#return-verified_chain" title="Permalink to this return value"></a><p class="ansible-option-type-line"><span class="ansible-option-type">list</span> / <span class="ansible-option-elements">elements=string</span></p>
+<p><em class="ansible-option-versionadded">added in community.crypto 2.21.0</em></p>
+</div></td>
+<td><div class="ansible-option-cell"><p>The verified certificate chain retrieved from the port.</p>
+<p>The first entry is always <code class="ansible-return-value docutils literal notranslate"><a class="reference internal" href="#ansible-collections-community-crypto-get-certificate-module-return-cert"><span class="std std-ref"><span class="pre">cert</span></span></a></code>.</p>
+<p>The last certificate the root certificate the chain is traced to. If <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-get-certificate-module-parameter-ca-cert"><span class="std std-ref"><span class="pre">ca_cert</span></span></a></strong></code> is provided this certificate is part of that store; otherwise it is part of the store used by default by Python.</p>
+<p>Note that <code class="ansible-return-value docutils literal notranslate"><a class="reference internal" href="#ansible-collections-community-crypto-get-certificate-module-return-unverified-chain"><span class="std std-ref"><span class="pre">unverified_chain</span></span></a></code> generally does not contain the root certificate, and might contain other certificates that are not part of the validated chain.</p>
+<p class="ansible-option-line"><strong class="ansible-option-returned-bold">Returned:</strong> success and <code class="ansible-option-value docutils literal notranslate"><a class="reference internal" href="#ansible-collections-community-crypto-get-certificate-module-parameter-get-certificate-chain"><span class="std std-ref"><span class="pre">get_certificate_chain=true</span></span></a></code></p>
+</div></td>
+</tr>
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="return-version"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-get-certificate-module-return-version"><strong>version</strong></p>
 <a class="ansibleOptionLink" href="#return-version" title="Permalink to this return value"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
 </div></td>