diff options
Diffstat (limited to 'security-utils/src/main/java/com/yahoo/security/token/Token.java')
-rw-r--r-- | security-utils/src/main/java/com/yahoo/security/token/Token.java | 85 |
1 files changed, 85 insertions, 0 deletions
diff --git a/security-utils/src/main/java/com/yahoo/security/token/Token.java b/security-utils/src/main/java/com/yahoo/security/token/Token.java new file mode 100644 index 00000000000..e830bdfd63d --- /dev/null +++ b/security-utils/src/main/java/com/yahoo/security/token/Token.java @@ -0,0 +1,85 @@ +// 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 + return "Token(fingerprint: %s)".formatted(fingerprint.toHexString()); + } + + /** + * 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); + } + +} |