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 com.revetsec.internal.crypto.ConstantTime;
020import com.revetsec.internal.crypto.SealerV1;
021import com.revetsec.internal.encoding.EncodingException;
022import com.revetsec.internal.encoding.StandardBase64;
023import org.jspecify.annotations.NonNull;
024
025import javax.annotation.concurrent.Immutable;
026import java.util.Arrays;
027
028import static java.util.Objects.requireNonNull;
029
030/**
031 * A secret key for {@link StateSealer}, with its key ID.
032 * <p>
033 * A key is exactly 32 random bytes, given as their canonical, padded standard Base64 encoding: 44 characters with
034 * one {@code =} at the end and no whitespace, such as the output of {@code openssl rand -base64 32}. A key whose 32
035 * bytes are all the same, such as all zeros, is rejected as a placeholder. Generate each key from a cryptographically
036 * secure random source, keep it out of source control, and use one key per application.
037 * <p>
038 * The key ID names the key inside every value it seals, so a sealer finds the right key without trying each one. It
039 * is 1 to 64 characters of {@code A-Z}, {@code a-z}, {@code 0-9}, {@code .}, {@code _}, {@code ~} and {@code -}, such
040 * as {@code 2026-09}. It is not secret: every sealed value carries it in the clear.
041 * <p>
042 * The key's bytes are never exposed. {@link #toString()} renders {@code SealingKey{keyId=..., key=<redacted>}}, and
043 * {@code equals} is reference identity, so no key material takes part in a comparison: two keys are equal only if they
044 * are the same instance.
045 *
046 * @author <a href="https://www.revetkn.com">Mark Allen</a>
047 * @since 1.0.0
048 */
049@Immutable
050public final class SealingKey {
051        private static final int ENCODED_LENGTH = 44;
052
053        @NonNull
054        private final String keyId;
055        /**
056         * Never modified after construction and never exposed; {@link #copyKeyBytes()} hands out copies.
057         */
058        private final byte @NonNull [] key;
059
060        private SealingKey(@NonNull String keyId,
061                                                                                 byte @NonNull [] key) {
062                this.keyId = keyId;
063                this.key = key;
064        }
065
066        /**
067         * Returns a sealing key from its key ID and its Base64 encoding.
068         * <p>
069         * Neither argument appears in an exception message, in case the two were swapped and the "key ID" is the key.
070         *
071         * @param keyId     the key ID: 1 to 64 characters of {@code A-Z}, {@code a-z}, {@code 0-9}, {@code .},
072         *                  {@code _}, {@code ~} and {@code -}
073         * @param base64Key the key: 32 bytes as canonical, padded standard Base64 (44 characters, no whitespace)
074         * @return a new sealing key
075         * @throws NullPointerException     if either argument is {@code null}
076         * @throws IllegalArgumentException if the key ID is not valid, the key is not the canonical Base64 encoding of
077         *                                  exactly 32 bytes, or its 32 bytes are all the same
078         * @since 1.0.0
079         */
080        @NonNull
081        public static SealingKey fromBase64(@NonNull String keyId,
082                                                                                                                                                        @NonNull String base64Key) {
083                requireNonNull(keyId);
084                requireNonNull(base64Key);
085
086                if (!SealerV1.isKeyId(keyId))
087                        throw new IllegalArgumentException("A sealing key ID must be 1 to " + SealerV1.MAXIMUM_KEY_ID_LENGTH
088                                        + " characters of A-Z, a-z, 0-9, '.', '_', '~' and '-'.");
089
090                // The length check comes first, so an oversized argument is never decoded.
091                if (base64Key.length() != ENCODED_LENGTH)
092                        throw invalidKey();
093
094                byte[] key;
095
096                try {
097                        key = StandardBase64.decode(base64Key);
098                } catch (EncodingException e) {
099                        throw invalidKey();
100                }
101
102                if (key.length != SealerV1.MASTER_KEY_LENGTH) {
103                        Arrays.fill(key, (byte) 0);
104                        throw invalidKey();
105                }
106
107                if (isUniform(key)) {
108                        Arrays.fill(key, (byte) 0);
109                        throw new IllegalArgumentException("A sealing key must not be 32 copies of the same byte.");
110                }
111
112                return new SealingKey(keyId, key);
113        }
114
115        /**
116         * Returns the key ID.
117         *
118         * @return the key ID
119         * @since 1.0.0
120         */
121        @NonNull
122        public String getKeyId() {
123                return this.keyId;
124        }
125
126        /**
127         * Returns {@code SealingKey{keyId=..., key=<redacted>}}; the key's bytes are never rendered.
128         *
129         * @return a description of this key without its secret
130         * @since 1.0.0
131         */
132        @Override
133        @NonNull
134        public String toString() {
135                return getClass().getSimpleName() + "{keyId=" + this.keyId + ", key=<redacted>}";
136        }
137
138        /**
139         * Returns a copy of the key's bytes, for {@link StateSealer} to derive its keys from. The caller zeroes the copy.
140         */
141        byte @NonNull [] copyKeyBytes() {
142                return this.key.clone();
143        }
144
145        /**
146         * Returns whether {@code other} holds the same key bytes, compared in constant time.
147         */
148        boolean hasSameKeyBytes(@NonNull SealingKey other) {
149                return ConstantTime.isEqual(this.key, requireNonNull(other).key);
150        }
151
152        /**
153         * Whether all 32 bytes are the same, examined in full whatever they hold.
154         */
155        private static boolean isUniform(byte @NonNull [] key) {
156                int difference = 0;
157
158                for (byte value : key)
159                        difference |= value ^ key[0];
160
161                return difference == 0;
162        }
163
164        @NonNull
165        private static IllegalArgumentException invalidKey() {
166                return new IllegalArgumentException("A sealing key must be the canonical, padded standard Base64 encoding of "
167                                + "exactly 32 bytes (44 characters).");
168        }
169}