Remote Two-factor Protected Services

R2PS Protocol Components

Outer JWE object The outer JWE object provides end-to-end encryption of the exchanged service data. It is used in one of two protection modes:

1FA, where the Content Encryption Key (CEK) is derived from a static recipient key and an ephemeral sender key.
2FA, where the session key derived from authentication of the user's two factors is used directly as the CEK. This mode provides forward secrecy.

The recipient determines the mode from the typ parameter of the JWE protected header. The JWE protected header is the only header used; per-recipient and unprotected headers are not used. This document defines the following typ parameters:

r2ps-1fa : identifies the 1FA mode defined in this document.
r2ps-2fa : identifies the 2FA mode defined in this document.

Deployments MAY define and agree on alternative protection modes identified by other typ parameter values.

1FA mode In 1FA mode the CEK is derived using ECDH-ES . The JWE protected header MUST contain:

typ: MUST be r2ps-1fa.
alg: MUST be ECDH-ES.
enc: MUST be A256GCM.
epk: the sender's ephemeral public key.
kid: identifies the recipient's static key-agreement key: the server's static ECDH key in a request, the client's agreement key (CAK) in a response.
apu: MUST be the client_id in a request and the context in a response.
apv: MUST be the context in a request and the client_id in a response.
cty: MUST be JWT.

where context identifies the security context and client_id is the client's identifier within that context. The resulting compact serialization is <header>..<iv>.<ciphertext>.<tag>; the encrypted-key field is empty, as ECDH-ES uses direct key agreement. The sender MUST destroy the ephemeral private key and the CEK as soon as the JWE has been constructed.

2FA mode In 2FA mode the session key, derived from authentication of the user's two factors, is used directly as the CEK (dir, direct encryption). The JWE protected header MUST contain:

typ: MUST be r2ps-2fa.
alg: MUST be dir.
enc: MUST be A256GCM.
kid: the 2FA session identifier.
cty: MUST be JWT.

The IV MUST be a freshly generated 96-bit random value for each message. The resulting compact serialization is <header>..<iv>.<ciphertext>.<tag>; the encrypted-key field is empty, as direct encryption uses the session key as the CEK. The 2FA session identifier identifies the 2FA session key that is negotiated during authentication of the users 2 factors. The 2FA session key is ephemeral and MUST be destroyed after use to preserve forward secrecy.

Inner JWS object The inner JWS object is signed by the sender with its context signing key and carries the request or response structure common to all service types. Variant content specific to a service type resides entirely within the data member of the payload. The JWS protected header MUST contain at least:

alg: SHOULD be ES256.
kid: identifies the signing key. In a request it MUST identify the client's Client Signing Key (CSK) for the security context; implementations SHOULD use the JWK Thumbprint of the CSK public key. In a response it MUST identify the server's Server Signing Key (SSK).
typ: MUST be r2ps-request+jwt in a request and r2ps-response+jwt in a response.

The JWS payload is a JSON object. Members that hold a binary value are encoded as base64 strings as defined in , Section 4 (the standard base64 alphabet, with padding). The following members are common to all exchanges and MUST be present in both requests and responses:

ver (string): the protocol version; "1.0" for this document.
nonce (string): a base64-encoded random byte array carrying at least 16 bytes of entropy. The client generates it for each request, and the server echoes it unchanged in the corresponding response.
iat (integer): the message creation time as a Unix timestamp. The server MUST enforce a maximum iat age and MUST reject a duplicate nonce received within that window. Freshness windows and the state required for replay protection are deployment-defined.
data (object): the service-specific payload, whose structure is determined by the service type.

Request data In addition to the common members, a request payload MUST include the following, which MUST NOT appear in a response:

type (string): the service type identifier. It determines the structure of data, the operations performed, and the required protection mode (1FA or 2FA).
jwe_hash (string): a digest binding this JWS to the JWE that encrypts it, constructed as defined below.

The jwe_hash binds the signed payload to the JWE protected header that carries it, preventing surreptitious forwarding (a recipient re-encrypting the inner JWS under a different JWE). It is computed over the JWE Protected Header exactly as transmitted in compact serialization. This is defined in JWE as BASE64URL(UTF8(JWE Protected Header)), which is the octets preceding the first period in compact serialization. The sender computes the SHA-256 digest of the ASCII octets of that encoded header and carries the resulting 32-octet digest in the jwe_hash member, encoded as a base64 string. The recipient MUST recompute jwe_hash over the received encoded JWE Protected Header and MUST reject the message on mismatch.

Response data

Success Response This response SHOULD be used on successful service completion, or where error handling is provided as part of service data in the response. The response payload includes the common members only (ver, nonce, iat and data). The nonce MUST equal the nonce of the request being answered. The response data object carries the service-specific response members defined by the service type, for example the p_data parameter.

Error response If a server fails to process a request and return a normal response, e.g. due to a missing or invalid parameter, decryption error or signature validation error, etc, it SHOULD return a suitable error response. When a HTTP API is used for service exchange, the server SHALL provide problem details as defined in . The following response codes are RECOMMENDED for use in a HTTP API:

Response code	HTTP response code
ILLEGAL_REQUEST_DATA	400
UNAUTHORIZED	401
ACCESS_DENIED	403
ILLEGAL_STATE	409
UNSUPPORTED_REQUEST_TYPE	415
SERVER_ERROR	500
TRY_LATER	503

Second factor establishment and session creation This section defines common service types for registration, update and authentication of a user's second factor to support session creation based on the user's two factors. The output of session creation is:

session key: a key suitable for direct use as the CEK in the 2FA protection mode in use; its length and parameters are determined by that mode's encryption algorithm. This key MUST be uniformly distributed, MUST be unique per session, and MUST provide forward secrecy.
session identifier: an identifier of the session key and the properties bound to it.
context: the context under which the session is exchanged.
task: an optional identifier of the task to be performed within the session.
session expiration: the time at which the session expires, regardless of whether its task has completed.

A second-factor authentication mechanism that already outputs a key meeting these requirements (for example, the session key produced by OPAQUE ) MAY use that key directly as the session key. Otherwise, the mechanism MUST derive a suitable key from its output, for example using HKDF .

Request parameters These request parameters are defined for use in the defined service types for second factor establishment and session creation.

protocol : (string) - Identifier of the protocol used for two-factor authentication. This parameter defines the content of the p_data parameter in both the request and the response.
state : (string) - Identifier of the state of the protocol exchange
authorization : (byte array) - Authorization data for registration of a new second factor
authorization_type : (string) - The type of authorization data provided in the authorization parameter
task : (string) - The requested session task used to determine the set of operations that are suitable for a created session
session_duration : (integer) - The requested max duration of the created session in seconds
p_data : (defined by protocol) - The protocol-specific request data. Its content is defined by the selected protocol and the current state, and MAY be a string, an object, or null.

Response parameters These response parameters are defined for use in the defined service types for second factor establishment and session creation.

success : (boolean) - Indicates whether the server accepted and successfully processed the exchange. This member MUST be present in every response.
p_data : (defined by protocol) - The protocol-specific response data for the current protocol and state. Its content is defined by the selected protocol and MAY be a string, an object, or null.
session_id : (string) - The session identifier of a created session
task : (string) - Confirming the session task set in the session request
session_expiration_time : (integer) - The latest time this session will end expressed as seconds since epoch

Member presence Each service type specifies, in the tables below, which members appear in its requests and responses. Presence depends on the member, on the position of the exchange within the protocol's sequence, and, for responses, on whether the server reports success. The exchange position is one of:

first: the first exchange of the protocol.
last: the concluding exchange of the protocol.
all: every exchange.
protocol : presence is defined by the protocol.

A protocol that completes in a single exchange treats that exchange as both the first and the last. The presence rule is one of:

required: the member MUST be present.
optional: the member MAY be present.
required on success: the member MUST be present when success is true, and MUST be absent otherwise.
required if requested: the member MUST be present when the corresponding member was present in the request.

A response with success set to false contains only the success member; the presence rules in the tables below describe the success path.

Service types The following service types are defined in this section

create_session: Authenticates the user's two factors and creates a session
2fa_registration: Register a user's second factor
2fa_update: Update a user's second factor

These service types are designed to allow any suitable protocol for authentication, registration and updates of the user's second factor. These service types have defined data structures as defined below.

create_session Service type This service type is used to create a session based on authentication of the user's two factors. This service type MUST be exchanged using 1FA protection mode. The create_session request contains:

Member	Exchange	Presence
`protocol`	all	required
`p_data`	all	required
`state`	all	required
`session_duration`	first	optional
`task`	first	optional

If session_duration is not specified, the server MUST use a default value. The create_session response contains:

Member	Exchange	Presence
`success`	all	required
`session_id`	all	required on success
`p_data`	all	required on success
`task`	last	required if requested
`session_expiration_time`	last	required on success

The session_id identifies the session this exchange is bound to and attempts to create. It MUST be unique within the context and is returned in every response of the exchange. A returned session_id is NOT an indication that the session has been created; that is determined by success and the protocol data in the concluding response.

2fa_registration Service type This service type is used to register a user's second factor. This service type MUST be exchanged using 1FA protection mode. The 2fa_registration request contains:

Member	Exchange	Presence
`protocol`	all	required
`p_data`	all	required
`state`	all	required
`authorization`	protocol	required
`authorization_type`	protocol	optional

The authorization member provides out-of-band authorization that the user is authorized to register a second factor. Its content is defined by authorization_type. NOTE: authorization is carried in the last exchange rather than the first so that protocols with stateless registration are supported uniformly. OPAQUE, for example, processes the evaluate (first) exchange without retaining server state; requiring authorization in the first exchange would force the server to keep state across the exchange. Placing it in the last exchange, where the server commits the registration, keeps registration stateless-friendly for all protocols. This specification defines the following authorization_type values:

otp : The authorization parameter is a one-time password given to the user by out-of-band means.

The 2fa_registration response contains:

Member	Exchange	Presence
`success`	all	required
`p_data`	all	required on success

2fa_update Service type This service type is used to update the user's second factor under the protection of the current 2 factors. This service type MUST be exchanged using 2FA protection mode. This means that a session must already exist that is bound to the user's current 2 factors. This session MUST be bound to a task with the value 2fa_update which allows one exchange of the 2fa_update service type under the 2FA protection mode. This ensures that the user MUST present its second factor as part of the process to update this factor. The 2fa_update request contains:

Member	Exchange	Presence
`protocol`	all	required
`p_data`	all	required
`state`	all	required

The 2fa_update response contains:

Member	Exchange	Presence
`success`	all	required
`p_data`	all	required on success

Defined authentication protocols This specification defines the following authentication protocols:

opaque: Uses OPAQUE to send a password knowledge proof to the server. This SHOULD be used for server-side password checks.
fido2: Proves the second factor with a roaming WebAuthn authenticator. This mode SHOULD be used for device-attested flows using a FIDO2 Authenticator.

OPAQUE protocol Use of the OPAQUE protocol option is identified by the protocol identifier opaque. OPAQUE needs two roundtrips to complete registration or authentication and uses the following defined state identifiers in the context of this protocol:

evaluate - Identifies the initial server evaluation state where the server evaluates the blinded OPRF data.
finalize - Identifies the final state where registration or authentication is finalized.

create_session Protection mode MUST be 1FA. The following OPAQUE data is exchanged between the client and server:

State	Direction	p_data content
`evaluate`	Request	AKE message 1 as Base64 encoded string
`evaluate`	Response	AKE message 2 as Base64 encoded string
`finalize`	Request	AKE message 3 as Base64 encoded string
`finalize`	Response	null

2fa_registration Protection mode MUST be 1FA. Authorization data MUST be present in the finalize state of the protocol and MUST NOT be provided in the evaluate state. The following OPAQUE data is exchanged between the client and server:

State	Direction	p_data content
`evaluate`	Request	Registration request as Base64 encoded string
`evaluate`	Response	Registration response as Base64 encoded string
`finalize`	Request	Registration record as Base64 encoded string
`finalize`	Response	null

2fa_update Protection mode MUST be 2FA. When OPAQUE is used in 2fa_update, the data exchanged between the client and server is the same as in 2fa_registration. The only difference is that the exchange is sent in 2FA protection mode, protected by the previous second-factor session key, and therefore does not need to provide any authorization data.

FIDO2 Authenticator protocol Use of the FIDO2 Authenticator protocol option is identified by the protocol identifier fido2. The second factor is established and verified locally by the user's FIDO2 authenticator. The resulting device attestation is verified by the server. The mechanism relies on two complementary signatures: the JWS signature, which demonstrates possession, and a WebAuthn assertion carried inside data, which demonstrates user verification. Every exchange is signed as an ES256 JWS by the context signing key (CSK). In a platform or smartphone deployment the CSK is the platform's registered signing key and signs the JWS directly. In a roaming FIDO2 deployment the CSK is held by the FIDO2 authenticator, and the JWS signature is produced over the JWS signing input using the WebAuthn sign extension [WebAuthn-sign] (a raw signature over the supplied input). Either way the result is an ordinary ES256 JWS. The second factor is demonstrated by a regular WebAuthn assertion whose authenticator data has the user-verification (UV) flag set. The server requests UV; the authenticator prompts for a PIN or biometric and sets the UV flag in the assertion. The assertion is carried inside the p_data of a fido2 request. To complete the second-factor check the server MUST:

Verify the assertion signature under the CSK registered for the context.
Verify that the UV flag is set.

There is no server-side password-verification object for this mechanism; registration enrols the WebAuthn credential itself. The following defined state identifiers are used in the context of this protocol:

challenge - Establish a challenge for the second factor authentication.
finalize - Provide a WebAuthn signature that proves the second factor.

The p_data content for each state is defined per service type below. The session-key exchange used by create_session (the ephemeral keys and the session-key derivation) is out of scope of this revision and is defined separately.

create_session Protection mode MUST be 1FA. FIDO2 authentication requires two round-trips; the first to establish a challenge, the second to create a WebAuthn signature that proves the second factor and to negotiate the 2FA session. The following data is exchanged between the client and server:

State	Direction	p_data content
`challenge`	Request	Authentication challenge request as JSON object
`challenge`	Response	Authentication challenge response as JSON object
`finalize`	Request	Authentication finalize request as JSON object
`finalize`	Response	Authentication finalize response as JSON object

The challenge request p_data is null. The challenge response p_data: ", "token": "", "user_verification": "required" } ]]>

challenge: the WebAuthn challenge to be signed in the assertion.
token: opaque server state bound to the challenge, echoed by the client in the finalize request so the server need not retain challenge state.
user_verification: the WebAuthn user-verification requirement; MUST be required.

The token is an authenticated encryption of the server's challenge state under a key known only to the server. The server MUST encrypt at least the challenge, the iat, the client_id, and the context, so that the server can, on finalize, recover the issued challenge and confirm it was issued to the same client and context. The encryption algorithm is the server's choice and has no interoperability impact, since the token is produced and consumed only by the server; A256GCM is RECOMMENDED. The server MUST ensure the token cannot be replayed beyond a single authentication, for example by enforcing the iat freshness window and unique IVs. The finalize request p_data: ", "assertion": { "client_epub : "", "credential_id": "", "authenticator_data": "", "client_data": "", "signature": "" } } ]]> The finalize response p_data: ", } ]]> Both sides establish the negotiated 2FA session key as follows:

Compute ikm = ECDH(own ephemeral private key, peer ephemeral public key).
Derive the 2FA session key K = HKDF(ikm, salt, info, L) where salt is message nonce for the finalize round, info is the DST concatenated with a transcript-binding hash, and L is 32 bytes. The DST MUST be r2ps-2fa_authentication-fido2. The transcript binding hash MUST be SHA256(2fa_mode || client_epub || server_epub || task || fido2 assertion signature).

2fa_registration Protection mode MUST be 1FA. Authorization data MUST be present in the finalize state of the protocol and MAY be present also in the challenge state. There is no server-side verification object to register for the fido2 mechanism. Registration instead enrolls the WebAuthn UV-capable credential and binds it to the client_id for that security context. The request carries the result of the WebAuthn credential-creation ceremony (the attestation object and client data); the server validates it according to [WebAuthn] and stores the credential public key. The authorization field authorizes the enrolment, as for the other mechanisms. The flow is double-round. The client first requests a challenge. It then runs the WebAuthn credential-creation ceremony using the challenge it received in round 1. The following data is exchanged between the client and server:

State	Direction	p_data content
`challenge`	Request	Registration challenge request as JSON object
`challenge`	Response	Registration challenge response as JSON object
`finalize`	Request	Registration finalize request as JSON object
`finalize`	Response	null

The challenge request p_data MAY carry client capabilities or preferences; otherwise it is null. Note: Consider if this specification should define a structure for client capabilities and preferences. The challenge response p_data: " } ]]> The finalize request p_data: ", "attestation_object": "", "client_data": "" } ]]> On receiving the finalize request, the server MUST validate the attestation according to [WebAuthn]. Specifically, the server MUST:

Parse client_data (the clientDataJSON) and verify that its type field is exactly "webauthn.create".
Verify that the challenge in client_data matches the challenge issued in the challenge response.
Verify that the origin in client_data matches the Relying Party's expected origin.
Decode attestation_object and verify that the rpIdHash in the authenticator data is the SHA-256 hash of the Relying Party ID.
Verify that the User Present (UP) flag in the authenticator data is set.
Verify that the User Verified (UV) flag in the authenticator data is set.
Verify the attestation statement's signature using the verification procedure for the attestation format.

On success, the server extracts the credential identifier and credential public key from the attested credential data, and binds the credential_id and public key to the client_id in that security context. This credential is the one from which UV assertions are required in subsequent create_session exchanges. On success, the finalize response p_data is null.

2fa_update When the FIDO2 Authenticator protocol is used in 2fa_update, the data exchanged between the client and server is the same as in 2fa_registration. The only difference is that the exchange is sent in 2FA protection mode, protected by the previous second-factor session key, and therefore does not need to provide any authorization data.