Credential 🧪🔗

Description🔗

Credential portal backend interface

Interface: org.freedesktop.impl.portal.experimental.Credential

Version: Experimental 🧪

The Credential portal allows sandboxed applications to retrieve application-scoped web credentials. The backend interface guides the user through the interactive authentication ceremony.

Properties🔗

org.freedesktop.impl.portal.experimental.Credential:version🔗

version readable u

Methods🔗

org.freedesktop.impl.portal.experimental.Credential.CreateSession🔗

CreateSession (
  IN session_handle o,
  IN parent_window s,
  IN origin s,
  IN type u,
  IN sources a(ss),
  IN app_id s,
  IN app_pid u,
  IN options a{sv}
)

Creates a session for an authentication ceremony with the client context and an initial list of credential sources. During the ceremony, the backend sends user interaction events to the frontend via signals in response to background events sent from the frontend via the other methods on this interface.

Before calling this method, the frontend MUST subscribe to all signals on this interface, filtering for the given session_handle argument. A Session object will be exported on the session_handle path, which can be used by the frontend to cancel the ceremony or receive notification that the user cancelled it. Frontends MUST use the same D-Bus connection throughout the ceremony.

Upon receiving this method call, backends MUST send org.freedesktop.impl.portal.experimental.Credential::DiscoveryRequested when the user is ready to perform the authentication ceremony. Backends MUST send all signals as unicast signals to the original sender calling this method.

Supported keys in the options vardict include:

  • activation_token (s)

    A token that can be used to activate the credential selection dialog.

  • top_origin (s)

    Top-level origin of the request if different from the origin.

  • rp_id (s)

    WebAuthn relying party ID.

    Required if type is PublicKeyCreate or PublicKeyGet.

session_handle

Object path for the Session to create.

parent_window

Identifier for the application window, see Window Identifiers.

origin

The origin of the request.

type

Type of the credential to create. Current supported types are PublicKeyCreate = 0, and PublicKeyGet = 1.

sources

Initial list of credential sources. Map from source ID to transport. Valid transports are Ble, HybridLinked, HybridQr, Internal, Nfc, Usb. Sources may be added or removed during the ceremony.

app_id

App ID of the application.

app_pid

PID of the application.

options

Vardict with optional further information.

Method available since: 1.

org.freedesktop.impl.portal.experimental.Credential.NotifyNeedsPin🔗

NotifyNeedsPin (
  IN session_handle o,
  IN attempts_left u,
  IN options a{sv}
)

The device needs PIN user verification: prompt the user to enter the PIN. The backend must emit the collected value as a org.freedesktop.impl.portal.experimental.Credential::ClientPinEntered signal. See the documentation on that signal for PIN requirements.

The backend should consider rate-limiting requests, or requiring the user to power-cycle (e.g., unplug and plug back in) the device after repeated incorrect attempts to prevent the device from being locked out due to user error or abuse.

The backend should warn the user that the credentials may be permanently lost if they continue to enter incorrect PINs.

There are currently no supported keys in the options vardict.

See also

session_handle

The Session for this authentication ceremony.

attempts_left

The number of PIN attempts remaining before the device is locked out and must be reset/wiped. 0xffffffff means the number of attempts left is unknown.

options

Vardict with optional further information.

Method available since: 1.

org.freedesktop.impl.portal.experimental.Credential.NotifyNeedsUserVerification🔗

NotifyNeedsUserVerification (
  IN session_handle o,
  IN attempts_left u,
  IN options a{sv}
)

The authenticator needs on-device user verification (likely biometrics, or can be on-device PIN entry). Prompt the user to interact with the device.

The backend should display the number of built-in user verification attempts remaining before falling back to client PIN verification.

Note

This is distinct from org.freedesktop.impl.portal.experimental.Credential.NotifyNeedsPin, which uses a PIN captured on the client device rather than directly on the authenticator.

There are currently no supported keys in the options vardict.

See also

session_handle

The Session for this authentication ceremony.

attempts_left

The number of user verification attempts remaining before the built-in user verification methods are disabled until the next successful PIN verification. 0xffffffff means the number of attempts left is unknown.

options

Vardict with optional further information.

Method available since: 1.

org.freedesktop.impl.portal.experimental.Credential.NotifyNeedsUserPresence🔗

NotifyNeedsUserPresence (
  IN session_handle o,
  IN options a{sv}
)

Device requires user interaction (e.g. pressing a button) to release credentials; prompt the user to do so. The device may require additional user verification, but that might not be known until after the user taps the device.

There are currently no supported keys in the options vardict.

session_handle

The Session for this authentication ceremony.

options

Vardict with optional further information.

Method available since: 1.

org.freedesktop.impl.portal.experimental.Credential.NotifySelectingCredential🔗

NotifySelectingCredential (
  IN session_handle o,
  IN credentials aa{sv},
  IN options a{sv}
)

The device is ready to release credentials, but multiple credentials match the request. The backend must prompt the user to select one of the credentials.

Each metadata object in credentials contains the following fields:

  • id: An opaque value to send back to the authenticator. It is NOT the WebAuthn credentialId.

  • name: The account name for the credential.

  • display_name: The human-readable username for the credential.

There are currently no supported keys in the options vardict.

session_handle

The Session for this authentication ceremony.

credentials

A list of metadata for credentials that are able to fulfill the request.

options

Vardict with optional further information.

Method available since: 1.

org.freedesktop.impl.portal.experimental.Credential.NotifyHybridStarted🔗

NotifyHybridStarted (
  IN session_handle o,
  IN invocation_data h,
  IN options a{sv}
)

Hybrid discovery is activated and is awaiting an invocation on the peer device. The backend MUST display the invocation_data as a QR code. For public key credentials (where type of org.freedesktop.impl.portal.experimental.Credential.CreateSession is set to PublicKeyCreate or PublicKeyGet), the backend SHOULD overlay the FIDO passkey logo on the QR code.

The backend MAY use other invocation methods besides QR code as the CTAP2 spec evolves.

invocation_data is a file descriptor whose data consists of the UTF-8-encoded PIN. The file must be memory-mapped to be read. Call fstat() to determine the length of the data.

There are currently no supported keys in the options vardict.

See also

session_handle

The Session for this authentication ceremony.

invocation_data

A memory-mapped filed containing a string of data that is used to invoke the hybrid flow on the peer device.

options

Vardict with optional further information.

Method available since: 1.

org.freedesktop.impl.portal.experimental.Credential.NotifyHybridConnecting🔗

NotifyHybridConnecting (
  IN session_handle o,
  IN options a{sv}
)

The other device has been detected, and a connection is being established. The backend should communicate a pending status and prompt the user to keep the devices close.

There are currently no supported keys in the options vardict.

See also

session_handle

The Session for this authentication ceremony.

options

Vardict with optional further information.

Method available since: 1.

org.freedesktop.impl.portal.experimental.Credential.NotifyHybridConnected🔗

NotifyHybridConnected (
  IN session_handle o,
  IN options a{sv}
)

A connection has been established, waiting for user to release credential on their device. The backend should prompt the user to follow the instructions on the peer device.

There are currently no supported keys in the options vardict.

See also

session_handle

The Session for this authentication ceremony.

options

Vardict with optional further information.

Method available since: 1.

org.freedesktop.impl.portal.experimental.Credential.NotifyNfcConnected🔗

NotifyNfcConnected (
  IN session_handle o,
  IN options a{sv}
)

An NFC device has been detected. The backend should prompt the user to keep the peer device on the NFC reader so that the ceremony can complete.

There are currently no supported keys in the options vardict.

session_handle

The Session for this authentication ceremony.

options

Vardict with optional further information.

Method available since: 1.

org.freedesktop.impl.portal.experimental.Credential.NotifyUsbConnected🔗

NotifyUsbConnected (
  IN session_handle o,
  IN options a{sv}
)

USB device connected, prompt user to interact with the device (e.g. press the button).

The device may require additional user verification to complete the ceremony, but that might not be known until after the user taps the device.

There are currently no supported keys in the options vardict.

session_handle

The Session for this authentication ceremony.

options

Vardict with optional further information.

Method available since: 1.

org.freedesktop.impl.portal.experimental.Credential.NotifyCeremonyCompleted🔗

NotifyCeremonyCompleted (
  IN session_handle o
)

The frontend should call this method when the ceremony completes successfully, and the dialog can be closed.

session_handle

The Session for this authentication ceremony.

Method available since: 1.

org.freedesktop.impl.portal.experimental.Credential.NotifyErrorOccurred🔗

NotifyErrorOccurred (
  IN session_handle o,
  IN error u
)

Notify the backend that an error occurred.

error may contain the following values:

  • ERROR_AUTHENTICATOR = 0x80000001

    An unknown authenticator error occurred.

  • ERROR_NO_CREDENTIALS = 0x80000002

    The authenticator reported that it has no matching credentials stored.

  • ERROR_PIN_ATTEMPTS_EXHAUSTED = 0x80000003

    Too many PIN attempts have been entered, and the authenticator is permanently locked out and must be reset.

  • ERROR_INTERNAL = 0x80000004

    An internal portal error occurred.

  • ERROR_TIMED_OUT = 0x80000005

    The credential request has timed out.

  • ERROR_CANCELLED = 0x80000006

    The user cancelled the request.

session_handle

The Session for this authentication ceremony.

error

The error that occurred.

Method available since: 1.

Signals🔗

org.freedesktop.impl.portal.experimental.Credential::DiscoveryRequested🔗

DiscoveryRequested (
  session_handle o,
  options a{sv}
)

Request for the platform to start credential discovery. This should be emitted by the backend after org.freedesktop.impl.portal.experimental.Credential.CreateSession is called, when all signals are subscribed and the user is ready to perform the authentication ceremony.

There are currently no supported keys in the options vardict.

session_handle

The Session for this authentication ceremony.

options

Vardict with optional further information.

Signal available since: 1.

org.freedesktop.impl.portal.experimental.Credential::ClientPinEntered🔗

ClientPinEntered (
  session_handle o,
  pin_fd h,
  options a{sv}
)

Sends the client PIN to the authenticator for user verification via pin_fd in response to org.freedesktop.impl.portal.experimental.Credential.NotifyNeedsPin.

This is a file descriptor whose data consists of the UTF-8-encoded PIN. The file must be memory-mapped to be read. Call fstat() to determine the length of the data.

Maximum pin length is 63 bytes.

There are currently no supported keys in the options vardict.

session_handle

The Session for this authentication ceremony.

pin_fd

The PIN entered by the user.

options

Vardict with optional further information.

Signal available since: 1.

org.freedesktop.impl.portal.experimental.Credential::CredentialSelected🔗

CredentialSelected (
  session_handle o,
  id s,
  options a{sv}
)

After receiving a org.freedesktop.impl.portal.experimental.Credential.NotifySelectingCredential signal, the backend must prompt the user to select a credential from the list of credential metadata. The backend must send the id of selected credential metadata to the authenticator to release the credential.

Note

id is NOT the WebAuthn credential ID; it is an opaque identifier used just for selecting the credential in this ceremony.

There are currently no supported keys in the options vardict.

session_handle

The Session for this authentication ceremony.

id

The opaque ID representing the selected credential metadata.

options

Vardict with optional further information.

Signal available since: 1.