diff --git a/NEWS b/NEWS index 3a5f6d0d3..2d1dd4877 100644 --- a/NEWS +++ b/NEWS @@ -2,6 +2,7 @@ New features: +* Added JavaDoc to `COSEAlgorithmIdentifier` constants. * (Experimental) Added a new suite of interfaces, starting with `CredentialRepositoryV2`. `RelyingParty` can now be configured with a `CredentialRepositoryV2` instance instead of a `CredentialRepository` diff --git a/webauthn-server-core/src/main/java/com/yubico/webauthn/RelyingParty.java b/webauthn-server-core/src/main/java/com/yubico/webauthn/RelyingParty.java index e7908df60..39e7c145e 100644 --- a/webauthn-server-core/src/main/java/com/yubico/webauthn/RelyingParty.java +++ b/webauthn-server-core/src/main/java/com/yubico/webauthn/RelyingParty.java @@ -210,13 +210,14 @@ public class RelyingParty { *
    *
  1. {@link com.yubico.webauthn.data.PublicKeyCredentialParameters#ES256 ES256} *
  2. {@link com.yubico.webauthn.data.PublicKeyCredentialParameters#EdDSA EdDSA} - *
  3. {@link com.yubico.webauthn.data.PublicKeyCredentialParameters#ES256 ES384} - *
  4. {@link com.yubico.webauthn.data.PublicKeyCredentialParameters#ES256 ES512} + *
  5. {@link com.yubico.webauthn.data.PublicKeyCredentialParameters#ES384 ES384} + *
  6. {@link com.yubico.webauthn.data.PublicKeyCredentialParameters#ES512 ES512} *
  7. {@link com.yubico.webauthn.data.PublicKeyCredentialParameters#RS256 RS256} *
  8. {@link com.yubico.webauthn.data.PublicKeyCredentialParameters#RS384 RS384} *
  9. {@link com.yubico.webauthn.data.PublicKeyCredentialParameters#RS512 RS512} *
* + * @since 0.2.0 * @see PublicKeyCredentialCreationOptions#getAttestation() * @see §6.4. * Attestation diff --git a/webauthn-server-core/src/main/java/com/yubico/webauthn/RelyingPartyV2.java b/webauthn-server-core/src/main/java/com/yubico/webauthn/RelyingPartyV2.java index f75157324..e4c32c568 100644 --- a/webauthn-server-core/src/main/java/com/yubico/webauthn/RelyingPartyV2.java +++ b/webauthn-server-core/src/main/java/com/yubico/webauthn/RelyingPartyV2.java @@ -224,8 +224,8 @@ public class RelyingPartyV2 { *
    *
  1. {@link PublicKeyCredentialParameters#ES256 ES256} *
  2. {@link PublicKeyCredentialParameters#EdDSA EdDSA} - *
  3. {@link PublicKeyCredentialParameters#ES256 ES384} - *
  4. {@link PublicKeyCredentialParameters#ES256 ES512} + *
  5. {@link PublicKeyCredentialParameters#ES384 ES384} + *
  6. {@link PublicKeyCredentialParameters#ES512 ES512} *
  7. {@link PublicKeyCredentialParameters#RS256 RS256} *
  8. {@link PublicKeyCredentialParameters#RS384 RS384} *
  9. {@link PublicKeyCredentialParameters#RS512 RS512} diff --git a/webauthn-server-core/src/main/java/com/yubico/webauthn/data/COSEAlgorithmIdentifier.java b/webauthn-server-core/src/main/java/com/yubico/webauthn/data/COSEAlgorithmIdentifier.java index 4b9ca5803..172ab46a9 100644 --- a/webauthn-server-core/src/main/java/com/yubico/webauthn/data/COSEAlgorithmIdentifier.java +++ b/webauthn-server-core/src/main/java/com/yubico/webauthn/data/COSEAlgorithmIdentifier.java @@ -38,18 +38,109 @@ * registered in the IANA COSE Algorithms registry, for instance, -7 for "ES256" and -257 for * "RS256". * + * @since 0.3.0 * @see §5.10.5. * Cryptographic Algorithm Identifier (typedef COSEAlgorithmIdentifier) */ public enum COSEAlgorithmIdentifier { + + /** + * The signature scheme Ed25519 as defined in RFC + * 8032. + * + *

    Note: This COSE identifier does not in general identify the full Ed25519 parameter suite, + * but is specialized to that meaning within the WebAuthn API. + * + * @since 1.4.0 + * @see COSE Algorithms + * registry + * @see RFC 8032 + * @see WebAuthn + * §5.8.5. Cryptographic Algorithm Identifier (typedef COSEAlgorithmIdentifier + * ) + */ EdDSA(-8), + + /** + * ECDSA with SHA-256 on the NIST P-256 curve. + * + *

    Note: This COSE identifier does not in general restrict the curve to P-256, but is + * specialized to that meaning within the WebAuthn API. + * + * @since 0.3.0 + * @see COSE Algorithms + * registry + * @see WebAuthn + * §5.8.5. Cryptographic Algorithm Identifier (typedef COSEAlgorithmIdentifier + * ) + */ ES256(-7), + + /** + * ECDSA with SHA-384 on the NIST P-384 curve. + * + *

    Note: This COSE identifier does not in general restrict the curve to P-384, but is + * specialized to that meaning within the WebAuthn API. + * + * @since 2.1.0 + * @see COSE Algorithms + * registry + * @see WebAuthn + * §5.8.5. Cryptographic Algorithm Identifier (typedef COSEAlgorithmIdentifier + * ) + */ ES384(-35), + + /** + * ECDSA with SHA-512 on the NIST P-521 curve. + * + *

    Note: This COSE identifier does not in general restrict the curve to P-521, but is + * specialized to that meaning within the WebAuthn API. + * + * @since 2.1.0 + * @see COSE Algorithms + * registry + * @see WebAuthn + * §5.8.5. Cryptographic Algorithm Identifier (typedef COSEAlgorithmIdentifier + * ) + */ ES512(-36), + + /** + * RSASSA-PKCS1-v1_5 using SHA-256. + * + * @since 0.3.0 + * @see COSE Algorithms + * registry + */ RS256(-257), + + /** + * RSASSA-PKCS1-v1_5 using SHA-384. + * + * @since 2.4.0 + * @see COSE Algorithms + * registry + */ RS384(-258), + + /** + * RSASSA-PKCS1-v1_5 using SHA-512. + * + * @since 2.4.0 + * @see COSE Algorithms + * registry + */ RS512(-259), + + /** + * RSASSA-PKCS1-v1_5 using SHA-1. + * + * @since 1.5.0 + * @see COSE Algorithms + * registry + */ RS1(-65535); @JsonValue @Getter private final long id; @@ -65,6 +156,7 @@ public enum COSEAlgorithmIdentifier { * COSEAlgorithmIdentifier} * @return The {@link COSEAlgorithmIdentifier} instance whose {@link #getId() id} equals id * , if any. + * @since 0.3.0 * @see §5.8.5. * Cryptographic Algorithm Identifier (typedef COSEAlgorithmIdentifier) */ @@ -80,6 +172,7 @@ public static Optional fromId(long id) { * COSEAlgorithmIdentifier}, if possible. Returns empty if the {@link COSEAlgorithmIdentifier} * enum has no constant matching the alg value. * @throws IllegalArgumentException if publicKeyCose is not a well-formed COSE_Key. + * @since 2.1.0 */ public static Optional fromPublicKey(@NonNull ByteArray publicKeyCose) { final CBORObject ALG = CBORObject.FromObject(3); diff --git a/webauthn-server-core/src/main/java/com/yubico/webauthn/data/PublicKeyCredentialParameters.java b/webauthn-server-core/src/main/java/com/yubico/webauthn/data/PublicKeyCredentialParameters.java index 4848bcd45..42e4be2f2 100644 --- a/webauthn-server-core/src/main/java/com/yubico/webauthn/data/PublicKeyCredentialParameters.java +++ b/webauthn-server-core/src/main/java/com/yubico/webauthn/data/PublicKeyCredentialParameters.java @@ -32,6 +32,7 @@ /** * Used to supply additional parameters when creating a new credential. * + * @since 0.2.0 * @see §5.3. * Parameters for Credential Generation (dictionary PublicKeyCredentialParameters) @@ -44,10 +45,16 @@ public class PublicKeyCredentialParameters { * Specifies the cryptographic signature algorithm with which the newly generated credential will * be used, and thus also the type of asymmetric key pair to be generated, e.g., RSA or Elliptic * Curve. + * + * @since 0.2.0 */ @NonNull private final COSEAlgorithmIdentifier alg; - /** Specifies the type of credential to be created. */ + /** + * Specifies the type of credential to be created. + * + * @since 0.2.0 + */ @NonNull @Builder.Default private final PublicKeyCredentialType type = PublicKeyCredentialType.PUBLIC_KEY; @@ -61,6 +68,8 @@ private PublicKeyCredentialParameters( /** * Algorithm {@link COSEAlgorithmIdentifier#EdDSA} and type {@link * PublicKeyCredentialType#PUBLIC_KEY}. + * + * @since 1.4.0 */ public static final PublicKeyCredentialParameters EdDSA = builder().alg(COSEAlgorithmIdentifier.EdDSA).build(); @@ -68,6 +77,8 @@ private PublicKeyCredentialParameters( /** * Algorithm {@link COSEAlgorithmIdentifier#ES256} and type {@link * PublicKeyCredentialType#PUBLIC_KEY}. + * + * @since 0.3.0 */ public static final PublicKeyCredentialParameters ES256 = builder().alg(COSEAlgorithmIdentifier.ES256).build(); @@ -75,6 +86,8 @@ private PublicKeyCredentialParameters( /** * Algorithm {@link COSEAlgorithmIdentifier#ES384} and type {@link * PublicKeyCredentialType#PUBLIC_KEY}. + * + * @since 2.1.0 */ public static final PublicKeyCredentialParameters ES384 = builder().alg(COSEAlgorithmIdentifier.ES384).build(); @@ -82,6 +95,8 @@ private PublicKeyCredentialParameters( /** * Algorithm {@link COSEAlgorithmIdentifier#ES512} and type {@link * PublicKeyCredentialType#PUBLIC_KEY}. + * + * @since 2.1.0 */ public static final PublicKeyCredentialParameters ES512 = builder().alg(COSEAlgorithmIdentifier.ES512).build(); @@ -89,6 +104,8 @@ private PublicKeyCredentialParameters( /** * Algorithm {@link COSEAlgorithmIdentifier#RS1} and type {@link * PublicKeyCredentialType#PUBLIC_KEY}. + * + * @since 1.5.0 */ public static final PublicKeyCredentialParameters RS1 = builder().alg(COSEAlgorithmIdentifier.RS1).build(); @@ -96,6 +113,8 @@ private PublicKeyCredentialParameters( /** * Algorithm {@link COSEAlgorithmIdentifier#RS256} and type {@link * PublicKeyCredentialType#PUBLIC_KEY}. + * + * @since 0.3.0 */ public static final PublicKeyCredentialParameters RS256 = builder().alg(COSEAlgorithmIdentifier.RS256).build(); @@ -103,6 +122,8 @@ private PublicKeyCredentialParameters( /** * Algorithm {@link COSEAlgorithmIdentifier#RS384} and type {@link * PublicKeyCredentialType#PUBLIC_KEY}. + * + * @since 2.4.0 */ public static final PublicKeyCredentialParameters RS384 = builder().alg(COSEAlgorithmIdentifier.RS384).build(); @@ -110,6 +131,8 @@ private PublicKeyCredentialParameters( /** * Algorithm {@link COSEAlgorithmIdentifier#RS512} and type {@link * PublicKeyCredentialType#PUBLIC_KEY}. + * + * @since 2.4.0 */ public static final PublicKeyCredentialParameters RS512 = builder().alg(COSEAlgorithmIdentifier.RS512).build(); @@ -127,6 +150,7 @@ public static class MandatoryStages { * {@link PublicKeyCredentialParametersBuilder#alg(COSEAlgorithmIdentifier) alg} is a required * parameter. * + * @since 0.3.0 * @see PublicKeyCredentialParametersBuilder#alg(COSEAlgorithmIdentifier) */ public PublicKeyCredentialParametersBuilder alg(COSEAlgorithmIdentifier alg) {