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}