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
|
// Copyright Yahoo. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.security.token;
import com.yahoo.security.HKDF;
import java.util.Objects;
import static com.yahoo.security.ArrayUtils.toUtf8Bytes;
/**
* <p>A token represents an arbitrary, opaque sequence of secret bytes (preferably from a secure
* random source) whose possession gives the holder the right to some resource(s) or action(s).
* For a token to be recognized it must be presented in its entirety, i.e. bitwise exact. This
* includes any (optional) text prefixes.
* </p><p>
* Only the party <em>presenting</em> the token should store the token secret itself; any
* parties that need to identify and/or verify the token should store <em>derivations</em>
* of the token instead (TokenFingerprint and TokenCheckHash, respectively).
* </p><p>
* A Token <em>object</em> is bound to a particular TokenDomain, but any given secret token
* string may be used to create many Token objects for any number of domains; it is opaque and
* not in and by itself tied to any specific domain.
* </p>
*/
public class Token {
private final TokenDomain domain;
private final String secretTokenString;
private final byte[] secretTokenBytes;
private final TokenFingerprint fingerprint;
Token(TokenDomain domain, String secretTokenString) {
this.domain = domain;
this.secretTokenString = secretTokenString;
this.secretTokenBytes = toUtf8Bytes(secretTokenString);
this.fingerprint = TokenFingerprint.of(this);
}
public static Token of(TokenDomain domain, String secretTokenString) {
return new Token(domain, secretTokenString);
}
public TokenDomain domain() { return domain; }
public String secretTokenString() { return secretTokenString; }
public TokenFingerprint fingerprint() { return fingerprint; }
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (o == null || getClass() != o.getClass()) return false;
Token token = (Token) o;
// We assume that domain+fingerprint suffices for equality check.
// If underlying secret bytes checking is added it MUST use SideChannelSafe.arraysEqual()
// to avoid leaking secret data via timing side-channels.
return Objects.equals(domain, token.domain) &&
Objects.equals(fingerprint, token.fingerprint);
}
// Important: actual secret bytes must NOT be part of hashCode calculation, as that risks
// leaking parts of the secret to an attacker that can influence and observe side effects
// of the hash code.
@Override
public int hashCode() {
return Objects.hash(domain, fingerprint);
}
@Override
public String toString() {
// Avoid leaking raw token secret as part of toString() output
// Fingerprint first, since that's the most important bit.
return "Token(fingerprint: %s, domain: %s)".formatted(fingerprint, domain);
}
/**
* Token derivations are created by invoking a HKDF (using HMAC-SHA256) that expands the
* original token secret to the provided number of bytes and the provided domain separation
* context. The same source token secret will result in different derivations when
* different contexts are used, but will always generate a deterministic result for the
* same token+#bytes+context combination.
*/
byte[] toDerivedBytes(int nHashBytes, byte[] domainSeparationContext) {
var hkdf = HKDF.unsaltedExtractedFrom(secretTokenBytes);
return hkdf.expand(nHashBytes, domainSeparationContext);
}
}
|
