Face-PKI ceremony flow

The face-PKI ceremony flow answers a request from an application for the user's face-locked keys. The application asks for one of three things: the user's public keys, a signature, or a shared secret. The request arrives on the phone as a CIBA link. The user approves it with a face scan. The SDK then does the key operation, delivers the signed result to the application, and posts the completion to SenseCrypt.

Your app supplies the same inputs as for a login: the link, an optional password, and a face capture. It observes the state machine to drive its UI. For the application side, see Face PKI over CIBA.

The keys are specific to the application and to the context it asks for. Two applications that ask for the same context get different keys, even in the same tenant. Your app does not see the context and cannot change it.

Starting the flow

let flow = authn.startPkiCeremonyFlow()

Task {
    for await state in flow.stateStream() {
        handle(state)
    }
}

val flow = withContext(Dispatchers.IO) { authn.startPkiCeremonyFlow() }

lifecycleScope.launch {
    flow.state.collect { state -> handle(state) }
}

startPkiCeremonyFlow() does not throw. Start it when a link arrives, not at app launch.

The state machine

The flow runs the liveness check before the face match. A badly framed frame then fails on liveness and does not spend a face-mismatch attempt.

States and their payloads

PkiCeremonyKind is one of publicKeys, sign or decapsulate. Use it to word the approval screen.

Step 1 — submit the link

A ceremony arrives on the same pushed link and universal link as a CIBA sign-in. Pass the raw link bytes to the flow. The call returns immediately. Observe the state for the outcome.

flow.submitLinkPayload(payload: linkBytes)

flow.submitLinkPayload(linkBytes)

Your app cannot tell a ceremony link from a sign-in link before it submits it. Each flow refuses the other flow's link, and names it:

You can try either flow first. The SenseCrypt Authenticator app submits every link to a LoginFlow first, and re-submits a refused ceremony link to a PkiCeremonyFlow.

Other refusals stay on awaitingLink:

Step 2 — the optional password step

If downloadingFaceToken.passwordRequired is true, the user's face token needs a password. Collect it and submit it:

flow.submitPassword(password: enteredPassword)

flow.submitPassword(enteredPassword)

A wrong password keeps the flow on downloadingFaceToken and sets lastPasswordError. This is the same step as in the login flow.

Step 3 — show the approval screen and capture a face

awaitingFaceCapture carries what the user approves. Show all of it before you open the camera:

• bindingMessage — the text the application sent. It is always present on a ceremony. Show it in full.
• kind — what the application asks for. Word the title from it, for example "Acme requests your signature".
• rpLabel and branding — the application's name, logo and colours.
• expiresAtUnix — when the request expires. Show a countdown.

Then run a face capture session and submit it:

flow.submitFaceCapture(captureSession: session)

flow.submitFaceCapture(captureSession = session)

The SDK checks liveness, matches the face, opens the face token, does the key operation, and moves to deliveringResult. A liveness failure or a face mismatch returns the flow to awaitingFaceCapture with a FaceCaptureRetryReason. The retry budget is the same as for a login: attemptsMax attempts. When the budget is spent, the SDK signs an abort to SenseCrypt and the flow ends in failed.

Some refusals are known only after the face match, because the answer would tell a stranger something about the user's keys. They end the flow in failed with one of the face-PKI failure reasons. Your app cannot fix them. Tell the user to contact the application.

Step 4 — delivery and completion

After the face match the SDK does two network calls in order:

1. Deliver. It POSTs the signed result to the application's delivery endpoint (deliveringResult).
2. Complete. It POSTs the completion to SenseCrypt (postingResult).

The order matters. SenseCrypt marks the request complete only after the application has accepted the result.

If the application refuses the result or cannot be reached, the flow moves to deliveryFailed(status:). The state is not terminal. Show a "Not delivered" sheet with two actions:

• Try again → retry(). The SDK re-sends the same signed bytes. It does not run a second face scan.
• Cancel → cancelCeremony(). The SDK signs a delivery_failed abort to SenseCrypt. The flow ends in failed.

If the completion fails on a transient error, the flow moves to postingResultFailed(reason:). Call retry() to re-post it. The application already holds the result.

succeeded is terminal. It carries rpLabel, kind and timestamp. Show a confirmation and dismiss.

Cancelling

Two calls end the flow. They differ in what SenseCrypt learns.

Prefer cancelCeremony() for a user action. The application then learns the outcome at once instead of after the request expires.

What your app observes about keys

Nothing, in the normal case. Three rules decide what happens underneath, and each shows up in your app in one way only.

• Keys arrive with the policy, not only at enrolment. The tenant's key policy reaches the phone on every sign-in and ceremony. If a user's face token predates it and holds no keys, the SDK seals keys into the token after the face match and before the key operation, as part of the token rotation every completion already performs. The upgrade is fill-only: a key the token already holds never changes, so a key an application pinned never moves. The ceremony that finds such a token completes on the keys it just gained.
• Two rotations from one token. A ceremony and a sign-in, or two devices, can be pending at once, and both rotate from the same token. SenseCrypt stores one of the two rotations. A ceremony whose rotation is not the one stored is refused at completion: the flow does not reach succeeded, the application's token request answers stale_token, and the application starts a new request, which stages the current token. The phone's stored state needs nothing fixed, but the flow stops in postingResultFailed and a retry cannot succeed: offer only cancel, and let the application start again.
• Protocol floor. Ceremonies need device protocol 7. An app built on an older SDK is refused when it submits a ceremony link and ends in failed(reason: .upgradeRequired). Prompt for an update; there is no retry.

What the SDK sends

You do not build the delivery. The SDK does. For reference, the delivery is a JSON body signed with the user's ML-DSA key in an X-SenseCrypt-Signature header, with the application's client_notification_token as the bearer. Its fields are described in Face PKI over CIBA. Of the result, the completion sends SenseCrypt only the SHA-256 of that body. SenseCrypt returns the hash to the application in the ID token as a receipt.

Related

• Face PKI over CIBA — the application side: the request, the endpoint checks, and the receipt.
• Login flow — the sign-in flow this one mirrors.
• Errors — the failure reasons a ceremony can end with.
• Push notifications — how the ceremony's link reaches the phone.