Internal FpSdcpDevice: libfprint Reference Manual

## Internal FpSdcpDevice Internal FpSdcpDevice — Internal SDCP device routines |

## Functions

GType | fpi_sdcp_claim_get_type ()
FpiSdcpClaim * | fpi_sdcp_claim_new ()
FpiSdcpClaim * | fpi_sdcp_claim_copy ()
void | fpi_sdcp_claim_free ()
void | fpi_sdcp_device_open_complete ()
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 ()
void | fpi_sdcp_device_get_print_id ()
void | fpi_sdcp_device_set_print_id ()

## Types and Values

| FpSdcpDeviceClass

## Description

Internal SDCP handling routines. See FpSdcpDevice for public routines.

## Functions

### fpi_sdcp_claim_get_type ()

    GType
    fpi_sdcp_claim_get_type (void);

### fpi_sdcp_claim_new ()

    FpiSdcpClaim *
    fpi_sdcp_claim_new (void);

Create an empty FpiSdcpClaim to provide to the base class.

#### Returns

A newly created FpiSdcpClaim.

[transfer full]

### fpi_sdcp_claim_copy ()

    FpiSdcpClaim *
    fpi_sdcp_claim_copy (FpiSdcpClaim *other);

Create a (shallow) copy of a FpiSdcpClaim.

#### Parameters

other | The FpiSdcpClaim to copy |

#### Returns

A newly created FpiSdcpClaim.

[transfer full]

### fpi_sdcp_claim_free ()

    void
    fpi_sdcp_claim_free (FpiSdcpClaim *claim);

Release the memory used by an FpiSdcpClaim.

#### Parameters

claim | a FpiSdcpClaim |

### 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_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]

### fpi_sdcp_device_get_print_id ()

    void
    fpi_sdcp_device_get_print_id (FpPrint *print,
                                  GBytes **id);

Gets the SDCP enrollment ID from the `print` data.

The returned `id` may be `NULL` if the data was not set or in the wrong format.

#### Parameters

print | an SDCP device FpPrint |
id | the ID gotten from the `print` data. | [out][transfer full]

### fpi_sdcp_device_set_print_id ()

    void
    fpi_sdcp_device_set_print_id (FpPrint *print,
                                  GBytes *id);

Sets the SDCP enrollment ID in the `print` data.

#### Parameters

print | an SDCP device FpPrint |
id | the ID to set in the `print` data |

## Types and Values

### 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);
    } 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. |