CryptoAuthLib
Microchip CryptoAuthentication Library
Certificate manipulation methods (atcacert_)

These methods provide convenient ways to perform certification I/O with CryptoAuth chips and perform certificate manipulation in memory. More...

Data Structures

struct  atcacert_tm_utc_s
 
struct  atcacert_device_loc_s
 
struct  atcacert_cert_loc_s
 
struct  atcacert_cert_element_s
 
struct  atcacert_def_s
 
struct  atcacert_build_state_s
 

Macros

#define FALSE   (0)
 
#define TRUE   (1)
 
#define ATCACERT_E_SUCCESS   0
 Operation completed successfully. More...
 
#define ATCACERT_E_ERROR   1
 General error. More...
 
#define ATCACERT_E_BAD_PARAMS   2
 Invalid/bad parameter passed to function. More...
 
#define ATCACERT_E_BUFFER_TOO_SMALL   3
 Supplied buffer for output is too small to hold the result. More...
 
#define ATCACERT_E_DECODING_ERROR   4
 Data being decoded/parsed has an invalid format. More...
 
#define ATCACERT_E_INVALID_DATE   5
 Date is invalid. More...
 
#define ATCACERT_E_UNIMPLEMENTED   6
 Function is unimplemented for the current configuration. More...
 
#define ATCACERT_E_UNEXPECTED_ELEM_SIZE   7
 A certificate element size was not what was expected. More...
 
#define ATCACERT_E_ELEM_MISSING   8
 The certificate element isn't defined for the certificate definition. More...
 
#define ATCACERT_E_ELEM_OUT_OF_BOUNDS   9
 Certificate element is out of bounds for the given certificate. More...
 
#define ATCACERT_E_BAD_CERT   10
 Certificate structure is bad in some way. More...
 
#define ATCACERT_E_WRONG_CERT_DEF   11
 
#define ATCACERT_E_VERIFY_FAILED   12
 Certificate or challenge/response verification failed. More...
 
#define DATEFMT_ISO8601_SEP_SIZE   (20)
 
#define DATEFMT_RFC5280_UTC_SIZE   (13)
 
#define DATEFMT_POSIX_UINT32_BE_SIZE   (4)
 
#define DATEFMT_POSIX_UINT32_LE_SIZE   (4)
 
#define DATEFMT_RFC5280_GEN_SIZE   (15)
 
#define DATEFMT_MAX_SIZE   DATEFMT_ISO8601_SEP_SIZE
 
#define ATCACERT_DATE_FORMAT_SIZES_COUNT   5
 

Typedefs

typedef struct atcacert_tm_utc_s atcacert_tm_utc_t
 
typedef enum atcacert_date_format_e atcacert_date_format_t
 
typedef enum atcacert_cert_type_e atcacert_cert_type_t
 
typedef enum atcacert_cert_sn_src_e atcacert_cert_sn_src_t
 
typedef enum atcacert_device_zone_e atcacert_device_zone_t
 
typedef enum atcacert_std_cert_element_e atcacert_std_cert_element_t
 
typedef struct atcacert_device_loc_s atcacert_device_loc_t
 
typedef struct atcacert_cert_loc_s atcacert_cert_loc_t
 
typedef struct atcacert_cert_element_s atcacert_cert_element_t
 
typedef struct atcacert_def_s atcacert_def_t
 
typedef struct atcacert_build_state_s atcacert_build_state_t
 

Enumerations

enum  atcacert_date_format_e {
  DATEFMT_ISO8601_SEP, DATEFMT_RFC5280_UTC, DATEFMT_POSIX_UINT32_BE, DATEFMT_POSIX_UINT32_LE,
  DATEFMT_RFC5280_GEN
}
 
enum  atcacert_cert_type_e { CERTTYPE_X509, CERTTYPE_CUSTOM }
 
enum  atcacert_cert_sn_src_e {
  SNSRC_STORED = 0x0, SNSRC_STORED_DYNAMIC = 0x7, SNSRC_DEVICE_SN = 0x8, SNSRC_SIGNER_ID = 0x9,
  SNSRC_PUB_KEY_HASH = 0xA, SNSRC_DEVICE_SN_HASH = 0xB, SNSRC_PUB_KEY_HASH_POS = 0xC, SNSRC_DEVICE_SN_HASH_POS = 0xD,
  SNSRC_PUB_KEY_HASH_RAW = 0xE, SNSRC_DEVICE_SN_HASH_RAW = 0xF
}
 
enum  atcacert_device_zone_e { DEVZONE_CONFIG = 0x00, DEVZONE_OTP = 0x01, DEVZONE_DATA = 0x02, DEVZONE_NONE = 0x07 }
 
enum  atcacert_std_cert_element_e {
  STDCERT_PUBLIC_KEY, STDCERT_SIGNATURE, STDCERT_ISSUE_DATE, STDCERT_EXPIRE_DATE,
  STDCERT_SIGNER_ID, STDCERT_CERT_SN, STDCERT_AUTH_KEY_ID, STDCERT_SUBJ_KEY_ID,
  STDCERT_NUM_ELEMENTS
}
 

Functions

int atcacert_read_cert (const atcacert_def_t *cert_def, const uint8_t ca_public_key[64], uint8_t *cert, size_t *cert_size)
 Reads the certificate specified by the certificate definition from the ATECC508A device. More...
 
int atcacert_write_cert (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size)
 Take a full certificate and write it to the ATECC508A device according to the certificate definition. More...
 
int atcacert_create_csr (const atcacert_def_t *csr_def, uint8_t *csr, size_t *csr_size)
 Creates a CSR specified by the CSR definition from the ATECC508A device. This process involves reading the dynamic CSR data from the device and combining it with the template found in the CSR definition, then signing it. Return the CSR int der format. More...
 
int atcacert_create_csr_pem (const atcacert_def_t *csr_def, char *csr, size_t *csr_size)
 Creates a CSR specified by the CSR definition from the ATECC508A device. This process involves reading the dynamic CSR data from the device and combining it with the template found in the CSR definition, then signing it. Return the CSR int der format. More...
 
int atcacert_get_response (uint8_t device_private_key_slot, const uint8_t challenge[32], uint8_t response[64])
 Calculates the response to a challenge sent from the host. More...
 
int atcacert_date_enc (atcacert_date_format_t format, const atcacert_tm_utc_t *timestamp, uint8_t *formatted_date, size_t *formatted_date_size)
 Format a timestamp according to the format type. More...
 
int atcacert_date_dec (atcacert_date_format_t format, const uint8_t *formatted_date, size_t formatted_date_size, atcacert_tm_utc_t *timestamp)
 Parse a formatted timestamp according to the specified format. More...
 
int atcacert_date_enc_compcert (const atcacert_tm_utc_t *issue_date, uint8_t expire_years, uint8_t enc_dates[3])
 Encode the issue and expire dates in the format used by the compressed certificate. More...
 
int atcacert_date_dec_compcert (const uint8_t enc_dates[3], atcacert_date_format_t expire_date_format, atcacert_tm_utc_t *issue_date, atcacert_tm_utc_t *expire_date)
 Decode the issue and expire dates from the format used by the compressed certificate. More...
 
int atcacert_date_get_max_date (atcacert_date_format_t format, atcacert_tm_utc_t *timestamp)
 Return the maximum date available for the given format. More...
 
int atcacert_date_enc_iso8601_sep (const atcacert_tm_utc_t *timestamp, uint8_t formatted_date[DATEFMT_ISO8601_SEP_SIZE])
 
int atcacert_date_dec_iso8601_sep (const uint8_t formatted_date[DATEFMT_ISO8601_SEP_SIZE], atcacert_tm_utc_t *timestamp)
 
int atcacert_date_enc_rfc5280_utc (const atcacert_tm_utc_t *timestamp, uint8_t formatted_date[DATEFMT_RFC5280_UTC_SIZE])
 
int atcacert_date_dec_rfc5280_utc (const uint8_t formatted_date[DATEFMT_RFC5280_UTC_SIZE], atcacert_tm_utc_t *timestamp)
 
int atcacert_date_enc_rfc5280_gen (const atcacert_tm_utc_t *timestamp, uint8_t formatted_date[DATEFMT_RFC5280_GEN_SIZE])
 
int atcacert_date_dec_rfc5280_gen (const uint8_t formatted_date[DATEFMT_RFC5280_GEN_SIZE], atcacert_tm_utc_t *timestamp)
 
int atcacert_date_enc_posix_uint32_be (const atcacert_tm_utc_t *timestamp, uint8_t formatted_date[DATEFMT_POSIX_UINT32_BE_SIZE])
 
int atcacert_date_dec_posix_uint32_be (const uint8_t formatted_date[DATEFMT_POSIX_UINT32_BE_SIZE], atcacert_tm_utc_t *timestamp)
 
int atcacert_date_enc_posix_uint32_le (const atcacert_tm_utc_t *timestamp, uint8_t formatted_date[DATEFMT_POSIX_UINT32_LE_SIZE])
 
int atcacert_date_dec_posix_uint32_le (const uint8_t formatted_date[DATEFMT_POSIX_UINT32_LE_SIZE], atcacert_tm_utc_t *timestamp)
 
int atcacert_get_device_locs (const atcacert_def_t *cert_def, atcacert_device_loc_t *device_locs, size_t *device_locs_count, size_t device_locs_max_count, size_t block_size)
 Add all the device locations required to rebuild the specified certificate (cert_def) to a device locations list. More...
 
int atcacert_cert_build_start (atcacert_build_state_t *build_state, const atcacert_def_t *cert_def, uint8_t *cert, size_t *cert_size, const uint8_t ca_public_key[64])
 Starts the certificate rebuilding process. More...
 
int atcacert_cert_build_process (atcacert_build_state_t *build_state, const atcacert_device_loc_t *device_loc, const uint8_t *device_data)
 Process information read from the ATECC device. If it contains information for the certificate, it will be incorporated into the certificate. More...
 
int atcacert_cert_build_finish (atcacert_build_state_t *build_state)
 Completes any final certificate processing required after all data from the device has been incorporated. More...
 
int atcacert_get_device_data (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size, const atcacert_device_loc_t *device_loc, uint8_t *device_data)
 Gets the dynamic data that would be saved to the specified device location. This function is primarily used to break down a full certificate into the dynamic components to be saved to a device. More...
 
int atcacert_set_subj_public_key (const atcacert_def_t *cert_def, uint8_t *cert, size_t cert_size, const uint8_t subj_public_key[64])
 Sets the subject public key and subject key ID in a certificate. More...
 
int atcacert_get_subj_public_key (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size, uint8_t subj_public_key[64])
 Gets the subject public key from a certificate. More...
 
int atcacert_get_subj_key_id (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size, uint8_t subj_key_id[20])
 Gets the subject key ID from a certificate. More...
 
int atcacert_set_signature (const atcacert_def_t *cert_def, uint8_t *cert, size_t *cert_size, size_t max_cert_size, const uint8_t signature[64])
 Sets the signature in a certificate. This may alter the size of the X.509 certificates. More...
 
int atcacert_get_signature (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size, uint8_t signature[64])
 Gets the signature from a certificate. More...
 
int atcacert_set_issue_date (const atcacert_def_t *cert_def, uint8_t *cert, size_t cert_size, const atcacert_tm_utc_t *timestamp)
 Sets the issue date (notBefore) in a certificate. Will be formatted according to the date format specified in the certificate definition. More...
 
int atcacert_get_issue_date (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size, atcacert_tm_utc_t *timestamp)
 Gets the issue date from a certificate. Will be parsed according to the date format specified in the certificate definition. More...
 
int atcacert_set_expire_date (const atcacert_def_t *cert_def, uint8_t *cert, size_t cert_size, const atcacert_tm_utc_t *timestamp)
 Sets the expire date (notAfter) in a certificate. Will be formatted according to the date format specified in the certificate definition. More...
 
int atcacert_get_expire_date (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size, atcacert_tm_utc_t *timestamp)
 Gets the expire date from a certificate. Will be parsed according to the date format specified in the certificate definition. More...
 
int atcacert_set_signer_id (const atcacert_def_t *cert_def, uint8_t *cert, size_t cert_size, const uint8_t signer_id[2])
 Sets the signer ID in a certificate. Will be formatted as 4 upper-case hex digits. More...
 
int atcacert_get_signer_id (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size, uint8_t signer_id[2])
 Gets the signer ID from a certificate. Will be parsed as 4 upper-case hex digits. More...
 
int atcacert_set_cert_sn (const atcacert_def_t *cert_def, uint8_t *cert, size_t *cert_size, size_t max_cert_size, const uint8_t *cert_sn, size_t cert_sn_size)
 Sets the certificate serial number in a certificate. More...
 
int atcacert_gen_cert_sn (const atcacert_def_t *cert_def, uint8_t *cert, size_t cert_size, const uint8_t device_sn[9])
 Sets the certificate serial number by generating it from other information in the certificate using the scheme specified by sn_source in cert_def. See the. More...
 
int atcacert_get_cert_sn (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size, uint8_t *cert_sn, size_t *cert_sn_size)
 Gets the certificate serial number from a certificate. More...
 
int atcacert_set_auth_key_id (const atcacert_def_t *cert_def, uint8_t *cert, size_t cert_size, const uint8_t auth_public_key[64])
 Sets the authority key ID in a certificate. Note that this takes the actual public key creates a key ID from it. More...
 
int atcacert_set_auth_key_id_raw (const atcacert_def_t *cert_def, uint8_t *cert, size_t cert_size, const uint8_t *auth_key_id)
 Sets the authority key ID in a certificate. More...
 
int atcacert_get_auth_key_id (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size, uint8_t auth_key_id[20])
 Gets the authority key ID from a certificate. More...
 
int atcacert_set_comp_cert (const atcacert_def_t *cert_def, uint8_t *cert, size_t *cert_size, size_t max_cert_size, const uint8_t comp_cert[72])
 Sets the signature, issue date, expire date, and signer ID found in the compressed certificate. This also checks fields common between the cert_def and the compressed certificate to make sure they match. More...
 
int atcacert_get_comp_cert (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size, uint8_t comp_cert[72])
 Generate the compressed certificate for the given certificate. More...
 
int atcacert_get_tbs (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size, const uint8_t **tbs, size_t *tbs_size)
 Get a pointer to the TBS data in a certificate. More...
 
int atcacert_get_tbs_digest (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size, uint8_t tbs_digest[32])
 Get the SHA256 digest of certificate's TBS data. More...
 
int atcacert_set_cert_element (const atcacert_def_t *cert_def, const atcacert_cert_loc_t *cert_loc, uint8_t *cert, size_t cert_size, const uint8_t *data, size_t data_size)
 Sets an element in a certificate. The data_size must match the size in cert_loc. More...
 
int atcacert_get_cert_element (const atcacert_def_t *cert_def, const atcacert_cert_loc_t *cert_loc, const uint8_t *cert, size_t cert_size, uint8_t *data, size_t data_size)
 Gets an element from a certificate. More...
 
int atcacert_get_key_id (const uint8_t public_key[64], uint8_t key_id[20])
 Calculates the key ID for a given public ECC P256 key. More...
 
int atcacert_merge_device_loc (atcacert_device_loc_t *device_locs, size_t *device_locs_count, size_t device_locs_max_count, const atcacert_device_loc_t *device_loc, size_t block_size)
 Merge a new device location into a list of device locations. If the new location overlaps with an existing location, the existing one will be modified to encompass both. Otherwise the new location is appended to the end of the list. More...
 
int atcacert_is_device_loc_overlap (const atcacert_device_loc_t *device_loc1, const atcacert_device_loc_t *device_loc2)
 
void atcacert_public_key_add_padding (const uint8_t raw_key[64], uint8_t padded_key[72])
 Takes a raw P256 ECC public key and converts it to the padded version used by ATECC devices. Input and output buffers can point to the same location to do an in-place transform. More...
 
void atcacert_public_key_remove_padding (const uint8_t padded_key[72], uint8_t raw_key[64])
 Takes a padded public key used by ATECC devices and converts it to a raw P256 ECC public key. Input and output buffers can point to the same location to do an in-place transform. More...
 
int atcacert_der_enc_length (uint32_t length, uint8_t *der_length, size_t *der_length_size)
 Encode a length in DER format. More...
 
int atcacert_der_dec_length (const uint8_t *der_length, size_t *der_length_size, uint32_t *length)
 Decode a DER format length. More...
 
int atcacert_der_adjust_length (uint8_t *der_length, size_t *der_length_size, int delta_length, uint32_t *new_length)
 
int atcacert_der_enc_integer (const uint8_t *int_data, size_t int_data_size, uint8_t is_unsigned, uint8_t *der_int, size_t *der_int_size)
 Encode an ASN.1 integer in DER format, including tag and length fields. More...
 
int atcacert_der_dec_integer (const uint8_t *der_int, size_t *der_int_size, uint8_t *int_data, size_t *int_data_size)
 Decode an ASN.1 DER encoded integer. More...
 
int atcacert_der_enc_ecdsa_sig_value (const uint8_t raw_sig[64], uint8_t *der_sig, size_t *der_sig_size)
 Formats a raw ECDSA P256 signature in the DER encoding found in X.509 certificates. More...
 
int atcacert_der_dec_ecdsa_sig_value (const uint8_t *der_sig, size_t *der_sig_size, uint8_t raw_sig[64])
 Parses an ECDSA P256 signature in the DER encoding as found in X.509 certificates. More...
 
int atcacert_verify_cert_hw (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size, const uint8_t ca_public_key[64])
 Verify a certificate against its certificate authority's public key using the host's ATECC device for crypto functions. More...
 
int atcacert_gen_challenge_hw (uint8_t challenge[32])
 Generate a random challenge to be sent to the client using the RNG on the host's ATECC device. More...
 
int atcacert_verify_response_hw (const uint8_t device_public_key[64], const uint8_t challenge[32], const uint8_t response[64])
 Verify a client's response to a challenge using the host's ATECC device for crypto functions. More...
 
int atcacert_verify_cert_sw (const atcacert_def_t *cert_def, const uint8_t *cert, size_t cert_size, const uint8_t ca_public_key[64])
 Verify a certificate against its certificate authority's public key using software crypto functions.The function is currently not implemented. More...
 
int atcacert_gen_challenge_sw (uint8_t challenge[32])
 Generate a random challenge to be sent to the client using a software PRNG.The function is currently not implemented. More...
 
int atcacert_verify_response_sw (const uint8_t device_public_key[64], const uint8_t challenge[32], const uint8_t response[64])
 Verify a client's response to a challenge using software crypto functions.The function is currently not implemented. More...
 

Variables

const size_t ATCACERT_DATE_FORMAT_SIZES [ATCACERT_DATE_FORMAT_SIZES_COUNT]
 

Detailed Description

These methods provide convenient ways to perform certification I/O with CryptoAuth chips and perform certificate manipulation in memory.

Macro Definition Documentation

◆ ATCACERT_DATE_FORMAT_SIZES_COUNT

#define ATCACERT_DATE_FORMAT_SIZES_COUNT   5

◆ ATCACERT_E_BAD_CERT

#define ATCACERT_E_BAD_CERT   10

Certificate structure is bad in some way.

◆ ATCACERT_E_BAD_PARAMS

#define ATCACERT_E_BAD_PARAMS   2

Invalid/bad parameter passed to function.

◆ ATCACERT_E_BUFFER_TOO_SMALL

#define ATCACERT_E_BUFFER_TOO_SMALL   3

Supplied buffer for output is too small to hold the result.

◆ ATCACERT_E_DECODING_ERROR

#define ATCACERT_E_DECODING_ERROR   4

Data being decoded/parsed has an invalid format.

◆ ATCACERT_E_ELEM_MISSING

#define ATCACERT_E_ELEM_MISSING   8

The certificate element isn't defined for the certificate definition.

◆ ATCACERT_E_ELEM_OUT_OF_BOUNDS

#define ATCACERT_E_ELEM_OUT_OF_BOUNDS   9

Certificate element is out of bounds for the given certificate.

◆ ATCACERT_E_ERROR

#define ATCACERT_E_ERROR   1

General error.

◆ ATCACERT_E_INVALID_DATE

#define ATCACERT_E_INVALID_DATE   5

Date is invalid.

◆ ATCACERT_E_SUCCESS

#define ATCACERT_E_SUCCESS   0

Operation completed successfully.

◆ ATCACERT_E_UNEXPECTED_ELEM_SIZE

#define ATCACERT_E_UNEXPECTED_ELEM_SIZE   7

A certificate element size was not what was expected.

◆ ATCACERT_E_UNIMPLEMENTED

#define ATCACERT_E_UNIMPLEMENTED   6

Function is unimplemented for the current configuration.

◆ ATCACERT_E_VERIFY_FAILED

#define ATCACERT_E_VERIFY_FAILED   12

Certificate or challenge/response verification failed.

◆ ATCACERT_E_WRONG_CERT_DEF

#define ATCACERT_E_WRONG_CERT_DEF   11

◆ DATEFMT_ISO8601_SEP_SIZE

#define DATEFMT_ISO8601_SEP_SIZE   (20)

◆ DATEFMT_MAX_SIZE

#define DATEFMT_MAX_SIZE   DATEFMT_ISO8601_SEP_SIZE

◆ DATEFMT_POSIX_UINT32_BE_SIZE

#define DATEFMT_POSIX_UINT32_BE_SIZE   (4)

◆ DATEFMT_POSIX_UINT32_LE_SIZE

#define DATEFMT_POSIX_UINT32_LE_SIZE   (4)

◆ DATEFMT_RFC5280_GEN_SIZE

#define DATEFMT_RFC5280_GEN_SIZE   (15)

◆ DATEFMT_RFC5280_UTC_SIZE

#define DATEFMT_RFC5280_UTC_SIZE   (13)

◆ FALSE

#define FALSE   (0)

◆ TRUE

#define TRUE   (1)

Typedef Documentation

◆ atcacert_build_state_t

Tracks the state of a certificate as it's being rebuilt from device information.

◆ atcacert_cert_element_t

Defines a generic dynamic element for a certificate including the device and template locations.

◆ atcacert_cert_loc_t

Defines a chunk of data in a certificate template.

◆ atcacert_cert_sn_src_t

Sources for the certificate serial number.

◆ atcacert_cert_type_t

Types of certificates.

◆ atcacert_date_format_t

Date formats.

◆ atcacert_def_t

Defines a certificate and all the pieces to work with it.

If any of the standard certificate elements (std_cert_elements) are not a part of the certificate definition, set their count to 0 to indicate their absence.

◆ atcacert_device_loc_t

Defines a chunk of data in an ATECC device.

◆ atcacert_device_zone_t

ATECC device zones. The values match the Zone Encodings as specified in the datasheet.

◆ atcacert_std_cert_element_t

Standard dynamic certificate elements.

◆ atcacert_tm_utc_t

Holds a broken-down date in UTC. Mimics atcacert_tm_utc_t from time.h.

Enumeration Type Documentation

◆ atcacert_cert_sn_src_e

Sources for the certificate serial number.

Enumerator
SNSRC_STORED 

Cert serial is stored on the device.

SNSRC_STORED_DYNAMIC 

Cert serial is stored on the device with the first byte being the DER size (X509 certs only).

SNSRC_DEVICE_SN 

Cert serial number is 0x40(MSB) + 9-byte device serial number. Only applies to device certificates.

SNSRC_SIGNER_ID 

Cert serial number is 0x40(MSB) + 2-byte signer ID. Only applies to signer certificates.

SNSRC_PUB_KEY_HASH 

Cert serial number is the SHA256(Subject public key + Encoded dates), with uppermost 2 bits set to 01.

SNSRC_DEVICE_SN_HASH 

Cert serial number is the SHA256(Device SN + Encoded dates), with uppermost 2 bits set to 01. Only applies to device certificates.

SNSRC_PUB_KEY_HASH_POS 

Depreciated, don't use. Cert serial number is the SHA256(Subject public key + Encoded dates), with MSBit set to 0 to ensure it's positive.

SNSRC_DEVICE_SN_HASH_POS 

Depreciated, don't use. Cert serial number is the SHA256(Device SN + Encoded dates), with MSBit set to 0 to ensure it's positive. Only applies to device certificates.

SNSRC_PUB_KEY_HASH_RAW 

Depreciated, don't use. Cert serial number is the SHA256(Subject public key + Encoded dates).

SNSRC_DEVICE_SN_HASH_RAW 

Depreciated, don't use. Cert serial number is the SHA256(Device SN + Encoded dates). Only applies to device certificates.

◆ atcacert_cert_type_e

Types of certificates.

Enumerator
CERTTYPE_X509 

Standard X509 certificate.

CERTTYPE_CUSTOM 

Custom format.

◆ atcacert_date_format_e

Date formats.

Enumerator
DATEFMT_ISO8601_SEP 

ISO8601 full date YYYY-MM-DDThh:mm:ssZ.

DATEFMT_RFC5280_UTC 

RFC 5280 (X.509) 4.1.2.5.1 UTCTime format YYMMDDhhmmssZ.

DATEFMT_POSIX_UINT32_BE 

POSIX (aka UNIX) date format. Seconds since Jan 1, 1970. 32 bit unsigned integer, big endian.

DATEFMT_POSIX_UINT32_LE 

POSIX (aka UNIX) date format. Seconds since Jan 1, 1970. 32 bit unsigned integer, little endian.

DATEFMT_RFC5280_GEN 

RFC 5280 (X.509) 4.1.2.5.2 GeneralizedTime format YYYYMMDDhhmmssZ.

◆ atcacert_device_zone_e

ATECC device zones. The values match the Zone Encodings as specified in the datasheet.

Enumerator
DEVZONE_CONFIG 

Configuration zone.

DEVZONE_OTP 

One Time Programmable zone.

DEVZONE_DATA 

Data zone (slots).

DEVZONE_NONE 

Special value used to indicate there is no device location.

◆ atcacert_std_cert_element_e

Standard dynamic certificate elements.

Enumerator
STDCERT_PUBLIC_KEY 
STDCERT_SIGNATURE 
STDCERT_ISSUE_DATE 
STDCERT_EXPIRE_DATE 
STDCERT_SIGNER_ID 
STDCERT_CERT_SN 
STDCERT_AUTH_KEY_ID 
STDCERT_SUBJ_KEY_ID 
STDCERT_NUM_ELEMENTS 

Special item to give the number of elements in this enum.

Function Documentation

◆ atcacert_cert_build_finish()

int atcacert_cert_build_finish ( atcacert_build_state_t build_state)

Completes any final certificate processing required after all data from the device has been incorporated.

The final certificate and its size in bytes are contained in the cert and cert_size elements of the build_state structure. This will be the same buffers as supplied to the atcacert_cert_build_start function at the beginning of the certificate rebuilding process.

Parameters
[in]build_stateCurrent certificate build state.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_cert_build_process()

int atcacert_cert_build_process ( atcacert_build_state_t build_state,
const atcacert_device_loc_t device_loc,
const uint8_t *  device_data 
)

Process information read from the ATECC device. If it contains information for the certificate, it will be incorporated into the certificate.

Parameters
[in]build_stateCurrent certificate building state.
[in]device_locDevice location structure describing where on the device the following data came from.
[in]device_dataActual data from the device. It should represent the offset and byte count specified in the device_loc parameter.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_cert_build_start()

int atcacert_cert_build_start ( atcacert_build_state_t build_state,
const atcacert_def_t cert_def,
uint8_t *  cert,
size_t *  cert_size,
const uint8_t  ca_public_key[64] 
)

Starts the certificate rebuilding process.

Parameters
[out]build_stateStructure is initialized to start the certificate building process. Will be passed to the other certificate building functions.
[in]cert_defCertificate definition for the certificate being built.
[in]certBuffer to contain the rebuilt certificate.
[in]cert_sizeAs input, the size of the cert buffer in bytes. This value will be adjusted to the current/final size of the certificate through the building process.
[in]ca_public_keyECC P256 public key of the certificate authority (issuer) for the certificate being built. Set to NULL if the authority key id is not needed, set properly in the cert_def template, or stored on the device as specified in the cert_def cert_elements.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_create_csr()

int atcacert_create_csr ( const atcacert_def_t csr_def,
uint8_t *  csr,
size_t *  csr_size 
)

Creates a CSR specified by the CSR definition from the ATECC508A device. This process involves reading the dynamic CSR data from the device and combining it with the template found in the CSR definition, then signing it. Return the CSR int der format.

Parameters
[in]csr_defCSR definition describing where to find the dynamic CSR information on the device and how to incorporate it into the template.
[out]csrBuffer to receive the CSR.
[in,out]csr_sizeAs input, the size of the CSR buffer in bytes. As output, the size of the CSR returned in cert in bytes.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcacert_create_csr_pem()

int atcacert_create_csr_pem ( const atcacert_def_t csr_def,
char *  csr,
size_t *  csr_size 
)

Creates a CSR specified by the CSR definition from the ATECC508A device. This process involves reading the dynamic CSR data from the device and combining it with the template found in the CSR definition, then signing it. Return the CSR int der format.

Parameters
[in]csr_defCSR definition describing where to find the dynamic CSR information on the device and how to incorporate it into the template.
[out]csrBuffer to received the CSR formatted as PEM.
[in,out]csr_sizeAs input, the size of the CSR buffer in bytes. As output, the size of the CSR as PEM returned in cert in bytes.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcacert_date_dec()

int atcacert_date_dec ( atcacert_date_format_t  format,
const uint8_t *  formatted_date,
size_t  formatted_date_size,
atcacert_tm_utc_t timestamp 
)

Parse a formatted timestamp according to the specified format.

Parameters
[in]formatFormat to parse the formatted date as.
[in]formatted_dateFormatted date to be parsed.
[in]formatted_date_sizeSize of the formatted date in bytes.
[out]timestampParsed timestamp is returned here.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_date_dec_compcert()

int atcacert_date_dec_compcert ( const uint8_t  enc_dates[3],
atcacert_date_format_t  expire_date_format,
atcacert_tm_utc_t issue_date,
atcacert_tm_utc_t expire_date 
)

Decode the issue and expire dates from the format used by the compressed certificate.

Parameters
[in]enc_datesEncoded date from the compressed certificate. 3 bytes.
[in]expire_date_formatExpire date format. Only used to determine max date when no expiration date is specified by the encoded date.
[out]issue_dateDecoded issue date is returned here.
[out]expire_dateDecoded expire date is returned here. If there is no expiration date, the expire date will be set to a maximum value for the given expire_date_format.
Returns
0 on success

◆ atcacert_date_dec_iso8601_sep()

int atcacert_date_dec_iso8601_sep ( const uint8_t  formatted_date[DATEFMT_ISO8601_SEP_SIZE],
atcacert_tm_utc_t timestamp 
)

◆ atcacert_date_dec_posix_uint32_be()

int atcacert_date_dec_posix_uint32_be ( const uint8_t  formatted_date[DATEFMT_POSIX_UINT32_BE_SIZE],
atcacert_tm_utc_t timestamp 
)

◆ atcacert_date_dec_posix_uint32_le()

int atcacert_date_dec_posix_uint32_le ( const uint8_t  formatted_date[DATEFMT_POSIX_UINT32_LE_SIZE],
atcacert_tm_utc_t timestamp 
)

◆ atcacert_date_dec_rfc5280_gen()

int atcacert_date_dec_rfc5280_gen ( const uint8_t  formatted_date[DATEFMT_RFC5280_GEN_SIZE],
atcacert_tm_utc_t timestamp 
)

◆ atcacert_date_dec_rfc5280_utc()

int atcacert_date_dec_rfc5280_utc ( const uint8_t  formatted_date[DATEFMT_RFC5280_UTC_SIZE],
atcacert_tm_utc_t timestamp 
)

◆ atcacert_date_enc()

int atcacert_date_enc ( atcacert_date_format_t  format,
const atcacert_tm_utc_t timestamp,
uint8_t *  formatted_date,
size_t *  formatted_date_size 
)

Format a timestamp according to the format type.

Parameters
[in]formatFormat to use.
[in]timestampTimestamp to format.
[out]formatted_dateFormatted date will be returned in this buffer.
[in,out]formatted_date_sizeAs input, the size of the formatted_date buffer. As output, the size of the returned formatted_date.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_date_enc_compcert()

int atcacert_date_enc_compcert ( const atcacert_tm_utc_t issue_date,
uint8_t  expire_years,
uint8_t  enc_dates[3] 
)

Encode the issue and expire dates in the format used by the compressed certificate.

Parameters
[in]issue_dateIssue date to encode. Note that minutes and seconds will be ignored.
[in]expire_yearsExpire date is expressed as a number of years past the issue date. 0 should be used if there is no expire date.
[out]enc_datesEncoded dates for use in the compressed certificate is returned here. 3 bytes.
Returns
0 on success

◆ atcacert_date_enc_iso8601_sep()

int atcacert_date_enc_iso8601_sep ( const atcacert_tm_utc_t timestamp,
uint8_t  formatted_date[DATEFMT_ISO8601_SEP_SIZE] 
)

◆ atcacert_date_enc_posix_uint32_be()

int atcacert_date_enc_posix_uint32_be ( const atcacert_tm_utc_t timestamp,
uint8_t  formatted_date[DATEFMT_POSIX_UINT32_BE_SIZE] 
)

◆ atcacert_date_enc_posix_uint32_le()

int atcacert_date_enc_posix_uint32_le ( const atcacert_tm_utc_t timestamp,
uint8_t  formatted_date[DATEFMT_POSIX_UINT32_LE_SIZE] 
)

◆ atcacert_date_enc_rfc5280_gen()

int atcacert_date_enc_rfc5280_gen ( const atcacert_tm_utc_t timestamp,
uint8_t  formatted_date[DATEFMT_RFC5280_GEN_SIZE] 
)

◆ atcacert_date_enc_rfc5280_utc()

int atcacert_date_enc_rfc5280_utc ( const atcacert_tm_utc_t timestamp,
uint8_t  formatted_date[DATEFMT_RFC5280_UTC_SIZE] 
)

◆ atcacert_date_get_max_date()

int atcacert_date_get_max_date ( atcacert_date_format_t  format,
atcacert_tm_utc_t timestamp 
)

Return the maximum date available for the given format.

Parameters
[in]formatFormat to get the max date for.
[out]timestampMax date is returned here.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_der_adjust_length()

int atcacert_der_adjust_length ( uint8_t *  der_length,
size_t *  der_length_size,
int  delta_length,
uint32_t *  new_length 
)

◆ atcacert_der_dec_ecdsa_sig_value()

int atcacert_der_dec_ecdsa_sig_value ( const uint8_t *  der_sig,
size_t *  der_sig_size,
uint8_t  raw_sig[64] 
)

Parses an ECDSA P256 signature in the DER encoding as found in X.509 certificates.

This will parse the DER encoding of the signatureValue field as found in an X.509 certificate (RFC 5280). x509_sig should include the tag, length, and value. The value of the signatureValue is the DER encoding of the ECDSA-Sig-Value as specified by RFC 5480 and SECG SEC1.

Parameters
[in]der_sigX.509 format signature (TLV of signatureValue) to be parsed.
[in,out]der_sig_sizeAs input, size of the der_sig buffer in bytes. As output, size of the DER x.509 signature parsed from the buffer.
[out]raw_sigParsed P256 ECDSA signature will be returned in this buffer. Formatted as R and S integers concatenated together. 64 bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_der_dec_integer()

int atcacert_der_dec_integer ( const uint8_t *  der_int,
size_t *  der_int_size,
uint8_t *  int_data,
size_t *  int_data_size 
)

Decode an ASN.1 DER encoded integer.

X.680 (http://www.itu.int/rec/T-REC-X.680/en) section 19.8, for tag value X.690 (http://www.itu.int/rec/T-REC-X.690/en) section 8.3, for encoding

Parameters
[in]der_intDER encoded ASN.1 integer, including the tag and length fields.
[in,out]der_int_sizeAs input, the size of the der_int buffer in bytes. As output, the size of the DER integer decoded in bytes.
[out]int_dataDecode integer is returned in this buffer in a signed big-endian format.
[in,out]int_data_sizeAs input, the size of int_data in bytes. As output, the size of the decoded integer in bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_der_dec_length()

int atcacert_der_dec_length ( const uint8_t *  der_length,
size_t *  der_length_size,
uint32_t *  length 
)

Decode a DER format length.

X.690 (http://www.itu.int/rec/T-REC-X.690/en) section 8.1.3, for encoding

Parameters
[in]der_lengthDER encoded length.
[in,out]der_length_sizeAs input, the size of the der_length buffer in bytes. As output, the size of the DER encoded length that was decoded.
[out]lengthDecoded length is returned here.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_der_enc_ecdsa_sig_value()

int atcacert_der_enc_ecdsa_sig_value ( const uint8_t  raw_sig[64],
uint8_t *  der_sig,
size_t *  der_sig_size 
)

Formats a raw ECDSA P256 signature in the DER encoding found in X.509 certificates.

This will return the DER encoding of the signatureValue field as found in an X.509 certificate (RFC 5280). This include the tag, length, and value. The value of the signatureValue is the DER encoding of the ECDSA-Sig-Value as specified by RFC 5480 and SECG SEC1.

Parameters
[in]raw_sigP256 ECDSA signature to be formatted. Input format is R and S integers concatenated together. 64 bytes.
[out]der_sigX.509 format signature (TLV of signatureValue) will be returned in this buffer.
[in,out]der_sig_sizeAs input, the size of the x509_sig buffer in bytes. As output, the size of the returned X.509 signature in bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_der_enc_integer()

int atcacert_der_enc_integer ( const uint8_t *  int_data,
size_t  int_data_size,
uint8_t  is_unsigned,
uint8_t *  der_int,
size_t *  der_int_size 
)

Encode an ASN.1 integer in DER format, including tag and length fields.

X.680 (http://www.itu.int/rec/T-REC-X.680/en) section 19.8, for tag value X.690 (http://www.itu.int/rec/T-REC-X.690/en) section 8.3, for encoding

Parameters
[in]int_dataRaw integer in big-endian format.
[in]int_data_sizeSize of the raw integer in bytes.
[in]is_unsignedIndicate whether the input integer should be treated as unsigned.
[out]der_intDER encoded integer is returned in this buffer.
[in,out]der_int_sizeAs input, the size of the der_int buffer in bytes. As output, the size of the DER integer returned in bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_der_enc_length()

int atcacert_der_enc_length ( uint32_t  length,
uint8_t *  der_length,
size_t *  der_length_size 
)

Encode a length in DER format.

X.690 (http://www.itu.int/rec/T-REC-X.690/en) section 8.1.3, for encoding

Parameters
[in]lengthLength to be encoded.
[out]der_lengthDER encoded length will returned in this buffer.
[in,out]der_length_sizeAs input, size of der_length buffer in bytes. As output, the size of the DER length encoding in bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_gen_cert_sn()

int atcacert_gen_cert_sn ( const atcacert_def_t cert_def,
uint8_t *  cert,
size_t  cert_size,
const uint8_t  device_sn[9] 
)

Sets the certificate serial number by generating it from other information in the certificate using the scheme specified by sn_source in cert_def. See the.

This method requires certain elements in the certificate be set properly as they're used for generating the serial number. See atcacert_cert_sn_src_t for what elements should be set in the certificate beforehand. If the sn_source is set to SNSRC_STORED or SNSRC_STORED_DYNAMIC, the function will return ATCACERT_E_SUCCESS without making any changes to the certificate.

Parameters
[in]cert_defCertificate definition for the certificate.
[in,out]certCertificate to update.
[in]cert_sizeSize of the certificate (cert) in bytes.
[in]device_snDevice serial number, only used if required by the sn_source scheme. Can be set to NULL, if not required.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_gen_challenge_hw()

int atcacert_gen_challenge_hw ( uint8_t  challenge[32])

Generate a random challenge to be sent to the client using the RNG on the host's ATECC device.

Parameters
[out]challengeRandom challenge is return here. 32 bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_gen_challenge_sw()

int atcacert_gen_challenge_sw ( uint8_t  challenge[32])

Generate a random challenge to be sent to the client using a software PRNG.The function is currently not implemented.

Parameters
[out]challengeRandom challenge is return here. 32 bytes.
Returns
ATCA_UNIMPLEMENTED , as the function is currently not implemented.

◆ atcacert_get_auth_key_id()

int atcacert_get_auth_key_id ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size,
uint8_t  auth_key_id[20] 
)

Gets the authority key ID from a certificate.

Parameters
[in]cert_defCertificate definition for the certificate.
[in]certCertificate to get element from.
[in]cert_sizeSize of the certificate (cert) in bytes.
[out]auth_key_idAuthority key ID is returned in this buffer. 20 bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_get_cert_element()

int atcacert_get_cert_element ( const atcacert_def_t cert_def,
const atcacert_cert_loc_t cert_loc,
const uint8_t *  cert,
size_t  cert_size,
uint8_t *  data,
size_t  data_size 
)

Gets an element from a certificate.

Parameters
[in]cert_defCertificate definition for the certificate.
[in]cert_locCertificate location for this element.
[in]certCertificate to get element from.
[in]cert_sizeSize of the certificate (cert) in bytes.
[out]dataElement data will be returned in this buffer. This buffer must be large enough to hold cert_loc.count bytes.
[in]data_sizeExpected size of the cert element data.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_get_cert_sn()

int atcacert_get_cert_sn ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size,
uint8_t *  cert_sn,
size_t *  cert_sn_size 
)

Gets the certificate serial number from a certificate.

Parameters
[in]cert_defCertificate definition for the certificate.
[in]certCertificate to get element from.
[in]cert_sizeSize of the certificate (cert) in bytes.
[out]cert_snCertificate SN will be returned in this buffer.
[in,out]cert_sn_sizeAs input, the size of the cert_sn buffer. As output, the size of the certificate SN (cert_sn) in bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_get_comp_cert()

int atcacert_get_comp_cert ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size,
uint8_t  comp_cert[72] 
)

Generate the compressed certificate for the given certificate.

Parameters
[in]cert_defCertificate definition for the certificate.
[in]certCertificate to generate the compressed certificate for.
[in]cert_sizeSize of the certificate (cert) in bytes.
[out]comp_certCompressed certificate is returned in this buffer. 72 bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_get_device_data()

int atcacert_get_device_data ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size,
const atcacert_device_loc_t device_loc,
uint8_t *  device_data 
)

Gets the dynamic data that would be saved to the specified device location. This function is primarily used to break down a full certificate into the dynamic components to be saved to a device.

The atcacert_add_device_locs function can be used to generate a list of device locations a particular certificate definition requires.

Parameters
[in]cert_defCertificate definition for the certificate we're getting data from.
[in]certCertificate to get the device data from.
[in]cert_sizeSize of the certificate in bytes.
[in]device_locDevice location to request data for.
[out]device_dataBuffer that represents the device data in device_loc. Required to be at least device_loc.count in size.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_get_device_locs()

int atcacert_get_device_locs ( const atcacert_def_t cert_def,
atcacert_device_loc_t device_locs,
size_t *  device_locs_count,
size_t  device_locs_max_count,
size_t  block_size 
)

Add all the device locations required to rebuild the specified certificate (cert_def) to a device locations list.

The block_size parameter will adjust all added device locations to have a offset and count that aligns with that block size. This allows one to generate a list of device locations that matches specific read or write semantics (e.g. 4 byte or 32 byte reads).

Parameters
[in]cert_defCertificate definition containing all the device locations to add to the list.
[in,out]device_locsList of device locations to add to.
[in,out]device_locs_countAs input, existing size of the device locations list. As output, the new size of the device locations list.
[in]device_locs_max_countMaximum number of elements device_locs can hold.
[in]block_sizeBlock size to align all offsets and counts to when adding device locations.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_get_expire_date()

int atcacert_get_expire_date ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size,
atcacert_tm_utc_t timestamp 
)

Gets the expire date from a certificate. Will be parsed according to the date format specified in the certificate definition.

Parameters
[in]cert_defCertificate definition for the certificate.
[in]certCertificate to get element from.
[in]cert_sizeSize of the certificate (cert) in bytes.
[out]timestampExpire date is returned in this structure.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_get_issue_date()

int atcacert_get_issue_date ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size,
atcacert_tm_utc_t timestamp 
)

Gets the issue date from a certificate. Will be parsed according to the date format specified in the certificate definition.

Parameters
[in]cert_defCertificate definition for the certificate.
[in]certCertificate to get element from.
[in]cert_sizeSize of the certificate (cert) in bytes.
[out]timestampIssue date is returned in this structure.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_get_key_id()

int atcacert_get_key_id ( const uint8_t  public_key[64],
uint8_t  key_id[20] 
)

Calculates the key ID for a given public ECC P256 key.

Uses method 1 for calculating the keyIdentifier as specified by RFC 5280, section 4.2.1.2: (1) The keyIdentifier is composed of the 160-bit SHA-1 hash of the value of the BIT STRING subjectPublicKey (excluding the tag, length, and number of unused bits).

Parameters
[in]public_keyECC P256 public key to calculate key key ID for. Formatted as the X and Y integers concatenated together. 64 bytes.
[in]key_idCalculated key ID will be returned in this buffer. 20 bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_get_response()

int atcacert_get_response ( uint8_t  device_private_key_slot,
const uint8_t  challenge[32],
uint8_t  response[64] 
)

Calculates the response to a challenge sent from the host.

The challenge-response protocol is an ECDSA Sign and Verify. This performs the ECDSA Sign on the challenge and returns the signature as the response.

Parameters
[in]device_private_key_slotSlot number for the device's private key. This must be the same slot used to generate the public key included in the device's certificate.
[in]challengeChallenge to generate the response for. Must be 32 bytes.
[out]responseResponse will be returned in this buffer. 64 bytes.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcacert_get_signature()

int atcacert_get_signature ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size,
uint8_t  signature[64] 
)

Gets the signature from a certificate.

Parameters
[in]cert_defCertificate definition for the certificate.
[in]certCertificate to get element from.
[in]cert_sizeSize of the certificate (cert) in bytes.
[out]signatureSignature is returned in this buffer. Formatted at R and S integers concatenated together. 64 bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_get_signer_id()

int atcacert_get_signer_id ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size,
uint8_t  signer_id[2] 
)

Gets the signer ID from a certificate. Will be parsed as 4 upper-case hex digits.

Parameters
[in]cert_defCertificate definition for the certificate.
[in]certCertificate to get element from.
[in]cert_sizeSize of the certificate (cert) in bytes.
[out]signer_idSigner ID will be returned in this buffer. 2 bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_get_subj_key_id()

int atcacert_get_subj_key_id ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size,
uint8_t  subj_key_id[20] 
)

Gets the subject key ID from a certificate.

Parameters
[in]cert_defCertificate definition for the certificate.
[in]certCertificate to get element from.
[in]cert_sizeSize of the certificate (cert) in bytes.
[out]subj_key_idSubject key ID is returned in this buffer. 20 bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_get_subj_public_key()

int atcacert_get_subj_public_key ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size,
uint8_t  subj_public_key[64] 
)

Gets the subject public key from a certificate.

Parameters
[in]cert_defCertificate definition for the certificate.
[in]certCertificate to get element from.
[in]cert_sizeSize of the certificate (cert) in bytes.
[out]subj_public_keySubject public key is returned in this buffer. Formatted at X and Y integers concatenated together. 64 bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_get_tbs()

int atcacert_get_tbs ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size,
const uint8_t **  tbs,
size_t *  tbs_size 
)

Get a pointer to the TBS data in a certificate.

Parameters
[in]cert_defCertificate definition for the certificate.
[in]certCertificate to get the TBS data pointer for.
[in]cert_sizeSize of the certificate (cert) in bytes.
[out]tbsPointer to a const pointer that will be set the start of the TBS data.
[out]tbs_sizeSize of the TBS data will be returned here.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_get_tbs_digest()

int atcacert_get_tbs_digest ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size,
uint8_t  tbs_digest[32] 
)

Get the SHA256 digest of certificate's TBS data.

Parameters
[in]cert_defCertificate definition for the certificate.
[in]certCertificate to get the TBS data pointer for.
[in]cert_sizeSize of the certificate (cert) in bytes.
[out]tbs_digestTBS data digest will be returned here. 32 bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_is_device_loc_overlap()

int atcacert_is_device_loc_overlap ( const atcacert_device_loc_t device_loc1,
const atcacert_device_loc_t device_loc2 
)

◆ atcacert_merge_device_loc()

int atcacert_merge_device_loc ( atcacert_device_loc_t device_locs,
size_t *  device_locs_count,
size_t  device_locs_max_count,
const atcacert_device_loc_t device_loc,
size_t  block_size 
)

Merge a new device location into a list of device locations. If the new location overlaps with an existing location, the existing one will be modified to encompass both. Otherwise the new location is appended to the end of the list.

The block_size parameter will adjust all added device locations to have an offset and count that aligns with that block size. This allows one to generate a list of device locations that matches specific read/write semantics (e.g. 4 byte or 32 byte reads). Note that this block_size only applies to the device_loc being added. Existing device locations in the list won't be modified to match the block size.

Parameters
[in,out]device_locsExisting device location list to merge the new device location into.
[in,out]device_locs_countAs input, the existing number of items in the device_locs list. As output, the new size of the device_locs list.
[in]device_locs_max_countMaximum number of items the device_locs list can hold.
[in]device_locNew device location to be merged into the device_locs list.
[in]block_sizeBlock size to align all offsets and counts to when adding device location.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_public_key_add_padding()

void atcacert_public_key_add_padding ( const uint8_t  raw_key[64],
uint8_t  padded_key[72] 
)

Takes a raw P256 ECC public key and converts it to the padded version used by ATECC devices. Input and output buffers can point to the same location to do an in-place transform.

Parameters
[in]raw_keyPublic key as X and Y integers concatenated together. 64 bytes.
[out]padded_keyPadded key is returned in this buffer. X and Y integers are padded with 4 bytes of 0 in the MSB. 72 bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_public_key_remove_padding()

void atcacert_public_key_remove_padding ( const uint8_t  padded_key[72],
uint8_t  raw_key[64] 
)

Takes a padded public key used by ATECC devices and converts it to a raw P256 ECC public key. Input and output buffers can point to the same location to do an in-place transform.

Parameters
[out]padded_keyX and Y integers are padded with 4 bytes of 0 in the MSB. 72 bytes.
[in]raw_keyRaw key is returned in this buffer. Public key as X and Y integers concatenated together. 64 bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_read_cert()

int atcacert_read_cert ( const atcacert_def_t cert_def,
const uint8_t  ca_public_key[64],
uint8_t *  cert,
size_t *  cert_size 
)

Reads the certificate specified by the certificate definition from the ATECC508A device.

This process involves reading the dynamic cert data from the device and combining it with the template found in the certificate definition.

Parameters
[in]cert_defCertificate definition describing where to find the dynamic certificate information on the device and how to incorporate it into the template.
[in]ca_public_keyThe ECC P256 public key of the certificate authority that signed this certificate. Formatted as the 32 byte X and Y integers concatenated together (64 bytes total). Set to NULL if the authority key id is not needed, set properly in the cert_def template, or stored on the device as specifed in the cert_def cert_elements.
[out]certBuffer to received the certificate.
[in,out]cert_sizeAs input, the size of the cert buffer in bytes. As output, the size of the certificate returned in cert in bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_set_auth_key_id()

int atcacert_set_auth_key_id ( const atcacert_def_t cert_def,
uint8_t *  cert,
size_t  cert_size,
const uint8_t  auth_public_key[64] 
)

Sets the authority key ID in a certificate. Note that this takes the actual public key creates a key ID from it.

Parameters
[in]cert_defCertificate definition for the certificate.
[in,out]certCertificate to update.
[in]cert_sizeSize of the certificate (cert) in bytes.
[in]auth_public_keyAuthority public key as X and Y integers concatenated together. 64 bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_set_auth_key_id_raw()

int atcacert_set_auth_key_id_raw ( const atcacert_def_t cert_def,
uint8_t *  cert,
size_t  cert_size,
const uint8_t *  auth_key_id 
)

Sets the authority key ID in a certificate.

Parameters
[in]cert_defCertificate definition for the certificate.
[in,out]certCertificate to update.
[in]cert_sizeSize of the certificate (cert) in bytes.
[in]auth_key_idAuthority key ID. Same size as defined in the cert_def.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_set_cert_element()

int atcacert_set_cert_element ( const atcacert_def_t cert_def,
const atcacert_cert_loc_t cert_loc,
uint8_t *  cert,
size_t  cert_size,
const uint8_t *  data,
size_t  data_size 
)

Sets an element in a certificate. The data_size must match the size in cert_loc.

Parameters
[in]cert_defCertificate definition for the certificate.
[in]cert_locCertificate location for this element.
[in,out]certCertificate to update.
[in]cert_sizeSize of the certificate (cert) in bytes.
[in]dataElement data to insert into the certificate. Buffer must contain cert_loc.count bytes to be copied into the certificate.
[in]data_sizeSize of the data in bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_set_cert_sn()

int atcacert_set_cert_sn ( const atcacert_def_t cert_def,
uint8_t *  cert,
size_t *  cert_size,
size_t  max_cert_size,
const uint8_t *  cert_sn,
size_t  cert_sn_size 
)

Sets the certificate serial number in a certificate.

Parameters
[in]cert_defCertificate definition for the certificate.
[in,out]certCertificate to update.
[in,out]cert_sizeSize of the certificate (cert) in bytes.
[in]max_cert_sizeMaximum size of the cert buffer.
[in]cert_snCertificate serial number.
[in]cert_sn_sizeSize of the certificate serial number in bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_set_comp_cert()

int atcacert_set_comp_cert ( const atcacert_def_t cert_def,
uint8_t *  cert,
size_t *  cert_size,
size_t  max_cert_size,
const uint8_t  comp_cert[72] 
)

Sets the signature, issue date, expire date, and signer ID found in the compressed certificate. This also checks fields common between the cert_def and the compressed certificate to make sure they match.

Parameters
[in]cert_defCertificate definition for the certificate.
[in,out]certCertificate to update.
[in,out]cert_sizeAs input, size of the certificate (cert) in bytes. As output, the new size of the certificate.
[in]max_cert_sizeMaximum size of the cert buffer.
[in]comp_certCompressed certificate. 72 bytes.
Returns
ATCACERT_E_SUCCESS on success. ATCACERT_E_WRONG_CERT_DEF if the template ID, chain ID, and/or SN source don't match between the cert_def and the compressed certificate.

◆ atcacert_set_expire_date()

int atcacert_set_expire_date ( const atcacert_def_t cert_def,
uint8_t *  cert,
size_t  cert_size,
const atcacert_tm_utc_t timestamp 
)

Sets the expire date (notAfter) in a certificate. Will be formatted according to the date format specified in the certificate definition.

Parameters
[in]cert_defCertificate definition for the certificate.
[in,out]certCertificate to update.
[in]cert_sizeSize of the certificate (cert) in bytes.
[in]timestampExpire date.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_set_issue_date()

int atcacert_set_issue_date ( const atcacert_def_t cert_def,
uint8_t *  cert,
size_t  cert_size,
const atcacert_tm_utc_t timestamp 
)

Sets the issue date (notBefore) in a certificate. Will be formatted according to the date format specified in the certificate definition.

Parameters
[in]cert_defCertificate definition for the certificate.
[in,out]certCertificate to update.
[in]cert_sizeSize of the certificate (cert) in bytes.
[in]timestampIssue date.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_set_signature()

int atcacert_set_signature ( const atcacert_def_t cert_def,
uint8_t *  cert,
size_t *  cert_size,
size_t  max_cert_size,
const uint8_t  signature[64] 
)

Sets the signature in a certificate. This may alter the size of the X.509 certificates.

Parameters
[in]cert_defCertificate definition for the certificate.
[in,out]certCertificate to update.
[in,out]cert_sizeAs input, size of the certificate (cert) in bytes. As output, the new size of the certificate.
[in]max_cert_sizeMaximum size of the cert buffer.
[in]signatureSignature as R and S integers concatenated together. 64 bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_set_signer_id()

int atcacert_set_signer_id ( const atcacert_def_t cert_def,
uint8_t *  cert,
size_t  cert_size,
const uint8_t  signer_id[2] 
)

Sets the signer ID in a certificate. Will be formatted as 4 upper-case hex digits.

Parameters
[in]cert_defCertificate definition for the certificate.
[in,out]certCertificate to update.
[in]cert_sizeSize of the certificate (cert) in bytes.
[in]signer_idSigner ID.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_set_subj_public_key()

int atcacert_set_subj_public_key ( const atcacert_def_t cert_def,
uint8_t *  cert,
size_t  cert_size,
const uint8_t  subj_public_key[64] 
)

Sets the subject public key and subject key ID in a certificate.

Parameters
[in]cert_defCertificate definition for the certificate.
[in,out]certCertificate to update.
[in]cert_sizeSize of the certificate (cert) in bytes.
[in]subj_public_keySubject public key as X and Y integers concatenated together. 64 bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

◆ atcacert_verify_cert_hw()

int atcacert_verify_cert_hw ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size,
const uint8_t  ca_public_key[64] 
)

Verify a certificate against its certificate authority's public key using the host's ATECC device for crypto functions.

Parameters
[in]cert_defCertificate definition describing how to extract the TBS and signature components from the certificate specified.
[in]certCertificate to verify.
[in]cert_sizeSize of the certificate (cert) in bytes.
[in]ca_public_keyThe ECC P256 public key of the certificate authority that signed this certificate. Formatted as the 32 byte X and Y integers concatenated together (64 bytes total).
Returns
ATCACERT_E_SUCCESS if the verify succeeds, ATCACERT_VERIFY_FAILED or ATCA_EXECUTION_ERROR if it fails to verify. ATCA_EXECUTION_ERROR may occur when the public key is invalid and doesn't fall on the P256 curve.

◆ atcacert_verify_cert_sw()

int atcacert_verify_cert_sw ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size,
const uint8_t  ca_public_key[64] 
)

Verify a certificate against its certificate authority's public key using software crypto functions.The function is currently not implemented.

Parameters
[in]cert_defCertificate definition describing how to extract the TBS and signature components from the certificate specified.
[in]certCertificate to verify.
[in]cert_sizeSize of the certificate (cert) in bytes.
[in]ca_public_keyThe ECC P256 public key of the certificate authority that signed this certificate. Formatted as the 32 byte X and Y integers concatenated together (64 bytes total).
Returns
ATCA_UNIMPLEMENTED , as the function is currently not implemented.

◆ atcacert_verify_response_hw()

int atcacert_verify_response_hw ( const uint8_t  device_public_key[64],
const uint8_t  challenge[32],
const uint8_t  response[64] 
)

Verify a client's response to a challenge using the host's ATECC device for crypto functions.

The challenge-response protocol is an ECDSA Sign and Verify. This performs an ECDSA verify on the response returned by the client, verifying the client has the private key counter-part to the public key returned in its certificate.

Parameters
[in]device_public_keyDevice public key as read from its certificate. Formatted as the X and Y integers concatenated together. 64 bytes.
[in]challengeChallenge that was sent to the client. 32 bytes.
[in]responseResponse returned from the client to be verified. 64 bytes.
Returns
ATCACERT_E_SUCCESS if the verify succeeds, ATCACERT_VERIFY_FAILED or ATCA_EXECUTION_ERROR if it fails to verify. ATCA_EXECUTION_ERROR may occur when the public key is invalid and doesn't fall on the P256 curve.

◆ atcacert_verify_response_sw()

int atcacert_verify_response_sw ( const uint8_t  device_public_key[64],
const uint8_t  challenge[32],
const uint8_t  response[64] 
)

Verify a client's response to a challenge using software crypto functions.The function is currently not implemented.

The challenge-response protocol is an ECDSA Sign and Verify. This performs an ECDSA verify on the response returned by the client, verifying the client has the private key counter-part to the public key returned in its certificate.

Parameters
[in]device_public_keyDevice public key as read from its certificate. Formatted as the X and Y integers concatenated together. 64 bytes.
[in]challengeChallenge that was sent to the client. 32 bytes.
[in]responseResponse returned from the client to be verified. 64 bytes.
Returns
ATCA_UNIMPLEMENTED , as the function is currently not implemented.

◆ atcacert_write_cert()

int atcacert_write_cert ( const atcacert_def_t cert_def,
const uint8_t *  cert,
size_t  cert_size 
)

Take a full certificate and write it to the ATECC508A device according to the certificate definition.

Parameters
[in]cert_defCertificate definition describing where the dynamic certificate information is and how to store it on the device.
[in]certFull certificate to be stored.
[in]cert_sizeSize of the full certificate in bytes.
Returns
ATCACERT_E_SUCCESS on success, otherwise an error code.

Variable Documentation

◆ ATCACERT_DATE_FORMAT_SIZES

const size_t ATCACERT_DATE_FORMAT_SIZES[ATCACERT_DATE_FORMAT_SIZES_COUNT]