From 0762b128b2546533676f9df13c88695c2c727fe9 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Thu, 4 Nov 2021 20:45:21 +0100 Subject: [PATCH] Add U2F migration guide --- NEWS | 1 + README | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) diff --git a/NEWS b/NEWS index 1a38fc2b5..1a2858ed7 100644 --- a/NEWS +++ b/NEWS @@ -5,6 +5,7 @@ New features: * New method `RegisteredCredential.builder().publicKeyEs256Raw(ByteArray)`. This is a mutually exclusive alternative to `.publicKeyCose(ByteArray)`, for easier backwards-compatibility with U2F-formatted (Raw ANSI X9.62) public keys. +* "Migrating from U2F" section added to project README == Version 1.11.0 == diff --git a/README b/README index 452c3b42d..f34605ea5 100644 --- a/README +++ b/README @@ -462,6 +462,70 @@ PublicKeyCredentialCreationOptions request = rp.startRegistration( ---------- +== Migrating from U2F + +This section is only relevant for applications that have user credentials registered via the +link:https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-javascript-api-v1.2-ps-20170411.html[U2F JavaScript API]. +New WebAuthn deployments can skip this section. + +The WebAuthn API is backwards-compatible with U2F authenticators, +and credentials registered via the U2F API will continue to work with the WebAuthn API with the right settings. + +To migrate to using the WebAuthn API, you need to do the following: + +* Follow the link:#getting-started[Getting started] guide above to set up WebAuthn support in general. ++ +Note that unlike a U2F AppID, the WebAuthn link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/data/RelyingPartyIdentity.RelyingPartyIdentityBuilder.html#id(java.lang.String)[RP ID] +consists of only the domain name of the AppID. +WebAuthn does not support link:https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-appid-and-facets-v1.2-ps-20170411.html[U2F Trusted Facet Lists]. + +* Set the + link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/RelyingParty.RelyingPartyBuilder.html#appId(com.yubico.webauthn.extension.appid.AppId)[`appId()`] + setting on your `RelyingParty` instance. + The argument to the `appid()` setting should be the same as you used for the `appId` argument to the + link:https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-javascript-api-v1.2-ps-20170411.html#high-level-javascript-api[U2F `register` and `sign` functions]. ++ +This will enable the link:https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#sctn-appid-extension[`appid`] +and link:https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#sctn-appid-exclude-extension[`appidExclude`] +extensions and configure the `RelyingParty` to accept the given AppId when verifying authenticator signatures. + +* Generate a link:https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#user-handle[user handle] for each existing user + and store it in their account, + or decide on a method for deriving one deterministically from existing user attributes. + For example, if your user records are assigned UUIDs, you can use that UUID as the user handle. + You SHOULD NOT use a plain username or e-mail address, or hash of either, as the user handle - + for more on this, see the link:https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#sctn-user-handle-privacy[User Handle Contents] + privacy consideration. + +* When your `CredentialRepository` creates a `RegisteredCredential` for a U2F credential, + use the U2F key handle as the + link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/RegisteredCredential.RegisteredCredentialBuilder.html#credentialId(com.yubico.webauthn.data.ByteArray)[credential ID]. + If you store key handles base64 encoded, you should decode them using + link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/data/ByteArray.html#fromBase64(java.lang.String)[`ByteArray.fromBase64`] + or + link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/data/ByteArray.html#fromBase64Url(java.lang.String)[`ByteArray.fromBase64Url`] + as appropriate before passing them to the `RegisteredCredential`. + +* When your `CredentialRepository` creates a `RegisteredCredential` for a U2F credential, + use the + link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/RegisteredCredential.RegisteredCredentialBuilder.html#publicKeyEs256Raw(com.yubico.webauthn.data.ByteArray)[`publicKeyEs256Raw()`] + method instead of link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/RegisteredCredential.RegisteredCredentialBuilder.html#publicKeyCose(com.yubico.webauthn.data.ByteArray)[`publicKeyCose()`] + to set the credential public key. + +* Replace calls to the U2F + link:https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-javascript-api-v1.2-ps-20170411.html#high-level-javascript-api[`register`] + method with calls to `navigator.credentials.create()` as described in link:#getting-started[Getting started]. + +* Replace calls to the U2F + link:https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-javascript-api-v1.2-ps-20170411.html#high-level-javascript-api[`sign`] + method with calls to `navigator.credentials.get()` as described in link:#getting-started[Getting started]. + +Existing U2F credentials should now work with the WebAuthn API. + +Note that new credentials registered on U2F authenticators via the WebAuthn API +are NOT backwards compatible with the U2F JavaScript API. + + == Architecture The library tries to place as few requirements on the overall application