SDCP Cryptographic Operations: libfprint Reference Manual

SDCP Cryptographic Operations

Functions

GError *	fpi_sdcp_error_new_msg ()
gboolean	fpi_sdcp_generate_host_key ()
GBytes *	fpi_sdcp_generate_random ()
gboolean	fpi_sdcp_verify_certificate ()
GBytes *	fpi_sdcp_verify_connect ()
gboolean	fpi_sdcp_verify_reconnect ()
gboolean	fpi_sdcp_verify_identify ()
GBytes *	fpi_sdcp_generate_enrollment_id ()
GBytes *	fpi_sdcp_mac ()

Description

Functions

fpi_sdcp_error_new_msg ()

GError *
fpi_sdcp_error_new_msg (FpDeviceError error_code,
                        const gchar *format,
                        ...);

Creates a new GError in the FP_DEVICE_ERROR domain with the given error_code . If there is a pending OpenSSL error, its string representation is appended to format ; the OpenSSL error stack is drained unconditionally.

Parameters

error_code	The FpDeviceError code for the new error
format	A printf-style format string for the error message
...	Format arguments

Returns

A newly allocated GError.

[transfer full]

fpi_sdcp_generate_host_key ()

gboolean
fpi_sdcp_generate_host_key (GBytes **private_key,
                            GBytes **public_key,
                            GError **error);

Function to generate a new ephemeral ECDH key pair for use with SDCP.

Parameters

private_key	The host private key (sk_h).	[out][transfer full]
public_key	The host public key (pk_h).	[out][transfer full]
error	GError in case the out values are `NULL`.	[out]

fpi_sdcp_generate_random ()

GBytes *
fpi_sdcp_generate_random (GError **error);

Parameters

error

GError in case the return value is NULL.

[out]

Returns

A new GBytes with a secure random of length FPI_SDCP_RANDOM_SIZE

fpi_sdcp_verify_certificate ()

gboolean
fpi_sdcp_verify_certificate (GBytes *x509_certificate,
                             GResource *additional_ca_store,
                             FpiDeviceSdcpVerificationFlags verification_flags,
                             GError **error);

Verifies an X.509 certificate (DER-encoded) against the SDCP trust store.

Parameters

x509_certificate	An X.509 certificate in DER (ASN.1) format
additional_ca_store	An optional GResource containing additional PEM certificates at the path `FPI_SDCP_CA_STORE_PATH` that are merged into the default SDCP CA store. Use `NULL` to use only the default CA store.	[nullable]
verification_flags	Flags to control certificate verification behaviour. See FpiDeviceSdcpVerificationFlags for details.
error	GError on failure.	[out]

Returns

TRUE if the certificate is trusted

fpi_sdcp_verify_connect ()

GBytes *
fpi_sdcp_verify_connect (GBytes *host_private_key,
                         GBytes *host_random,
                         GBytes *device_random,
                         FpiSdcpClaim *claim,
                         GBytes *mac,
                         GResource *additional_ca_store,
                         FpiDeviceSdcpVerificationFlags verification_flags,
                         GError **error);

High level function which internally handles the derivation of all necessary SDCP-related keys and secrets from the device's ConnectResponse and derives the application secret for use with all other SDCP-related functions. The KDF and MAC labels used during key derivation are taken from the claim label fields; NULL fields fall back to the FPI_SDCP_DEFAULT_LABEL_* constants.

This function will also perform a validation of the ConnectResponse MAC and optionally perform additional verifications based on the provided verification_flags . If any of these these validations fail then NULL will be returned, indicating that the SDCP secure connection channel could not be established.

Parameters

host_private_key	Private key generated using `fpi_sdcp_generate_host_key()` (sk_h)
host_random	Random generated using `fpi_sdcp_generate_random()` (r_h)
device_random	The random provided in the device's ConnectResponse (r_d)
claim	FpiSdcpClaim provided in the device's ConnectResponse (c)
mac	The MAC provided in the device's ConnectResponse (m)
additional_ca_store	An optional GResource containing additional PEM certificates at the path `FPI_SDCP_CA_STORE_PATH` that are merged into the default SDCP CA store before certificate verification. Pass `NULL` to use only the default CA store.	[nullable]
verification_flags	Flags to control which verifications should be performed during the ConnectResponse validation. See FpiDeviceSdcpVerificationFlags for details.
error	GError in case the return value is `NULL`.	[out]

Returns

A new GBytes with the derived application secret (s) of length FPI_SDCP_APPLICATION_SECRET_SIZE, or NULL on failure.

[transfer full]

fpi_sdcp_verify_reconnect ()

gboolean
fpi_sdcp_verify_reconnect (GBytes *application_secret,
                           const gchar *label,
                           GBytes *random,
                           GBytes *mac,
                           GError **error);

Verifies the SDCP ReconnectResponse.

Parameters

application_secret	The host's derived application secret (s)
label	HMAC label, or `NULL` to use `FPI_SDCP_DEFAULT_LABEL_RECONNECT`
random	The host-generated random sent to the device's Reconnect command (r)
mac	The MAC provided in the device's ReconnectResponse (m)
error	GError in case the return value is `FALSE`.	[out]

Returns

TRUE if the ReconnectResponse is verified successfully

fpi_sdcp_verify_identify ()

gboolean
fpi_sdcp_verify_identify (GBytes *application_secret,
                          const gchar *label,
                          GBytes *nonce,
                          GBytes *id,
                          GBytes *mac,
                          GError **error);

Verifies the SDCP AuthorizedIdentity.

Parameters

application_secret	The host's derived application secret (s)
label	HMAC label, or `NULL` to use `FPI_SDCP_DEFAULT_LABEL_IDENTIFY`
nonce	The host-generated nonce sent to the device's Identify command (n)
id	The ID provided in the device's AuthorizedIdentity (id)
mac	The MAC provided in the device's AuthorizedIdentity (m)
error	GError in case the return value is `FALSE`.	[out]

Returns

TRUE if the AuthorizedIdentity is verified successfully

fpi_sdcp_generate_enrollment_id ()

GBytes *
fpi_sdcp_generate_enrollment_id (GBytes *application_secret,
                                 const gchar *label,
                                 GBytes *nonce,
                                 GError **error);

Generates a new id for use with the device's EnrollCommit command.

Parameters

application_secret	The host's derived application secret (s)
label	HMAC label, or `NULL` to use `FPI_SDCP_DEFAULT_LABEL_ENROLL`
nonce	The nonce received from the device in response to the EnrollBegin command (n)
error	GError in case the return value is `NULL`.	[out]

Returns

A new GBytes with the generated enrollment id of length FPI_SDCP_ENROLLMENT_ID_SIZE

fpi_sdcp_mac ()

GBytes *
fpi_sdcp_mac (GBytes *application_secret,
              const gchar *label,
              GBytes *data_a,
              GBytes *data_b,
              GError **error);

Computes HMAC-SHA256(application_secret , label || data_a || data_b ).

Parameters

application_secret	The application secret to use as the HMAC key
label	Label string (included with a trailing NUL byte), or `NULL`
data_a	First data buffer, or `NULL`
data_b	Second data buffer, or `NULL`
error	GError in case the return value is `NULL`.	[out]

Returns

A new GBytes with the MAC of length FPI_SDCP_MAC_SIZE