Class LicenseDocument

java.lang.Object
com.iizix.license.v2.LicenseDocument

public final class LicenseDocument extends Object
A verified license document (LICENSE-V2-DESIGN.md section 2.2): the parsed payload with typed accessors, constructed only by LicenseVerifier.verify(byte[], UUID, PublicKey) after steps 1 and 2 of 2.5 accepted the bytes, so an instance is always a document signed by a key a pinned root certified. Step 5 is the document's own verdict: isExpired() tells whether expires had passed by the verifier's clock; an expired document is returned, never refused (2.5, 8).

The payload (2.2, ruling LV-1 (a)) is UTF-8 text, one key=value per line, every line terminated by LF, keys ascending in String order, each key once, no blank line, no comment, no byte-order mark, no carriage return or other control character, no empty value: one byte form of a given content, so the verifier verifies the bytes it received and only then parses them, and never canonicalizes. The keys:

  • v - 2. Required.
  • lic - the license UUID, lower case. Required.
  • product - 1 iiziGo, 2 iiziServer development, 3 iiziServer standard, 4 container; 5 is retired (LV-22) and refused. Required.
  • acct - the account's uid on the MLS. Required. acctName - its e-mail.
  • ikey - the installation's Ed25519 public key, base64url of its 32 bytes (2.3). Required.
  • iid - the hardware-bound installation ID.
  • ent, entName - the entitlement's UUID and display name.
  • state - active, trial, deactivated or revoked (LicenseState). Required.
  • validFrom, validTo - the entitlement's validity, epoch milliseconds UTC; absent = unbounded.
  • trialUntil - the end of a trial, epoch milliseconds.
  • maxUsers - concurrent signed-in users of the entitlement; -1 unlimited.
  • maxServers - members of one hub holding the entitlement; -1 unlimited.
  • devID, groupID - the Developer ID and Developer Group ID.
  • issued - the MLS's clock at issue, epoch milliseconds. Required.
  • refreshAfter - when the installation should ask for a new document (issued plus 7 days, LV-6). Required.
  • expires - when this document stops being valid, whatever the entitlement says (issued plus 30 days, LV-6). Required.
  • rn - the request nonce of the request that produced the document, base64url of 32 bytes (5.1).
  • enforce - 1 when the license server turns the enforcement of this license on (com.iizix.license.LicenseEnforcement, order CC-LICENSE-ENFORCE-SWITCH); absent, as in every v5.0 document, it says nothing. The license server serves it only to builds that know the key (CAT-D-16): a build that does not refuses the document.

A number is canonical decimal, a UUID lower case, an instant its epoch milliseconds, a byte string base64url without padding; every other spelling is refused, and so is an unknown key (a new key is served only to builds that know it). Which optional keys a consumer needs is the consumer's check: a server needs ent and maxUsers, iiziGo does not. The document carries no secret and no personal data beyond the account's e-mail; a client may show all of it.

Author:
Christopher Mindus
  • Field Details

    • VERSION

      public static final int VERSION
      The format version: 2.
      See Also:
    • V

      public static final String V
      The payload key "v": the format version, VERSION.
      See Also:
    • LIC

      public static final String LIC
      The payload key "lic": the license UUID.
      See Also:
    • PRODUCT

      public static final String PRODUCT
      The payload key "product": the product, PRODUCT_IIZIGO to PRODUCT_CONTAINER_SERVER.
      See Also:
    • ACCT

      public static final String ACCT
      The payload key "acct": the account's uid on the MLS.
      See Also:
    • ACCT_NAME

      public static final String ACCT_NAME
      The payload key "acctName": the account's e-mail.
      See Also:
    • IKEY

      public static final String IKEY
      The payload key "ikey": the installation's Ed25519 public key, base64url.
      See Also:
    • IID

      public static final String IID
      The payload key "iid": the hardware-bound installation ID.
      See Also:
    • ENT

      public static final String ENT
      The payload key "ent": the entitlement's UUID.
      See Also:
    • ENT_NAME

      public static final String ENT_NAME
      The payload key "entName": the entitlement's display name.
      See Also:
    • STATE

      public static final String STATE
      The payload key "state": the state, a LicenseState token.
      See Also:
    • VALID_FROM

      public static final String VALID_FROM
      The payload key "validFrom": the start of the entitlement's validity, epoch milliseconds.
      See Also:
    • VALID_TO

      public static final String VALID_TO
      The payload key "validTo": the end of the entitlement's validity, epoch milliseconds.
      See Also:
    • TRIAL_UNTIL

      public static final String TRIAL_UNTIL
      The payload key "trialUntil": the end of a trial, epoch milliseconds.
      See Also:
    • MAX_USERS

      public static final String MAX_USERS
      The payload key "maxUsers": the concurrent signed-in users allowed, UNLIMITED for no limit.
      See Also:
    • MAX_SERVERS

      public static final String MAX_SERVERS
      The payload key "maxServers": the members of one hub allowed, UNLIMITED for no limit.
      See Also:
    • DEV_ID

      public static final String DEV_ID
      The payload key "devID": the Developer ID.
      See Also:
    • GROUP_ID

      public static final String GROUP_ID
      The payload key "groupID": the Developer Group ID.
      See Also:
    • ISSUED

      public static final String ISSUED
      The payload key "issued": the MLS's clock at issue, epoch milliseconds.
      See Also:
    • REFRESH_AFTER

      public static final String REFRESH_AFTER
      The payload key "refreshAfter": when to ask for a new document, epoch milliseconds.
      See Also:
    • EXPIRES

      public static final String EXPIRES
      The payload key "expires": when the document stops being valid, epoch milliseconds.
      See Also:
    • RN

      public static final String RN
      The payload key "rn": the request nonce, base64url of 32 bytes.
      See Also:
    • ENFORCE

      public static final String ENFORCE
      The payload key "enforce": 1 when the license server turns the enforcement of this license on (order CC-LICENSE-ENFORCE-SWITCH, com.iizix.license.LicenseEnforcement); absent, it says nothing. Only 1 is accepted: an entitlement that does not enforce carries no key, so that a v5.0 build, which refuses the key, is served its documents unchanged.
      See Also:
    • REQUIRED

      public static final List<String> REQUIRED
      The required keys, in the order a missing one is reported.
    • KEYS

      public static final Set<String> KEYS
      Every key of the format. Any other key is a refusal.
    • PRODUCT_IIZIGO

      public static final int PRODUCT_IIZIGO
      The product 1: iiziGo.
      See Also:
    • PRODUCT_DEVELOPMENT_SERVER

      public static final int PRODUCT_DEVELOPMENT_SERVER
      The product 2: iiziServer development (inside iiziGo).
      See Also:
    • PRODUCT_STANDARD_SERVER

      public static final int PRODUCT_STANDARD_SERVER
      The product 3: iiziServer standard.
      See Also:
    • PRODUCT_CONTAINER_SERVER

      public static final int PRODUCT_CONTAINER_SERVER
      The product 4: iiziServer container (JakartaEE or other).
      See Also:
    • UNLIMITED

      public static final int UNLIMITED
      The limit value -1 of maxUsers and maxServers: no limit.
      See Also:
  • Method Details

    • getBytes

      public byte[] getBytes()
      Gets the document bytes, the envelope exactly as received: what a client stores and what a member sends the hub principal.
      Returns:
      A copy of the bytes.
    • getKeyID

      public String getKeyID()
      Gets the signing key's ID, the envelope's kid.
      Returns:
      The key ID.
    • getCertificate

      public KeyCertificate getCertificate()
      Gets the signing key's certificate, which verified under a pinned root.
      Returns:
      The certificate.
    • getVerifiedAt

      public Instant getVerifiedAt()
      Gets the verifier's clock when the document was verified.
      Returns:
      The instant.
    • isExpired

      public boolean isExpired()
      Tells whether the document had expired when it was verified: step 5 of 2.5, by the verifier's clock.
      Returns:
      true when expires was not in the future.
    • isExpired

      public boolean isExpired(Instant now)
      Tells whether the document has expired at an instant.
      Parameters:
      now - The instant.
      Returns:
      true when expires is not after it.
    • getVersion

      public int getVersion()
      Gets the format version.
      Returns:
      VERSION.
    • getLicenseUUID

      public UUID getLicenseUUID()
      Gets the license UUID, lic.
      Returns:
      The UUID.
    • getProduct

      public int getProduct()
      Gets the product, product.
      Returns:
      PRODUCT_IIZIGO to PRODUCT_CONTAINER_SERVER.
    • getAccountUID

      public long getAccountUID()
      Gets the account's uid on the MLS, acct.
      Returns:
      The uid.
    • getAccountName

      public String getAccountName()
      Gets the account's e-mail, acctName.
      Returns:
      The e-mail, or null when absent.
    • getInstallationKey

      public PublicKey getInstallationKey()
      Gets the installation's public key, ikey.
      Returns:
      The Ed25519 public key.
    • getInstallationKeyBytes

      public byte[] getInstallationKeyBytes()
      Gets the installation's public key as its 32 bytes.
      Returns:
      A copy of the bytes.
    • getInstallationKeyText

      public String getInstallationKeyText()
      Gets the installation's public key as text, ikey as written.
      Returns:
      The key, base64url.
    • getInstallID

      public String getInstallID()
      Gets the hardware-bound installation ID, iid.
      Returns:
      The ID, or null when absent.
    • getEntitlementUUID

      public UUID getEntitlementUUID()
      Gets the entitlement's UUID, ent.
      Returns:
      The UUID, or null when absent.
    • getEntitlementName

      public String getEntitlementName()
      Gets the entitlement's display name, entName.
      Returns:
      The name, or null when absent.
    • getState

      public LicenseState getState()
      Gets the state, state.
      Returns:
      The state.
    • getValidFrom

      public Instant getValidFrom()
      Gets the start of the entitlement's validity, validFrom.
      Returns:
      The instant, or null when unbounded.
    • getValidTo

      public Instant getValidTo()
      Gets the end of the entitlement's validity, validTo.
      Returns:
      The instant, or null when unbounded.
    • getTrialUntil

      public Instant getTrialUntil()
      Gets the end of a trial, trialUntil.
      Returns:
      The instant, or null when absent.
    • getMaxUsers

      public Integer getMaxUsers()
      Gets the concurrent signed-in users allowed, maxUsers.
      Returns:
      The limit, UNLIMITED for none, or null when absent.
    • getMaxServers

      public Integer getMaxServers()
      Gets the members of one hub allowed, maxServers.
      Returns:
      The limit, UNLIMITED for none, or null when absent.
    • getDeveloperID

      public String getDeveloperID()
      Gets the Developer ID, devID.
      Returns:
      The ID, or null when absent.
    • getDeveloperGroupID

      public String getDeveloperGroupID()
      Gets the Developer Group ID, groupID.
      Returns:
      The ID, or null when absent.
    • getIssued

      public Instant getIssued()
      Gets the MLS's clock at issue, issued.
      Returns:
      The instant.
    • getRefreshAfter

      public Instant getRefreshAfter()
      Gets when the installation should ask for a new document, refreshAfter.
      Returns:
      The instant.
    • getExpires

      public Instant getExpires()
      Gets when the document stops being valid, expires.
      Returns:
      The instant.
    • getRequestNonce

      public byte[] getRequestNonce()
      Gets the request nonce, rn.
      Returns:
      A copy of the 32 bytes, or null when absent.
    • isEnforced

      public boolean isEnforced()
      Tells whether the license server turned the enforcement of this license on, enforce=1 (order CC-LICENSE-ENFORCE-SWITCH): one of the three sources of com.iizix.license.LicenseEnforcement. A document without the key - every v5.0 document - answers false, which says nothing: the build may enforce by itself.
      Returns:
      true when the document carries enforce=1.
    • get

      public String get(String key)
      Gets a value as written.
      Parameters:
      key - The key.
      Returns:
      The value, or null when the key is absent.
    • asMap

      public Map<String,String> asMap()
      Gets the payload as written, in key order.
      Returns:
      An unmodifiable map.
    • toString

      public String toString()
      The license UUID, the product, the state and the expiry.
      Overrides:
      toString in class Object