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 org.jspecify.annotations.NonNull; 020 021import javax.annotation.concurrent.Immutable; 022import java.util.Optional; 023 024import static java.util.Objects.requireNonNull; 025 026/** 027 * A JWS signature algorithm, named by its {@code alg} header value (RFC 7515 section 4.1.1, RFC 7518 section 3.1, 028 * RFC 8037 section 3.1 and RFC 9864). 029 * <p> 030 * Revetsec verifies RSASSA-PKCS1-v1_5 ({@code RS*}), RSASSA-PSS ({@code PS*}), ECDSA on P-256, P-384 and P-521 031 * ({@code ES*}) and EdDSA over Ed25519, which RFC 9864 names {@code Ed25519} and the older RFC 8037 names 032 * {@code EdDSA}. {@code EdDSA} is accepted for Ed25519 keys only. The HMAC algorithms ({@code HS*}) can be named here, 033 * but {@link JwtValidator} refuses them: it verifies only with public keys. There is no constant for {@code none}. 034 * <p> 035 * Wire values are compared exactly and case-sensitively, so {@code rs256} and {@code NONE} name no algorithm here. 036 * <p> 037 * This enum is not switch-stable: a later release may add constants, so a {@code switch} over it needs a default 038 * branch. 039 * 040 * @author <a href="https://www.revetkn.com">Mark Allen</a> 041 * @since 1.0.0 042 */ 043@Immutable 044public enum JwsAlgorithm { 045 /** 046 * RSASSA-PKCS1-v1_5 with SHA-256 ({@code RS256}, RFC 7518 section 3.3). 047 */ 048 RS256("RS256"), 049 /** 050 * RSASSA-PKCS1-v1_5 with SHA-384 ({@code RS384}, RFC 7518 section 3.3). 051 */ 052 RS384("RS384"), 053 /** 054 * RSASSA-PKCS1-v1_5 with SHA-512 ({@code RS512}, RFC 7518 section 3.3). 055 */ 056 RS512("RS512"), 057 /** 058 * RSASSA-PSS with SHA-256, MGF1 with SHA-256 and a 32-byte salt ({@code PS256}, RFC 7518 section 3.5). 059 */ 060 PS256("PS256"), 061 /** 062 * RSASSA-PSS with SHA-384, MGF1 with SHA-384 and a 48-byte salt ({@code PS384}, RFC 7518 section 3.5). 063 */ 064 PS384("PS384"), 065 /** 066 * RSASSA-PSS with SHA-512, MGF1 with SHA-512 and a 64-byte salt ({@code PS512}, RFC 7518 section 3.5). 067 */ 068 PS512("PS512"), 069 /** 070 * ECDSA on P-256 with SHA-256 ({@code ES256}, RFC 7518 section 3.4). 071 */ 072 ES256("ES256"), 073 /** 074 * ECDSA on P-384 with SHA-384 ({@code ES384}, RFC 7518 section 3.4). 075 */ 076 ES384("ES384"), 077 /** 078 * ECDSA on P-521 with SHA-512 ({@code ES512}, RFC 7518 section 3.4). 079 */ 080 ES512("ES512"), 081 /** 082 * EdDSA over Ed25519, by its fully specified name ({@code Ed25519}, RFC 9864). 083 */ 084 ED25519("Ed25519"), 085 /** 086 * EdDSA ({@code EdDSA}, RFC 8037 section 3.1), accepted for Ed25519 keys only. RFC 9864 deprecates this name 087 * (section 4.1.2) in favor of fully specified ones, {@link #ED25519} for Ed25519 keys (section 2.2). On an Ed25519 088 * key both name the same operation, so a key whose {@code alg} is one of the two verifies tokens that name the 089 * other; that alias is Revetsec's, not the RFC's. 090 */ 091 EDDSA("EdDSA"), 092 /** 093 * HMAC with SHA-256 ({@code HS256}, RFC 7518 section 3.2). {@link JwtValidator} refuses it. 094 */ 095 HS256("HS256"), 096 /** 097 * HMAC with SHA-384 ({@code HS384}, RFC 7518 section 3.2). {@link JwtValidator} refuses it. 098 */ 099 HS384("HS384"), 100 /** 101 * HMAC with SHA-512 ({@code HS512}, RFC 7518 section 3.2). {@link JwtValidator} refuses it. 102 */ 103 HS512("HS512"); 104 105 @NonNull 106 private final String wireValue; 107 108 JwsAlgorithm(@NonNull String wireValue) { 109 this.wireValue = wireValue; 110 } 111 112 /** 113 * Returns the algorithm named by an {@code alg} value, compared exactly and case-sensitively. 114 * 115 * @param wireValue the {@code alg} value, such as {@code RS256} or {@code Ed25519} 116 * @return the algorithm, or empty if {@code wireValue} names none of these algorithms 117 * @throws NullPointerException if {@code wireValue} is {@code null} 118 * @since 1.0.0 119 */ 120 @NonNull 121 public static Optional<@NonNull JwsAlgorithm> findByWireValue(@NonNull String wireValue) { 122 requireNonNull(wireValue); 123 124 return switch (wireValue) { 125 case "RS256" -> Optional.of(RS256); 126 case "RS384" -> Optional.of(RS384); 127 case "RS512" -> Optional.of(RS512); 128 case "PS256" -> Optional.of(PS256); 129 case "PS384" -> Optional.of(PS384); 130 case "PS512" -> Optional.of(PS512); 131 case "ES256" -> Optional.of(ES256); 132 case "ES384" -> Optional.of(ES384); 133 case "ES512" -> Optional.of(ES512); 134 case "Ed25519" -> Optional.of(ED25519); 135 case "EdDSA" -> Optional.of(EDDSA); 136 case "HS256" -> Optional.of(HS256); 137 case "HS384" -> Optional.of(HS384); 138 case "HS512" -> Optional.of(HS512); 139 default -> Optional.empty(); 140 }; 141 } 142 143 /** 144 * Returns this algorithm's {@code alg} value. 145 * 146 * @return the {@code alg} value, such as {@code RS256} or {@code Ed25519} 147 * @since 1.0.0 148 */ 149 @NonNull 150 public String getWireValue() { 151 return this.wireValue; 152 } 153}