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 com.revetsec.internal.jose.VerificationKey; 020import org.jspecify.annotations.NonNull; 021import org.jspecify.annotations.Nullable; 022 023import javax.annotation.concurrent.Immutable; 024import java.util.Locale; 025import java.util.Objects; 026import java.util.Optional; 027 028import static java.util.Objects.requireNonNull; 029 030/** 031 * One usable public key from a {@link Jwks}: an RSA, EC (P-256, P-384 or P-521) or Ed25519 key that passed 032 * every rule for verifying JWS signatures (see {@link JwkSkipReason}). 033 * <p> 034 * Instances exist only for such keys, so there is no public factory: they come from 035 * {@link Jwks#getKeys()}. This class describes the key; it holds no private key material and exposes no 036 * JCA key. 037 * <p> 038 * <strong>Equality</strong> is by value: the RFC 7638 thumbprint, which identifies the key material, and the 039 * {@code kid}, {@code alg} and {@code use} members, and also the key's JWK {@code issuer} member, which this class does 040 * not expose but which decides the tokens the key may verify. {@link #toString()} shows the key ID with its control 041 * characters escaped, the key type, curve and algorithm, and the thumbprint. 042 * 043 * @author <a href="https://www.revetkn.com">Mark Allen</a> 044 * @since 1.0.0 045 */ 046@Immutable 047public final class Jwk { 048 @NonNull 049 private final VerificationKey verificationKey; 050 051 private Jwk(@NonNull VerificationKey verificationKey) { 052 this.verificationKey = verificationKey; 053 } 054 055 /** 056 * Returns the public view of a key that {@code internal.jose} has parsed and checked. 057 * 058 * @param verificationKey the parsed key 059 * @return the public view 060 */ 061 @NonNull 062 static Jwk fromVerificationKey(@NonNull VerificationKey verificationKey) { 063 return new Jwk(requireNonNull(verificationKey)); 064 } 065 066 /** 067 * The parsed key behind this view. 068 */ 069 @NonNull 070 VerificationKey verificationKey() { 071 return this.verificationKey; 072 } 073 074 /** 075 * Returns the key ID ({@code kid}, RFC 7517 section 4.5). 076 * 077 * @return the key ID, 1 to 256 characters, or empty if the key has none 078 * @since 1.0.0 079 */ 080 @NonNull 081 public Optional<@NonNull String> getKeyId() { 082 return Optional.ofNullable(this.verificationKey.keyId()); 083 } 084 085 /** 086 * Returns the key type ({@code kty}, RFC 7517 section 4.1). 087 * 088 * @return {@code RSA}, {@code EC} or {@code OKP} 089 * @since 1.0.0 090 */ 091 @NonNull 092 public String getKeyType() { 093 return this.verificationKey.keyType(); 094 } 095 096 /** 097 * Returns the curve ({@code crv}; RFC 7518 section 6.2.1.1, RFC 8037 section 2). 098 * 099 * @return {@code P-256}, {@code P-384}, {@code P-521} or {@code Ed25519}, or empty for an RSA key 100 * @since 1.0.0 101 */ 102 @NonNull 103 public Optional<@NonNull String> getCurve() { 104 return Optional.ofNullable(this.verificationKey.curve()); 105 } 106 107 /** 108 * Returns the algorithm the key is restricted to ({@code alg}, RFC 7517 section 4.4). A key with an algorithm 109 * verifies only that algorithm, except that {@link JwsAlgorithm#EDDSA} and {@link JwsAlgorithm#ED25519} verify 110 * each other; an RSA key without one verifies only while exactly one RSA algorithm is allowed. 111 * 112 * @return the algorithm, or empty if the key has none 113 * @since 1.0.0 114 */ 115 @NonNull 116 public Optional<@NonNull JwsAlgorithm> getAlgorithm() { 117 return Optional.ofNullable(this.verificationKey.algorithm()); 118 } 119 120 /** 121 * Returns the key's intended use ({@code use}, RFC 7517 section 4.2). 122 * 123 * @return {@code sig}, or empty if the key has no {@code use} member 124 * @since 1.0.0 125 */ 126 @NonNull 127 public Optional<@NonNull String> getUse() { 128 return Optional.ofNullable(this.verificationKey.use()); 129 } 130 131 /** 132 * Returns the key's RFC 7638 JWK thumbprint with SHA-256, which identifies the key material whatever its other 133 * members say. 134 * 135 * @return the thumbprint, in unpadded base64url (43 characters) 136 * @since 1.0.0 137 */ 138 @NonNull 139 public String getThumbprintSha256() { 140 return this.verificationKey.thumbprintSha256(); 141 } 142 143 /** 144 * Compares by value: the thumbprint, key ID, algorithm, use and the JWK {@code issuer} member. 145 * 146 * @param object the other object 147 * @return whether {@code object} is an equal key 148 * @since 1.0.0 149 */ 150 @Override 151 public boolean equals(@Nullable Object object) { 152 if (this == object) 153 return true; 154 if (!(object instanceof Jwk other)) 155 return false; 156 157 VerificationKey mine = this.verificationKey; 158 VerificationKey theirs = other.verificationKey; 159 return mine.thumbprintSha256().equals(theirs.thumbprintSha256()) && Objects.equals(mine.keyId(), theirs.keyId()) 160 && mine.algorithm() == theirs.algorithm() && Objects.equals(mine.use(), theirs.use()) 161 && Objects.equals(mine.issuer(), theirs.issuer()); 162 } 163 164 /** 165 * Returns a hash of the thumbprint. 166 * 167 * @return the hash code 168 * @since 1.0.0 169 */ 170 @Override 171 public int hashCode() { 172 return this.verificationKey.thumbprintSha256().hashCode(); 173 } 174 175 /** 176 * Describes the key by its public facts. The key ID comes from the key set's author, so its control characters, 177 * quotation marks, backslashes and bidirectional formatting characters are escaped. 178 * 179 * @return the description 180 * @since 1.0.0 181 */ 182 @Override 183 @NonNull 184 public String toString() { 185 VerificationKey key = this.verificationKey; 186 String keyId = key.keyId(); 187 String curve = key.curve(); 188 JwsAlgorithm algorithm = key.algorithm(); 189 190 return getClass().getSimpleName() + "{" + (keyId == null ? "" : "kid=\"" + escape(keyId) + "\", ") + "kty=" 191 + key.keyType() + (curve == null ? "" : ", crv=" + curve) 192 + (algorithm == null ? "" : ", alg=" + algorithm.getWireValue()) + ", thumbprint=" 193 + key.thumbprintSha256() + "}"; 194 } 195 196 /** 197 * Escapes the characters that could forge or hide text in a log line as {@code \}{@code uXXXX}: C0 and C1 198 * controls, DEL, {@code "}, {@code \}, the line and paragraph separators, the bidirectional formatting characters 199 * and unpaired surrogates. 200 */ 201 @NonNull 202 static String escape(@NonNull String value) { 203 StringBuilder escaped = new StringBuilder(value.length()); 204 205 for (int index = 0; index < value.length(); ++index) { 206 char character = value.charAt(index); 207 boolean unpaired = (Character.isHighSurrogate(character) && (index + 1 >= value.length() 208 || !Character.isLowSurrogate(value.charAt(index + 1)))) 209 || (Character.isLowSurrogate(character) && (index == 0 210 || !Character.isHighSurrogate(value.charAt(index - 1)))); 211 212 if (character < 0x20 || (character >= 0x7F && character <= 0x9F) || character == '"' || character == '\\' 213 || character == 0x2028 || character == 0x2029 || (character >= 0x202A && character <= 0x202E) 214 || (character >= 0x2066 && character <= 0x2069) || character == 0x200E || character == 0x200F 215 || character == 0x061C || unpaired) 216 escaped.append(String.format(Locale.ROOT, "\\u%04X", (int) character)); 217 else 218 escaped.append(character); 219 } 220 221 return escaped.toString(); 222 } 223}