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}