NervesKey

The NervesKey is a configured ATECC508A or ATECC608A Crypto Authentication chip that's used for authenticating devices with NervesHub and other cloud services. At a high level, it is a simple hardware security module (HSM) that protects one private key by requiring all operations on that key to occur inside chip. The project provides access to the chip from Elixir and makes configuration decisions to make working with the device easier. It has the following features:

Provision blank ATECC508A/608A devices - this includes private key generation
Storage for serial number and one-time calibration data (useful if primary storage is on a removable MicroSD card)
Support for Microchip's compressed X.509 certificate format to work with Microchip's C libraries
Support for signing device certificates so that devices can be included in a PKI
Support for storing a small amount of run-time configuration in unused data EEPROM slots
Support auxillary device/signer certificate storage to support pre-production experimentation without needing to lock down certificates

It cannot be stressed enough that the NervesKey library locks down the ATECC508A/608A during the provisioning process. This is a feature and is required for normal operation, but if you're getting started, make sure that you have a few extra parts just in case you make a mistake.

See NervesHub documentation for end-user NervesKey and NervesHub documentation.

See hw/hw.md for hardware information or go to Tindie/NervesKey for a prebuilt-one.

Installation

If available in Hex, the package can be installed by adding nerves_key to your list of dependencies in mix.exs:

def deps do
  [
    {:nerves_key, "~> 0.1.0"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/nerves_key.

General use

NervesKeys need to be provisioned before they can be used. That's a one-time step that could already have been done for you. If not, see subsequent sections for how that works.

To use any of the NervesKey APIs, you will need a "transport" to communicate with the ATECC508A/608A that's doing all of the work. Currently the only supported transport is I2C. The following line would be run on your Nerves device (like a Raspberry Pi, BeagleBone or your own custom hardware):

iex> {:ok, i2c} = ATECC508A.Transport.I2C.init([])

Check if your NervesKey has been provisioned:

iex> NervesKey.provisioned?(i2c)
true

If you get false, go to the provisioning sections. If you received an error, check that the NervesKey has a good connection to your hardware. If you have a custom board, you may need to pass parameters to ATECC508A.Transport.I2C.init/1 to set the correct I2C bus.

NervesKeys are provisioned with serial numbers. In production, these can be of your choosing.

iex> NervesKey.manufacturer_sn(i2c)
"ABC12345"

Of course, the more interesting part of the NervesKeys are its storage of device private keys and their certificates. For the common case, it stores two X.509 certificates: one for the device and one for the certificate that signed the device certificate. The signer certificate is usually uploaded to the servers that the device will connect to so that it can authenticate the device. Here's how to get both of the certificates:

iex> NervesKey.device_cert(i2c)
{:OTPCertificate, ...}

# Put this in a convenient form:
iex> X509.Certificate.to_pem(v()) |> IO.puts
-----BEGIN CERTIFICATE-----
stuff
stuff
stuff
-----END CERTIFICATE-----

iex> NervesKey.signer_cert(i2c)
{:OTPCertificate, ...}

The next step is to tell Erlang's SSL library that you want to use the NervesKey when connecting to the server. For that, you'll need nerves_key_pkcs11 which is included as a dependency of this library. This code is somewhat tedious but hopefully the following code fragment will help:

   {:ok, engine} = NervesKey.PKCS11.load_engine()
   {:ok, i2c} = ATECC508A.Transport.I2C.init([])

   signer_cert = X509.Certificate.to_der(NervesKey.signer_cert(i2c))
   cert = X509.Certificate.to_der(NervesKey.device_cert(i2c))
   key = NervesKey.PKCS11.private_key(engine, {:i2c, 1})
   cacerts = [signer_cert] ++ Keyword.get(opts, :trusted_certs, [])

   Tortoise.Supervisor.start_child(
     server: {
       Tortoise.Transport.SSL,
       verify: :verify_peer,
       host: Keyword.get(opts, :host),
       cert: cert,
       key: key,
       cacerts: cacerts,
       versions: [:"tlsv1.2"],
     })

Preparing for provisioning

The ATECC508A/608A in the NervesKey needs to be provisioned before it can be used. Before you can do that, you'll need the following:

A signing certificate and its private certificate (in other contexts, this is called a certificate authority)
A serial number for your device
A name for the device

The signing certificate and serial number are very important. After the provisioning process, they are locked down and cannot be changed without replacing the ATECC508A/608A. The device name is purely informational unless you choose to use it in your software.

NervesKeys support an auxillary set of certificates that identify the device. These are writable after the provisioning process. Since they're writable, they can be provisioned and updated at any time. As such, they're not programmed in the first-time provisioning process.

Signing certificates

Part of the provisioning process creates an X.509 certificate for the NervesKey that can be used to authenticate TLS connections. This certificate is signed by a "signer certificate". You will eventually need to upload the signer certificate to NervesHub or AWS IoT or wherever you would like to authenticate devices.

Due to memory limitations, the ATECC508A/608A has a way to compress X.509 certificates on chip. See ATECC Compressed Certificate Definition. To comply with the limitations of compressible certificates, NervesKey provides a mix task to create them:

$ mix nerves_key.signer create nerveskey_prod_signer1
Created signing cert, nerveskey_prod_signer1.cert and private key, nerveskey_prod_signer1.key.

Please store nerveskey_prod_signer1.key in a safe place.

nerveskey_prod_signer1.cert is ready to be uploaded to the servers that need
to authenticate devices signed by the private key.

There is no magic in the compressible certificates. They're just limited in what they can contain. You can inspect them with openssl x509 -in nerveskey_prod_signer1.cert -text.

Check with your IoT service on how the signer certificate is used. If it's only used for first-time device registration, then the signer certificate may not need a long expiration time. You may also be interested in creating more than one signing certificate if you have more than one manufacturing facility.

Manufacturer serial numbers

Be aware that there are a lot of things called serial numbers. In an attempt to minimize confusion, we'll refer to the serial number that identifies the device to humans and other machines as the "manufacturer serial number". This string (it need not be a number) is commonly printed on a label on a device. It may be embedded in a barcode. Other serial numbers exist - the ATECC508A/608A has a 9 byte one and X.509 certificates have ones. Those serial numbers have guarantees on uniqueness. It is up to the device manufacturer to make sure that the "manufacturer serial number" is unique. People generally want to do this for their own sanity.

The NervesKey saves the manufacturing serial number in the one-time programmable memory on the ATECC508A/608A and also in the device's X.509 certificate. The device's X.509 certificate is signed, so cloud servers can trust the manufacturer serial number.

At this point, you're the manufacturer. Decide how you'd like your serial numbers to look. Whatever you pick, it must fit in 16-bytes. Representing the serial number is ASCII is commonly done. If you don't want to deal with this, do what we do (Base32-encode the ATECC508A/608A's globally unique identifier):

iex> {:ok, i2c} = ATECC508A.Transport.I2C.init([])
{:ok, {ATECC508A.Transport.I2C, {#Reference<0.879310498.269090821.27261>, 96}}}
iex> NervesKey.default_info(i2c)
%NervesKey.ProvisioningInfo{
  board_name: "NervesKey",
  manufacturer_sn: "AER245UNQOY4T3Q"
}

Provisioning

Now that you have a signing certificate, the signer's private key, and a manufacturer serial number, you can provision a NervesKey or the ATECC508A/608A acting as a NervesKey in your device. Usually there's some custom manufacturing support software that performs this step. We'll provision at the iex prompt.

Use sftp to copy the signer certificate and private key to your device. We'll put them /tmp so that they disappear on reboot:

$ sftp nerves.local
Connected to nerves.local.
sftp> cd /tmp
sftp> put nerveskey_prod_signer1.*
Uploading nerveskey_prod_signer1.cert to /tmp/nerveskey_prod_signer1.cert
nerveskey_prod_signer1.cert                                              100%  636    78.3KB/s   00:00
Uploading nerveskey_prod_signer1.key to /tmp/nerveskey_prod_signer1.key
nerveskey_prod_signer1.key                                               100%  228    78.3KB/s   00:00
sftp> exit

Next, go to the IEx prompt on the device and run the following:

# Customize these or use `NervesKey.default_info/1` for defaults
cert_name="nerveskey_prod_signer1"
manufacturer_sn = "N1234"
board_name = "NervesKey"

# These lines should be copy/paste
signer_cert = File.read!("/tmp/#{cert_name}.cert") |> X509.Certificate.from_pem!;true
signer_key = File.read!("/tmp/#{cert_name}.key") |> X509.PrivateKey.from_pem!();true

{:ok, i2c} = ATECC508A.Transport.I2C.init([])
provision_info = %NervesKey.ProvisioningInfo{manufacturer_sn: manufacturer_sn, board_name: board_name}

# Double-check what you typed above before running this
NervesKey.provision(i2c, provision_info, signer_cert, signer_key)

If the last line returns :ok after about 2 seconds, then celebrate. You successfully programmed a NervesKey. You can't program it again. If you try, you'll get an error.

Provisioning an auxiliary certificate

If a situation arises where the originally provisioned certificate can't be used, it's possible to store a second certificate on the device. This second certificate uses the same private key as the first certificate. (It is assumed that the algorithmic and physical protections on the first private key are sufficient that storing two different private keys doesn't add value.) Use cases include:

Recovering from expiration or loss of the original signer key
Experimentation
Fixing errors in the original certificates

The auxiliary certificate is stored in writable memory on the ATECC508A/608A.

The NervesKey must be provisioned before the auxiliary certificate can be written. Assuming that's been done, copy the signer certificate and private key to your device similar to what you did before. Then run the following at the IEx prompt:

# Customize these
cert_name="nerveskey_prod_signer1"

# These lines should be copy/paste
signer_cert = File.read!("/tmp/#{cert_name}.cert") |> X509.Certificate.from_pem!;true
signer_key = File.read!("/tmp/#{cert_name}.key") |> X509.PrivateKey.from_pem!();true

{:ok, i2c} = ATECC508A.Transport.I2C.init([])
NervesKey.provision_aux_certificates(i2c, signer_cert, signer_key)

Settings

The NervesKey has bytes left over for storing a few settings. The NervesKey.put_settings/2 and NervesKey.get_settings/1 APIs let you store and retrieve a map. Since the storage is limited and relatively slow, this is intended for settings that rarely change or may be tightly coupled with certificates already being stored in the NervesKey.

Internally, NervesKey calls :erlang.term_to_binary to convert the map to raw bytes and then it spreads it across ATECC508A slots for storage. This means that the keys used in the map take up space too.

Support

If you run into problems, please help us improve this project by filing an issue.

ATECC508A configuration

This section describes the ATECC508A/608A configuration used for the NervesKey. This information isn't needed for using the library.

See Table 2-5 in the ATECC508A data sheet for documentation on the configuration zone. This software expects the following configuration to be programmed (unspecified bytes are either not programmable or kept as their defaults):

Bytes	Name	Value	Description
14	I2C_Enable	01	I2C mode
16	I2C_Address	C0	I2C address of the module (default)
18	OTPmode	AA	OTP is in read-only mode
19	ChipMode	00	Default mode
20-51	SlotConfig	N/A	See the next table
92-95	X509Format	00..00	Unused
96-127	KeyConfig	N/A	See next table

The slots are programmed as follows. This definition is organized to be similar to the Microchip Standard TLS Configuration to minimize changes to other software. Unused slots are configured so that applications can use them as they would an EEPROM.

Slot	Description	SlotConfig	KeyConfig	Primary properties
0	Device private key	87 20	33 00	Private key, read only; lockable
1	Unused	0F 0F	1C 00	Clear read/write; not lockable
2	Unused	0F 0F	1C 00	Clear read/write; not lockable
3	Unused	0F 0F	1C 00	Clear read/write; not lockable
4	Unused	0F 0F	1C 00	Clear read/write; not lockable
5	Settings (Part 3)	0F 0F	1C 00	Clear read/write; not lockable
6	Settings (Part 2)	0F 0F	1C 00	Clear read/write; not lockable
7	Settings (Part 1)	0F 0F	1C 00	Clear read/write; not lockable
8	Settings (Part 0)	0F 0F	3C 00	Clear read/write; lockable
9	Aux device certificate	0F 0F	3C 00	Clear read/write; lockable
10	Device certificate	0F 2F	3C 00	Clear read only; lockable
11	Signer public key	0F 2F	30 00	P256; Clear read only; lockable
12	Signer certificate	0F 2F	3C 00	Clear read only; lockable
13	Signer serial number +	0F 2F	3C 00	Clear read only; lockable
14	Aux signer public key	0F 0F	3C 00	Clear read/write; lockable
15	Aux signer certificate	0F 0F	3C 00	Clear read/write; lockable

The signer serial number slot is currently unused since the signer's cert is computed from the public key

The ATECC508A includes a 64 byte OTP (one-time programmable) memory. It has the following layout:

Bytes	Name	Contents
0-3	Magic	4e 72 76 73
4-5	Flags	TBD. Set to 0
6-15	Board name	10 byte name for the board in ASCII (set unused bytes to 0)
16-31	Mfg serial number	16 byte manufacturer-assigned serial number in ASCII (set unused bytes to 0)
32-63	User	These are unassigned

jackyz / nerves_key