Class ShieldToken

java.lang.Object

com.codename1.security.shield.ShieldToken

public final class ShieldToken
extends Object

A short-lived attestation token, ready to be attached to a request.

The value is opaque to the app. It is meaningful only to the backend that verifies it against the published Codename One signing keys -- do not parse it, and do not make a security decision on the device based on its contents, because a device the attacker controls can be made to say anything.

Expiry is measured locally, on purpose

Validity is tracked as "fetched at + time to live" using local elapsed time, never by reading an expiry field out of the token and comparing it against the device clock. On a rooted device the clock is attacker-controlled, so a token-embedded expiry can be made to look valid forever. The verifying backend does its own absolute-time check regardless; isValid() exists so the client knows when to refresh, not to enforce anything.

Constructor Summary

Constructors

Constructor	Description
ShieldToken(String value, ShieldStatus status, long fetchedAt, long ttlMillis, String binding)

Method Summary

Modifier and Type	Method	Description
String	getBinding()	The request-binding data this token was minted for, or null when it is a plain time-limited token not tied to a specific request.
long	getFetchedAt()	When this token was fetched, in wall-clock time.
long	getMillisUntilExpiry()	Milliseconds until this token stops being worth sending, or 0 once it has lapsed.
ShieldStatus	getStatus()	Outcome of the fetch that produced this token.
String	getValue()	The opaque token to place in the request header.
boolean	isBoundTo(String data)	True when this token was minted for exactly the supplied binding data.
boolean	isValid()	True when the token has a value, was fetched successfully, and has not lapsed.
boolean	shouldRefresh(int thresholdPercent)	True once the token is far enough through its lifetime to be worth refreshing in the background.
String	toString()	Never renders the token value -- these strings end up in logs.

Methods inherited from class Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

ShieldToken

public ShieldToken(String value,
 ShieldStatus status,
 long fetchedAt,
 long ttlMillis,
 String binding)

Method Details

getValue

public String getValue()

The opaque token to place in the request header. May be null when getStatus() is not ShieldStatus.OK.

getStatus

public ShieldStatus getStatus()

Outcome of the fetch that produced this token.

getMillisUntilExpiry

public long getMillisUntilExpiry()

Milliseconds until this token stops being worth sending, or 0 once it has lapsed.

isValid

public boolean isValid()

True when the token has a value, was fetched successfully, and has not lapsed.

shouldRefresh

public boolean shouldRefresh(int thresholdPercent)

True once the token is far enough through its lifetime to be worth refreshing in the background. Refreshing before expiry is what keeps a request from ever having to block.

getBinding

public String getBinding()

The request-binding data this token was minted for, or null when it is a plain time-limited token not tied to a specific request.

isBoundTo

public boolean isBoundTo(String data)

True when this token was minted for exactly the supplied binding data. A token bound to one request must not be reused for another; that is the whole point of binding.

getFetchedAt

public long getFetchedAt()

When this token was fetched, in wall-clock time.

For correlating a client log with a server log, and nothing else -- lifetime decisions use the monotonic reference instead, for the reasons in the class documentation.

toString

public String toString()

Never renders the token value -- these strings end up in logs.

Overrides:

toString in class Object