Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Use COSE_Key and COSE Algorithm Identifiers #514

Merged
merged 12 commits into from
Aug 4, 2017
Merged

Use COSE_Key and COSE Algorithm Identifiers #514

Changes from 4 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
3fc9a3b
Use COSE_Key and COSE Algorithm Identifiers
selfissued Aug 2, 2017
5a74b00
Merge branch 'master' of https://github.com/w3c/webauthn into mbj-COS…
selfissued Aug 2, 2017
c6dfe7f
Merge branch 'master' of https://github.com/w3c/webauthn into mbj-COS…
selfissued Aug 3, 2017
20116e7
Restored incorrectly deleted Credential ID
selfissued Aug 3, 2017
cc290fd
add refs for IANA COSE & JOSE registries
Aug 3, 2017
2846f07
create AlgorithmIdentifier typedef
Aug 3, 2017
174c1c1
fix biblio json - delete commas
Aug 3, 2017
c976484
polish several things, eg UV, UP, uv, rk -related
Aug 4, 2017
2c10415
fixup figs 1 & 3, fix attestation data description S 5.3.1
Aug 4, 2017
64f0d84
really fixing attestation data description S 5.3.1
Aug 4, 2017
e1cc12f
Merge pull request #1 from selfissued/jeffh-COSE_Key
selfissued Aug 4, 2017
b2b1793
Added dashes in registry references to make them more readable
selfissued Aug 4, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 21 additions & 51 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,13 +64,6 @@ spec: TokenBinding; urlPrefix: https://tools.ietf.org/html/draft-ietf-tokbind-pr
text: Token Binding
text: Token Binding ID; url: section-3.2

spec: WebCryptoAPI; urlPrefix: https://www.w3.org/TR/WebCryptoAPI/
type: dfn
text: normalizing an algorithm; url: dfn-normalize-an-algorithm
text: recognized algorithm name
type: dictionary
text: AlgorithmIdentifier; url: dfn-AlgorithmIdentifier

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

when one deletes stuff like this, one needs to run BikeShed and check for errors -- in this case, we still use the "recognized algorithm name" from WebCrypto, and that is causing linking errors without at least that portion the above in the spec.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where we are using WebCrypto "recognized algorithm names" for the hash algorithms (which are listed at http://www.w3.org/TR/WebCryptoAPI/#sha-registration - such as "SHA-256"), maybe we should give an example value, such as "SHA-256".

Interestingly, the Travis-CI build succeeded for the PR without Bikeshed errors.

<!-- Remove these once Shepherd picks up the changes -->
spec: credential-management-1; urlPrefix: https://w3c.github.io/webappsec-credential-management/
type: dictionary
Expand Down Expand Up @@ -203,6 +196,9 @@ below and in [[#index-defined-elsewhere]].
: CDDL
:: This specification describes the syntax of all CBOR-encoded data using the CBOR Data Definition Language (CDDL) [[!CDDL]].

: COSE
:: CBOR Object Signing and Encryption (COSE) [[!RFC8152]]. The IANA COSE Algorithms registry established by this specification is also used.

: Credential Management
:: The API described in this document is an extension of the {{Credential}} concept defined in [[!CREDENTIAL-MANAGEMENT-1]].

Expand All @@ -216,10 +212,6 @@ below and in [[#index-defined-elsewhere]].
:: The concepts of [=relevant settings object=], [=origin=],
[=opaque origin=], and [=is a registrable domain suffix of or is equal to=] are defined in [[!HTML52]].

: Web Cryptography API
:: The {{AlgorithmIdentifier}} type and the method for [=normalizing an algorithm=] are defined in
[[WebCryptoAPI#algorithm-dictionary]].

: Web IDL
:: Many of the interface definitions and all of the IDL in this specification depend on [[!WebIDL-1]]. This updated version of
the Web IDL standard adds support for {{Promise}}s, which are now the preferred mechanism for asynchronous
Expand Down Expand Up @@ -579,16 +571,14 @@ When this method is invoked, the user agent MUST execute the following algorithm
{{CredentialsContainer/create()}}.
</li>

1. Let |normalizedParameters| be a new [=list=] whose [=list/items=] are pairs of {{PublicKeyCredentialType}} and a
[=dictionary=] type (as returned by [=normalizing an algorithm=]).
1. Let |normalizedParameters| be a new [=list=] whose [=list/items=] are pairs of {{PublicKeyCredentialType}} and
an {{AlgorithmIdentifier}}.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the type {{AlgorithmIdentifier}} is now a dangling pointer in that it is not itself defined.


1. [=list/For each=] |current| of |options|.{{MakePublicKeyCredentialOptions/pubKeyCredParams}}:
1. If <code>|current|.{{PublicKeyCredentialParameters/type}}</code> does not contain a {{PublicKeyCredentialType}} supported
by this implementation, then [=continue=].
1. Let |normalizedAlgorithm| be the result of [=normalizing an algorithm=] [[!WebCryptoAPI]], with |alg| set to
<code>|current|.{{PublicKeyCredentialParameters/alg}}</code> and |op| set to `"generateKey"`. If an error occurs during
this procedure, then [=continue=].
1. [=list/Append=] the pair of <code>|current|.{{PublicKeyCredentialParameters/type}}</code> and |normalizedAlgorithm| to
1. Let |alg| be <code>|current|.{{PublicKeyCredentialParameters/alg}}</code>.
1. [=list/Append=] the pair of <code>|current|.{{PublicKeyCredentialParameters/type}}</code> and |alg| to
|normalizedParameters|.

1. If |normalizedParameters| [=list/is empty=] and |options|.{{MakePublicKeyCredentialOptions/pubKeyCredParams}} [=list/is not empty=],
Expand Down Expand Up @@ -1414,11 +1404,13 @@ the {{CredentialsContainer/create()}} or {{CredentialsContainer/get()}} methods.
</div>


### Cryptographic Algorithm Identifier (type {{AlgorithmIdentifier}}) ### {#alg-identifier}

A string or dictionary identifying a cryptographic algorithm and optionally a set of parameters for that algorithm. This type is
defined in [[!WebCryptoAPI]].
### Cryptographic Algorithm Identifier (type <dfn>AlgorithmIdentifier</dfn>) ### {#alg-identifier}

A number or string identifying a cryptographic algorithm.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there needs to be IDL here defining AlgorithmIdentifier -- I'm working on that now.

The algorithm identifiers MUST be values registered in the IANA COSE Algorithms registry,
when available, for instance, -7 for "ES256".
For algorithms not present in the IANA COSE Algorithms registry, string values from the
JSON Web Signature and Encryption Algorithms SHOULD be used, for instance "RS256".

# WebAuthn Authenticator model # {#authenticator-model}

Expand Down Expand Up @@ -1600,9 +1592,8 @@ input parameters:
- The [=hash of the serialized client data=], provided by the client.
- The [=[RP]=]'s {{PublicKeyCredentialEntity}}.
- The user account's {{PublicKeyCredentialUserEntity}}.
- A sequence of pairs of {{PublicKeyCredentialType}} and cryptographic algorithms (a dictionary type) requested by the [=[RP]=],
where the cryptographic algorithms are normalized as per the procedure in
[[WebCryptoAPI#algorithm-normalization-normalize-an-algorithm]]. This sequence is ordered from most preferred to least
- A sequence of pairs of {{PublicKeyCredentialType}} and {{AlgorithmIdentifier}} requested by the [=[RP]=].
This sequence is ordered from most preferred to least
preferred. The platform makes a best-effort to create the most preferred credential that it can.
- An optional list of {{PublicKeyCredentialDescriptor}} objects provided by the [=[RP]=] with the intention that, if any of
these are known to the authenticator, it should not create a new credential.
Expand Down Expand Up @@ -1783,30 +1774,9 @@ credential. It has the following format:
<tr>
<td>variable</td>
<td>
Credential public key encoded in CBOR format. This is a CBOR map defined by the following CDDL rules:

```
pubKey = $pubKeyFmt

; All public key formats must include an alg name
pubKeyTemplate = { alg: text }
pubKeyTemplate .within $pubKeyFmt

pubKeyFmt /= rsaPubKey
rsaPubKey = { alg: rsaAlgName, n: biguint, e: uint }
rsaAlgName = "RS256" / "RS384" / "RS512" / "PS256" / "PS384" / "PS512"

pubKeyFmt /= eccPubKey
eccPubKey = { alg: eccAlgName, x: biguint, y: biguint }
eccAlgName = "ES256" / "ES384" / "ES512"
```

Thus, each public key type is a CBOR map starting with an entry named `alg`, which contains a text string that
specifies the name of the signature algorithm associated with the credential private key, using values defined in
[[!RFC7518]] section 3.1. The semantics and naming of the other fields (though not their encoding) follows the
definitions in [[!RFC7518]] section 6. Specifically, for ECC keys, the semantics of the `x` and `y` fields are
defined in [[!RFC7518]] sections 6.2.1.2 and 6.2.1.3, while for RSA keys, the semantics of the `n` and `e` fields
are defined in [[!RFC7518]] sections 6.3.1.1 and 6.3.1.2.
The Credential ID is the credential public key encoded in COSE_Key format, as defined in Section 7 of [[!RFC8152]].
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Cred ID is separate from the Cred Pub Key. They are two different things.

The COSE_Key MUST contain the "alg" parameter and MUST NOT contain any other optional parameters.
The "alg" parameter MUST contain an {{AlgorithmIdentifier}} value.
</td>
</tr>
</table>
Expand Down Expand Up @@ -2534,7 +2504,7 @@ This attestation statement format is used with FIDO U2F authenticators using the
:: The [=attestation signature=].

: Signing procedure
:: If the credential public key of the given credential is not of algorithm "ES256", stop and return an error.
:: If the credential public key of the given credential is not of algorithm -7 ("ES256"), stop and return an error.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

-7 should be <code>-7</code> -- I'm fixing that.


Let |authenticatorData| denote the [=authenticator data for the attestation=], and let |clientDataHash| denote the
[=hash of the serialized client data=].
Expand Down Expand Up @@ -3304,11 +3274,11 @@ The sample code for generating and registering a new key follows:
pubKeyCredParams: [
{
type: "public-key",
alg: "ES256",
alg: -7 // "ES256" as registered in the IANA COSE Algorithms registry
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we need refs for IANA COSE Algorithms registry and for JOSE Algs registry. I'm working on adding those.

},
{
type: "public-key",
alg: "RS256",
alg: "RS256" // Use the IANA JOSE algorithm identifier since "RS256" not in COSE Algorithms registry
}
],

Expand Down