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.ErrorCategory; 020import com.revetsec.RevetsecException; 021import org.jspecify.annotations.NonNull; 022import javax.annotation.concurrent.Immutable; 023import javax.annotation.concurrent.NotThreadSafe; 024import static java.util.Objects.requireNonNull; 025 026/** 027 * A failure to sign with an application-owned RSA key, or to verify the signature before releasing it. 028 * Every reason has a fixed message without key, provider or credential contents. No cause or suppressed 029 * exception is retained. Applications catch these exceptions; only Revetsec constructs them. 030 * 031 * @author <a href="https://www.revetkn.com">Mark Allen</a> 032 * @since 1.0.0 033 */ 034@NotThreadSafe 035public final class JwsSigningException extends RevetsecException { 036 private static final long serialVersionUID = 1L; 037 /** The fixed, non-sensitive reason retained when this exception is serialized. */ 038 private final @NonNull Reason reason; 039 040 private JwsSigningException(@NonNull Reason reason) { 041 super(requireNonNull(reason).category, reason == Reason.BUDGET_EXHAUSTED, reason.message, null); 042 this.reason = reason; 043 } 044 045 static @NonNull JwsSigningException fromReason(@NonNull Reason reason) { 046 return new JwsSigningException(reason); 047 } 048 049 /** 050 * Returns why signing failed. 051 * @return the fixed reason 052 * @since 1.0.0 053 */ 054 public @NonNull Reason getReason() { 055 return this.reason; 056 } 057 058 /** 059 * Why signing failed. Signing and pair failures are nontransient configuration failures; exhausted budgets 060 * are transient transport timeouts. Revetsec never retries signing automatically. Later releases may add 061 * reasons, so application switches need a default branch. 062 * 063 * @author <a href="https://www.revetkn.com">Mark Allen</a> 064 * @since 1.0.0 065 */ 066 @Immutable 067 public enum Reason { 068 /** The provider could not produce or verify a well-formed signature. */ 069 SIGNING_UNAVAILABLE(ErrorCategory.CONFIGURATION, "The JWS signing operation is unavailable."), 070 /** The generated signature did not verify against the checked public key. */ 071 KEY_PAIR_MISMATCH(ErrorCategory.CONFIGURATION, "The JWS signing key pair does not match."), 072 /** The supplied remaining budget was exhausted; no credential was released. */ 073 BUDGET_EXHAUSTED(ErrorCategory.TRANSPORT, "The JWS signing budget is exhausted."); 074 075 private final @NonNull ErrorCategory category; 076 private final @NonNull String message; 077 078 Reason(@NonNull ErrorCategory category, @NonNull String message) { 079 this.category = category; 080 this.message = message; 081 } 082 } 083}