Skip to content

Commit abb6b07

Browse files
emlunemlun
committed
Add missing JavaDoc to CredentialRecord and RegisteredCredential
1 parent e60d332 commit abb6b07

File tree

2 files changed

+169
-3
lines changed

2 files changed

+169
-3
lines changed

‎webauthn-server-core/src/main/java/com/yubico/webauthn/CredentialRecord.java

Lines changed: 112 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,40 @@
11
package com.yubico.webauthn;
22

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;
37
import com.yubico.webauthn.data.AuthenticatorTransport;
48
import com.yubico.webauthn.data.ByteArray;
9+
import com.yubico.webauthn.data.PublicKeyCredentialCreationOptions;
510
import com.yubico.webauthn.data.PublicKeyCredentialDescriptor;
11+
import com.yubico.webauthn.data.PublicKeyCredentialRequestOptions;
12+
import com.yubico.webauthn.data.UserIdentity;
613
import java.util.Optional;
714
import java.util.Set;
815
import lombok.NonNull;
916

1017
/**
11-
* @see <a href="https://w3c.github.io/webauthn/#credential-record">Credential Record</a>
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)
1222
* @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted
1323
* before reaching a mature release.
1424
*/
1525
@Deprecated
1626
public interface CredentialRecord extends ToPublicKeyCredentialDescriptor {
1727

1828
/**
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()
1938
* @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted
2039
* before reaching a mature release.
2140
*/
@@ -24,6 +43,13 @@ public interface CredentialRecord extends ToPublicKeyCredentialDescriptor {
2443
ByteArray getCredentialId();
2544

2645
/**
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()
2753
* @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted
2854
* before reaching a mature release.
2955
*/
@@ -32,6 +58,19 @@ public interface CredentialRecord extends ToPublicKeyCredentialDescriptor {
3258
ByteArray getUserHandle();
3359

3460
/**
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()
3574
* @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted
3675
* before reaching a mature release.
3776
*/
@@ -40,13 +79,48 @@ public interface CredentialRecord extends ToPublicKeyCredentialDescriptor {
4079
ByteArray getPublicKeyCose();
4180

4281
/**
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()
4393
* @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted
4494
* before reaching a mature release.
4595
*/
4696
@Deprecated
4797
long getSignatureCount();
4898

4999
/**
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()
50124
* @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted
51125
* before reaching a mature release.
52126
*/
@@ -56,15 +130,50 @@ public interface CredentialRecord extends ToPublicKeyCredentialDescriptor {
56130
// boolean isUvInitialized();
57131

58132
/**
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+
*
59151
* @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted
60-
* before reaching a mature release.
152+
* before reaching a mature release. EXPERIMENTAL: This feature is from a not yet mature
153+
* standard; it could change as the standard matures.
61154
*/
62155
@Deprecated
63156
Optional<Boolean> isBackupEligible();
64157

65158
/**
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+
*
66174
* @deprecated EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted
67-
* before reaching a mature release.
175+
* before reaching a mature release. EXPERIMENTAL: This feature is from a not yet mature
176+
* standard; it could change as the standard matures.
68177
*/
69178
@Deprecated
70179
Optional<Boolean> isBackedUp();

‎webauthn-server-core/src/main/java/com/yubico/webauthn/RegisteredCredential.java

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,14 @@
3131
import com.fasterxml.jackson.annotation.JsonProperty;
3232
import com.yubico.webauthn.data.AttestedCredentialData;
3333
import com.yubico.webauthn.data.AuthenticatorAssertionResponse;
34+
import com.yubico.webauthn.data.AuthenticatorAttestationResponse;
3435
import com.yubico.webauthn.data.AuthenticatorData;
3536
import com.yubico.webauthn.data.AuthenticatorTransport;
3637
import com.yubico.webauthn.data.ByteArray;
3738
import com.yubico.webauthn.data.COSEAlgorithmIdentifier;
39+
import com.yubico.webauthn.data.PublicKeyCredentialCreationOptions;
3840
import com.yubico.webauthn.data.PublicKeyCredentialDescriptor;
41+
import com.yubico.webauthn.data.PublicKeyCredentialRequestOptions;
3942
import com.yubico.webauthn.data.UserIdentity;
4043
import java.io.IOException;
4144
import java.security.NoSuchAlgorithmException;
@@ -120,6 +123,33 @@ public PublicKey getParsedPublicKey()
120123
*/
121124
@Builder.Default private final long signatureCount = 0;
122125

126+
/**
127+
* Transport hints as to how the client might communicate with the authenticator this credential
128+
* is bound to.
129+
*
130+
* <p>This SHOULD be set to the value returned by {@link
131+
* AuthenticatorAttestationResponse#getTransports()} when the credential was created. That value
132+
* SHOULD NOT be modified.
133+
*
134+
* <p>This is only used if the {@link RelyingParty} is configured with a {@link
135+
* CredentialRepositoryV2}, in which case this is used to set {@link
136+
* PublicKeyCredentialDescriptor#getTransports()} in {@link
137+
* PublicKeyCredentialCreationOptions#getExcludeCredentials() excludeCredentials} in {@link
138+
* RelyingParty#startRegistration(StartRegistrationOptions)} and {@link
139+
* PublicKeyCredentialRequestOptions#getAllowCredentials() allowCredentials} in {@link
140+
* RelyingParty#startAssertion(StartAssertionOptions)}. This is not used if the {@link
141+
* RelyingParty} is configured with a {@link CredentialRepository}.
142+
*
143+
* @see <a
144+
* href="https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#dom-authenticatorattestationresponse-gettransports">getTransports()
145+
* in 5.2.1. Information About Public Key Credential (interface
146+
* AuthenticatorAttestationResponse)</a>
147+
* @see <a
148+
* href="https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#dom-publickeycredentialdescriptor-transports">transports
149+
* in 5.8.3. Credential Descriptor (dictionary PublicKeyCredentialDescriptor)</a>
150+
* @see AuthenticatorAttestationResponse#getTransports()
151+
* @see PublicKeyCredentialDescriptor#getTransports()
152+
*/
123153
@Builder.Default private final Set<AuthenticatorTransport> transports = null;
124154

125155
/**
@@ -188,6 +218,33 @@ private RegisteredCredential(
188218
this.backupState = backupState;
189219
}
190220

221+
/**
222+
* Transport hints as to how the client might communicate with the authenticator this credential
223+
* is bound to.
224+
*
225+
* <p>This SHOULD be set to the value returned by {@link
226+
* AuthenticatorAttestationResponse#getTransports()} when the credential was created. That value
227+
* SHOULD NOT be modified.
228+
*
229+
* <p>This is only used if the {@link RelyingParty} is configured with a {@link
230+
* CredentialRepositoryV2}, in which case this is used to set {@link
231+
* PublicKeyCredentialDescriptor#getTransports()} in {@link
232+
* PublicKeyCredentialCreationOptions#getExcludeCredentials() excludeCredentials} in {@link
233+
* RelyingParty#startRegistration(StartRegistrationOptions)} and {@link
234+
* PublicKeyCredentialRequestOptions#getAllowCredentials() allowCredentials} in {@link
235+
* RelyingParty#startAssertion(StartAssertionOptions)}. This is not used if the {@link
236+
* RelyingParty} is configured with a {@link CredentialRepository}.
237+
*
238+
* @see <a
239+
* href="https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#dom-authenticatorattestationresponse-gettransports">getTransports()
240+
* in 5.2.1. Information About Public Key Credential (interface
241+
* AuthenticatorAttestationResponse)</a>
242+
* @see <a
243+
* href="https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#dom-publickeycredentialdescriptor-transports">transports
244+
* in 5.8.3. Credential Descriptor (dictionary PublicKeyCredentialDescriptor)</a>
245+
* @see AuthenticatorAttestationResponse#getTransports()
246+
* @see PublicKeyCredentialDescriptor#getTransports()
247+
*/
191248
@Override
192249
public Optional<Set<AuthenticatorTransport>> getTransports() {
193250
return Optional.ofNullable(transports);

0 commit comments

Comments
 (0)