API

adafruit_atecc

CircuitPython module for the Microchip ATECCx08A Cryptographic Co-Processor

  • Author(s): Brent Rubell

Implementation Notes

Software and Dependencies:

class adafruit_atecc.adafruit_atecc.ATECC(i2c_bus: I2C, address: int = 96, debug: bool = False)

CircuitPython interface for ATECCx08A Crypto Co-Processor Devices.

counter(counter: int = 0, increment_counter: bool = True) → bytearray

Reads the binary count value from one of the two monotonic counters located on the device within the configuration zone. The maximum value that the counter may have is 2,097,151.

Parameters:

  • counter (int) – Device’s counter to increment.

  • increment_counter (bool) – Increments the value of the counter specified.

Returns:

bytearray with the count

ecdsa_sign(slot: int, message: bytearray) → bytearray

Generates and returns a signature using the ECDSA algorithm.

Parameters:

  • slot (int) – Which ECC slot to use.

  • message (bytearray) – Message to be signed.

Returns:

bytearray containing the signature

gen_key(key: bytearray, slot_num: int, private_key: bool = False) → bytearray

Generates a private or public key.

Parameters:

  • key – Buffer to put the key into

  • slot_num (int) – ECC slot (from 0 to 4).

  • private_key (bool) – Generates a private key if true.

Returns:

The requested key

idle()

Puts the chip into idle mode until wakeup is called.

info(mode: int, param: Any | None = None) → bytearray

Returns device state information

Parameters:

  • mode (int) – Mode encoding, see Table 9-26.

  • param – Optional parameter

Returns:

bytearray containing the response

lock(zone: int)

Locks specific ATECC zones. :param int zone: ATECC zone to lock.

lock_all_zones()

Locks Config, Data and OTP Zones.

property locked

Returns if the ATECC is locked.

nonce(data: bytearray, mode: int = 0, zero: int = 0) → bytearray

Generates a nonce by combining internally generated random number with an input value.

Parameters:

  • data (bytearray) – Input value from system or external.

  • mode (int) – Controls the internal RNG and seed mechanism.

  • zero (int) – Param2, see Table 9-35.

Returns:

bytearray containing the calculated nonce

random(rnd_min: int = 0, rnd_max: int = 0) → int

Generates a random number for use by the system.

Parameters:

  • rnd_min (int) – Minimum Random value to generate.

  • rnd_max (int) – Maximum random value to generate.

Returns:

Random integer

property serial_number

Returns the ATECC serial number.

sha_digest(message: bytearray = None) → bytearray

Returns the digest of the data passed to the sha_update method so far.

Parameters:

message (bytearray) – Up to 64 bytes of data to be included into the hash operation.

Returns:

bytearray containing the digest

sha_start() → bytearray

Initializes the SHA-256 calculation engine and the SHA context in memory. This method MUST be called before sha_update or sha_digest

sha_update(message: bytes) → bytearray

Appends bytes to the message. Can be repeatedly called.

Parameters:

message (bytes) – Up to 64 bytes of data to be included into the hash operation.

Returns:

bytearray containing the status

sign(slot_id: int) → bytearray

Performs ECDSA signature calculation with key in provided slot.

Parameters:

slot_id (int) – ECC slot containing key for use with signature.

Returns:

bytearray containing the signature

sleep()

Puts the chip into low-power sleep mode until wakeup is called.

version()

Returns the ATECC608As revision number

wakeup()

Wakes up THE ATECC608A from sleep or idle modes.

write_config(data: bytearray)

Writes configuration data to the device’s EEPROM.

Parameters:

data (bytearray) – Configuration data to-write

adafruit_atecc.adafruit_atecc.EXEC_TIME = {micropython.const: micropython.const, micropython.const: micropython.const, micropython.const: micropython.const, micropython.const: micropython.const, micropython.const: micropython.const, micropython.const: micropython.const, micropython.const: micropython.const, micropython.const: micropython.const, micropython.const: micropython.const}

Configuration Zone Bytes

Serial Number (Bytes 0-3 and 8-12), Revision Number (Bytes 4-7) AES Enable (Byte 13), I2C Enable (Byte 14), Reserved (Byte 15) I2C Address (Byte 16), Reserved (Byte 17); Count Match (Byte 18) Chip Mode (Byte 19), Slot Config (Bytes 20-51) Counter 0 (Bytes 52-59), Counter 1 (Bytes 60-67) Use Lock (Byte 68), Volatile Key Permission (Byte 69) Secure Boot (Bytes 70-71), KDF (Bytes 72-74) Reserved (Bytes 75-83), User Extra (Bytes 84-85) Lock Config (Bytes 86-89), Chip Options (Bytes 90-91) X509 (Bytes 92-95), Key Config (Bytes 96-127)

I2C Config

HEX

DEC

BIN

Description

Byte 14: C0

192
1100 0000

^xxx xxxx

Bit 0 (MSB): 0:Single Wire, 1:I2C; Bit 1-7: Set by Microchip

Byte 16: C0

192

1100 0000

Default 7 bit I2C Address: 0xC0>>1: 0x60 ATECC608A-MAHDA

Byte 16: 6A

106

0110 1010

Default 7 bit I2C Address: 0x6A>>1: 0x35 ATECC608A-TNGTLS

Byte 16: 20

32

0010 0000

Default 7 bit I2C Address: 0x20>>1: 0x10 ATECC608A-UNKNOWN

adafruit_atecc_asn1

ASN.1 Utilities for the Adafruit_ATECC Module.

  • Author(s): Brent Rubell

Implementation Notes

Software and Dependencies:

adafruit_atecc.adafruit_atecc_asn1.get_issuer_or_subject(data: bytearray, country: str, state_prov: str, locality: str, org: str, org_unit: str, common: str)

Appends issuer or subject, if they exist, to data.

Parameters:

  • data (bytearray) – buffer to append to

  • country (str) – The country to append to the buffer

  • state_prov (str) – The state/province to append to the buffer

  • locality (str) – The locality to append to the buffer

  • org (str) – The organization to append to the buffer

  • org_unit (str) – The organizational unit to append to the buffer

  • common (str) – The common data to append to the buffer

adafruit_atecc.adafruit_atecc_asn1.get_name(name: str, obj_type: int, data: bytearray) → int

Appends ASN.1 string in form: set -> seq -> objid -> string

Parameters:

  • name (str) – String to append to buffer.

  • obj_type (int) – Object identifier type.

  • data (bytearray) – Buffer to write to.

Returns:

Length of the updated buffer

adafruit_atecc.adafruit_atecc_asn1.get_public_key(data: bytearray, public_key: bytearray) → None

Appends public key subject and object identifiers.

Parameters:
adafruit_atecc.adafruit_atecc_asn1.get_sequence_header(length: int, data: bytearray) → None

Appends sequence header to provided data.

Parameters:

  • length (int) – Length of the buffer

  • data (bytearray) – The buffer

adafruit_atecc.adafruit_atecc_asn1.get_sequence_header_length(seq_header_len: int) → int

Returns length of SEQUENCE header.

Parameters:

seq_header_len (int) – Sequence header length

Returns:

Length of the sequence header

adafruit_atecc.adafruit_atecc_asn1.get_signature(signature: bytearray, data: bytearray) → int

Appends signature data to buffer.

Parameters:

  • signature (bytearray) – The signature to append

  • data (bytearray) – The buffer to append the signature to

Returns:

Updated length of the buffer

adafruit_atecc.adafruit_atecc_asn1.get_signature_length(signature: bytearray) → int

Return length of ECDSA signature.

Parameters:

signature (bytearray) – Signed SHA256 hash.

Returns:

length of ECDSA signature.

adafruit_atecc.adafruit_atecc_asn1.get_version(data: bytearray) → None

Appends X.509 version to data.

Parameters:

data (bytearray) – Buffer to append the version to

adafruit_atecc.adafruit_atecc_asn1.issuer_or_subject_length(country: str, state_prov: str, city: str, org: str, org_unit: str, common: str) → int

Returns total length of provided certificate information.

Parameters:

  • country (str) – Country of certificate

  • state_prov (str) – State/province of certificate

  • city (str) – City of certificate

  • org (str) – Organization of certificate

  • org_unit (str) – Organization unit of certificate

  • common (str) – Common data of certificate

Raises:

TypeError if return value is 0

Returns:

Total length of provided certificate information.

adafruit_atecc_cert_util

Certification Generation and Helper Utilities for the Adafruit_ATECC Module.

  • Author(s): Brent Rubell

Implementation Notes

Software and Dependencies:

class adafruit_atecc.adafruit_atecc_cert_util.CSR(atecc: ATECC, slot_num: int, private_key: bool, country: str, state_prov: str, city: str, org: str, org_unit: str)

Certificate Signing Request Builder.

Parameters:

  • atecc (adafruit_atecc) – ATECC module.

  • slot_num – ATECC module slot (from 0 to 4).

  • private_key (bool) – Generate a new private key in selected slot?

  • country (str) – 2-letter country code.

  • state_prov (str) – State or Province name,

  • city (str) – City name.

  • org (str) – Organization name.

  • org_unit (str) – Organizational unit name.

generate_csr() → bytearray

Generates and returns a certificate signing request.