CryptoAuthLib
Atmel CryptoAuthentication Library
TLS integration with ATECC (atcatls_)

Instructions for integrating the ECC508 into a platform: More...

Data Structures

struct  TlsSlotDef
 

Macros

#define MEM_BLOCK_SIZE   ATCA_BLOCK_SIZE
 
#define TLS_RANDOM_SIZE   MEM_BLOCK_SIZE
 
#define PUB_KEY_SIZE   ATCA_PUB_KEY_SIZE
 
#define PRIV_KEY_SIZE   ATCA_PRIV_KEY_SIZE
 
#define SIGNATURE_SIZE   ATCA_SIG_SIZE
 
#define TLS_SLOT_AUTH_PRIV   ((uint8_t)0x0)
 Primary authentication private key. More...
 
#define TLS_SLOT_AUTH_PMK   ((uint8_t)0x1)
 Premaster key for ECDH cipher suites. More...
 
#define TLS_SLOT_ECDH_PRIV   ((uint8_t)0x2)
 ECDH private key. More...
 
#define TLS_SLOT_ECDHE_PRIV   ((uint8_t)0x2)
 ECDHE private key. More...
 
#define TLS_SLOT_ECDH_PMK   ((uint8_t)0x3)
 ECDH/ECDHE pmk slot. This slot is encrypted with encParentSlot. More...
 
#define TLS_SLOT_ENC_PARENT   ((uint8_t)0x4)
 The parent encryption key. This is a random key set on a per-platform basis. More...
 
#define TLS_SLOT_SHAKEY   ((uint8_t)0x5)
 SHA key slot. Used for SHA use cases. More...
 
#define TLS_SLOT_HOST_SHAKEY   ((uint8_t)0x6)
 Host SHA key slot. Used for host SHA use cases. More...
 
#define TLS_SLOT_FEATURE_PRIV   ((uint8_t)0x7)
 Feature private key. Used for feature use cases. More...
 
#define TLS_SLOT8_ENC_STORE   ((uint8_t)0x8)
 Encrypted storage for 416 bytes. More...
 
#define TLS_SLOT9_ENC_STORE   ((uint8_t)0x9)
 Encrypted storage for 72 bytes. More...
 
#define TLS_SLOT_AUTH_CERT   ((uint8_t)0xA)
 Compressed certificate information for the authPrivSlot. More...
 
#define TLS_SLOT_SIGNER_PUBKEY   ((uint8_t)0xB)
 Public key of the signer of authCertSlot. More...
 
#define TLS_SLOT_SIGNER_CERT   ((uint8_t)0xC)
 Compressed certificate information for the signerPubkey. More...
 
#define TLS_SLOT_FEATURE_CERT   ((uint8_t)0xD)
 Compressed certificate information for the featurePrivSlot. More...
 
#define TLS_SLOT_PKICA_PUBKEY   ((uint8_t)0xE)
 Public key for the PKI certificate authority. More...
 
#define TLS_SLOT_MFRCA_PUBKEY   ((uint8_t)0xF)
 Public key for the MFR certificate authority. More...
 

Typedefs

typedef ATCA_STATUSatcatlsfn_get_enckey) (uint8_t *enckey, int16_t keysize)
 

Functions

ATCA_STATUS atcatls_config_default (void)
 Configure the ECC508 for use with TLS API funcitons. The configuration zone is written and locked. All GenKey and slot initialization is done and then the data zone is locked. This configuration needs to be performed before the TLS API functions are called On a locked ECC508 device, this function will check the configuraiton against the default and fail if it does not match. More...
 
ATCA_STATUS atcatls_init (ATCAIfaceCfg *pCfg)
 Initialize the ECC508 for use with the TLS API. Like a constructor. More...
 
ATCA_STATUS atcatls_finish (void)
 Finalize the ECC508 when finished. Like a destructor. More...
 
ATCA_STATUS atcatls_sign (uint8_t slotid, const uint8_t *message, uint8_t *signature)
 Sign the message with the specified slot and return the signature. More...
 
ATCA_STATUS atcatls_verify (const uint8_t *message, const uint8_t *signature, const uint8_t *pubkey, bool *verified)
 Verify the signature of the specified message using the specified public key. More...
 
ATCA_STATUS atcatls_ecdh (uint8_t slotid, const uint8_t *pubkey, uint8_t *pmk)
 Generate a pre-master key (pmk) given a private key slot and a public key that will be shared with. More...
 
ATCA_STATUS atcatls_ecdh_enc (uint8_t slotid, uint8_t enckeyId, const uint8_t *pubkey, uint8_t *pmk)
 Generate a pre-master key (pmk) given a private key slot and a public key that will be shared with. More...
 
ATCA_STATUS atcatls_ecdhe (uint8_t slotid, const uint8_t *pubkey, uint8_t *pubkeyret, uint8_t *pmk)
 Generate a pre-master key (pmk) given a private key slot and a public key that will be shared with. More...
 
ATCA_STATUS atcatls_create_key (uint8_t slotid, uint8_t *pubkey)
 Create a unique public-private key pair in the specified slot. More...
 
ATCA_STATUS atcatls_calc_pubkey (uint8_t slotid, uint8_t *pubkey)
 Get the public key from the specified private key slot. More...
 
ATCA_STATUS atcatls_write_pubkey (uint8_t slotid, uint8_t pubkey[PUB_KEY_SIZE], bool lock)
 
ATCA_STATUS atcatls_read_pubkey (uint8_t slotid, uint8_t *pubkey)
 reads a pub key from a readable data slot versus atcab_get_pubkey which generates a pubkey from a private key slot More...
 
ATCA_STATUS atcatls_random (uint8_t *randout)
 Get a random number. More...
 
ATCA_STATUS atcatls_get_sn (uint8_t sn_out[ATCA_SERIAL_NUM_SIZE])
 Get the serial number of this device. More...
 
ATCA_STATUS atcatls_get_cert (const atcacert_def_t *cert_def, const uint8_t *ca_public_key, uint8_t *certout, size_t *certsize)
 Get the certificate of der format. More...
 
ATCA_STATUS atcatls_get_ca_cert (uint8_t *certout, size_t *certsize)
 Get the certificate. More...
 
ATCA_STATUS atcatls_verify_cert (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size, const uint8_t *ca_public_key)
 Verify a certificate against its certificate authority's public key. More...
 
ATCA_STATUS atcatls_read_ca_pubkey (uint8_t caPubkey[PUB_KEY_SIZE])
 
ATCA_STATUS atcatls_get_device_cert (uint8_t *certout, size_t *certsize)
 Get the certificate. More...
 
ATCA_STATUS atcatls_get_signer_cert (uint8_t *certout, size_t *certsize)
 Get the certificate. More...
 
ATCA_STATUS atcatls_init_enckey (uint8_t *enckeyout, uint8_t enckeyId, bool lock)
 Initialize the unique encryption key for this platform. Write a random number to the parent encryption key slot Return the random number for storage on platform. More...
 
ATCA_STATUS atcatls_set_enckey (uint8_t *enckeyin, uint8_t enckeyId, bool lock)
 Initialize the unique encryption key for this platform Write the provided encryption key to the parent encryption key slot Function optionally lock the parent encryption key slot after it is written. More...
 
ATCA_STATUS atcatls_get_enckey (uint8_t *enckeyout)
 Return the random number for storage on platform. This function reads from platform storage, not the ECC508 device Therefore, the implementation is platform specific and must be provided at integration. More...
 
ATCA_STATUS atcatls_enc_read (uint8_t slotid, uint8_t block, uint8_t enckeyId, uint8_t *data, int16_t *bufsize)
 Read encrypted bytes from the specified slot. More...
 
ATCA_STATUS atcatls_enc_write (uint8_t slotid, uint8_t block, uint8_t enckeyId, uint8_t *data, int16_t bufsize)
 Write encrypted bytes to the specified slot. More...
 
ATCA_STATUS atcatls_enc_rsakey_read (uint8_t enckeyId, uint8_t *rsakey, int16_t *keysize)
 
ATCA_STATUS atcatls_enc_rsakey_write (uint8_t enckeyId, uint8_t *rsakey, int16_t keysize)
 
ATCA_STATUS atcatlsfn_set_get_enckey (atcatlsfn_get_enckey *fn_get_enckey)
 Set the function used to retrieve the unique encryption key for this platform. More...
 

Detailed Description

Instructions for integrating the ECC508 into a platform:

  1. Add compiler switch for ECC_HAL
  2. Define the configuration properties of the secure element in the atcatls_cfg.h file
  3. Add call to HAL_init() before main loop.
    • This will use the configuration information and replace the private key resource in /oic/sec/cred with a handle to the secure element keys.
  4. Re-compile the OIC implementation for the target platform

Macro Definition Documentation

#define MEM_BLOCK_SIZE   ATCA_BLOCK_SIZE
#define PRIV_KEY_SIZE   ATCA_PRIV_KEY_SIZE
#define PUB_KEY_SIZE   ATCA_PUB_KEY_SIZE
#define SIGNATURE_SIZE   ATCA_SIG_SIZE
#define TLS_RANDOM_SIZE   MEM_BLOCK_SIZE
#define TLS_SLOT8_ENC_STORE   ((uint8_t)0x8)

Encrypted storage for 416 bytes.

#define TLS_SLOT9_ENC_STORE   ((uint8_t)0x9)

Encrypted storage for 72 bytes.

#define TLS_SLOT_AUTH_CERT   ((uint8_t)0xA)

Compressed certificate information for the authPrivSlot.

#define TLS_SLOT_AUTH_PMK   ((uint8_t)0x1)

Premaster key for ECDH cipher suites.

#define TLS_SLOT_AUTH_PRIV   ((uint8_t)0x0)

Primary authentication private key.

#define TLS_SLOT_ECDH_PMK   ((uint8_t)0x3)

ECDH/ECDHE pmk slot. This slot is encrypted with encParentSlot.

#define TLS_SLOT_ECDH_PRIV   ((uint8_t)0x2)

ECDH private key.

#define TLS_SLOT_ECDHE_PRIV   ((uint8_t)0x2)

ECDHE private key.

#define TLS_SLOT_ENC_PARENT   ((uint8_t)0x4)

The parent encryption key. This is a random key set on a per-platform basis.

#define TLS_SLOT_FEATURE_CERT   ((uint8_t)0xD)

Compressed certificate information for the featurePrivSlot.

#define TLS_SLOT_FEATURE_PRIV   ((uint8_t)0x7)

Feature private key. Used for feature use cases.

#define TLS_SLOT_HOST_SHAKEY   ((uint8_t)0x6)

Host SHA key slot. Used for host SHA use cases.

#define TLS_SLOT_MFRCA_PUBKEY   ((uint8_t)0xF)

Public key for the MFR certificate authority.

#define TLS_SLOT_PKICA_PUBKEY   ((uint8_t)0xE)

Public key for the PKI certificate authority.

#define TLS_SLOT_SHAKEY   ((uint8_t)0x5)

SHA key slot. Used for SHA use cases.

#define TLS_SLOT_SIGNER_CERT   ((uint8_t)0xC)

Compressed certificate information for the signerPubkey.

#define TLS_SLOT_SIGNER_PUBKEY   ((uint8_t)0xB)

Public key of the signer of authCertSlot.

Typedef Documentation

typedef ATCA_STATUS( atcatlsfn_get_enckey) (uint8_t *enckey, int16_t keysize)

Function Documentation

ATCA_STATUS atcatls_calc_pubkey ( uint8_t  slotid,
uint8_t *  pubkey 
)

Get the public key from the specified private key slot.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_config_default ( void  )

Configure the ECC508 for use with TLS API funcitons. The configuration zone is written and locked. All GenKey and slot initialization is done and then the data zone is locked. This configuration needs to be performed before the TLS API functions are called On a locked ECC508 device, this function will check the configuraiton against the default and fail if it does not match.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_create_key ( uint8_t  slotid,
uint8_t *  pubkey 
)

Create a unique public-private key pair in the specified slot.

Parameters
[in]slotidthe slot id to create the ECC private key
[in]pubkeypointer the public key bytes that coorespond to the private key that was created
Returns
ATCA_STATUS
ATCA_STATUS atcatls_ecdh ( uint8_t  slotid,
const uint8_t *  pubkey,
uint8_t *  pmk 
)

Generate a pre-master key (pmk) given a private key slot and a public key that will be shared with.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_ecdh_enc ( uint8_t  slotid,
uint8_t  enckeyId,
const uint8_t *  pubkey,
uint8_t *  pmk 
)

Generate a pre-master key (pmk) given a private key slot and a public key that will be shared with.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_ecdhe ( uint8_t  slotid,
const uint8_t *  pubkey,
uint8_t *  pubkeyret,
uint8_t *  pmk 
)

Generate a pre-master key (pmk) given a private key slot and a public key that will be shared with.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_enc_read ( uint8_t  slotid,
uint8_t  block,
uint8_t  enckeyId,
uint8_t *  data,
int16_t *  bufsize 
)

Read encrypted bytes from the specified slot.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_enc_rsakey_read ( uint8_t  enckeyId,
uint8_t *  rsakey,
int16_t *  keysize 
)
ATCA_STATUS atcatls_enc_rsakey_write ( uint8_t  enckeyId,
uint8_t *  rsakey,
int16_t  keysize 
)
ATCA_STATUS atcatls_enc_write ( uint8_t  slotid,
uint8_t  block,
uint8_t  enckeyId,
uint8_t *  data,
int16_t  bufsize 
)

Write encrypted bytes to the specified slot.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_finish ( void  )

Finalize the ECC508 when finished. Like a destructor.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_get_ca_cert ( uint8_t *  certout,
size_t *  certsize 
)

Get the certificate.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_get_cert ( const atcacert_def_t cert_def,
const uint8_t *  ca_public_key,
uint8_t *  certout,
size_t *  certsize 
)

Get the certificate of der format.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_get_device_cert ( uint8_t *  certout,
size_t *  certsize 
)

Get the certificate.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_get_enckey ( uint8_t *  enckeyout)

Return the random number for storage on platform. This function reads from platform storage, not the ECC508 device Therefore, the implementation is platform specific and must be provided at integration.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_get_signer_cert ( uint8_t *  certout,
size_t *  certsize 
)

Get the certificate.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_get_sn ( uint8_t  sn_out[ATCA_SERIAL_NUM_SIZE])

Get the serial number of this device.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_init ( ATCAIfaceCfg pCfg)

Initialize the ECC508 for use with the TLS API. Like a constructor.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_init_enckey ( uint8_t *  enckeyout,
uint8_t  enckeyId,
bool  lock 
)

Initialize the unique encryption key for this platform. Write a random number to the parent encryption key slot Return the random number for storage on platform.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_random ( uint8_t *  randout)

Get a random number.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_read_ca_pubkey ( uint8_t  caPubkey[PUB_KEY_SIZE])
ATCA_STATUS atcatls_read_pubkey ( uint8_t  slotid,
uint8_t *  pubkey 
)

reads a pub key from a readable data slot versus atcab_get_pubkey which generates a pubkey from a private key slot

Parameters
[in]slotid- slot number to read, expected value is 0x8 through 0xF
[out]pubkey- space to receive read pubkey
Returns
ATCA_STATUS
ATCA_STATUS atcatls_set_enckey ( uint8_t *  enckeyin,
uint8_t  enckeyId,
bool  lock 
)

Initialize the unique encryption key for this platform Write the provided encryption key to the parent encryption key slot Function optionally lock the parent encryption key slot after it is written.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_sign ( uint8_t  slotid,
const uint8_t *  message,
uint8_t *  signature 
)

Sign the message with the specified slot and return the signature.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_verify ( const uint8_t *  message,
const uint8_t *  signature,
const uint8_t *  pubkey,
bool *  verified 
)

Verify the signature of the specified message using the specified public key.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_verify_cert ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size,
const uint8_t *  ca_public_key 
)

Verify a certificate against its certificate authority's public key.

Returns
ATCA_STATUS
ATCA_STATUS atcatls_write_pubkey ( uint8_t  slotid,
uint8_t  pubkey[PUB_KEY_SIZE],
bool  lock 
)
ATCA_STATUS atcatlsfn_set_get_enckey ( atcatlsfn_get_enckey fn_get_enckey)

Set the function used to retrieve the unique encryption key for this platform.

Returns
ATCA_STATUS