2024-04-03 13:39:44 +05:30

19 KiB

Raw Blame History

Passkeys on Ente

Passkeys is a colloquial term for a relatively new authentication standard called WebAuthn. Now rolled out to all major browsers and operating systems, it uses asymmetric cryptography to authenticate the user with a server using replay-attack resistant signatures. These processes are usually abstracted from the user through biometric prompts, such as Touch ID/Face ID/Optic ID, Fingerprint Unlock and Windows Hello. These passkeys can also be securely synced by major password managers, such as Bitwarden and 1Password, although the syncing experience can greatly vary due to some operating system restrictions.

Terms

Term	Definition
Credential	Passkey. It is an asymmetric keypair identified by a unique ID generated by the client.
Authenticator	A software-based implementation or physical device capable of storing and using credentials to authenticate.
Relying Party	Us. We rely on the user's authenticator to verify their identity through a cryptographic signature. We prove this signature through the credential's public key that we store.
Ceremony	An analogy referring to the multiple steps involved in authenticating or registering a credential with a relying party. Ceremonies have a "begin" and a "finish". Information must be persisted between these two steps.

Getting to the passkeys manager

As of Feb 2024, Ente clients have a button to navigate to a WebView of Ente Accounts. Ente Accounts allows users to add and manage their registered passkeys.

❗ Your WebView MUST invoke the operating-system's default browser, or an equivalent browser with matching API parity. Otherwise, the user will not be able to register or use registered WebAuthn credentials.

Accounts-Specific Session Token

When a user clicks this button, the client sends a request for an Accounts-specific JWT session token as shown below. The Ente Accounts API is restricted to this type of session token, so the user session token cannot be used. This restriction is a byproduct of the enablement for automatic login.

GET /users/accounts-token

Headers

Name	Type	Value
X-Auth-Token	string	The user session token. It is encoded in base64.

Response Body (JSON)

Key	Type	Value
accountsToken	string	The Accounts-specific JWT session token. It is encoded in base64.

Automatically logging into Accounts

Clients open a WebView with the URL https://accounts.ente.io/accounts-handoff?token=<accountsToken>&package=<app package name>. This page will appear like a normal loading screen to the user, but in the background, the app parses the token and package for usage in subsequent Accounts-related API calls.

If valid, the user will be automatically redirected to the passkeys management page. Otherwise, they will be required to login with their Ente credentials.

Registering a WebAuthn credential

Requesting publicKey options (begin)

The registration ceremony starts in the browser. When the user clicks the "Add new passkey" button, a request is sent to the server for "public key" creation options. Although named "public key" options, they actually define customizable parameters for the entire credential creation process. They're like an instructional sheet that defines exactly what we want. As of the creation of this document, the plan is to restrict user authenticators to cross-platform ones, like hardware keys. Platform authenticators, such as TPM, are not portable and are prone to loss.

On the server side, the WebAuthn library generates this information based on data provided from a webauthn.User interface. As a result, we satisfy this interface by creating a type with methods returning information from the database. Information stored in the database about credentials are all pre-processed using base64 where necessary.

type PasskeyUser struct {
	*ente.User
	repo *Repository
}

func (u *PasskeyUser) WebAuthnID() []byte {
	b, _ := byteMarshaller.ConvertInt64ToByte(u.ID)
	return b
}

func (u *PasskeyUser) WebAuthnName() string {
	return u.Email
}

func (u *PasskeyUser) WebAuthnDisplayName() string {
	return u.Name
}

func (u *PasskeyUser) WebAuthnCredentials() []webauthn.Credential {
	creds, err := u.repo.GetUserPasskeyCredentials(u.ID)
	if err != nil {
		return []webauthn.Credential{}
	}

	return creds
}

GET /passkeys/registration/begin

Headers

Name	Type	Value
X-Auth-Token	string	The user session token. It is encoded in base64.

Response Body (JSON)

Key	Type	Value
options	object	The credential creation options that will be provided to the browser.
sessionID	string (uuidv4)	The identifier the server uses to persist metadata about the registration ceremony, like the user ID and challenge to prevent replay attacks.

{
    "options": {
        "publicKey": {
            "rp": {
                "name": "Ente",
                "id": "accounts.ente.io"
            },
            "user": {
                "name": "james@example.org",
                "displayName": "",
                "id": "AAWdgssasAY"
            },
            "challenge": "xYVv1V08dgrsU_4k5niEkFcfIGbwPauWKPBARS6C6Dg",
            "pubKeyCredParams": [
                {
                    "type": "public-key",
                    "alg": -7
                },
                {
                    "type": "public-key",
                    "alg": -35
                },
                {
                    "type": "public-key",
                    "alg": -36
                },
                {
                    "type": "public-key",
                    "alg": -257
                },
                {
                    "type": "public-key",
                    "alg": -258
                },
                {
                    "type": "public-key",
                    "alg": -259
                },
                {
                    "type": "public-key",
                    "alg": -37
                },
                {
                    "type": "public-key",
                    "alg": -38
                },
                {
                    "type": "public-key",
                    "alg": -39
                },
                {
                    "type": "public-key",
                    "alg": -8
                }
            ],
            "timeout": 300000,
            "authenticatorSelection": {
                "requireResidentKey": false,
                "userVerification": "preferred"
            }
        }
    },
    "sessionID": "0a8442d7-8580-4391-8ac3-4a75d6a7f115"
}

Pre-processing the options before registration

Even though the server generates these options, the browser still doesn't understand them. For interoperability, the server's WebAuthn library returns binary data in base64, like IDs and the challenge. However, the browser requires this data back in binary.

We just have to decode the base64 fields back into Uint8Array.

const options = response.options;

options.publicKey.challenge = _sodium.from_base64(options.publicKey.challenge);
options.publicKey.user.id = _sodium.from_base64(options.publicKey.user.id);

Creating the credential

We use navigator.credentials.create with these options to generate the credential. At this point, the user will see a prompt to decide where to save this credential, and probably a biometric authentication gate depending on the platform.

const newCredential = await navigator.credentials.create(options);

Sending the public key to the server (finish)

The browser returns the newly created credential with a bunch of binary fields, so we have to encode them into base64 for transport to the server.

const attestationObjectB64 = _sodium.to_base64(
	new Uint8Array(credential.response.attestationObject),
	_sodium.base64_variants.URLSAFE_NO_PADDING
);
const clientDataJSONB64 = _sodium.to_base64(
	new Uint8Array(credential.response.clientDataJSON),
	_sodium.base64_variants.URLSAFE_NO_PADDING

Attestation object contains information about the nature of the credential, like what device it was generated on. Client data JSON contains metadata about the credential, like where it is registered to.

After pre-processing, the client sends the public key to the server so it can verify future signatures during authentication.

POST /passkeys/registration/finish

When the server receives the new public key credential, it pre-processes the JSON objects so they can fit within the database. This includes base64 encoding []byte slices and their encompassing arrays or objects.

// Convert the PublicKey to base64
publicKeyB64 := base64.StdEncoding.EncodeToString(cred.PublicKey)

// Convert the Transports slice to a comma-separated string
var transports []string
for _, t := range cred.Transport {
	transports = append(transports, string(t))
}
authenticatorTransports := strings.Join(transports, ",")

// Marshal the Flags to JSON
credentialFlags, err := json.Marshal(cred.Flags)
if err != nil {
	return nil, err
}

// Marshal the Authenticator to JSON and encode AAGUID to base64
authenticatorMap := map[string]interface{}{
	"AAGUID":       base64.StdEncoding.EncodeToString(cred.Authenticator.AAGUID),
	"SignCount":    cred.Authenticator.SignCount,
	"CloneWarning": cred.Authenticator.CloneWarning,
	"Attachment":   cred.Authenticator.Attachment,
}
authenticatorJSON, err := json.Marshal(authenticatorMap)
if err != nil {
	return nil, err
}

// convert cred.ID into base64
credID := base64.StdEncoding.EncodeToString(cred.ID)

On retrieval, this process is effectively the opposite.

Query Parameters

Key	Value
friendlyName	The user's entered name for their credential. It helps them identify it in the dashboard in the future.
sessionID	The server's identifier for this registration ceremony instance, as returned from the begin step.

Headers

Name	Type	Value
X-Auth-Token	string	The user session token. It is encoded in base64.

Request Body (JSON)

Key	Type	Value
id	string	Base64 encoded client generated identifier for the credential.
rawId	string	Base64 encoded client generated identifier for the credential that can be derived from the browser's rawId field, but can also just be set to id.
type	string	The type of credential.
response	object	Contains attestationObject and clientDataJSON fields that were encoded prior to request.

Example

{
	id: credential.id,
	rawId: credential.id,
	type: credential.type,
	response: {
		attestationObject: attestationObjectB64,
		clientDataJSON: clientDataJSONB64,
	},
}

Authenticating with a credential

Passkeys have been integrated into the existing two-factor ceremony. When logging in via SRP or verifying an email OTT, the server checks if the user has any number of credentials setup or has 2FA TOTP enabled. If the user has setup at least one credential, they will be served a passkeySessionID which will initiate the authentication ceremony.

const {
    // ...
    twoFactorSessionID,
    passkeySessionID,
} = await loginViaSRP(srpAttributes, kek);
setIsFirstLogin(true);
if (passkeySessionID) {
    // ...
}

The client should redirect the user to Accounts with this session ID to prompt credential authentication. We use Accounts as the central WebAuthn hub because credentials are locked to an FQDN.

window.location.href = `${getAccountsURL()}/passkeys/flow?passkeySessionID=${passkeySessionID}&redirect=${
    window.location.origin
}/passkeys/finish`;

Requesting publicKey options (begin)

GET /users/two-factor/passkeys/begin

Query Parameters

Key	Value
sessionID	The `passkeySessionID` returned from SRP login or email OTT verification.

Response Body (JSON)

Example

{
    "ceremonySessionID": "98a80fbd-c484-4f3b-a139-c43faf4b171f",
    "options": {
        "publicKey": {
            "challenge": "dF-mmdZSBxP6Z7OhZrmQ4h-k-BkuuX6ERnW_ckYdkvc",
            "timeout": 300000,
            "rpId": "accounts.ente.io",
            "allowCredentials": [
                {
                    "type": "public-key",
                    "id": "lGfY8iSVjdAsqGKzWv3mkAesRfo",
                    "transports": [""]
                }
            ],
            "userVerification": "preferred"
        }
    }
}

Key	Type	Value
ceremonySessionID	string	The server identifier for the authentication session.
options	object	publicKey options that define which WebAuthn credentials are valid. These credentials can be safely shared with the user because they do not contain any personally identifiable information.

Pre-processing the options before retrieval

The browser requires Uint8Array versions of the options challenge and credential IDs.

publicKey.challenge = _sodium.from_base64(
    publicKey.challenge,
    _sodium.base64_variants.URLSAFE_NO_PADDING,
);
publicKey.allowCredentials?.forEach(function (listItem: any) {
    listItem.id = _sodium.from_base64(
        listItem.id,
        _sodium.base64_variants.URLSAFE_NO_PADDING,
    );
});

Retrieving the credential

const credential = await navigator.credentials.get({
    publicKey: options,
});

Pre-processing the credential metadata and signature before authentication

Before sending the public key and signature to the server, their outputs must be encoded into Base64.

authenticatorData: _sodium.to_base64(
    new Uint8Array(credential.response.authenticatorData),
    _sodium.base64_variants.URLSAFE_NO_PADDING
),
clientDataJSON: _sodium.to_base64(
    new Uint8Array(credential.response.clientDataJSON),
    _sodium.base64_variants.URLSAFE_NO_PADDING
),
signature: _sodium.to_base64(
    new Uint8Array(credential.response.signature),
    _sodium.base64_variants.URLSAFE_NO_PADDING
),
userHandle: _sodium.to_base64(
    new Uint8Array(credential.response.userHandle),
    _sodium.base64_variants.URLSAFE_NO_PADDING
),

Sending the credential metadata and signature to the server (finish)

POST /users/two-factor/passkeys/finish

Query Parameters

Key	Value
ceremonySessionID	The `ceremonySessionID` identifier from the begin step.
sessionID	The `passkeySessionID` identifier from the SRP login or email OTT verification response.

Request Body (JSON)

Key	Type	Value
id	string	Base64 encoded client generated identifier for the credential.
rawId	string	Base64 encoded client generated identifier for the credential that can be derived from the browser's rawId field, but can also just be set to id.
type	string	The type of credential.
response	object	Contains authenticatorData, clientDataJSON, signature and userHandle fields that were encoded prior to request.

Response Body (JSON)

Key	Type	Value
id	int64	The user's ID.
keyAttributes	object	Contains user encryption metadata.
encryptedToken	string	The encrypted user session token in Base64.

19 KiB Raw Blame History

Passkeys on Ente

Terms

Getting to the passkeys manager

Accounts-Specific Session Token

GET /users/accounts-token

Headers

Response Body (JSON)

Automatically logging into Accounts

Registering a WebAuthn credential

Requesting publicKey options (begin)

GET /passkeys/registration/begin

Headers

Response Body (JSON)

Pre-processing the options before registration

Creating the credential

Sending the public key to the server (finish)

POST /passkeys/registration/finish

Query Parameters

Headers

Request Body (JSON)

Authenticating with a credential

Requesting publicKey options (begin)

GET /users/two-factor/passkeys/begin

Query Parameters

Response Body (JSON)

Pre-processing the options before retrieval

Retrieving the credential

Pre-processing the credential metadata and signature before authentication

Sending the credential metadata and signature to the server (finish)

POST /users/two-factor/passkeys/finish

Query Parameters

Request Body (JSON)

Response Body (JSON)

19 KiB

Raw Blame History