SDCP Cryptographic Operations: libfprint Reference Manual

## SDCP Cryptographic Operations 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`