1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
// Copyright Yahoo. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.security;
import java.nio.ByteBuffer;
import java.util.Arrays;
import java.util.Objects;
import static com.yahoo.security.ArrayUtils.hex;
/**
* A SealedSharedKey represents the public part of a secure one-way ephemeral key exchange.
*
* It is "sealed" in the sense that it is expected to be computationally infeasible
* for anyone to derive the correct shared key from the sealed key without holding
* the correct private key.
*
* A SealedSharedKey can be converted to--and from--an opaque string token representation.
* This token representation is expected to be used as a convenient serialization
* form when communicating shared keys.
*/
public record SealedSharedKey(int version, KeyId keyId, byte[] enc, byte[] ciphertext) {
/** Current encoding version of opaque sealed key tokens. Must be less than 256. */
public static final int CURRENT_TOKEN_VERSION = 2;
/** Encryption context for v{1,2} tokens is always a 32-byte X25519 public key */
public static final int MAX_ENC_CONTEXT_LENGTH = 255;
// Expected max decoded size for v1 is 3 + 255 + 32 + 32 = 322. For simplicity, round this
// up to 512 to effectively not have to care about the overhead of any reasonably chosen encoding.
public static final int MAX_TOKEN_STRING_LENGTH = 512;
public SealedSharedKey {
if (enc.length > MAX_ENC_CONTEXT_LENGTH) {
throw new IllegalArgumentException("Encryption context is too large to be encoded (max is %d, got %d)"
.formatted(MAX_ENC_CONTEXT_LENGTH, enc.length));
}
}
/**
* Creates an opaque URL-safe string token that contains enough information to losslessly
* reconstruct the SealedSharedKey instance when passed verbatim to fromTokenString().
*/
public String toTokenString() {
return Base62.codec().encode(toSerializedBytes());
}
byte[] toSerializedBytes() {
byte[] keyIdBytes = keyId.asBytes();
// u8 token version || u8 length(key id) || key id || u8 length(enc) || enc || ciphertext
ByteBuffer encoded = ByteBuffer.allocate(1 + 1 + keyIdBytes.length + 1 + enc.length + ciphertext.length);
encoded.put((byte)version);
encoded.put((byte)keyIdBytes.length);
encoded.put(keyIdBytes);
encoded.put((byte)enc.length);
encoded.put(enc);
encoded.put(ciphertext);
encoded.flip();
byte[] encBytes = new byte[encoded.remaining()];
encoded.get(encBytes);
return encBytes;
}
/**
* Attempts to unwrap a SealedSharedKey opaque token representation that was previously
* created by a call to toTokenString().
*/
public static SealedSharedKey fromTokenString(String tokenString) {
verifyInputTokenStringNotTooLarge(tokenString);
byte[] rawTokenBytes = Base62.codec().decode(tokenString);
return fromSerializedBytes(rawTokenBytes);
}
static SealedSharedKey fromSerializedBytes(byte[] rawTokenBytes) {
if (rawTokenBytes.length < 1) {
throw new IllegalArgumentException("Decoded token too small to contain a version");
}
ByteBuffer decoded = ByteBuffer.wrap(rawTokenBytes);
// u8 token version || u8 length(key id) || key id || u8 length(enc) || enc || ciphertext
int version = Byte.toUnsignedInt(decoded.get());
if (version < 1 || version > CURRENT_TOKEN_VERSION) {
throw new IllegalArgumentException("Token had unexpected version. Expected value in [1, %d], was %d"
.formatted(CURRENT_TOKEN_VERSION, version));
}
int keyIdLen = Byte.toUnsignedInt(decoded.get());
byte[] keyIdBytes = new byte[keyIdLen];
decoded.get(keyIdBytes);
int encLen = Byte.toUnsignedInt(decoded.get());
byte[] enc = new byte[encLen];
decoded.get(enc);
byte[] ciphertext = new byte[decoded.remaining()];
decoded.get(ciphertext);
return new SealedSharedKey(version, KeyId.ofBytes(keyIdBytes), enc, ciphertext);
}
public int tokenVersion() { return version; }
private static void verifyInputTokenStringNotTooLarge(String tokenString) {
if (tokenString.length() > MAX_TOKEN_STRING_LENGTH) {
throw new IllegalArgumentException("Token string is too long to possibly be a valid token");
}
}
// Friendlier toString() with hex dump of enc/ciphertext fields
@Override
public String toString() {
return "SealedSharedKey{" +
"version=" + version +
", keyId=" + keyId +
", enc=" + hex(enc) +
", ciphertext=" + hex(ciphertext) +
'}';
}
// Explicitly generated equals() and hashCode() to use _contents_ of
// enc/ciphertext arrays, and not just their refs.
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (o == null || getClass() != o.getClass()) return false;
SealedSharedKey that = (SealedSharedKey) o;
return version == that.version && keyId.equals(that.keyId) &&
Arrays.equals(enc, that.enc) &&
Arrays.equals(ciphertext, that.ciphertext);
}
@Override
public int hashCode() {
int result = Objects.hash(version, keyId);
result = 31 * result + Arrays.hashCode(enc);
result = 31 * result + Arrays.hashCode(ciphertext);
return result;
}
}
|
