View Source NervesKey (nerves_key v1.2.0)

This is a high level interface to provisioning and using the NervesKey or any ATECC508A/608A that can be configured similarly.

Link to this section Summary

Types

Which device/signer certificate pair to use

Which type of device to use

Functions

Clear out the auxiliary certificates

Create a signing key pair

Return default provisioning info for a NervesKey

Detect if a NervesKey is available on the transport

Read the device certificate from the slot

Return the settings block as a binary

Return all of the setting stored in the NervesKey as a map

Check whether the auxiliary certificates were programmed

IEEE EUI-48 MAC address that can be used as a unique identifier in LAN networking This is only available on :trust_and_go

Read the manufacturer's serial number

Return the max length of settings

Provision a NervesKey in one step.

Provision the auxiliary device/signer certificates on a NervesKey.

Check whether the NervesKey has been provisioned

Store raw settings on the Nerves Key

Sign a SHA256 digest

Read the signer certificate from the slot

Return ssl_opts for using the NervesKey

Link to this section Types

@type certificate_pair() :: :primary | :aux

Which device/signer certificate pair to use

@type device_type() :: :nerves_key | :trust_and_go

Which type of device to use

Link to this section Functions

Link to this function

clear_aux_certificates(transport)

View Source
@spec clear_aux_certificates(ATECC508A.Transport.t()) :: :ok

Clear out the auxiliary certificates

This function overwrites the auxiliary certificate slots with

Link to this function

create_signing_key_pair(opts \\ [])

View Source
@spec create_signing_key_pair(keyword()) ::
  {X509.Certificate.t(), X509.PrivateKey.t()}

Create a signing key pair

This returns a tuple that contains a new signer certificate and private key. It is compatible with the ATECC508A certificate compression.

Options:

  • :years_valid - how many years this key is valid for

Return default provisioning info for a NervesKey

This function is used for pre-programmed NervesKey devices. The serial number is a Base32-encoded version of the ATECC508A/608A's globally unique serial number. No additional care is needed to keep the number unique.

@spec detected?(ATECC508A.Transport.t()) :: boolean()

Detect if a NervesKey is available on the transport

Link to this function

device_cert(transport, which \\ :primary, type \\ :nerves_key)

View Source

Read the device certificate from the slot

The device must be programmed for this to work.

Examples:

iex> NervesKey.device_cert(transport, :primary, :nerves_key)
{:OTPCertificate, ...}

iex> NervesKey.device_cert(transport, :primary, :trust_and_go)
{:OTPCertificate, ...}
Link to this function

get_raw_settings(transport, device_type \\ :nerves_key)

View Source
@spec get_raw_settings(ATECC508A.Transport.t(), device_type()) ::
  {:ok, binary()} | {:error, atom()}

Return the settings block as a binary

Link to this function

get_settings(transport, device_type \\ :nerves_key)

View Source
@spec get_settings(ATECC508A.Transport.t(), device_type()) ::
  {:ok, map()} | {:error, atom()}

Return all of the setting stored in the NervesKey as a map

Link to this function

has_aux_certificates?(transport)

View Source
@spec has_aux_certificates?(ATECC508A.Transport.t()) :: boolean()

Check whether the auxiliary certificates were programmed

Link to this function

manufacturer_mac(transport, atom)

View Source

IEEE EUI-48 MAC address that can be used as a unique identifier in LAN networking This is only available on :trust_and_go

Link to this function

manufacturer_sn(transport, type \\ :nerves_key)

View Source
@spec manufacturer_sn(ATECC508A.Transport.t(), device_type()) :: binary()

Read the manufacturer's serial number

@spec max_settings_len(device_type()) :: integer()

Return the max length of settings

Link to this function

provision(transport, info, signer_cert, signer_key)

View Source

Provision a NervesKey in one step.

See the README.md for how to use this. This function locks the ATECC508A down, so you'll want to be sure what you pass it is correct.

This function does it all. It requires the signer's private key so handle that with care. Alternatively, please consider sending a PR for supporting off-device signatures so that HSMs can be used.

Link to this function

provision_aux_certificates(transport, signer_cert, signer_key, type \\ :nerves_key)

View Source
@spec provision_aux_certificates(
  ATECC508A.Transport.t(),
  X509.Certificate.t(),
  X509.PrivateKey.t(),
  device_type()
) :: :ok

Provision the auxiliary device/signer certificates on a NervesKey.

This function creates and saves the auxiliary certificates. These are only needed if the ones written by provision/4 are not usable. They are not used unless explicitly requested. See the README.md for details.

You may call this function multiple times after the ATECC508A has been provisioned.

@spec provisioned?(ATECC508A.Transport.t()) :: boolean()

Check whether the NervesKey has been provisioned

Link to this function

put_raw_settings(transport, raw_settings, device_type)

View Source
@spec put_raw_settings(ATECC508A.Transport.t(), binary(), device_type()) :: :ok

Store raw settings on the Nerves Key

This overwrites all of the settings and should be used with care since there's no protection against race conditions with other users of this API.

Link to this function

put_settings(transport, settings, device_type \\ :nerves_key)

View Source
@spec put_settings(ATECC508A.Transport.t(), map(), device_type()) :: :ok

Store settings on the NervesKey

This overwrites all of the settings that are currently on the key and should be used with care since there's no protection against a race condition with other NervesKey users.

Link to this function

sign_digest(transport, digest)

View Source
@spec sign_digest(ATECC508A.Transport.t(), binary()) ::
  {:ok, binary()} | {:error, atom()}

Sign a SHA256 digest

Link to this function

signer_cert(transport, which \\ :primary, type \\ :nerves_key)

View Source

Read the signer certificate from the slot

Link to this function

ssl_opts(transport, which \\ :primary, type \\ :nerves_key)

View Source

Return ssl_opts for using the NervesKey

Pass an engine and optionally which certificate that you'd like to use.