# 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`