Copyright © 2013-2017 FIDO Alliance All Rights Reserved.
Platform APIs are specific to the individual platform. Instead of mandating a specific FIDO API (e.g. function names, parameter lists, etc.), FIDO specifies a set of functional requirements for a platform. Platform vendors can decide how to best provide such functionality in their respective platform API. Platforms implementing all FIDO functional requirements can be FIDO certified and hence indicate that they provide native FIDO support.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current FIDO Alliance publications and the latest revision of this technical report can be found in the FIDO Alliance specifications index at https://www.fidoalliance.org/specifications/.
This document was published by the FIDO Alliance as a Review Draft. This document is intended to become a FIDO Alliance Proposed Standard. If you wish to make comments regarding this document, please Contact Us. All comments are welcome.
This is a Review Draft Specification and is not intended to be a basis for any implementations as the Specification may change. Permission is hereby granted to use the Specification solely for the purpose of reviewing the Specification. No rights are granted to prepare derivative works of this Specification. Entities seeking permission to reproduce portions of this Specification for other uses must contact the FIDO Alliance to determine whether an appropriate license for such use is available.
Implementation of certain elements of this Specification may require licenses under third party intellectual property rights, including without limitation, patent rights. The FIDO Alliance, Inc. and its Members and any other contributors to the Specification are not, and shall not be held, responsible in any manner for identifying or failing to identify any or all such third party intellectual property rights.
THIS FIDO ALLIANCE SPECIFICATION IS PROVIDED “AS IS” AND WITHOUT ANY WARRANTY OF ANY KIND, INCLUDING, WITHOUT LIMITATION, ANY EXPRESS OR IMPLIED WARRANTY OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
All diagrams, examples, notes in this specification are non-normative.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].
This section is non-normative.
FIDO defines an authenticator to maintain FIDO Credentials (see [FIDOGlossary]) and protect the use of such FIDO Credentials by some User Gesture. FIDO 2 specifies the format of the cryptographic objects (attestationStatement [FIDOKeyAttestation] and FIDOSignature [FIDOSignatureFormat]).
Authenticators use different credentials for different FIDO Relying Parties (RPs). An RP comprises one or more application facets. Examples of facets are: a web application, or a native app (e.g., Android App, iOS App, or Windows App). Facets have identifiers -- for example, an Android app can be identified by its package signature, and a web application can be identified by its web origin [RFC6454]. As a full example, an RP named "Example" may include various subdomains under example.com ("www.example.com", "login.example.com", etc.), as well as fielding various Android, iOS, and Windows Apps. A user’s FIDO Authenticator uses the same credential for a user's given RP account across an RP's application facets, and uses a different credential when interacting with other RPs.
We achieve this through the following mechanism: Each RP is associated with an RP ID, which is the "public suffix + 1" or "PS+1" (which is also referred to as the "Effective Top-Level Domain plus One" or "eTLD+1"), that the RP uses as the basis for its DNS names [PUBLICSUFFIXWEB]. To continue the above example, "www.example.com" and "login.example.com" share the PS+1 of "example.com", which is thus the RP ID of the "Example" RP.
When generating, or using, FIDO credentials on the web platform, i.e., via browser-implemented JavaScript APIs, the FIDO Client derives the RP ID from the web origin of the caller of the FIDO API. For example, if the calling web origin is "https://login.example.com", the FIDO Client determines the RP ID of that caller to be "example.com".
When generating, or using, credentials via "native" platform APIs (e.g., Android, Window, iOS), it is the platform’s responsibility to associate a native app with an RP ID. For example, the Android OS platform must provide a mechanism for associating Example's Android app with the eTLD+1 "example.com". One way it may accomplish this, for example, is by having the same Android OS developer account prove ownership of both the Example Android app and the "example.com" domain name, or through some other mechanism determined by the platform provider.
Requirements incorporating the RP ID concept in platform APIs are expressed in the following section.
There MUST be some API functionality allowing an application to generate a new FIDO Credential.
The purpose of this functionality is to use asymmetric keys protected by a user gesture
in a challenge response protocol for authentication.
At a minimum, the discovery API MUST provide the ability
for an application to query for all available authenticators
on the device and their associated authenticator data
(including at a minimum authenticator ID,
protocol version supported, and supported protocol extensions).
The purpose of this functionality is to allow the relying party to select the most
appropriate authenticator without user input.
There MUST be some API functionality allowing an application to influence the authenticator
being used for generating a new FIDO Credential.
The purpose of this functionality is to allow the relying party to select the most
appropriate authenticator without user input.
There MUST be some API functionality allowing an application to influence the behavior (e.g. details of user
verification, specifics of the crypto, etc.) of the authenticator being used for generating a new
FIDO Credential - to the extent this is supported by the authenticator.
The purpose of this functionality is to enable an ecosystem of authenticators.
There MUST be some API functionality allowing an application to request an
AttestationStatement [FIDOKeyAttestation] for
a FIDO Credential.
The purpose of this functionality is to provide a cryptographic proof of the authenticator model
protecting the FIDO Credential to the relying party.
The attData field in the attestation object MUST include the public key (i.e. FIDO Credential)
or a cryptographic hash of it.
There MUST be some API functionality allowing an application to bind an application context
to the AttestationStatement.
The purpose of this functionality is to provide a general means for providing the server challenge
and any kind of channel binding. This is required in order to protect against
replay attacks as well as man-in-the-middle attacks.
There MUST be some API functionality binding the FIDO
Credential being generated to the
RP ID of the calling application, the RP ID MUST be in the form of a PS+1
domain name, and the platform provider MUST have a means of associating
native applications to the RP ID
The purpose of this functionality is to restrict the access of a
FIDO Credential to applications implemented by the same
relying party.
There MUST be some API functionality allowing an application to use a
FIDO Credential for creating a FIDOSignature object [FIDOSignatureFormat].
The purpose of this functionality is to use asymmetric keys protected by a user gesture
in a challenge response protocol for authentication.
There MUST be some API functionality allowing an application to
regain access to a previously generated FIDO Credential.
The purpose of this functionality is to allow an application to
generate a FIDO Credential once and use it
multiple times.
There MUST be some API functionality preventing applications with different
RP IDs from accessing FIDO Credentials bound to other RP IDs.
The purpose of this functionality is to protect the user's privacy.
There MUST be some API functionality allowing an application
to bind an application context to the AttestationStatement.
The purpose of this functionality is to have a mean to provide the server challenge
and any kind of channel binding. This is required in order to protect against
replay attacks and against man-in-the-middle attacks.
There MUST be some API functionality allowing an application to influence the behavior (e.g. details of user
verification, specifics of the crypto, etc.) of the authenticator being
used - to the extent this is supported by the authenticator.
The purpose of this functionality is enable an ecosystem of authenticators.
The platform SHALL support external authenticators plugged into the platform using the FIDO Client To Authenticator Protocol [FIDOCTAP]. If the platform doesn't support external authenticators as described above, it MUST have at least one embedded authenticator.
Platforms MUST support the generation of a FIDOSignature object [FIDOSignatureFormat].
The Client Data [FIDOSignatureFormat] is composed of several data elements (e.g. server challenge, facetId etc.), some of which may not be directly available to the platform (e.g. the server challenge). The platform signature API MUST support a way for its invokers to provide relevant Client Data elements as input.
The Platform FIDO signature implementation MUST provide the hashed Client Data to the authenticator for inclusion in the authenticator signature.
The Platform signature implementation MUST enable the authenticator to determine which key pair should be used to generate the authenticator signature.
The Platform signature implementation MUST preserve any extra data passed by the authenticator in the authenticator signature and include such data in the FIDOSignature object.