TLS Client Authentication

During a standard TLS handshake, the server authenticates the client but possesses limited client information. TLS Client Authentication extends this by enabling the server to authenticate clients, ensuring that only authorized ones can connect. This method provides several advantages, such as improved security and privacy of communication, reduced dependency on other authentication methods, simplified access control management, and enhanced server performance and scalability.

How to use TLS Client Authentication on Meadow

To enable TLS client authentication on Meadow you just need to follow a few steps:

Step 1: Upload the client credentials to the Meadow device

Upload the client certificate file client_cert.pem, the client private_key.pem, and the private key passphrase private_key_pass.txt to the Meadow using the meadow file write CLI command or by including them in your .NET project .csproj file:

<None Update="client_cert.pem">
  <CopyToOutputDirectory>Always</CopyToOutputDirectory>
</None>
<None Update="private_key.pem">
  <CopyToOutputDirectory>Always</CopyToOutputDirectory>
</None>
<None Update="private_key_pass.txt">
  <CopyToOutputDirectory>Always</CopyToOutputDirectory>
</None>

After uploading the client credential files, they'll be removed from the Meadow storage in the first OS initialization, and stored in a different storage on the secrets directory, as an additional security layer.

The client credential files stored in the secrets directory cannot be deleted, but the user can just flash empty files to overwrite the credentials (client_cert.pem, private_key.pem and private_key_pass.txt) previously stored.

It's restricted to a single certificate per client.

The client certificate will be attached automatically by the operating system to all connections that request one. So, you don't need to worry about adding them to your C# application.

That's all! :)

Meadow TLS Client Authentication Sample App with Azure IoT Hub

For straightforward TLS Client Authentication testing, you can utilize self-signed certificates. These certificates can be generated using libraries such as OpenSSL, eliminating the need for a Certificate Authority (CA) to sign them.

Step 1: Creating a self-signed client certificate

First, you need to create a private key, and a self-signed client certificate, by running these commands, you should get a private_key.pem and a client_cert.pem:

openssl genpkey -algorithm RSA -out private_key.pem
openssl req -new -key private_key.pem -out client_csr.pem
openssl x509 -req -in client_csr.pem -signkey private_key.pem -out client_cert.pem

Step 2: Adding your certificate to your Azure IoT Hub

After creating your Azure IoT Hub, go to Security Settings -> Certificates, and add a new certificate, uploading your client_cert.pem. You should save the certificate Thumbprint, since it'll be required in the next step.

Step 3: Link a new device to your client certificate

Go to Device Management -> Devices, and add a new device, using X509 Self-Signed as the Authentication type, and using your certificate Thumbprint got in the last step as Primary Thumbprint and Secondary Thumbprint. This will link the device to your client certificate.

Step 4: Uploading your client certificate to a Meadow device

After creating a device on your Azure IoT Hub, and configuring it, you'll need to upload the client certificate file client_cert.pem, and the client private_key.pem to your Meadow device, which can be done by running the meadow file write CLI command.

Step 5 (Optional): Encrypting your private key

If you want to encrypt your private key, you can just run an OpenSSL command like the following:

openssl rsa -in decrypted_private_key.pem -out private_key.pem -des3 -traditional

Then, you'll need to create a file private_key_pass.txt carrying the client certificate private key passphrase and upload it as well to the device.

Step 6: Sending MQTT messages to an Azure IoT Hub

Finally, you can use this Meadow Sample App to send messages to your Azure IoT Hub. Just remember to replace the variables IOT_HUB_NAME and IOT_HUB_DEVICE_ID with your Azure IoT Hub name and your device ID.

Troubleshooting

How to use .PFX certificate files

The .PFX certificates are not supported by the Meadow TLS provider (mbedTLS). However, it's pretty simple to extract the private key and the client certificate from a PFX file using the OpenSSL library. You just need to run the following commands to generate the private_key.pem and client_cert.pem files:

openssl pkcs12 -in yourfile.pfx -nocerts -out private_key.pem
openssl pkcs12 -in yourfile.pfx -clcerts -nokeys -out client_cert.pem

Failed to parse private key

You may see this error if you attempt to use encrypted private keys, since some encryption algorithms are not supported by the Meadow TLS provider (mbedTLS), so if you see the error Failed to parse private key, try to encrypt your private key using another algorithm, such as the RSA algorithm with DES3 (Triple DES) encryption and the traditional PKCS#1 formatting, which can be done by using your OS OpenSSL:

openssl rsa -in private_key.pem -out private_key_output.pem -des3 -traditional

Then, you should get a private key with a header like this:

-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,637E819E82DF740E