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;
018
019import org.jspecify.annotations.NonNull;
020import javax.annotation.concurrent.Immutable;
021import javax.annotation.concurrent.NotThreadSafe;
022import static java.util.Objects.requireNonNull;
023
024/**
025 * A fixed-diagnostic key import or explicit pair-check failure. No input, key or provider message, cause or
026 * suppressed exception is retained. Only Revetsec constructs these exceptions.
027 * @author <a href="https://www.revetkn.com">Mark Allen</a>
028 * @since 1.0.0
029 */
030@NotThreadSafe
031public final class KeyImportException extends RevetsecException {
032        private static final long serialVersionUID = 1L;
033        /** The fixed, non-sensitive reason retained when this exception is serialized. */
034        private final @NonNull Reason reason;
035
036        private KeyImportException(@NonNull Reason reason) {
037                super(requireNonNull(reason).category, reason == Reason.BUDGET_EXHAUSTED, reason.message, null);
038                this.reason = reason;
039        }
040
041        static @NonNull KeyImportException fromReason(@NonNull Reason reason) { return new KeyImportException(reason); }
042
043        /**
044         * Returns the fixed failure reason.
045         * @return the reason
046         * @since 1.0.0
047         */
048        public @NonNull Reason getReason() { return this.reason; }
049
050        /**
051         * Fixed reasons; later versions may add reasons, so application switches need a default branch.
052         * @author <a href="https://www.revetkn.com">Mark Allen</a>
053         * @since 1.0.0
054         */
055        @Immutable
056        public enum Reason {
057                /** The input exceeds the fixed representation ceiling. */
058                INPUT_TOO_LARGE(ErrorCategory.MALFORMED_INPUT, "The key import input exceeds its size limit."),
059                /** Armor, Base64 or a selected key structure is malformed or noncanonical. */
060                MALFORMED_INPUT(ErrorCategory.MALFORMED_INPUT, "The key import input is malformed."),
061                /** The algorithm, parameters, label or container profile is not selected. */
062                UNSUPPORTED_KEY(ErrorCategory.UNSUPPORTED, "The key import profile is not supported."),
063                /** The decoded key fails the selected strength or point policy. */
064                KEY_REJECTED(ErrorCategory.VALIDATION_FAILURE, "The imported key does not satisfy the key policy."),
065                /** The probe signature does not agree with the checked public key. */
066                KEY_PAIR_MISMATCH(ErrorCategory.CONFIGURATION, "The key pair does not match."),
067                /** A trusted synchronous provider cannot complete the operation. */
068                OPERATION_UNAVAILABLE(ErrorCategory.CONFIGURATION, "The key import operation is unavailable."),
069                /** The original monotonic budget is exhausted. */
070                BUDGET_EXHAUSTED(ErrorCategory.TRANSPORT, "The key pair check budget is exhausted."),
071                /** The calling thread remains interrupted. */
072                CANCELLED(ErrorCategory.TRANSPORT, "The key pair check was interrupted.");
073
074                private final @NonNull ErrorCategory category;
075                private final @NonNull String message;
076                Reason(@NonNull ErrorCategory category, @NonNull String message) { this.category = category; this.message = message; }
077        }
078}