piv_identity.c
depends on presence_link.h piv_identity.h
flowchart TD backend_change_pin --> hash_pin backend_change_pin --> pin_is_unset_marker backend_change_pin --> pin_is_valid backend_change_pin --> pin_matches backend_change_pin --> record_wrong_pin backend_change_pin --> save_identity
API
Cstruct piv_identity_blob
Serialized identity blob holding a private key, public key, certificate, provisioned PIN state, retries, salt, and hash. Magic and version fields used to detect format changes. GUID identifies the identity. Reserved bytes for future use.
Cstruct piv_key_management_blob
Serialized key management blob holding a private key, public key, and certificate. Magic and version fields used to detect format changes. Serial field distinguishes multiple key management keys. Certificate is DER-encoded.
Fstatic int certificate_rng(void *ctx, unsigned char *out, size_t len)
Fill a buffer with random bytes from the Aliro CSPRNG. Return 0 on success or nonzero on error.
Fstatic int make_pk_context(const uint8_t private_key[ALIRO_P256_SCALAR], const uint8_t public_key[ALIRO_P256_POINT], mbedtls_pk_context *key)
Encode an RFC 5915 ECPrivateKey around the key material generated by PSA. Parsing this standard DER object lets the X.509 writer use the same key without reaching into private mbedTLS structures.
make_certificateFstatic int make_certificate(const uint8_t private_key[ALIRO_P256_SCALAR], const uint8_t public_key[ALIRO_P256_POINT], const uint8_t serial_source[16], const char *name, unsigned int key_usage, uint8_t *certificate, size_t certificate_cap, uint16_t *certificate_len)
Encode a self-signed X.509v3 certificate around the given P-256 key pair. Sets the subject and issuer name to the same string, validity from 2026-01-01 to 2046-01-01, and key usage to the provided flags. Serial is derived from serial_source, with a fallback of 1 if all bytes are zero. Returns 0 on success, -1 on failure (null pointer, buffer too small, or mbedTLS operation failure). Output certificate is DER-encoded at certificate and its length is written to certificate_len.
piv_identity_init · calls make_pk_contextFstatic int save_identity(void)
Persist the in-memory identity blob to NVS under the key PIV_IDENTITY_KEY. Returns 0 on success, -1 on NVS failure (open, set, or commit).
backend_change_pin, backend_verify_pin, piv_identity_init, record_wrong_pinFstatic int save_key_management(void)
Persist the in-memory key management blob to NVS under the key PIV_KEY_MANAGEMENT_KEY. Returns 0 on success, -1 on NVS failure (open, set, or commit).
piv_identity_initFstatic int load_identity(void)
Return 0 for a valid blob, 1 when no identity exists, and -1 on corruption.
piv_identity_initFstatic int load_key_management(void)
Return 0 for a valid slot-9D blob, 1 when absent, and -1 on corruption.
piv_identity_initFstatic bool pin_is_valid(const uint8_t pin[PIV_PIN_BYTES])
Return true if the PIN is valid: at least 6 ASCII decimal digits followed by padding bytes of 0xff, false otherwise.
backend_change_pinFstatic bool pin_is_unset_marker(const uint8_t pin[PIV_PIN_BYTES])
Return true if the PIN buffer is the unset marker (all bytes 0xff), false otherwise.
backend_change_pinFstatic int hash_pin(const uint8_t salt[PIV_PIN_SALT_BYTES], const uint8_t pin[PIV_PIN_BYTES], uint8_t hash[32])
Hash a PIN with its salt using SHA-256: concatenate salt and PIN, compute the hash, and clear intermediate buffers. Return 0 on success or -1 if the PSA operation fails or returns a wrong length.
backend_change_pin, pin_matchesFstatic int backend_get_certificate(void *ctx, uint8_t key_ref, const uint8_t **certificate, size_t *certificate_len)
Retrieve the certificate for a given key reference (AUTH or KEY_MANAGEMENT) and return its pointer and length. Return 0 on success or -1 on error or invalid key reference.
Fstatic int backend_get_guid(void *ctx, uint8_t guid[16])
Copy the 16-byte GUID from the PIV identity to the caller's buffer. Return 0 on success or -1 on error or if the backend is not ready.
Fstatic int backend_pin_status(void *ctx, uint8_t *retries)
Return the PIN retry counter and status: 0 if the PIN is provisioned and retries remain, -2 if the PIN is not provisioned or retries are exhausted, -1 on error or if the backend is not ready.
Fstatic int backend_sign_hash(void *ctx, const uint8_t hash[PIV_P256_HASH_BYTES], uint8_t signature[PIV_P256_RAW_SIGNATURE_BYTES])
Sign a 32-byte P-256 hash using the identity private key, after verifying that presence is fresh. Return 0 on success or -1 on error, if the backend is not ready, or if presence validation fails.
Fconst struct piv_apdu_backend *piv_identity_backend(void)
Return a pointer to the APDU backend implementation struct for PIV identity operations.
Undocumented (5)
pin_matches, record_wrong_pin, backend_verify_pin, backend_change_pin, piv_identity_init