001/*
002 * Copyright 2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.revetsec.jose;
018
019import javax.annotation.concurrent.Immutable;
020
021/**
022 * Why a key in a JSON Web Key Set is not used.
023 * <p>
024 * A key that fails any rule is skipped, never used for part of what it holds, and it never makes the whole set fail
025 * (RFC 7517 section 5). Only the document's structure or size does that. The checks run in a fixed order, and the
026 * first one that fails names the reason:
027 * <ol>
028 *   <li>{@code kty} is missing or not a string: {@link #MALFORMED_KEY};</li>
029 *   <li>{@code kty} is not {@code RSA}, {@code EC} or {@code OKP}: {@link #SYMMETRIC_KEY} for {@code oct}, otherwise
030 *   {@link #UNSUPPORTED_KEY_TYPE};</li>
031 *   <li>a private or symmetric member ({@code d}, {@code p}, {@code q}, {@code dp}, {@code dq}, {@code qi},
032 *   {@code oth} or {@code k}) is present: {@link #PRIVATE_KEY_MEMBERS};</li>
033 *   <li>{@code use} or {@code key_ops} does not allow verification: {@link #NOT_A_VERIFICATION_KEY};</li>
034 *   <li>{@code alg} is not a {@link JwsAlgorithm}, or names another key type or curve:
035 *   {@link #UNSUPPORTED_ALGORITHM} or {@link #ALGORITHM_MISMATCH};</li>
036 *   <li>{@code crv} names an unsupported curve: {@link #UNSUPPORTED_CURVE};</li>
037 *   <li>a member is missing, of the wrong type or not canonically encoded: {@link #MALFORMED_KEY};</li>
038 *   <li>the RSA modulus size is out of range: {@link #RSA_KEY_SIZE};</li>
039 *   <li>the RSA public exponent is out of range: {@link #RSA_EXPONENT};</li>
040 *   <li>the EC point is not on its curve: {@link #EC_POINT_NOT_ON_CURVE};</li>
041 *   <li>the key is known to be weak: {@link #WEAK_KEY};</li>
042 *   <li>{@code x5c} does not hold the same key: {@link #CERTIFICATE_MISMATCH}.</li>
043 * </ol>
044 * This enum is not switch-stable: a later release may add constants, so a {@code switch} over it needs a default
045 * branch.
046 *
047 * @author <a href="https://www.revetkn.com">Mark Allen</a>
048 * @since 1.0.0
049 */
050@Immutable
051public enum JwkSkipReason {
052        /**
053         * A member is missing, has the wrong JSON type or is not canonically encoded: {@code kty} missing or not a string;
054         * a required key member ({@code n} and {@code e}, {@code crv} with {@code x} and {@code y}, or {@code crv} with
055         * {@code x}) missing, not a string or not canonical base64url; an RSA integer with a leading zero octet or an even
056         * modulus; an EC coordinate of the wrong length; an Ed25519 {@code x} that is not 32 octets or does not decode to a
057         * curve point (RFC 8032 section 5.1.3); a {@code kid} that is not a string of 1 to 256 characters; or an
058         * {@code issuer} member that is present but not a non-empty string.
059         */
060        MALFORMED_KEY,
061        /**
062         * The key type ({@code kty}) is not {@code RSA}, {@code EC}, {@code OKP} or {@code oct}.
063         */
064        UNSUPPORTED_KEY_TYPE,
065        /**
066         * The key is symmetric ({@code kty} {@code oct}). Revetsec verifies only with public keys from a key set.
067         */
068        SYMMETRIC_KEY,
069        /**
070         * The key holds a private or symmetric member ({@code d}, {@code p}, {@code q}, {@code dp}, {@code dq},
071         * {@code qi}, {@code oth} or {@code k}), so the set publishes key material it should not. Its public half is not
072         * used either.
073         */
074        PRIVATE_KEY_MEMBERS,
075        /**
076         * The key is not for verifying signatures: its {@code use} is not {@code sig}, its {@code key_ops} is not an array
077         * of strings that contains {@code verify}, or the two members disagree (RFC 7517 sections 4.2 and 4.3).
078         */
079        NOT_A_VERIFICATION_KEY,
080        /**
081         * The key's {@code alg} is present but is not a {@link JwsAlgorithm} wire value, such as {@code RSA-OAEP} or
082         * {@code ES521}.
083         */
084        UNSUPPORTED_ALGORITHM,
085        /**
086         * The key's {@code alg} names an algorithm for another key type or curve, such as {@code ES384} on a P-256 key or
087         * any HMAC algorithm.
088         */
089        ALGORITHM_MISMATCH,
090        /**
091         * The key's curve ({@code crv}) is not P-256, P-384 or P-521 for an {@code EC} key, or not Ed25519 for an
092         * {@code OKP} key. A key on secp256k1, Ed448, X25519 or X448 is skipped here unless an earlier check refuses it
093         * first: {@link #UNSUPPORTED_ALGORITHM} for {@code alg} {@code ES256K} or {@code ECDH-ES}, or
094         * {@link #NOT_A_VERIFICATION_KEY} for {@code use} {@code enc}.
095         */
096        UNSUPPORTED_CURVE,
097        /**
098         * The RSA modulus is shorter than 2048 or longer than 16384 bits.
099         */
100        RSA_KEY_SIZE,
101        /**
102         * The RSA public exponent is even, below 65537 or at least 2<sup>32</sup>.
103         */
104        RSA_EXPONENT,
105        /**
106         * An EC coordinate is not below the field prime, or the point is not on the curve.
107         */
108        EC_POINT_NOT_ON_CURVE,
109        /**
110         * The key is well formed but known to be weak: an RSA modulus with the ROCA fingerprint (CVE-2017-15361), or an
111         * Ed25519 point of small order.
112         */
113        WEAK_KEY,
114        /**
115         * The key's {@code x5c} is not an array whose first element is a certificate in standard base64 that parses
116         * strictly, or that certificate holds a different key.
117         */
118        CERTIFICATE_MISMATCH
119}