Registration Options Service

By calling the Registration Options Service and requesting a ServerPublicKeyCredentialCreationOptionsResponse object from the FIDO2 server. This chapter describes the request and response messages between the FIDO2 Relying Party client and Server when calling the Registration Options Service.

info

It is recommended to protect this service using a SecToken.

Base URL

All URLs referenced in this section have the following base:

https://fido.siven.ch/nevisfido/fido2/attestation/options

HTTP Methods

POST and OPTIONS are the only supported HTTP method.

Request Headers

The following request headers are mandatory:

Name	Description
Accept	Accept header, must be application/json.
Content-Type	Content type header, must be application/json.

Request Body

The Registration Options Service requires from the FIDO2 client side of the Relying Party a JSON payload with a ServerPublicKeyCredentialOptionsRequest object. This object has the following structure:

Attribute	Type	Description	Optional
username	String	Should match conceptually with the user-attribute in the credential-repository.	false
displayName	String	Human-palatable name for the user account. Intended only for display.	false
authenticatorSelection	Object	AuthenticatorSelectionCriteria to select the appropriate authenticators to participate in the registration.	true
authenticatorSelection.authenticatorAttachment	String	Describes the authenticators' attachment modalities.	true
authenticatorSelection.requireResidentKey	Boolean	Backwards compatibility, SHOULD set it to true if, and only if, residentKey is set to required.	true
authenticatorSelection.residentKey	String	Specifies the extent to which the Relying Party desires to create a client-side discoverable credential.	true
authenticatorSelection.userVerification	String	This member describes the Relying Party's requirements regarding user verification for the create() operation.	true
attestation	String	Specify preference regarding attestation conveyance during credential generation.	true

Response Headers

The following response headers will be set:

Name	Description
Content-Type	Content type header, fixed to application/json.

Response Body

The Registration Options Service returns a JSON body with a ServerPublicKeyCredentialCreationOptionsResponse object. This object has the following structure:

Attribute	Type	Description
status	String	Describing the status of the response. Can be set to either "ok" or "failed".
errorMessage	String	Error message in case the status is failed.
fido2SessionId	String	Identifier of the FIDO2 session in nevisFIDO. Can be used to query the status from the status service.
rp.id	String	A unique identifier for the Relying Party entity. Configured in nevisfido.yml.
rp.name	String	A human-palatable identifier for the Relying Party, intended only for display. Configured in nevisfido.yml.
user.id	String	The user handle of the user account entity.
user.displayName	String	A human-palatable name for the user account, intended only for display.
user.name	String	A human-palatable identifier for a user account. It is intended only for display, i.e., aiding the user in determining the difference between user accounts with similar displayNames.
challenge	String	Challenge intended to be used for generating the newly created credential's attestation object.
pubKeyCredParams	Array	Describes the algorithms the server requires the client to adhere to upon credential generation.
pubKeyCredParams[].type	String	Type of credential to be created. It is an extension point, currently only support public-key.
pubKeyCredParams[].alg	Number	The COSEAlgorithmIdentifier specifies the cryptographic signature algorithm with which the newly generated credential will be used, and thus also the type of asymmetric key pair to be generated, e.g., RSA or Elliptic Curve.
timeout	Number	Timeout of the ceremony expressed in milliseconds.
excludeCredentials	Array	A sequence of ServerPublicKeyCredentialDescriptor objects, which represent authenticators the backend require the client to exclude from the ceremony, to avoid the registration of multiple credentials with the same authenticator.
authenticatorSelection.authenticatorAttachment	String	Describes the authenticators' attachment modalities.
authenticatorSelection.requireResidentKey	Boolean	Backwards compatibility, SHOULD set it to true if, and only if, residentKey is set to required.
authenticatorSelection.residentKey	String	Specifies the extent to which the Relying Party desires to create a client-side discoverable credential.
authenticatorSelection.userVerification	String	This member describes the Relying Party's requirements regarding user verification for the create() operation.
attestation	String	Specify preference regarding attestation conveyance during credential generation.

info

The nevisFIDO component currently does not support the FIDO2 specification for extensions.

Example Request

POST /nevisfido/fido2/attestation/options HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: fido.siven.ch
Content-Length: 274

{
  "username" : "[email protected]",
  "displayName" : "jeff",
  "authenticatorSelection" : {
    "authenticatorAttachment" : "platform",
    "requireResidentKey" : false,
    "residentKey" : "discouraged",
    "userVerification" : "preferred"
  },
  "attestation" : "direct"
}

cURL:

$ curl 'https://fido.siven.ch/nevisfido/fido2/attestation/options' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "username" : "[email protected]",
  "displayName" : "jeff",
  "authenticatorSelection" : {
    "authenticatorAttachment" : "platform",
    "requireResidentKey" : false,
    "residentKey" : "discouraged",
    "userVerification" : "preferred"
  },
  "attestation" : "direct"
}'

Example Response

HTTP/1.1 200 OK
Date: Mon, 25 Jul 2022 11:31:03 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Content-Length: 963

{
  "status" : "ok",
  "errorMessage" : "",
  "fido2SessionId" : "a89d00cb-0957-4b58-8f87-55ccf5d51b35",
  "rp" : {
    "id" : "siven.ch",
    "name" : "siven"
  },
  "user" : {
    "id" : "amVmZkBzaXZlbi5jaA",
    "displayName" : "jeff",
    "name" : "[email protected]"
  },
  "challenge" : "7T0MFD8EQrmG5wKe0bWd6Q",
  "pubKeyCredParams" : [ {
    "type" : "public-key",
    "alg" : -65535
  }, {
    "type" : "public-key",
    "alg" : -257
  }, {
    "type" : "public-key",
    "alg" : -258
  }, {
    "type" : "public-key",
    "alg" : -259
  }, {
    "type" : "public-key",
    "alg" : -7
  }, {
    "type" : "public-key",
    "alg" : -35
  }, {
    "type" : "public-key",
    "alg" : -36
  } ],
  "timeout" : 300000,
  "excludeCredentials" : [ ],
  "authenticatorSelection" : {
    "authenticatorAttachment" : "platform",
    "requireResidentKey" : false,
    "residentKey" : "discouraged",
    "userVerification" : "preferred"
  },
  "attestation" : "direct"
}

info

Note that nevisFIDO includes proprietary extensions on the top of what is defined by the Conformance Test API:

• fido2SessionId

HTTP Status Codes

The following HTTP status codes are returned by the Registration Options Service:

HTTP Code	Description
200	OK The server processed the request successfully. A ServerPublicKeyCredentialCreationOptionsResponse JSON object is returned.
405	Method Not Allowed The method of the received request was not POST.
406	Not Acceptable The Accept header is not properly set to application/json.
415	Unsupported Media Type The Content-Type header is not properly set to application/json.