| 1 | package com.yubico.webauthn; | |
| 2 | ||
| 3 | import com.yubico.webauthn.data.AttestedCredentialData; | |
| 4 | import com.yubico.webauthn.data.AuthenticatorAssertionResponse; | |
| 5 | import com.yubico.webauthn.data.AuthenticatorAttestationResponse; | |
| 6 | import com.yubico.webauthn.data.AuthenticatorData; | |
| 7 | import com.yubico.webauthn.data.AuthenticatorTransport; | |
| 8 | import com.yubico.webauthn.data.ByteArray; | |
| 9 | import com.yubico.webauthn.data.PublicKeyCredentialCreationOptions; | |
| 10 | import com.yubico.webauthn.data.PublicKeyCredentialDescriptor; | |
| 11 | import com.yubico.webauthn.data.PublicKeyCredentialRequestOptions; | |
| 12 | import com.yubico.webauthn.data.UserIdentity; | |
| 13 | import java.util.Optional; | |
| 14 | import java.util.Set; | |
| 15 | import lombok.NonNull; | |
| 16 | ||
| 17 | /** | |
| 18 | * An abstraction of properties of a stored WebAuthn credential. | |
| 19 | * | |
| 20 | * @see <a href="https://w3c.github.io/webauthn/#credential-record">Credential Record</a> in Web | |
| 21 | * Authentication Level 3 (Editor's Draft) | |
| 22 | * @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted | |
| 23 | * before reaching a mature release. | |
| 24 | */ | |
| 25 | @Deprecated | |
| 26 | public interface CredentialRecord extends ToPublicKeyCredentialDescriptor { | |
| 27 | ||
| 28 | /** | |
| 29 | * The <a href="https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#credential-id">credential | |
| 30 | * ID</a> of the credential. | |
| 31 | * | |
| 32 | * <p>Implementations MUST NOT return null. | |
| 33 | * | |
| 34 | * @see <a href="https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#credential-id">Credential | |
| 35 | * ID</a> | |
| 36 | * @see RegistrationResult#getKeyId() | |
| 37 | * @see PublicKeyCredentialDescriptor#getId() | |
| 38 | * @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted | |
| 39 | * before reaching a mature release. | |
| 40 | */ | |
| 41 | @Deprecated | |
| 42 | @NonNull | |
| 43 | ByteArray getCredentialId(); | |
| 44 | ||
| 45 | /** | |
| 46 | * The <a href="https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#user-handle">user handle</a> | |
| 47 | * of the user the credential is registered to. | |
| 48 | * | |
| 49 | * <p>Implementations MUST NOT return null. | |
| 50 | * | |
| 51 | * @see <a href="https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#user-handle">User Handle</a> | |
| 52 | * @see UserIdentity#getId() | |
| 53 | * @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted | |
| 54 | * before reaching a mature release. | |
| 55 | */ | |
| 56 | @Deprecated | |
| 57 | @NonNull | |
| 58 | ByteArray getUserHandle(); | |
| 59 | ||
| 60 | /** | |
| 61 | * The credential public key encoded in COSE_Key format, as defined in Section 7 of <a | |
| 62 | * href="https://tools.ietf.org/html/rfc8152">RFC 8152</a>. | |
| 63 | * | |
| 64 | * <p>This is used to verify the {@link AuthenticatorAssertionResponse#getSignature() signature} | |
| 65 | * in authentication assertions. | |
| 66 | * | |
| 67 | * <p>If your database has credentials encoded in U2F (raw) format, you may need to use {@link | |
| 68 | * #cosePublicKeyFromEs256Raw(ByteArray)} to convert them before returning them in this method. | |
| 69 | * | |
| 70 | * <p>Implementations MUST NOT return null. | |
| 71 | * | |
| 72 | * @see AttestedCredentialData#getCredentialPublicKey() | |
| 73 | * @see RegistrationResult#getPublicKeyCose() | |
| 74 | * @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted | |
| 75 | * before reaching a mature release. | |
| 76 | */ | |
| 77 | @Deprecated | |
| 78 | @NonNull | |
| 79 | ByteArray getPublicKeyCose(); | |
| 80 | ||
| 81 | /** | |
| 82 | * The stored <a href="https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#signcount">signature | |
| 83 | * count</a> of the credential. | |
| 84 | * | |
| 85 | * <p>This is used to validate the {@link AuthenticatorData#getSignatureCounter() signature | |
| 86 | * counter} in authentication assertions. | |
| 87 | * | |
| 88 | * @see <a | |
| 89 | * href="https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#sctn-authenticator-data">§6.1. | |
| 90 | * Authenticator Data</a> | |
| 91 | * @see AuthenticatorData#getSignatureCounter() | |
| 92 | * @see AssertionResult#getSignatureCount() | |
| 93 | * @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted | |
| 94 | * before reaching a mature release. | |
| 95 | */ | |
| 96 | @Deprecated | |
| 97 | long getSignatureCount(); | |
| 98 | ||
| 99 | /** | |
| 100 | * Transport hints as to how the client might communicate with the authenticator this credential | |
| 101 | * is bound to. | |
| 102 | * | |
| 103 | * <p>Implementations SHOULD return the value returned by {@link | |
| 104 | * AuthenticatorAttestationResponse#getTransports()} when the credential was created. That value | |
| 105 | * SHOULD NOT be modified. | |
| 106 | * | |
| 107 | * <p>Implementations MUST NOT return null. | |
| 108 | * | |
| 109 | * <p>This is used to set {@link PublicKeyCredentialDescriptor#getTransports()} in {@link | |
| 110 | * PublicKeyCredentialCreationOptions#getExcludeCredentials() excludeCredentials} in {@link | |
| 111 | * RelyingParty#startRegistration(StartRegistrationOptions)} and and {@link | |
| 112 | * PublicKeyCredentialRequestOptions#getAllowCredentials() allowCredentials} in {@link | |
| 113 | * RelyingParty#startAssertion(StartAssertionOptions)}. | |
| 114 | * | |
| 115 | * @see <a | |
| 116 | * href="https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#dom-authenticatorattestationresponse-gettransports">getTransports() | |
| 117 | * in 5.2.1. Information About Public Key Credential (interface | |
| 118 | * AuthenticatorAttestationResponse)</a> | |
| 119 | * @see <a | |
| 120 | * href="https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#dom-publickeycredentialdescriptor-transports">transports | |
| 121 | * in 5.8.3. Credential Descriptor (dictionary PublicKeyCredentialDescriptor)</a> | |
| 122 | * @see AuthenticatorAttestationResponse#getTransports() | |
| 123 | * @see PublicKeyCredentialDescriptor#getTransports() | |
| 124 | * @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted | |
| 125 | * before reaching a mature release. | |
| 126 | */ | |
| 127 | @Deprecated | |
| 128 | Optional<Set<AuthenticatorTransport>> getTransports(); | |
| 129 | ||
| 130 | // boolean isUvInitialized(); | |
| 131 | ||
| 132 | /** | |
| 133 | * The state of the <a href="https://w3c.github.io/webauthn/#authdata-flags-be">BE flag</a> when | |
| 134 | * this credential was registered, if known. | |
| 135 | * | |
| 136 | * <p>If absent, it is not known whether or not this credential is backup eligible. | |
| 137 | * | |
| 138 | * <p>If present and <code>true</code>, the credential is backup eligible: it can be backed up in | |
| 139 | * some way, most commonly by syncing the private key to a cloud account. | |
| 140 | * | |
| 141 | * <p>If present and <code>false</code>, the credential is not backup eligible: it cannot be | |
| 142 | * backed up in any way. | |
| 143 | * | |
| 144 | * <p>{@link CredentialRecord} implementations SHOULD return the first known value returned by | |
| 145 | * {@link RegistrationResult#isBackupEligible()} or {@link AssertionResult#isBackupEligible()}, if | |
| 146 | * known. If unknown, {@link CredentialRecord} implementations SHOULD return <code> | |
| 147 | * Optional.empty()</code>. | |
| 148 | * | |
| 149 | * <p>Implementations MUST NOT return null. | |
| 150 | * | |
| 151 | * @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted | |
| 152 | * before reaching a mature release. EXPERIMENTAL: This feature is from a not yet mature | |
| 153 | * standard; it could change as the standard matures. | |
| 154 | */ | |
| 155 | @Deprecated | |
| 156 | Optional<Boolean> isBackupEligible(); | |
| 157 | ||
| 158 | /** | |
| 159 | * The last known state of the <a href="https://w3c.github.io/webauthn/#authdata-flags-bs">BS | |
| 160 | * flag</a> for this credential, if known. | |
| 161 | * | |
| 162 | * <p>If absent, the backup state of the credential is not known. | |
| 163 | * | |
| 164 | * <p>If present and <code>true</code>, the credential is believed to be currently backed up. | |
| 165 | * | |
| 166 | * <p>If present and <code>false</code>, the credential is believed to not be currently backed up. | |
| 167 | * | |
| 168 | * <p>{@link CredentialRecord} implementations SHOULD return the most recent value returned by | |
| 169 | * {@link AssertionResult#isBackedUp()} or {@link RegistrationResult#isBackedUp()}, if known. If | |
| 170 | * unknown, {@link CredentialRecord} implementations SHOULD return <code>Optional.empty()</code>. | |
| 171 | * | |
| 172 | * <p>Implementations MUST NOT return null. | |
| 173 | * | |
| 174 | * @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted | |
| 175 | * before reaching a mature release. EXPERIMENTAL: This feature is from a not yet mature | |
| 176 | * standard; it could change as the standard matures. | |
| 177 | */ | |
| 178 | @Deprecated | |
| 179 | Optional<Boolean> isBackedUp(); | |
| 180 | ||
| 181 | /** | |
| 182 | * This default implementation of {@link | |
| 183 | * ToPublicKeyCredentialDescriptor#toPublicKeyCredentialDescriptor()} sets the {@link | |
| 184 | * PublicKeyCredentialDescriptor.PublicKeyCredentialDescriptorBuilder#id(ByteArray) id} field to | |
| 185 | * the return value of {@link #getCredentialId()} and the {@link | |
| 186 | * PublicKeyCredentialDescriptor.PublicKeyCredentialDescriptorBuilder#transports(Optional) | |
| 187 | * transports} field to the return value of {@link #getTransports()}. | |
| 188 | * | |
| 189 | * @see <a | |
| 190 | * href="https://w3c.github.io/webauthn/#credential-descriptor-for-a-credential-record">credential | |
| 191 | * descriptor for a credential record</a> in Web Authentication Level 3 (Editor's Draft) | |
| 192 | */ | |
| 193 | @Override | |
| 194 | default PublicKeyCredentialDescriptor toPublicKeyCredentialDescriptor() { | |
| 195 |
1
1. toPublicKeyCredentialDescriptor : replaced return value with null for com/yubico/webauthn/CredentialRecord::toPublicKeyCredentialDescriptor → KILLED |
return PublicKeyCredentialDescriptor.builder() |
| 196 | .id(getCredentialId()) | |
| 197 | .transports(getTransports()) | |
| 198 | .build(); | |
| 199 | } | |
| 200 | ||
| 201 | /** | |
| 202 | * Convert a credential public key from U2F format to COSE_Key format. | |
| 203 | * | |
| 204 | * <p>The U2F JavaScript API encoded credential public keys in <code>ALG_KEY_ECC_X962_RAW</code> | |
| 205 | * format as specified in <a | |
| 206 | * href="https://fidoalliance.org/specs/fido-v2.0-id-20180227/fido-registry-v2.0-id-20180227.html#public-key-representation-formats">FIDO | |
| 207 | * Registry §3.6.2 Public Key Representation Formats</a>. If your database has credential public | |
| 208 | * keys stored in this format, those public keys need to be converted to COSE_Key format before | |
| 209 | * they can be used by a {@link CredentialRecord} instance. This function performs the conversion. | |
| 210 | * | |
| 211 | * <p>If your application has only used the <code>navigator.credentials.create()</code> API to | |
| 212 | * register credentials, you likely do not need this function. | |
| 213 | * | |
| 214 | * @param es256RawKey a credential public key in <code>ALG_KEY_ECC_X962_RAW</code> format as | |
| 215 | * specified in <a | |
| 216 | * href="https://fidoalliance.org/specs/fido-v2.0-id-20180227/fido-registry-v2.0-id-20180227.html#public-key-representation-formats">FIDO | |
| 217 | * Registry §3.6.2 Public Key Representation Formats</a>. | |
| 218 | * @return a credential public key in COSE_Key format, suitable to be returned by {@link | |
| 219 | * CredentialRecord#getPublicKeyCose()}. | |
| 220 | * @see RegisteredCredential.RegisteredCredentialBuilder#publicKeyEs256Raw(ByteArray) | |
| 221 | */ | |
| 222 | static ByteArray cosePublicKeyFromEs256Raw(final ByteArray es256RawKey) { | |
| 223 |
1
1. cosePublicKeyFromEs256Raw : replaced return value with null for com/yubico/webauthn/CredentialRecord::cosePublicKeyFromEs256Raw → KILLED |
return WebAuthnCodecs.rawEcKeyToCose(es256RawKey); |
| 224 | } | |
| 225 | } | |
Mutations | ||
| 195 |
1.1 |
|
| 223 |
1.1 |