defmodule NervesKey do
@moduledoc """
This is a high level interface to provisioning and using the NervesKey
or any ATECC508A/608A that can be configured similarly.
"""
alias NervesKey.{Config, OTP, Data, ProvisioningInfo}
@build_year DateTime.utc_now().year
@settings_slots_nerves_key [8, 7, 6, 5]
@settings_slot_trust_and_go 8
@typedoc "Which device/signer certificate pair to use"
@type certificate_pair() :: :primary | :aux
@typedoc "Which type of device to use"
@type device_type() :: :nerves_key | :trust_and_go
@doc """
Detect if a NervesKey is available on the transport
"""
@spec detected?(ATECC508A.Transport.t()) :: boolean()
defdelegate detected?(transport), to: ATECC508A.Transport
@doc """
Check whether the NervesKey has been provisioned
"""
@spec provisioned?(ATECC508A.Transport.t()) :: boolean()
def provisioned?(transport) do
{:ok, config} = ATECC508A.Configuration.read(transport)
# If the OTP and data sections are locked, then this chip has been provisioned.
config.lock_value == 0
end
@doc """
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
"""
@spec create_signing_key_pair(keyword()) :: {X509.Certificate.t(), X509.PrivateKey.t()}
def create_signing_key_pair(opts \\ []) do
years_valid = Keyword.get(opts, :years_valid, 1)
ATECC508A.Certificate.new_signer(years_valid)
end
@doc """
Read the manufacturer's serial number
"""
@spec manufacturer_sn(ATECC508A.Transport.t(), device_type()) :: binary()
def manufacturer_sn(transport, type \\ :nerves_key)
def manufacturer_sn(transport, :nerves_key) do
{:ok, %OTP{manufacturer_sn: serial_number}} = OTP.read(transport)
serial_number
end
def manufacturer_sn(transport, :trust_and_go) do
{:ok, config} = ATECC508A.Configuration.read(transport)
%ATECC508A.Configuration{serial_number: sn_bytes} = config
Base.encode16(sn_bytes)
end
@doc """
IEEE EUI-48 MAC address that can be used as a unique identifier in LAN networking
This is only available on `:trust_and_go`
"""
def manufacturer_mac(transport, :trust_and_go) do
{:ok, <<eui48::bytes-12, _::binary>>} = ATECC508A.DataZone.read(transport, 5)
eui48
end
@doc """
Sign a SHA256 digest
"""
@spec sign_digest(ATECC508A.Transport.t(), binary()) ::
{:ok, binary()} | {:error, atom()}
def sign_digest(transport, digest) do
private_key_slot_id = 0
ATECC508A.Request.sign_digest(transport, private_key_slot_id, digest)
end
@doc """
Return ssl_opts for using the NervesKey
Pass an engine and optionally which certificate that you'd like to use.
"""
@spec ssl_opts(ATECC508A.Transport.t(), certificate_pair(), device_type()) :: keyword()
def ssl_opts(transport, which \\ :primary, type \\ :nerves_key) do
{:ok, engine} = NervesKey.PKCS11.load_engine()
cert =
NervesKey.device_cert(transport, which, type)
|> X509.Certificate.to_der()
signer_cert =
NervesKey.signer_cert(transport, which, type)
|> X509.Certificate.to_der()
transport_info = ATECC508A.Transport.info(transport)
key =
NervesKey.PKCS11.private_key(engine, i2c: i2c_instance(transport_info.bus_name), type: type)
cacerts = [signer_cert]
[key: key, cert: cert, cacerts: cacerts]
end
defp i2c_instance(<<"i2c-", instance::binary>>) do
String.to_integer(instance)
end
@doc """
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, ...}
```
"""
@spec device_cert(ATECC508A.Transport.t(), certificate_pair(), device_type()) ::
X509.Certificate.t()
def device_cert(transport, which \\ :primary, type \\ :nerves_key)
def device_cert(transport, which, :nerves_key) do
{:ok, device_sn} = Config.device_sn(transport)
{:ok, device_data} = ATECC508A.DataZone.read(transport, Data.device_cert_slot(which))
{:ok, <<signer_public_key_raw::64-bytes, _pad::8-bytes>>} =
ATECC508A.DataZone.read(transport, Data.signer_pubkey_slot(which))
signer_public_key = ATECC508A.Certificate.raw_to_public_key(signer_public_key_raw)
{:ok, %OTP{manufacturer_sn: serial_number}} = OTP.read(transport)
{:ok, public_key_raw} = Data.genkey_raw(transport, false)
template = ATECC508A.Certificate.NervesKeyTemplate.device(serial_number, signer_public_key)
compressed = %ATECC508A.Certificate.Compressed{
data: device_data,
device_sn: device_sn,
public_key: public_key_raw,
template: template,
issuer_rdn: X509.RDNSequence.new("/CN=Signer", :otp),
subject_rdn: X509.RDNSequence.new("/CN=" <> serial_number, :otp)
}
ATECC508A.Certificate.decompress(compressed)
end
def device_cert(transport, which, :trust_and_go) do
{:ok, device_sn} = NervesKey.Config.device_sn(transport)
{:ok, device_data} =
ATECC508A.DataZone.read(transport, NervesKey.Data.device_cert_slot(which))
{:ok,
<<_pad1::bytes-4, signer_public_key_raw_x::bytes-32, _pad2::bytes-4,
signer_public_key_raw_y::bytes-32>>} =
ATECC508A.DataZone.read(transport, NervesKey.Data.signer_pubkey_slot(which))
signer_public_key_raw = signer_public_key_raw_x <> signer_public_key_raw_y
{:ok, public_key_raw} = NervesKey.Data.genkey_raw(transport, false)
<<
_compressed_signature::binary-size(64),
_compressed_validity::binary-size(3),
signer_id::size(16),
template_id::size(4),
_chain_id::size(4),
_serial_number_source::size(4),
_format_version::size(4),
0::size(8)
>> = device_data
aki = :crypto.hash(:sha, <<4>> <> signer_public_key_raw)
ski = :crypto.hash(:sha, <<4>> <> public_key_raw)
signer_id_hex_str = Integer.to_string(signer_id, 16)
eui48 = manufacturer_mac(transport, :trust_and_go)
template =
ATECC508A.Certificate.TrustAndGoTemplate.device(
device_sn,
signer_id,
template_id,
"eui48_#{eui48}",
ski,
aki
)
issuer_rdn =
X509.RDNSequence.new(
"/O=Microchip Technology Inc/CN=Crypto Authentication Signer #{signer_id_hex_str}",
:otp
)
subject_rdn =
X509.RDNSequence.new(
"/O=Microchip Technology Inc/CN=sn" <> Base.encode16(device_sn),
:otp
)
compressed = %ATECC508A.Certificate.Compressed{
data: device_data,
device_sn: device_sn,
public_key: public_key_raw,
template: template,
issuer_rdn: issuer_rdn,
subject_rdn: subject_rdn
}
ATECC508A.Certificate.decompress(compressed)
end
@doc """
Read the signer certificate from the slot
"""
@spec signer_cert(ATECC508A.Transport.t(), certificate_pair(), device_type()) ::
X509.Certificate.t()
def signer_cert(transport, which \\ :primary, type \\ :nerves_key)
def signer_cert(transport, which, :nerves_key) do
{:ok, signer_data} = ATECC508A.DataZone.read(transport, Data.signer_cert_slot(which))
{:ok, <<signer_public_key_raw::64-bytes, _pad::8-bytes>>} =
ATECC508A.DataZone.read(transport, Data.signer_pubkey_slot(which))
signer_public_key = ATECC508A.Certificate.raw_to_public_key(signer_public_key_raw)
template = ATECC508A.Certificate.NervesKeyTemplate.signer(signer_public_key)
compressed = %ATECC508A.Certificate.Compressed{
data: signer_data,
public_key: signer_public_key_raw,
template: template,
issuer_rdn: X509.RDNSequence.new("/CN=Signer", :otp),
subject_rdn: X509.RDNSequence.new("/CN=Signer", :otp)
}
ATECC508A.Certificate.decompress(compressed)
end
def signer_cert(transport, which, :trust_and_go) do
{:ok, signer_data} = ATECC508A.DataZone.read(transport, Data.signer_cert_slot(which))
{:ok,
<<_pad1::bytes-4, signer_public_key_raw_x::bytes-32, _pad2::bytes-4,
signer_public_key_raw_y::bytes-32>>} =
ATECC508A.DataZone.read(transport, Data.signer_pubkey_slot(which))
signer_public_key_raw = signer_public_key_raw_x <> signer_public_key_raw_y
<<
_compressed_signature::binary-size(64),
_compressed_validity::binary-size(3),
signer_id::size(16),
_template_id::size(4),
_chain_id::size(4),
_serial_number_source::size(4),
_format_version::size(4),
0::size(8)
>> = signer_data
root_public_key_raw =
<<189, 84, 230, 109, 227, 135, 84, 132, 0, 107, 83, 174, 21, 128, 213, 10, 160, 105, 231,
138, 223, 85, 120, 216, 92, 226, 213, 77, 213, 184, 48, 41, 107, 255, 221, 110, 111, 114,
86, 251, 217, 158, 241, 161, 22, 177, 29, 51, 173, 73, 16, 58, 161, 133, 135, 57, 220,
250, 228, 55, 225, 157, 99, 78>>
aki = :crypto.hash(:sha, <<4>> <> root_public_key_raw)
ski = :crypto.hash(:sha, <<4>> <> signer_public_key_raw)
template = ATECC508A.Certificate.TrustAndGoTemplate.signer(signer_id, ski, aki)
signer_id_hex_str = Integer.to_string(signer_id, 16)
issuer_rdn =
X509.RDNSequence.new(
"/O=Microchip Technology Inc/CN=Crypto Authentication Root CA 002",
:otp
)
subject_rdn =
X509.RDNSequence.new(
"/O=Microchip Technology Inc/CN=Crypto Authentication Signer #{signer_id_hex_str}",
:otp
)
compressed = %ATECC508A.Certificate.Compressed{
data: signer_data,
public_key: signer_public_key_raw,
template: template,
issuer_rdn: issuer_rdn,
subject_rdn: subject_rdn
}
ATECC508A.Certificate.decompress(compressed)
end
@doc """
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.
"""
@spec provision(
ATECC508A.Transport.t(),
ProvisioningInfo.t(),
X509.Certificate.t(),
X509.PrivateKey.t()
) :: :ok
def provision(transport, info, signer_cert, signer_key) do
check_time()
:ok = configure(transport)
otp_info = OTP.new(info.board_name, info.manufacturer_sn)
otp_data = OTP.to_raw(otp_info)
:ok = OTP.write(transport, otp_data)
{:ok, device_public_key} = Data.genkey(transport)
{:ok, device_sn} = Config.device_sn(transport)
device_cert =
ATECC508A.Certificate.new_device(
device_public_key,
device_sn,
info.manufacturer_sn,
signer_cert,
signer_key
)
slot_data = Data.slot_data(device_sn, device_cert, signer_cert)
:ok = Data.write_slots(transport, slot_data)
# This is the point of no return!!
# Lock the data and OTP zones
:ok = Data.lock(transport, otp_data, slot_data)
# Lock the slot that contains the private key to prevent calls to GenKey
# from changing it. See datasheet for how GenKey doesn't check the zone
# lock.
:ok = ATECC508A.Request.lock_slot(transport, 0)
end
@doc """
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 provision_aux_certificates(
ATECC508A.Transport.t(),
X509.Certificate.t(),
X509.PrivateKey.t(),
device_type()
) :: :ok
def provision_aux_certificates(transport, signer_cert, signer_key, type \\ :nerves_key) do
check_time()
manufacturer_sn =
if type == :nerves_key do
manufacturer_sn(transport)
else
manufacturer_mac(transport, :trust_and_go)
end
{:ok, device_public_key} = Data.genkey(transport, false)
{:ok, device_sn} = Config.device_sn(transport)
device_cert =
ATECC508A.Certificate.new_device(
device_public_key,
device_sn,
manufacturer_sn,
signer_cert,
signer_key
)
Data.write_aux_certs(transport, device_sn, device_cert, signer_cert)
end
@doc """
Clear out the auxiliary certificates
This function overwrites the auxiliary certificate slots with
"""
@spec clear_aux_certificates(ATECC508A.Transport.t()) :: :ok
def clear_aux_certificates(transport) do
Data.clear_aux_certs(transport)
end
@doc """
Check whether the auxiliary certificates were programmed
"""
@spec has_aux_certificates?(ATECC508A.Transport.t()) :: boolean()
def has_aux_certificates?(transport) do
slot = Data.device_cert_slot(:aux)
slot_size = ATECC508A.DataZone.slot_size(slot)
{:ok, slot_contents} = ATECC508A.DataZone.read(transport, slot)
slot_contents != <<0::size(slot_size)-unit(8)>>
end
@doc """
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 default_info(ATECC508A.Transport.t()) :: ProvisioningInfo.t()
def default_info(transport) do
{:ok, sn} = Config.device_sn(transport)
%ProvisioningInfo{manufacturer_sn: Base.encode32(sn, padding: false), board_name: "NervesKey"}
end
@doc """
Return the max length of settings
"""
@spec max_settings_len(device_type()) :: integer()
def max_settings_len(:nerves_key) do
Enum.reduce(@settings_slots_nerves_key, 0, fn slot, acc ->
acc + ATECC508A.DataZone.slot_size(slot)
end)
end
def max_settings_len(:trust_and_go) do
ATECC508A.DataZone.slot_size(@settings_slot_trust_and_go)
end
@doc """
Return the settings block as a binary
"""
@spec get_raw_settings(ATECC508A.Transport.t(), device_type()) ::
{:ok, binary()} | {:error, atom()}
def get_raw_settings(transport, device_type \\ :nerves_key) do
if device_type == :nerves_key do
all_reads = Enum.map(@settings_slots_nerves_key, &ATECC508A.DataZone.read(transport, &1))
case Enum.find(all_reads, fn {result, _} -> result != :ok end) do
nil ->
raw = Enum.map_join(all_reads, fn {:ok, contents} -> contents end)
{:ok, raw}
error ->
error
end
else
case ATECC508A.DataZone.read(transport, @settings_slot_trust_and_go) do
{:ok, data} ->
{:ok, data}
error ->
error
end
end
end
@doc """
Return all of the setting stored in the NervesKey as a map
"""
@spec get_settings(ATECC508A.Transport.t(), device_type()) :: {:ok, map()} | {:error, atom()}
def get_settings(transport, device_type \\ :nerves_key) do
with {:ok, raw_settings} <- get_raw_settings(transport, device_type) do
try do
settings = :erlang.binary_to_term(raw_settings, [:safe])
{:ok, settings}
catch
_, _ -> {:error, :corrupt}
end
end
end
@doc """
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.
"""
@spec put_settings(ATECC508A.Transport.t(), map(), device_type()) :: :ok
def put_settings(transport, settings, device_type \\ :nerves_key) when is_map(settings) do
raw_settings = :erlang.term_to_binary(settings)
put_raw_settings(transport, raw_settings, device_type)
end
@doc """
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.
"""
@spec put_raw_settings(ATECC508A.Transport.t(), binary(), device_type()) :: :ok
def put_raw_settings(transport, raw_settings, device_type) when is_binary(raw_settings) do
if byte_size(raw_settings) > max_settings_len(device_type) do
raise "Settings are too large and won't fit in the NervesKey. The max raw size is #{max_settings_len(device_type)}."
end
padded_settings = pad(raw_settings, max_settings_len(device_type))
slots =
case device_type do
:nerves_key -> break_into_slots(padded_settings, @settings_slots_nerves_key)
:trust_and_go -> break_into_slots(padded_settings, [@settings_slot_trust_and_go])
end
Enum.each(slots, fn {slot, data} -> ATECC508A.DataZone.write(transport, slot, data) end)
end
defp pad(bin, len) when byte_size(bin) < len do
to_pad = 8 * (len - byte_size(bin))
<<bin::binary, 0::size(to_pad)>>
end
defp pad(bin, _len), do: bin
defp break_into_slots(bin, slots) do
break_into_slots(bin, slots, [])
|> Enum.reverse()
end
defp break_into_slots(<<>>, [], result), do: result
defp break_into_slots(bin, [slot | rest], result) do
slot_len = ATECC508A.DataZone.slot_size(slot)
{contents, next} = :erlang.split_binary(bin, slot_len)
break_into_slots(next, rest, [{slot, contents} | result])
end
# Configure an ATECC508A or ATECC608A as a NervesKey.
#
# This is called from `provision/4`. It can be called multiple
# times and so long as the part is configured in a compatible
# way, then it succeeds. This is needed to recover from failures
# in the provisioning process.
defp configure(transport) do
cond do
Config.config_compatible?(transport) == {:ok, true} -> :ok
Config.configured?(transport) == {:ok, true} -> {:error, :config_locked}
true -> Config.configure(transport)
end
end
defp check_time() do
unless DateTime.utc_now().year >= @build_year do
raise """
It doesn't look like the clock has been set. Check that `nerves_time` is running
or something else is providing time.
"""
end
end
end
