Attesto.PairwiseSubject (Attesto v2.28.0)

Copy Markdown View Source

Pairwise Subject Identifiers (OpenID Connect Core 1.0 §8.1).

A pairwise sub is a different value for each sector of Relying Parties, so two clients in different sectors cannot correlate one End-User by comparing subject identifiers. This module holds the two pure rules: which sector a client belongs to, and how a sub is derived for it.

Sector identifier

§8.1 defines the sector identifier as the host component of the client's sector_identifier_uri when it registered one, and otherwise the host component of its registered redirect_uri, which then requires every registered redirect URI to share one host. This module implements the second form only: sector_identifier/1 takes the registered redirect URIs and answers {:error, :multiple_hosts} when they span hosts. Fetching and validating a sector_identifier_uri document (§8.1) is not implemented, so a client whose redirect URIs span hosts cannot use pairwise identifiers.

Derivation

derive/3 computes

base64url(HMAC-SHA256(salt, len(sector) || sector || local_subject))

where len(sector) is the sector identifier's byte length as a 32-bit integer. §8.1 allows any method that is deterministic, cannot be reversed by anyone but the provider, and gives different results per sector. The length prefix keeps two different (sector, subject) pairs from producing the same input. The value is stable for as long as the salt, the sector identifier and the local subject are: changing the salt, or moving a client to another redirect host, changes every sub that client sees.

Summary

Functions

Derive the pairwise sub for local_subject in sector_identifier.

The minimum salt length derive/3 accepts, in bytes.

Encrypt local_subject for recovery by the authorization server or a same-deployment resource server sharing salt.

The sector identifier for a client with these registered redirect URIs: the host they all share, lowercased.

The subject types this module knows: ["public", "pairwise"].

Decrypt a sealed subject produced by seal_subject/3, authenticating against pairwise_sub and salt.

Whether salt is usable: a binary of at least min_salt_bytes/0 bytes.

Functions

derive(sector, subject, salt)

@spec derive(String.t(), String.t(), binary()) :: String.t()

Derive the pairwise sub for local_subject in sector_identifier.

Raises ArgumentError for a salt shorter than min_salt_bytes/0 or an empty sector identifier or subject.

min_salt_bytes()

@spec min_salt_bytes() :: pos_integer()

The minimum salt length derive/3 accepts, in bytes.

seal_subject(subject, pairwise_sub, salt)

@spec seal_subject(String.t(), String.t(), binary()) :: String.t()

Encrypt local_subject for recovery by the authorization server or a same-deployment resource server sharing salt.

Pads the length-prefixed subject to a multiple of 64 bytes and derives a single-use AES-256-GCM key per call from a fresh random 32-byte token nonce via HMAC-SHA256, with pairwise_sub as associated authenticated data. Two tokens therefore carry distinct ciphertexts that cannot be correlated, short subjects share the same ciphertext size, and the ciphertext is bound to its sub.

sector_identifier(redirect_uris)

@spec sector_identifier([String.t()]) ::
  {:ok, String.t()}
  | {:error, :no_redirect_uris | :invalid_redirect_uri | :multiple_hosts}

The sector identifier for a client with these registered redirect URIs: the host they all share, lowercased.

Returns {:error, :no_redirect_uris} for an empty list, {:error, :invalid_redirect_uri} when one has no host, and {:error, :multiple_hosts} when they do not all share one host.

subject_types()

@spec subject_types() :: [String.t()]

The subject types this module knows: ["public", "pairwise"].

unseal_subject(sealed, pairwise_sub, salt)

@spec unseal_subject(term(), term(), term()) :: {:ok, String.t()} | :error

Decrypt a sealed subject produced by seal_subject/3, authenticating against pairwise_sub and salt.

valid_salt?(salt)

@spec valid_salt?(term()) :: boolean()

Whether salt is usable: a binary of at least min_salt_bytes/0 bytes.