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}