Skip to content

Latest commit

 

History

History
101 lines (71 loc) · 5.13 KB

README.md

File metadata and controls

101 lines (71 loc) · 5.13 KB
Raw

WindowsCert Connect

Return to main sample list

This sample is similar to the Basic Connect sample, in that it connects via Mutual TLS (mTLS) using a certificate and key file. However, unlike the Basic Connect where the certificate and private key file are stored on disk, this sample uses a PKCS#12 file stored in the Windows certificate store. This adds a layer of security because the private key file is not just sitting on the computer and instead is hidden securely away in the Windows certificate store.

WARNING: Windows only

Your IoT Core Thing's Policy must provide privileges for this sample to connect. Below is a sample policy that can be used on your IoT Core Thing that will allow this sample to run as intended.

(see sample policy) 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Connect"
      ],
      "Resource": [
        "arn:aws:iot:region:account:client/test-*"
      ]
    }
  ]
}

Replace with the following with the data from your AWS account:

  • <region>: The AWS IoT Core region where you created your AWS IoT Core thing you wish to use with this sample. For example us-east-1.
  • <account>: Your AWS IoT Core account ID. This is the set of numbers in the top right next to your AWS account name when using the AWS IoT Core website.

Note that in a real application, you may want to avoid the use of wildcards in your ClientID or use them selectively. Please follow best practices when working with AWS on production applications using the SDK. Also, for the purposes of this sample, please make sure your policy allows a client ID of test-* to connect or use --client_id <client ID here> to send the client ID your policy supports.

How to run

To run the Windows certificate connect sample use the following command:

.\windows-cert-connect.exe --endpoint <endpoint> --cert <path to certificate>

You can also pass a Certificate Authority file (CA) if your certificate and key combination requires it:

.\windows-cert-connect.exe --endpoint <endpoint> --cert <path to certificate> --ca_file <path to root CA>

How to setup and run

To run this sample, you will need the path to your certificate in the Windows certificate store. This will look something like the following:

CurrentUser\MY\A11F8A9B5DF5B98BA3508FBCA575D09570E0D2C6

Where "CurrentUser\MY" is the store and "A11F8A9B5DF5B98BA3508FBCA575D09570E0D2C6" is the certificate's thumbprint. Note that if your certificate and private key are in a TPM then you would use them by passing their certificate store path.

The steps to take a AWS IoT Thing certificate and key with the Windows Certificate Connect sample are listed below:

  1. Create an IoT Thing with a certificate and key if you haven't already.

  2. Combine the certificate and private key into a single .pfx file. You will be prompted for a password while creating this file and it is important that you remember it for this process. Otherwise you will need to restart and create a new .pfx file should you forget the password.

    If you have OpenSSL installed you can run the following to create a .pfx file:

    openssl pkcs12 -in certificate.pem.crt -inkey private.pem.key -out certificate.pfx

    Otherwise use CertUtil to create the .pfx file:

    certutil -mergePFX certificate.pem.crt,private.pem.key certificate.pfx

  3. Add the .pfx file to a Windows certificate store using PowerShell's Import-PfxCertificate

    $mypwd = Get-Credential -UserName 'Enter password below' -Message 'Enter password below'
Import-PfxCertificate -FilePath certificate.pfx -CertStoreLocation Cert:\CurrentUser\My -Password $mypwd.Password

    Replace $mypwd.Password with the password of your .pfx file.

    Once you run the command, note the certificate thumbprint that is printed out:

    Thumbprint                                Subject
----------                                -------
A11F8A9B5DF5B98BA3508FBCA575D09570E0D2C6  CN=AWS IoT Certificate

    In the example above, the certificate's path would be: CurrentUser\MY\A11F8A9B5DF5B98BA3508FBCA575D09570E0D2C6. This is important as you need to pass this path into the --cert argument when running this sample.

  4. You can run the sample using the following:

    .\windows-cert-connect.exe --endpoint <endpoint> --cert <path to certificate>