Backend API. Server-side code: this runs in a Codename One backend, not in the app on the device.
public final class SignedTokens
- Object
- SignedTokens
Makes and checks the tokens a server mails out: the link that confirms an address, the link that resets a password, an invitation. A token names its subject and when it stops working, is signed with HMAC-SHA256, and needs no table: whoever comes back with one that verifies was sent it.
SignedTokens tokens = new SignedTokens(secret); // 32 random bytes, kept
String link = "/reset?token=" + tokens.create("password-reset", user.getId(), 3600,
user.getPasswordHash());
// later, from the link:
String userId = tokens.verify("password-reset", token, user.getPasswordHash());Two things keep a token to the one job it was made for.
- The purpose is part of what is signed, so a token made to confirm an address is not one that resets a password, though the same secret signed both.
- The fingerprint, when one is given, is something that changes once the
token has done its work: the password hash for a reset link, the address
for a confirmation. It is signed and not carried, and the token stops
verifying the moment the value moves on – which is what makes a reset
link single-use without a table of used ones. Where the subject has to be
known to look the fingerprint up,
subjectreads it out of a token that has not been checked yet.
The token is opaque to whoever holds it, and not secret from them: the subject is readable. Do not put in it what its holder should not see.
Constructors
public SignedTokens(byte[] secret) |
Methods
public void setClock(Clock clock) | Reads the time from clock instead of the machine. |
public String create(String purpose, String subject, long ttlSeconds) | A token for subject that works for ttlSeconds. |
public String create(String purpose, String subject, long ttlSeconds, String fingerprint) | A token for subject that works for ttlSeconds, and only while fingerprint is what it is now. |
public String verify(String purpose, String token) | The subject of token, when it was made by this secret for this purpose and has not expired; null otherwise. |
public String verify(String purpose, String token, String fingerprint) | The subject of token, when it was made by this secret for this purpose while the fingerprint was fingerprint, and has not expired; null otherwise. |
public static String subject(String token) | The subject a token names, read without checking anything. |
Inherited methods
Constructor details
SignedTokens
public SignedTokens(byte[] secret)Parameters
secretbyte[]- at least 32 bytes that stay the same for as long as the
tokens are to verify;
Crypto.randomBytes(32), stored
Method details
setClock
public void setClock(Clock clock)Reads the time from
clock instead of the machine.create
public String create(String purpose, String subject, long ttlSeconds)A token for
subject that works for ttlSeconds.create
public String create(String purpose, String subject, long ttlSeconds, String fingerprint)A token for
subject that works for ttlSeconds, and only while
fingerprint is what it is now.verify
public String verify(String purpose, String token)The subject of
token, when it was made by this secret for this
purpose and has not expired; null otherwise.verify
public String verify(String purpose, String token, String fingerprint)The subject of
token, when it was made by this secret for this
purpose while the fingerprint was fingerprint, and has not expired;
null otherwise. Why a token is refused is not said: whoever presents a
bad one learns nothing from the answer.subject
public static String subject(String token)The subject a token names, read without checking anything. For finding
the record whose fingerprint
verify then needs – never for deciding
anything: this is what the bearer wrote, until verify says otherwise.Returns
the subject, or null when
token does not have a token’s shape