m5::unit::UnitATECC608B Class Reference

ATECC608B unit. More...

#include <unit_ATECC608B.hpp>

Inheritance diagram for m5::unit::UnitATECC608B:

Classes
struct	config_t
	Settings for begin. More...

Public Member Functions
	UnitATECC608B (const uint8_t addr=DEFAULT_ADDRESS)
virtual bool	begin () override
const uint8_t *	revision () const
	Get the revison.
uint16_t	getSlotSize (const atecc608::Slot slot) const
	Gets the size of the specified data slot in bytes.
Settings for begin
config_t	config ()
	Gets the configration.
void	config (const config_t &cfg)
	Set the configration.
State transition
bool	wakeup ()
	Device to active.
bool	idle ()
	Device to idle.
bool	sleep ()
	Device to sleep.
Counter
bool	readCounter (uint32_t &value, const uint8_t target)
	Read the counter value.
bool	incrementCounter (uint32_t &value, const uint8_t target)
	Increment counter.
Info
bool	readRevision (uint8_t data[4])
	Read the revision.
bool	readKeyValid (bool &valid, const atecc608::Slot slot)
	Read the KeyValid.
bool	readDeviceState (uint16_t &state)
	Read the device state.
Nonce
bool	createNonce (uint8_t output[32], const uint8_t input[20], const bool useRNG=true, const bool updateSeed=true)
	Create nonce to TempKey by input data with RNG or TempKey.
bool	writeNonce32 (const atecc608::Destination dest, const uint8_t input[32])
	write nonce 32 bytes
bool	writeNonce64 (const atecc608::Destination dest, const uint8_t input[64])
	write nonce 64 bytes
Random
bool	readRandomArray (uint8_t data[32], const bool updateSeed=true)
	Read TRNG output.
template<typename T , typename std::enable_if< std::is_integral< T >::value, std::nullptr_t >::type = nullptr>
bool	readRandom (T &value, const T lower, const T upper)
	Generate a random value of type T in the specified range.
template<typename T , typename std::enable_if< std::is_floating_point< T >::value, std::nullptr_t >::type = nullptr>
bool	readRandom (T &value, const T lower, const T upper)
	Generate a random floating-point value in the specified range.
template<typename T , typename std::enable_if< std::is_integral< T >::value, std::nullptr_t >::type = nullptr>
bool	readRandom (T &value)
	Generate a random integral value covering the entire valid range of type T.
template<typename T , typename std::enable_if< std::is_floating_point< T >::value, std::nullptr_t >::type = nullptr>
bool	readRandom (T &value)
	Generate a random floating-point value covering the full range of T.
Read
bool	readConfigZone (uint8_t config[128])
	Read the config zone.
bool	readSerialNumber (uint8_t sn[9])
	Read the serial number.
bool	readSerialNumber (char str[19])
	Read the serial number as string.
bool	readZoneLocked (bool &configLocked, bool &dataLocked)
	Read the lock state for zone.
bool	readSlotLocked (uint16_t &slotLockedBits)
	Read the lock state for data zone.
bool	readSlotConfig (uint16_t &cfg, const atecc608::Slot slot)
	Read the SlotConfig.
bool	readKeyConfig (uint16_t &cfg, const atecc608::Slot slot)
	Read the KeyConfig.
bool	readDataZone (uint8_t *data, const uint16_t len, const atecc608::Slot slot)
	Read the data zone.
bool	readOTPZone (uint8_t otp[64])
	Read the OTP zone @paran[out] Output buffer at least 64 bytes.
SelfTest
bool	selfTest (uint8_t resultBits, const uint8_t testBits=0x3D)
	Self test.
SHA256
bool	startSHA256 ()
	Start calculate SHA256.
bool	updateSHA256 (const uint8_t *msg, const uint32_t mlen)
	Update calculate SHA256.
bool	finalizeSHA256 (const atecc608::Destination dest, uint8_t digest[32])
	Finalize calculate SHA256.
bool	SHA256 (const atecc608::Destination dest, uint8_t digest[32], const uint8_t *msg, const uint32_t mlen)
	Calculate SHA256.
ECDH
Warning For TNGTLS, the ECDH command may be run using the ECC private keys stored in Slots 0 and 2-4
bool	ECDHStoredKey (uint8_t out[32], const atecc608::Slot slot, const uint8_t pubKey[64])
	ECDH (Plane text)
bool	ECDHStoredKey (uint8_t out[32], uint8_t nonce[32], const atecc608::Slot slot, const uint8_t pubKey[64])
	ECDH (Encrypted)
bool	ECDHStoredKey (const atecc608::Slot slot, const uint8_t pubKey[64])
	ECDH (Stored in TempKey)
bool	ECDHTempKey (uint8_t out[32], const uint8_t pubKey[64])
	ECDH (Plane text)
bool	ECDHTempKey (uint8_t out[32], uint8_t nonce[32], const uint8_t pubKey[64])
	ECDH (Encrypted)
bool	ECDHTempKey (const uint8_t pubKey[64])
	ECDH (Stored in to TempKey)
bool	ECDHTempKey (const atecc608::Slot slot, const uint8_t pubKey[64])
	ECDH(Stored in slot)
GenKey
bool	generatePrivateKey (const atecc608::Slot slot, uint8_t pubKey[64], const bool digest=false)
	Generate the private key stored in slot.
bool	generateKey (uint8_t pubKey[64])
	Make disposable private key to TempKey and output public key.
bool	generatePublicKey (uint8_t pubKey[64], const atecc608::Slot slot, const bool digest=false)
	Generate the public key from private key in slot.
bool	generatePublicKeyDigest (const atecc608::Slot slot, const uint8_t otherData[3]=nullptr)
	Generate digest of a public key and stored in TempKey.
Sign
bool	signInternal (uint8_t signature[64], const atecc608::Slot slot, const atecc608::Source src, const bool includeSerial=false)
	Sign internal message.
bool	signExternal (uint8_t signature[64], const atecc608::Slot slot, const atecc608::Source src, const bool includeSerial=false)
	Sign external message.
Verify
bool	verifyExternal (uint8_t mac[32], const uint8_t signature[64], const uint8_t pubKey[64], const atecc608::Source src)
	Verify the external public key.
bool	verifyStored (uint8_t mac[32], const uint8_t signature[64], const atecc608::Slot slot, const atecc608::Source src)
	Verify the stored publick key.

Protected Member Functions
virtual bool	begin_impl ()
bool	send_command (const uint8_t opcode, const uint8_t param1=0, const uint16_t param2=0, const uint8_t *data=nullptr, uint32_t dlen=0)
bool	receive_response (uint8_t *data, const uint32_t dlen)
bool	counter (uint32_t &value, const uint8_t counter, const uint8_t mode)
bool	write_nonce (const atecc608::Destination dest, const uint8_t *input, const uint32_t ilen)
bool	read_data (uint8_t *rbuf, const uint32_t rlen, const uint8_t zone, const uint16_t address, const uint32_t delayMs=3)
bool	read_slot_config_word (uint16_t &cfg, const uint8_t baseOffset, const atecc608::Slot slot)
virtual bool	ecdh_receive32 (uint8_t out[32], const uint8_t mode, const uint16_t param2, const uint8_t pubKey[64])
virtual bool	ecdh_receive32x2 (uint8_t out[32], uint8_t nonce[32], const uint8_t mode, const uint16_t param2, const uint8_t pubKey[64])
virtual bool	ecdh_no_output (const uint8_t mode, const uint16_t param2, const uint8_t pubKey[64])
virtual bool	generate_key (uint8_t pubKey[64], const uint8_t mode, const uint16_t param2=0x0000, const uint8_t *data=nullptr, const uint32_t dlen=0)
virtual bool	sign (uint8_t signature[64], const uint8_t mode, const uint16_t param2, const atecc608::Source src)
bool	verify (uint8_t mac[32], const uint8_t mode, const uint16_t param2, const uint8_t signature[64], const uint8_t pubKey[64], const atecc608::Source src)

Detailed Description

ATECC608B unit.

ATECC608B-TNGTLS unit.

Member Function Documentation

createNonce()

bool m5::unit::UnitATECC608B::createNonce	(	uint8_t	output[32],
		const uint8_t	input[20],
		const bool	useRNG = true,
		const bool	updateSeed = true )

Create nonce to TempKey by input data with RNG or TempKey.

Parameters

[out]	output	Output buffer at least 32 bytes if not nullptr
	input	Input buffer at least 20 bytes
	useRNG	Using TRNG if true, Using TempKey if false
	updateSeed	Update seed if true

Returns

True if successful

Warning

If useRNG is false, TempKey must already have a valid value

ECDHStoredKey() [1/3]

bool m5::unit::UnitATECC608B::ECDHStoredKey ( const atecc608::Slot slot, const uint8_t pubKey[64] )

inline

ECDH (Stored in TempKey)

Parameters

slot	ECC private key source Slot
pubKey	Public key

Returns

True if successful

ECDHStoredKey() [2/3]

bool m5::unit::UnitATECC608B::ECDHStoredKey ( uint8_t out[32], const atecc608::Slot slot, const uint8_t pubKey[64] )

inline

ECDH (Plane text)

Parameters

[out]	out	Shared Master Secret as clear text at least 32 bytes
	slot	ECC private key source Slot
	pubKey	Public key

Returns

True if successful

ECDHStoredKey() [3/3]

bool m5::unit::UnitATECC608B::ECDHStoredKey ( uint8_t out[32], uint8_t nonce[32], const atecc608::Slot slot, const uint8_t pubKey[64] )

inline

ECDH (Encrypted)

Parameters

[out]	out	Shared Master Secret as encrypted text at least 32 bytes
[out]	nonce	nonce used for encryption
	slot	ECC private key source Slot
	pubKey	Public key

Returns

True if successful

ECDHTempKey() [1/4]

bool m5::unit::UnitATECC608B::ECDHTempKey ( const atecc608::Slot slot, const uint8_t pubKey[64] )

inline

ECDH(Stored in slot)

Parameters

slot	Output slot
pubKey	Public key

Returns

True if successful

Note

TempKey as its starting value for an ECDH command

ECDHTempKey() [2/4]

bool m5::unit::UnitATECC608B::ECDHTempKey ( const uint8_t pubKey[64] )

inline

ECDH (Stored in to TempKey)

Parameters

pubKey

Public key

Returns

True if successful

Note

TempKey as its starting value for an ECDH command

ECDHTempKey() [3/4]

bool m5::unit::UnitATECC608B::ECDHTempKey ( uint8_t out[32], const uint8_t pubKey[64] )

inline

ECDH (Plane text)

Parameters

[out]	out	Shared Master Secret as clear text at least 32 bytes
	pubKey	Public key

Returns

True if successful

Note

TempKey as its starting value for an ECDH command

ECDHTempKey() [4/4]

bool m5::unit::UnitATECC608B::ECDHTempKey ( uint8_t out[32], uint8_t nonce[32], const uint8_t pubKey[64] )

inline

ECDH (Encrypted)

Parameters

[out]	out	Shared Master Secret as encrypted text at least 32 bytes
[out]	nonce	nonce used for encryption
	pubKey	Public key

Returns

True if successful

Note

TempKey as its starting value for an ECDH command

finalizeSHA256()

bool m5::unit::UnitATECC608B::finalizeSHA256	(	const atecc608::Destination	dest,
		uint8_t	digest[32] )

Finalize calculate SHA256.

Parameters

	dest	Output destination (Output buffer is always output)
[out]	digest	Output buffer at least 32 bytes

Returns

True if successful

generateKey()

bool m5::unit::UnitATECC608B::generateKey

(

uint8_t

pubKey[64]

)

Make disposable private key to TempKey and output public key.

Parameters

[out]

pubKey

Output buffer at least 64 bytes

Returns

True if successful

generatePrivateKey()

bool m5::unit::UnitATECC608B::generatePrivateKey ( const atecc608::Slot slot, uint8_t pubKey[64], const bool digest = false )

inline

Generate the private key stored in slot.

Parameters

	slot	Output slot
[out]	pubKey	Output buffer at least 64 bytes
	digest	Public key digest is generated and stored in TempKey if true

Returns

True if successful

Warning

For TNGTLS, the GenKey command can be used to generate private keys only in Slots 2, 3 and 4

generatePublicKey()

bool m5::unit::UnitATECC608B::generatePublicKey ( uint8_t pubKey[64], const atecc608::Slot slot, const bool digest = false )

inline

Generate the public key from private key in slot.

Parameters

[out]	pubKey	Output buffer at least 64 bytes
	slot	Private key Slot
	digest	Public key digest is generated and stored in TempKey if true

Returns

True if successful

generatePublicKeyDigest()

bool m5::unit::UnitATECC608B::generatePublicKeyDigest	(	const atecc608::Slot	slot,
		const uint8_t	otherData[3] = nullptr )

Generate digest of a public key and stored in TempKey.

Parameters

slot	Public key slot
otherData	Other data for use in digest calculations at leaset 3 byes (nullptrAllowed)

Returns

True if successful

Warning

For TNGTLS, a digest can be created from Slot 11

idle()

bool m5::unit::UnitATECC608B::idle

(

)

Device to idle.

Returns

True if successful

Note

Keep SRAM memory

incrementCounter()

bool m5::unit::UnitATECC608B::incrementCounter ( uint32_t & value, const uint8_t target )

inline

Increment counter.

Parameters

[out]	value	Counter value (incremented)
	target	Target counter (0 or 1)

Returns

True if successful

Note

The maximum value that the counter may have is 2097151 (0x1fffff)

readConfigZone()

bool m5::unit::UnitATECC608B::readConfigZone

(

uint8_t

config[128]

)

Read the config zone.

Parameters

[out]

config[128]

Output buffer at least 128 bytes

readCounter()

bool m5::unit::UnitATECC608B::readCounter ( uint32_t & value, const uint8_t target )

inline

Read the counter value.

Parameters

[out]	value	Counter value
	target	Target counter (0 or 1)

Returns

True if successful

Note

The maximum value that the counter may have is 2097151 (0x1fffff)

readDataZone()

bool m5::unit::UnitATECC608B::readDataZone	(	uint8_t *	data,
		const uint16_t	len,
		const atecc608::Slot	slot )

Read the data zone.

Parameters

[out]	data	Output buffer
	slot	Slot @patam len Buffer length

Returns

True if successful

Warning

For TNGTLS Only read slot are Slot 5,8,10,11,12

readDeviceState()

bool m5::unit::UnitATECC608B::readDeviceState

(

uint16_t &

state

)

Read the device state.

Parameters

[out]

state

Device status

Returns

True if successful

Note

Status flags

bit	name	decription
15	TempKey.NoMacFlag	Valid if 1
14	TempKey.GenKeyData	Valid if 1
13	TempKey.GenDigData	Valid if 1
12	TempKey.SourceFlag	1:TempKey is derived from external input 0:TempKey is derived from internal RNG only
11:8	TempKey.KeyID	TempKey keyslot ID
7	TempKey.Valid	Valid if 1
6:3	AuthComplete.KeyID	Authorization keyslot ID
2	AuthComplete.Valid	Valid if 1
1:0	No use	b00

readKeyConfig()

bool m5::unit::UnitATECC608B::readKeyConfig ( uint16_t & cfg, const atecc608::Slot slot )

inline

Read the KeyConfig.

Parameters

[out]	cfg	KeyConfig value
	slot	Slot

Returns

True if successful

readKeyValid()

bool m5::unit::UnitATECC608B::readKeyValid	(	bool &	valid,
		const atecc608::Slot	slot )

Read the KeyValid.

Is the ECC private or public key a valid ECC key?

Parameters

[out]	valid	ECC key is valid if true
	slot	Slot

Returns

True if successful

Warning

For TNGTLS device, the keys stored in Slots 1-4 are ECC keys that can be checked with theKeyValid mode of the Info command

readOTPZone()

bool m5::unit::UnitATECC608B::readOTPZone

(

uint8_t

otp[64]

)

Read the OTP zone @paran[out] Output buffer at least 64 bytes.

Returns

True if successful

readRandom() [1/4]

template<typename T , typename std::enable_if< std::is_integral< T >::value, std::nullptr_t >::type = nullptr>

bool m5::unit::UnitATECC608B::readRandom ( T & value )

inline

Generate a random integral value covering the entire valid range of type T.

Template Parameters

T	Type of the value (must be an integral type)

Parameters

[out]

value

The output variable to store the random value

Returns

True if successful

Note

Range is [lowest, max) - covers the full valid value space of T

readRandom() [2/4]

template<typename T , typename std::enable_if< std::is_floating_point< T >::value, std::nullptr_t >::type = nullptr>

bool m5::unit::UnitATECC608B::readRandom ( T & value )

inline

Generate a random floating-point value covering the full range of T.

Template Parameters

T	Type of the value (must be a floating-point type)

Parameters

[out]

value

The output variable to store the random value

Returns

True if successful

Note

Output range is [lowest, max)

readRandom() [3/4]

template<typename T , typename std::enable_if< std::is_integral< T >::value, std::nullptr_t >::type = nullptr>

bool m5::unit::UnitATECC608B::readRandom ( T & value, const T lower, const T upper )

inline

Generate a random value of type T in the specified range.

Template Parameters

T	Type of the value (must be an integral type)

Parameters

[out]	value	The output variable to store the random value
	lower	The lower bound (inclusive)
	upper	The upper bound (exclusive)

Returns

True if successful

Note

Output range is [lower, upper) - that is, lower <= value < upper

readRandom() [4/4]

template<typename T , typename std::enable_if< std::is_floating_point< T >::value, std::nullptr_t >::type = nullptr>

bool m5::unit::UnitATECC608B::readRandom ( T & value, const T lower, const T upper )

inline

Generate a random floating-point value in the specified range.

Template Parameters

T	Type of the value (must be a floating-point type)

Parameters

[out]	value	The output variable to store the random value
	lower	The lower bound (inclusive)
	upper	The upper bound (exclusive)

Returns

True if successful

Note

Output range is [lower, upper) - that is, lower <= value < upper

Warning

Note that if the difference between lower and higher is too large, nan/inf will result

readRandomArray()

bool m5::unit::UnitATECC608B::readRandomArray	(	uint8_t	data[32],
		const bool	updateSeed = true )

Read TRNG output.

Parameters

[out]

data

Output value (At least 32 bytes)

Returns

True if successful

readRevision()

bool m5::unit::UnitATECC608B::readRevision

(

uint8_t

data[4]

)

Read the revision.

Parameters

[out]

data[4]

Output buffer at least 4 bytes

Returns

True if successful

readSerialNumber() [1/2]

bool m5::unit::UnitATECC608B::readSerialNumber

(

char

str[19]

)

Read the serial number as string.

Parameters

[out]

str[9]

Output buffer at least 19 bytes

Returns

True if successful

readSerialNumber() [2/2]

bool m5::unit::UnitATECC608B::readSerialNumber

(

uint8_t

sn[9]

)

Read the serial number.

Parameters

[out]

sn[9]

Output buffer at least 9 bytes

Returns

True if successful

readSlotConfig()

bool m5::unit::UnitATECC608B::readSlotConfig ( uint16_t & cfg, const atecc608::Slot slot )

inline

Read the SlotConfig.

Parameters

[out]	cfg	SlotConfig value
	slot	Slot

Returns

True if successful

readSlotLocked()

bool m5::unit::UnitATECC608B::readSlotLocked

(

uint16_t &

slotLockedBits

)

Read the lock state for data zone.

Parameters

[out]

slotLockedBits

Bits representing the lock status of each slot

Returns

True if successful

readZoneLocked()

bool m5::unit::UnitATECC608B::readZoneLocked	(	bool &	configLocked,
		bool &	dataLocked )

Read the lock state for zone.

Parameters

[out]	configLocked	Configurate zone
[out]	dataLocked	Data zone

Returns

True if successful

revision()

const uint8_t * m5::unit::UnitATECC608B::revision ( ) const

inline

Get the revison.

Returns

uint8_t[4]

Warning

Void if obtained before begin()

selfTest()

bool m5::unit::UnitATECC608B::selfTest	(	uint8_t	resultBits,
		const uint8_t	testBits = 0x3D )

Self test.

Parameters

[out]	resultBits	The bit corresponding to a failed test is set
	testBits	Bits to be tested

Returns

True if successful

Note

bits

b[7:6]	b[5]	b[4]	b[3]	b[2]	b[1]	b[0]
00	SHA	AES	ECDH	EECDSA	0	RNG,DRBG

SHA256()

bool m5::unit::UnitATECC608B::SHA256 ( const atecc608::Destination dest, uint8_t digest[32], const uint8_t * msg, const uint32_t mlen )

inline

Calculate SHA256.

Parameters

	dest	Output destination (Output buffer is always output)
[out]	digest	Output buffer at least 32 bytes
	msg	Message
	mlen	Length of the message

Returns

True if successful

signExternal()

bool m5::unit::UnitATECC608B::signExternal ( uint8_t signature[64], const atecc608::Slot slot, const atecc608::Source src, const bool includeSerial = false )

inline

Sign external message.

Parameters

[out]	signature	Signature at least 64 butes
	slot	Private key slot used to sign the message
	src	Message source
	includeSerial	Serial number is included in the message digest calculation

Returns

True if successful

Warning

For TNGTLS device, Slots 0 and 2-4 are enabled to sign external messages

signInternal()

bool m5::unit::UnitATECC608B::signInternal ( uint8_t signature[64], const atecc608::Slot slot, const atecc608::Source src, const bool includeSerial = false )

inline

Sign internal message.

Parameters

[out]	signature	Signature at least 64 butes
	slot	Slot of the private key to be used to sign the message
	src	Message source
	includeSerial	Serial number is included in the message digest calculation

Returns

True if successful

Warning

For TNGTLS device, only Slot 1 is capable of signing internally generated messages

sleep()

bool m5::unit::UnitATECC608B::sleep

(

)

Device to sleep.

Returns

True if successful

Warning

Clear SRAM memory (TempKey,Message Digest Buffer,Alternate Key Buffer, SHA Context Buffer,...)

startSHA256()

bool m5::unit::UnitATECC608B::startSHA256

(

)

Start calculate SHA256.

Returns

True if successful

updateSHA256()

bool m5::unit::UnitATECC608B::updateSHA256	(	const uint8_t *	msg,
		const uint32_t	mlen )

Update calculate SHA256.

Parameters

msg	Message
mlen	Length of the message

Returns

True if successful

verifyExternal()

bool m5::unit::UnitATECC608B::verifyExternal ( uint8_t mac[32], const uint8_t signature[64], const uint8_t pubKey[64], const atecc608::Source src )

inline

Verify the external public key.

Parameters

[out]	mac	validating MAC output buffer if not nullptr
	signature	Signature to be verified
	pubKey	public key to be used for verification
	src	Message source

Returns

True if successful

verifyStored()

bool m5::unit::UnitATECC608B::verifyStored ( uint8_t mac[32], const uint8_t signature[64], const atecc608::Slot slot, const atecc608::Source src )

inline

Verify the stored publick key.

Parameters

[out]	mac	validating MAC output buffer if not nullptr
	signature	Signature to be verified
	slot	Slot containing the public key to be used for the verification
	src	Message source

Returns

True if successful

wakeup()

bool m5::unit::UnitATECC608B::wakeup

(

)

Device to active.

Returns

True if successful

Note

The following error message is output, but can be ignored

"write_with_transaction(): 2 endTransmission stop:1"

writeNonce32()

bool m5::unit::UnitATECC608B::writeNonce32 ( const atecc608::Destination dest, const uint8_t input[32] )

inline

write nonce 32 bytes

Parameters

dest	Output destination
input	Input buffer at least 32 bytes

Returns

True if successful

writeNonce64()

bool m5::unit::UnitATECC608B::writeNonce64 ( const atecc608::Destination dest, const uint8_t input[64] )

inline

write nonce 64 bytes

Parameters

dest	Output destination
input	Input buffer at least 64 bytes

Returns

True if successful