Module pin 

PIN / PUK hashing and CheckMac MAC computation.

The project stores SHA-256(PIN || pin_salt) in slot 5 and SHA-256(PUK || puk_salt) in slot 6. The salts are derived from the chip’s unique serial number at provisioning so that two physically distinct tokens never share a hash even when the user picks the same PIN, without paying the cost of storing an explicit salt elsewhere.

The CheckMac verification on slot 5 / 6 mirrors what the chip itself computes. The byte layout below is taken verbatim from CryptoAuthLib’s atcah_check_mac (lib/host/atca_host.c), which is the authoritative reference, and validated against it by checkmac_response_matches_cryptoauthlib_oracle_* tests.

msg[0..32]   = slot_value         (32)
msg[32..64]  = challenge          (32)
msg[64..68]  = other_data[0..4]   ( 4)  OpCode, Mode, Param2 LE
msg[68..76]  = OTP[0..8] or zero  ( 8)
msg[76..79]  = other_data[4..7]   ( 3)
msg[79]      = serial[8]          ( 1)  SN[8]
msg[80..84]  = other_data[7..11]  ( 4)
msg[84..86]  = serial[0..2]       ( 2)  SN[0..2]
msg[86..88]  = other_data[11..13] ( 2)

Total = 88 bytes (ATCA_MSG_SIZE_MAC).

Notable surprises vs. the Microchip ASF documentation table:

• SN[4..8] and SN[2..4] do not participate in the hash.
• other_data is consumed in three discontinuous chunks: [0..4], [4..7], [7..11], [11..13]. All 13 bytes contribute.

We pass OTP as zeros: PIN verification in this project is not coupled to the OTP zone.

Enums

FormatError

Errors returned when a PIN or PUK does not match the expected format.

Constants

HASH_LEN 🔒

Length of a SHA-256 digest.

PIN_LEN 🔒

PIN length in bytes (4 ASCII digits).

PIN_SALT_DOMAIN 🔒

Domain separation tag for the PIN salt.

PUK_LEN 🔒

PUK length in bytes (8 ASCII digits).

PUK_SALT_DOMAIN 🔒

Domain separation tag for the PUK salt.

Functions

checkmac_other_data 🔒

Build the other_data block for a CheckMac call against key_id on this project’s slots, with zero OTP coupling.

checkmac_response 🔒

Compute the host-side CheckMac response for slot 5 or 6.

pin_hash 🔒

Compute SHA-256(pin || pin_salt). This is the value stored in slot 5.

pin_salt 🔒

Compute the PIN salt deterministically from the chip serial number.

puk_hash 🔒

Compute SHA-256(puk || puk_salt). This is the value stored in slot 6.

puk_salt 🔒

Compute the PUK salt deterministically from the chip serial number.

validate_digits 🔒

Validate that every byte of code is an ASCII digit '0'..='9'.