## Internal FpSdcpDevice

Internal FpSdcpDevice — Internal SDCP device routines

## Functions

void | fpi_sdcp_device_open_complete ()
GBytes * | fpi_sdcp_device_get_application_secret ()
void | fpi_sdcp_device_get_connect_data ()
void | fpi_sdcp_device_connect_complete ()
void | fpi_sdcp_device_get_reconnect_data ()
void | fpi_sdcp_device_reconnect_complete ()
void | fpi_sdcp_device_list_complete ()
void | fpi_sdcp_device_enroll_commit ()
void | fpi_sdcp_device_enroll_commit_complete ()
void | fpi_sdcp_device_get_identify_data ()
void | fpi_sdcp_device_set_identify_data ()
void | fpi_sdcp_device_identify_retry ()
void | fpi_sdcp_device_identify_complete ()

## Types and Values

enum | FpiDeviceSdcpVerificationFlags
| FpSdcpDeviceClass
#define | FPI_SDCP_RANDOM_SIZE
#define | FPI_SDCP_APPLICATION_SECRET_SIZE
#define | FPI_SDCP_ENROLLMENT_ID_SIZE
#define | FPI_SDCP_NONCE_SIZE
#define | FPI_SDCP_MAC_SIZE
#define | FPI_SDCP_DIGEST_SIZE
#define | FPI_SDCP_CURVE_FIELD_SIZE
#define | FPI_SDCP_PUBLIC_KEY_SIZE
#define | FPI_SDCP_PRIVATE_KEY_SIZE
#define | FPI_SDCP_SIGNATURE_SIZE
#define | FPI_SDCP_ENCRYPTION_BLOCK_SIZE
#define | FPI_SDCP_ENCRYPTION_KEY_SIZE
#define | FPI_SDCP_MASTER_SECRET_SIZE
#define | FPI_SDCP_APPLICATION_KEYS_SIZE
#define | FPI_SDCP_DEFAULT_LABEL_MASTER_SECRET
#define | FPI_SDCP_DEFAULT_LABEL_APPLICATION_KEYS
#define | FPI_SDCP_DEFAULT_LABEL_CONNECT
#define | FPI_SDCP_DEFAULT_LABEL_RECONNECT
#define | FPI_SDCP_DEFAULT_LABEL_SAMPLE
#define | FPI_SDCP_DEFAULT_LABEL_ENROLL
#define | FPI_SDCP_DEFAULT_LABEL_IDENTIFY
#define | FPI_SDCP_CA_STORE_PATH

## Description

Internal SDCP handling routines. See FpSdcpDevice for public routines.

## Functions

### fpi_sdcp_device_open_complete ()

    void
    fpi_sdcp_device_open_complete (FpSdcpDevice *self,
                                   GError *error);

Reports completion of open operation. Responsible for triggering SDCP connect or reconnect as necessary.

#### Parameters

self | a FpSdcpDevice fingerprint device |
error | A GError or `NULL` on success |

### fpi_sdcp_device_get_application_secret ()

    GBytes *
    fpi_sdcp_device_get_application_secret
                                   (FpSdcpDevice *self);

Returns the SDCP application secret derived during the connect phase. This is the shared symmetric secret established via ECDH key agreement and used as the HMAC key for all subsequent SDCP MAC operations (reconnect, identify, enrollment ID derivation).

This function is intended mostly for testing purposes.

#### Parameters

self | a FpSdcpDevice fingerprint device |

#### Returns

A GBytes containing the application secret, or `NULL` if no SDCP session has been established yet. The caller owns the returned value and must call `g_bytes_unref()` when done.

[transfer full]

### fpi_sdcp_device_get_connect_data ()

    void
    fpi_sdcp_device_get_connect_data (FpSdcpDevice *self,
                                      GBytes **host_random,
                                      GBytes **host_public_key);

### fpi_sdcp_device_connect_complete ()

    void
    fpi_sdcp_device_connect_complete (FpSdcpDevice *self,
                                      GBytes *device_random,
                                      FpiSdcpClaim *claim,
                                      GBytes *mac,
                                      GError *error);

Reports completion of connect operation. Responsible for performing SDCP key agreement, deriving secrets necessary for processing all other SDCP-related payloads, and verifying the device connection is trusted.

#### Parameters

self | a FpSdcpDevice fingerprint device |
device_random | The device random |
claim | The device FpiSdcpClaim |
mac | The MAC authenticating `claim` |
error | A GError or `NULL` on success |

### fpi_sdcp_device_get_reconnect_data ()

    void
    fpi_sdcp_device_get_reconnect_data (FpSdcpDevice *self,
                                        GBytes **reconnect_random);

### fpi_sdcp_device_reconnect_complete ()

    void
    fpi_sdcp_device_reconnect_complete (FpSdcpDevice *self,
                                        GBytes *mac,
                                        GError *error);

Reports completion of a reconnect (i.e. open) operation.

#### Parameters

self | a FpSdcpDevice fingerprint device |
mac | The MAC authenticating `claim` |
error | A GError or `NULL` on success |

### fpi_sdcp_device_list_complete ()

    void
    fpi_sdcp_device_list_complete (FpSdcpDevice *self,
                                   GPtrArray *ids,
                                   GError *error);

Convenience function to create the minimally required FpPrint list for FpSdcpDevice prints using the provided `ids` , then uses that FpPrint list to report completion of the list operation.

If the device provides additional attributes that should be stored on each FpPrint as part of the list operation, a GPtrArray of FpPrint can instead be created with the additional attributes and `fpi_device_list_complete()` can be used instead of this function.

Please note that the `ids` array will be freed using `g_ptr_array_unref()` and the elements are destroyed automatically. As such, you must use `g_ptr_array_new_with_free_func()` with `(GDestroyNotify) g_bytes_unref` as the free func when creating the GPtrArray.

#### Parameters

self | a FpSdcpDevice fingerprint device |
ids | A GPtrArray of GBytes of each SDCP enrollment ID stored on the device |
error | A GError or `NULL` on success |

### fpi_sdcp_device_enroll_commit ()

    void
    fpi_sdcp_device_enroll_commit (FpSdcpDevice *self,
                                   GBytes *nonce,
                                   GError *error);

Called when the print is ready to be committed to device memory. During enrollment, `fpi_device_enroll_progress()` must be called for each successful stage before the print can be committed. The `nonce` generated by the device-specific EnrollmentNonce response must be provided in order for the enrollment ID to be generated. The driver's `enroll_commit()` vfunc will be triggered upon successfully generating the enrollment ID.

#### Parameters

self | a FpSdcpDevice fingerprint device |
nonce | The device generated nonce |
error | a GError or `NULL` on success |

### fpi_sdcp_device_enroll_commit_complete ()

    void
    fpi_sdcp_device_enroll_commit_complete
                                   (FpSdcpDevice *self,
                                    GError *error);

Called when device has committed the given print to memory. This finalizes the enroll operation.

#### Parameters

self | a FpSdcpDevice fingerprint device |
error | a GError or `NULL` on success |

### fpi_sdcp_device_get_identify_data ()

    void
    fpi_sdcp_device_get_identify_data (FpSdcpDevice *self,
                                       GBytes **nonce);

### fpi_sdcp_device_set_identify_data ()

    void
    fpi_sdcp_device_set_identify_data (FpSdcpDevice *self,
                                       GBytes *nonce);

### fpi_sdcp_device_identify_retry ()

    void
    fpi_sdcp_device_identify_retry (FpSdcpDevice *self,
                                    GError *error);

Called when the device requires the finger to be presented again. This should not be called for a verified no-match, it should only be called if e.g. the finger was not centered properly or similar.

Effectively this simply raises the error up. This function exists to bridge the difference in semantics that SDPC has from how libfprint works internally.

#### Parameters

self | a FpSdcpDevice fingerprint device |
error | a GError containing the retry condition |

### fpi_sdcp_device_identify_complete ()

    void
    fpi_sdcp_device_identify_complete (FpSdcpDevice *self,
                                       GBytes *id,
                                       GBytes *mac,
                                       GError *error);

Called when device is done with the identification routine. The returned ID may be `NULL` if none of the in-device templates matched.

#### Parameters

self | a FpSdcpDevice fingerprint device |
id | the ID as reported by the device. | [transfer none]
mac | MAC authenticating the message. | [transfer none]
error | GError if an error occured. | [transfer full]

## Types and Values

### enum FpiDeviceSdcpVerificationFlags

Bitfield of SDCP verification flags for a device.

#### Members

FPI_DEVICE_SDCP_VERIFICATION_DEFAULT | No flags. Perform all verifications. |
FPI_DEVICE_SDCP_VERIFICATION_IGNORE_CERTIFICATES | Skip validating the device's FpiSdcpClaim.model_certificate against the SDCP CA store. SDCP CA store. It determines if the model certificate (cert_m) should be parsed and its trust chain validated as issued from Microsoft's well-known issuers. |
FPI_DEVICE_SDCP_VERIFICATION_IGNORE_SIGNATURES | Skip validating the FpiSdcpClaim.model_signature and FpiSdcpClaim.device_signature. It determines if the model signature (s_m) and device signature (s_d) should be validated against the certificate and keys provided in the claim. |
FPI_DEVICE_SDCP_VERIFICATION_CERTIFICATE_NO_CHECK_TIME | Skip validating the certificate's validity period. |
FPI_DEVICE_SDCP_VERIFICATION_CERTIFICATE_NON_X509_STRICT | Use a less strict validation approach for the certificate, allowing certain non-critical issues to be ignored. |
FPI_DEVICE_SDCP_VERIFICATION_CERTIFICATE_ALLOW_PARTIAL_CHAIN | Allow validation of the certificate even if the trust chain is incomplete. |

### FpSdcpDeviceClass

    typedef struct {
      FpDeviceClass                  parent_class;

      FpiDeviceSdcpVerificationFlags verification_flags;

      void                           (*open)            (FpSdcpDevice *sdcp_device);
      void                           (*connect)         (FpSdcpDevice *sdcp_device);
      void                           (*reconnect)       (FpSdcpDevice *sdcp_device);
      void                           (*list)            (FpSdcpDevice *sdcp_device);
      void                           (*enroll)          (FpSdcpDevice *sdcp_device);
      void                           (*enroll_commit)   (FpSdcpDevice *sdcp_device,
                                                         GBytes       *id);
      void                           (*identify)        (FpSdcpDevice *sdcp_device);

      GResource                    * (*get_ca_store)    (FpSdcpDevice *sdcp_device);
    } FpSdcpDeviceClass;

These are the main entry points for drivers implementing SDCP.

Drivers *must* eventually call the corresponding function to finish the operation.

The following FpDeviceClass entry points are also compatible and can be set on the FpDeviceClass if supported for a given device:

- FpDeviceClass.probe

- FpDeviceClass.close

- FpDeviceClass.delete

- FpDeviceClass.clear_storage

- FpDeviceClass.cancel

- FpDeviceClass.suspend

- FpDeviceClass.resume

Drivers *must* also handle cancellation properly for any long running operation (i.e. any operation that requires capturing). It is entirely fine to ignore cancellation requests for short operations (e.g. open/close).

This API is solely intended for drivers. It is purely internal and neither API nor ABI stable.

#### Members

FpiDeviceSdcpVerificationFlags `verification_flags`; | Bitfield of FpiDeviceSdcpVerificationFlags to control verification behavior. |
`open` () | Open the device. Similar to FpDeviceClass.open except that completion with `fpi_sdcp_device_open_complete()` will also take care of executing `connect` and `reconnect` as necessary. |
`connect` () | Establish SDCP connection. |
`reconnect` () | Perform a faster reconnect. Drivers do not need to provide this function. If reconnect fails, then a normal connect will be tried. |
`list` () | List prints stored on the device. The driver must create a GPtrArray of GBytes with each enrollment ID stored on the device and use it to call `fpi_sdcp_device_list_complete()` in order to complete the operation. |
`enroll` () | Start the enrollment procedure and capture all samples. The driver must report enrollment progress using `fpi_device_enroll_progress()`. It should also store available metadata about the print in device memory. The driver must call `fpi_sdcp_device_enroll_commit()` when all enrollment stages are complete and the print is ready to be commited to the device. |
`enroll_commit` () | Commit the newly-enrolled print to the device memory using the passed id. id may be `NULL`, in which case the driver must abort the enrollment process. id is owned by the base class and remains valid throughout the operation. On completion, the driver must call `fpi_sdcp_device_enroll_commit_complete()`. |
`identify` () | Start identification process. On completion, the driver must call `fpi_sdcp_device_identify_complete()`. To request the user to retry the `fpi_sdcp_device_identify_retry()` function is used. |
`get_ca_store` () | Return a GResource containing additional PEM certificates at the path `FPI_SDCP_CA_STORE_PATH` that will be merged into the default SDCP CA store during certificate verification. This allows drivers to supply device-specific CA certificates without affecting other devices. If not implemented, only the default CA store is used. | [optional]

### FPI_SDCP_RANDOM_SIZE

    #define FPI_SDCP_RANDOM_SIZE 32

### FPI_SDCP_APPLICATION_SECRET_SIZE

    #define FPI_SDCP_APPLICATION_SECRET_SIZE 32

### FPI_SDCP_ENROLLMENT_ID_SIZE

    #define FPI_SDCP_ENROLLMENT_ID_SIZE 32

### FPI_SDCP_NONCE_SIZE

    #define FPI_SDCP_NONCE_SIZE 32

### FPI_SDCP_MAC_SIZE

    #define FPI_SDCP_MAC_SIZE 32

### FPI_SDCP_DIGEST_SIZE

    #define FPI_SDCP_DIGEST_SIZE 32           /* SHA256 */

### FPI_SDCP_CURVE_FIELD_SIZE

    #define FPI_SDCP_CURVE_FIELD_SIZE 32      /* P256 */

### FPI_SDCP_PUBLIC_KEY_SIZE

    #define FPI_SDCP_PUBLIC_KEY_SIZE 65       /* 0x04||x||y */

### FPI_SDCP_PRIVATE_KEY_SIZE

    #define FPI_SDCP_PRIVATE_KEY_SIZE 32      /* log_2(n)/8 */

### FPI_SDCP_SIGNATURE_SIZE

    #define FPI_SDCP_SIGNATURE_SIZE 64        /* r||s */

### FPI_SDCP_ENCRYPTION_BLOCK_SIZE

    #define FPI_SDCP_ENCRYPTION_BLOCK_SIZE 16 /* AES */

### FPI_SDCP_ENCRYPTION_KEY_SIZE

    #define FPI_SDCP_ENCRYPTION_KEY_SIZE 32   /* AES256 */

### FPI_SDCP_MASTER_SECRET_SIZE

    #define FPI_SDCP_MASTER_SECRET_SIZE 32

### FPI_SDCP_APPLICATION_KEYS_SIZE

    #define FPI_SDCP_APPLICATION_KEYS_SIZE 64

### FPI_SDCP_DEFAULT_LABEL_MASTER_SECRET

    #define FPI_SDCP_DEFAULT_LABEL_MASTER_SECRET "master secret"

### FPI_SDCP_DEFAULT_LABEL_APPLICATION_KEYS

    #define FPI_SDCP_DEFAULT_LABEL_APPLICATION_KEYS "application keys"

### FPI_SDCP_DEFAULT_LABEL_CONNECT

    #define FPI_SDCP_DEFAULT_LABEL_CONNECT "connect"

### FPI_SDCP_DEFAULT_LABEL_RECONNECT

    #define FPI_SDCP_DEFAULT_LABEL_RECONNECT "reconnect"

### FPI_SDCP_DEFAULT_LABEL_SAMPLE

    #define FPI_SDCP_DEFAULT_LABEL_SAMPLE "sample"

### FPI_SDCP_DEFAULT_LABEL_ENROLL

    #define FPI_SDCP_DEFAULT_LABEL_ENROLL "enroll"

### FPI_SDCP_DEFAULT_LABEL_IDENTIFY

    #define FPI_SDCP_DEFAULT_LABEL_IDENTIFY "identify"

### FPI_SDCP_CA_STORE_PATH

    #define FPI_SDCP_CA_STORE_PATH "/org/freedesktop/fprint/SDCP/ca-store/"