Internet Identity technical overview

Registration

When registering a new identity anchor, the user’s browser first generates a fresh session key pair. Once the user activates their secure device, it generates a fresh key pair that will act as the master key pair for this identity anchor. The secure device then signs a delegation from the master public key master_pk to the session public key session_pk, so that the browser can sign a registration ingress message under session_pk using a delegated signature under the principal SHA224(master_pk) · 0x02.

Note that the secret key corresponding to master_pk never leaves the secure device, while the secret key corresponding to session_pk is kept in browser storage where the same-origin policy shields it from being accessed by other canisters than the II canister. The II canister creates a new II anchor and links the principal to the identity anchor. When the user adds an additional device to the anchor, the II canister adds the principals derived from the master public key of the new device to the anchor.

All subsequent operations for this identity anchor must be authenticated under one of the principals associated with the anchor. The user’s browser will use an existing session key pair if the browser memory for the II canister origin contains one with a valid delegation, or creates a new one by repeating the previous procedure. Note that II does not use local storage for II – that's why the user always has to use biometrics/tap the Yubikey. Once the user closes the tab, the delegation is gone.

Authentication

A single page load can involve multiple signed requests and responses. To avoid a user having to activate their security token for each individual message, the user’s browser will generate a session key pair for each relying canister and have the public key for the session certified by the II canister.

More specifically, when the user visits a relying canister and clicks to login with Internet Identity, the user’s browser generates a fresh session key pair and stores it in the browser storage for the relying canister; we refer to the public key as rel_session_pk. The browser is then redirected to the II canister, passing rel_session_pk along by encoding it as part of the URL.

The browser signs an ingress message to log in to the II canister using the authentication procedure above, meaning, re-using a valid session key for the II canister if one exists, or creating a new one if not.

When the user clicks to agree to authenticate to the relying canister, the browser creates a second ingress message to the II canister (also signed with the session public key) that contains the relying canister identity and the relying session public key rel_session_pk

The II canister computes a unique self-authenticating principal for this user anchor and this relying canister as

SHA224(|id_provider| · id_provider · seed) · 02

where the seed is computed based on a secret salt held by the II canister, the user’s identity anchor, and the relying canister as

where anchor is the user’s identity anchor, rel_canister_id is the principal of the relying canister, and seed is a secret seed held by the II canister.

The salt was randomly chosen when the II canister was initialized and is stored in the II canister state. This offers some privacy against canisters that try to track users by linking principals that belong to the same identity anchor. The privacy guarantee does not hold against an adversary who knows the secret seed, though, e.g., a node provider participating in the subnet of the II canister. Note that this only affects privacy, not security: knowledge of the seed does not enable the adversary to impersonate any users.

In its response, the II canister includes the nonce as well as a certified variable (also known as a canister signature) linking the relying canister ID to rel_session_pk and an expiry time. The user’s browser is then redirected to the relying canister, where it signs ingress messages under rel_session_pk.

User experience

[|Internet Identity] does not use passwords and usernames to log in. Internet Identity takes advantage of the Web Authentication (WebAuthn) API to provide secure cryptographic authentication. This means that a user authenticates by "something they have" (e.g a phone, yubikey, etc...) rather than "something they know" (e.g. a password).

From the point of view of the user, a user would use the following methods to authenticate:

Computers
1. Yubikey or Ledger hardware wallet (with computers with USB ports)
2. Thumbprint or face recognition (with computers with electronic fingerprint recognition features like Touch ID or Windows Hello)
Smartphones
1. Face ID (for smartphones with facial recognition systems)
2. Thumbprint (for smartphones with electronic fingerprint recognition features like Touch ID)

Key Concepts

Anchor

An anchor is a number attached to a user's identity. This number is auto-generated by the system and there is only one per identity.

Example: 193431

Devices

Users can add many devices to the same identity anchor. A common example is that users may add their smartphone and desktop computer to an identity anchor. It is recommended to add multiple devices in case users lose access to a device. Devices names are chosen by the user and there can be many per identity.

Example:

"Macbook Pro Alice"
"iPhone Alice"

Recovery Mechanisms

In addition to adding multiple devices and using security keys, a user can set up account recovery at the prompt by clicking Add a recovery mechanism to an Identity Anchor.

Seed Phrase

A user can select this option to generate a cryptographically-secure seed phrase that they can use to recover an Identity Anchor. It is important that the user ensures this phrase is stored somewhere safe and is known only to the user, as anyone who knows the seed phrase will be able to take full control of this Identity Anchor. Note that the first string in a user's seed phrase is the Identity Anchor. This number to begin the recovery process.

The user must click the copy button and then continue or the seed phrase will not be registered.

Security Key

A dedicated security key can be used to recover an Identity Anchor in the event that a user loses access to their authorized devices. This key must be different from the ones the user actively used to authenticate to Internet Identity using the given Identity Anchor. This key should be kept somewhere safe and ensure it is available only to the user. As above, anyone in possession of this security key will be able to take full control of the user's Identity Anchor. A user will need to know the Identity Anchor to begin recovery.

Security

Internet Identity is a canister running on the NNS network, so developers can verify it is running the code it is claimed to run. To verify the code, see Verifying the Internet Identity Code: A Walkthrough.

Support

To see current support of WebAuthn, see Webauthn Support.