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 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.
@spec min_salt_bytes() :: pos_integer()
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.
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.
@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.
@spec subject_types() :: [String.t()]
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.