Support mutual TLS using a certificate from a Windows cert store (#292)

Add the ability to use a client certificate located in a Windows certificate store. Previously, the client certificate and private key had to be passed by filepath or file contents. With this change, certificates and keys stored on TPM devices can be used.

Add new `windows_cert_pubsub.py` sample to show this in action.

Author: graebm

.gitignore

@@ -1,3 +1,4 @@
 docs/.buildinfo
 docs/.doctrees/
 __pycache__/
+*.egg-info

awsiot/mqtt_connection_builder.py

@@ -267,6 +267,8 @@ def mtls_with_pkcs11(*,
     This builder creates an :class:`awscrt.mqtt.Connection`, configured for an mTLS MQTT connection to AWS IoT,
     using a PKCS#11 library for private key operations.
 
+    NOTE: Unix only
+
     This function takes all :mod:`common arguments<awsiot.mqtt_connection_builder>`
     described at the top of this doc, as well as...
 
@@ -309,6 +311,30 @@ def mtls_with_pkcs11(*,
     return _builder(tls_ctx_options, **kwargs)
 
 
+def mtls_with_windows_cert_store_path(*,
+                                      cert_store_path: str,
+                                      **kwargs) -> awscrt.mqtt.Connection:
+    """
+    This builder creates an :class:`awscrt.mqtt.Connection`, configured for an mTLS MQTT connection to AWS IoT,
+    using a client certificate in a Windows certificate store.
+
+    NOTE: Windows only
+
+    This function takes all :mod:`common arguments<awsiot.mqtt_connection_builder>`
+    described at the top of this doc, as well as...
+
+    Args:
+        cert_store_path: Path to certificate in a Windows certificate store.
+                The path must use backslashes and end with the certificate's thumbprint.
+                Example: ``CurrentUser\\MY\\A11F8A9B5DF5B98BA3508FBCA575D09570E0D2C6``
+    """
+    _check_required_kwargs(**kwargs)
+
+    tls_ctx_options = awscrt.io.TlsContextOptions.create_client_with_mtls_windows_cert_store_path(cert_store_path)
+
+    return _builder(tls_ctx_options, **kwargs)
+
+
 def websockets_with_default_aws_signing(
         region,
         credentials_provider,

docs/awsiot/eventstreamrpc.html

@@ -196,13 +196,13 @@ <h3>Navigation</h3>
 </dl>
 <dl class="py attribute">
 <dt class="sig sig-object py" id="awsiot.eventstreamrpc.MessageAmendment.headers">
-<span class="sig-name descname"><span class="pre">headers</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">Optional</span><span class="p"><span class="pre">[</span></span><span class="pre">Sequence</span><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://awslabs.github.io/aws-crt-python/api/eventstream.html#awscrt.eventstream.Header" title="(in awscrt)"><span class="pre">awscrt.eventstream.Header</span></a><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></em><a class="headerlink" href="#awsiot.eventstreamrpc.MessageAmendment.headers" title="Permalink to this definition">¶</a></dt>
+<span class="sig-name descname"><span class="pre">headers</span></span><a class="headerlink" href="#awsiot.eventstreamrpc.MessageAmendment.headers" title="Permalink to this definition">¶</a></dt>
 <dd><p>Headers to add</p>
 </dd></dl>
 
 <dl class="py attribute">
 <dt class="sig sig-object py" id="awsiot.eventstreamrpc.MessageAmendment.payload">
-<span class="sig-name descname"><span class="pre">payload</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">Optional</span><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#bytes" title="(in Python v3.10)"><span class="pre">bytes</span></a><span class="p"><span class="pre">]</span></span></em><a class="headerlink" href="#awsiot.eventstreamrpc.MessageAmendment.payload" title="Permalink to this definition">¶</a></dt>
+<span class="sig-name descname"><span class="pre">payload</span></span><a class="headerlink" href="#awsiot.eventstreamrpc.MessageAmendment.payload" title="Permalink to this definition">¶</a></dt>
 <dd><p>Binary payload data</p>
 </dd></dl>
 
@@ -221,7 +221,7 @@ <h3>Navigation</h3>
 <cite>connect_message_amender</cite> init arg.</p>
 </dd>
 <dt class="field-odd">Return type</dt>
-<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Callable" title="(in Python v3.10)"><em>Callable</em></a>[[], <a class="reference internal" href="#awsiot.eventstreamrpc.MessageAmendment" title="awsiot.eventstreamrpc.MessageAmendment">awsiot.eventstreamrpc.MessageAmendment</a>]</p>
+<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Callable" title="(in Python v3.10)"><em>Callable</em></a>[<a class="reference internal" href="#awsiot.eventstreamrpc.MessageAmendment" title="awsiot.eventstreamrpc.MessageAmendment">awsiot.eventstreamrpc.MessageAmendment</a>]</p>
 </dd>
 </dl>
 </dd></dl>
@@ -250,7 +250,7 @@ <h3>Navigation</h3>
 <li><p><strong>tls_connection_options</strong> (<a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Optional" title="(in Python v3.10)"><em>Optional</em></a><em>[</em><a class="reference external" href="https://awslabs.github.io/aws-crt-python/api/io.html#awscrt.io.TlsConnectionOptions" title="(in awscrt)"><em>awscrt.io.TlsConnectionOptions</em></a><em>]</em>) – Optional TLS connection options.
 If None is provided, then the connection will be attempted over
 plain-text.</p></li>
-<li><p><strong>connect_message_amender</strong> (<a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Optional" title="(in Python v3.10)"><em>Optional</em></a><em>[</em><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Callable" title="(in Python v3.10)"><em>Callable</em></a><em>[</em><em>[</em><em>]</em><em>, </em><a class="reference internal" href="#awsiot.eventstreamrpc.MessageAmendment" title="awsiot.eventstreamrpc.MessageAmendment"><em>awsiot.eventstreamrpc.MessageAmendment</em></a><em>]</em><em>]</em>) – Optional callable that should return a
+<li><p><strong>connect_message_amender</strong> (<a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Optional" title="(in Python v3.10)"><em>Optional</em></a><em>[</em><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Callable" title="(in Python v3.10)"><em>Callable</em></a><em>[</em><a class="reference internal" href="#awsiot.eventstreamrpc.MessageAmendment" title="awsiot.eventstreamrpc.MessageAmendment"><em>awsiot.eventstreamrpc.MessageAmendment</em></a><em>]</em><em>]</em>) – Optional callable that should return a
 <a class="reference internal" href="#awsiot.eventstreamrpc.MessageAmendment" title="awsiot.eventstreamrpc.MessageAmendment"><code class="xref py py-class docutils literal notranslate"><span class="pre">MessageAmendment</span></code></a> for the
 <a class="reference external" href="https://awslabs.github.io/aws-crt-python/api/eventstream.html#awscrt.eventstream.rpc.MessageType.CONNECT" title="(in awscrt)"><code class="xref py py-attr docutils literal notranslate"><span class="pre">CONNECT</span></code></a> message.
 This callable will be invoked whenever a network connection is
@@ -398,6 +398,30 @@ <h3>Navigation</h3>
 </ul>
 </dd>
 </dl>
+<dl class="py method">
+<dt class="sig sig-object py" id="awsiot.eventstreamrpc.Client.close">
+<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">reason</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#awsiot.eventstreamrpc.Client.close" title="Permalink to this definition">¶</a></dt>
+<dd><p>Close the connection.</p>
+<p>Shutdown is asynchronous. This call has no effect if the connection
+is already closed or closing.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><p><strong>reason</strong> (<a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Optional" title="(in Python v3.10)"><em>Optional</em></a><em>[</em><a class="reference external" href="https://docs.python.org/3/library/exceptions.html#Exception" title="(in Python v3.10)"><em>Exception</em></a><em>]</em>) – If set, the connection will
+close with this error as the reason (unless
+it was already closing for another reason).</p>
+</dd>
+<dt class="field-even">Returns</dt>
+<dd class="field-even"><p>The future which will complete
+when the shutdown process is done. The future will have an
+exception if shutdown was caused by an error, or a result
+of None if the shutdown was clean and user-initiated.</p>
+</dd>
+<dt class="field-odd">Return type</dt>
+<dd class="field-odd"><p>concurrent.futures._base.Future</p>
+</dd>
+</dl>
+</dd></dl>
+
 </dd></dl>
 
 </section>

docs/awsiot/greengrass_discovery.html

@@ -104,13 +104,13 @@ <h3>Navigation</h3>
 </dl>
 <dl class="py attribute">
 <dt class="sig sig-object py" id="awsiot.greengrass_discovery.DiscoveryException.http_response_code">
-<span class="sig-name descname"><span class="pre">http_response_code</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.10)"><span class="pre">int</span></a></em><a class="headerlink" href="#awsiot.greengrass_discovery.DiscoveryException.http_response_code" title="Permalink to this definition">¶</a></dt>
+<span class="sig-name descname"><span class="pre">http_response_code</span></span><a class="headerlink" href="#awsiot.greengrass_discovery.DiscoveryException.http_response_code" title="Permalink to this definition">¶</a></dt>
 <dd><p>HTTP response code</p>
 </dd></dl>
 
 <dl class="py attribute">
 <dt class="sig sig-object py" id="awsiot.greengrass_discovery.DiscoveryException.message">
-<span class="sig-name descname"><span class="pre">message</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.10)"><span class="pre">str</span></a></em><a class="headerlink" href="#awsiot.greengrass_discovery.DiscoveryException.message" title="Permalink to this definition">¶</a></dt>
+<span class="sig-name descname"><span class="pre">message</span></span><a class="headerlink" href="#awsiot.greengrass_discovery.DiscoveryException.message" title="Permalink to this definition">¶</a></dt>
 <dd><p>Message</p>
 </dd></dl>
 
@@ -198,7 +198,7 @@ <h3>Navigation</h3>
 <p>Discovery response</p>
 <dl class="py attribute">
 <dt class="sig sig-object py" id="awsiot.greengrass_discovery.DiscoverResponse.gg_groups">
-<span class="sig-name descname"><span class="pre">gg_groups</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">Optional</span><span class="p"><span class="pre">[</span></span><span class="pre">List</span><span class="p"><span class="pre">[</span></span><a class="reference internal" href="#awsiot.greengrass_discovery.GGGroup" title="awsiot.greengrass_discovery.GGGroup"><span class="pre">awsiot.greengrass_discovery.GGGroup</span></a><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></em><a class="headerlink" href="#awsiot.greengrass_discovery.DiscoverResponse.gg_groups" title="Permalink to this definition">¶</a></dt>
+<span class="sig-name descname"><span class="pre">gg_groups</span></span><a class="headerlink" href="#awsiot.greengrass_discovery.DiscoverResponse.gg_groups" title="Permalink to this definition">¶</a></dt>
 <dd><p>List of <a class="reference internal" href="#awsiot.greengrass_discovery.GGGroup" title="awsiot.greengrass_discovery.GGGroup"><code class="xref py py-class docutils literal notranslate"><span class="pre">GGGroup</span></code></a></p>
 </dd></dl>