The watermarking token (WMT)

Here, we cover the composition of the WMT and include requirements you can share with your watermarking vendor to properly format them.

A WMT is created by your selected watermarking vendor. Your client application ("player") needs to request it from the vendor, and send it to the edge with every segment or fragment request for content. Akamai ensures the token is present, and verifies the signature of the token to prevent tampering.

The WMT format

The WMT is formatted using the JSON Web Token (JWT) format. It consists of a header, payload, and signature separated by period characters:

Watermarking Token (WMT) = JWT = <header>.<payload>.<signature>
  • <header>: This is a JSON object that needs to be base64url encoded . It confirms the format of the object and the algorithm used to compute the <signature>. It also specifies the "kid" (Key ID) associated with the <signature> that's used for verification. This must match the Verification Key ID #<#> set in your AMD property for the applicable Verification Public Key #<#>. If you've defined both a Verification Public Key #1 and Verification Public Key #2 for added security, the Verification Key ID #1 needs to be included as the "kid" to use Verification Public Key #1; and Verification Key ID #2 needs to be included to use Verification Public Key #2. With watermarking enabled for your AMD property, any request that's missing a "kid" is denied.
  • <payload>: This is a JSON object that needs to be base64url encoded. Also referred to as the "claim set," this includes the watermarking pattern (WMID) that Akamai should use to deliver content. You can optionally set up support for Pattern Encryption which must also be enabled and configured in your AMD property.
  • <signature>: This is a JSON Web Signature (JWS) for security to protect the WMT from tampering via signing. This must match what you've set as the Verification Public Key #1 (or Verification Public Key #2) in the Token Signing options in your AMD property. It is hash encrypted using the algorithm ("alg") set in the JWT Header.

Example token

The table that follows shows pre-base64url encoded examples of the JWT Header and JWT Payload in a WMT that use the watermarking pattern “ABABAABBAABBAAABBBABAB.” Pattern Encryption has also been incorporated using a pattern encryption password of “password1.” The Signature is generated based on values set in both the JWT Header and Payload.

Note: Random values have been included here, and what's displayed is for example purposes, only.
Component Example Notes
JWT Header 
{
    "typ": "JWT",
    "alg": "RS256",
    "kid": "cn=allsports.basbeballshorts.com; nva=2021-09-23 18:59:59 EST"
}
 "RS256" (RSA Signature with SHA-256) is the algorithm that's used to hash encrypt the JWT Signature.
JWT Payload 
{
  "iss": "urn:baseballshorts",
  "iat": 0132547698,
  "wmver": 1,
  "wmid": "<watermarking ID>
  "wmidalg": "aes-128-cbc",
  "wmidivlen": 16,
  "wmidivhex": "a91283746f99aebaa4567qx123ab010a",
  "wmidivb64": "pFiQBy8GrrqkeG+1QKtweg==",
  "wmidctb64": "5hOdS05QcLFVSyjlZnF9mDGR1ipqw949MqYfanFIyMI=",
  "wmidpid": "decryptpw_2020-01-01",
  "wmidpalg": "sha256"
}
Since we've also included Pattern Encryption in this example, all of the wmid* claims are included in the payload. The watermarking identifier (wmid), Initialization Vector (wmidiv*), encryption password (wmidp*), and of course the actual cipher-text of the WMID itself (wmidctb64) are all specified so that Akamai can properly decrypt it. Knowing the shared-secret password identified by “decryptpw_2020-01-01” whose value in this example is “password1,” Akamai can generate the SHA-256 hash (as specified by “wmidpalg”) and decrypt the pattern.
JWT Signature 
<sha256 hash of the Verification Public Key #<#>.>
 The "alg" parameter from the JWT Header is used to determine the algorithm for hash encryption of the JWT Signature, and it's verified using the key identified by the "kid" parameter in the JWT Header.

The JWT Payload Claim Set

The table that follows discusses the set of claims that can be used in the JWT Payload for a WMT.

Parameter Claim Name Allowable Values Usage Description
iat Issued At A number representing the numeric date of issue (for example, the UNIX timestamp) Required The "iat" (issued at) claim identifies the time at which the JWT was issued. This claim can be used to determine the age of the JWT.
iss Issuer A case sensitive string or URI Required The "iss" (issuer) claim identifies the principal that issued the JWT.
wmver WMT Schema Version 1 Required The “wmver” claim identifies the schema version of the WMT. This gives a hint to the parser as to the fields found in the token.
wmid Watermarking ID (WMID) 1 *

The “wmid” is the Watermarking ID that's used to tell the Akamai (or other CDN) edge which variant should be delivered for the specific end-user session.

* If you've enabled Pattern Encryptionin your AMD, then "wmidctb64" carries the encrypted version of the wmid and this claim is not required. This parameter is required if you're not using Pattern Encryption.
wmidalg WMID Decryption Algorithm aes-128-cbc, aes-256-cbc Optional The “wmidalg” claim identifies the cipher algorithm that's used to decrypt content. This only applies if you've enabled Pattern Encryption in your AMD property.
wmidfmt WMID Format ab, hex Optional The “wmidfmt” claim identifies the encoding format of the WMID pattern.
  • ab (Default): specifies the pattern is a sequence of “A” and “B” characters. For example, "wmid": "ABBABAAABBBABABBBAAABBABBAAA"
  • hex: specifies the pattern is a hex string when decoded into binary implies 0=A and 1=B. For example, "wmid": "68EB8D8" (which translates to "ABBABAAABBBABABBBAAABBABBAAA.")
wmidivlen WMID IV Length 1..N Optional The “wmidivlen” claim identifies the length of the Initialization Vector (IV) suitable for the specified decryption algorithm (wmidalg).
wmidivhex WMID IV Hex String Hexadecimal String * The “wmidivhex” claim identifies the IV to use with the specified decryption algorithm.

* This claim is required if the wmidalg cipher requires an IV, and the target system must receive a Hex String encoded value. This is typically the case with Akamai. Contact your account representative if you require a different configuration.
wmidivb64 WMID IV Base64 Base64 String * The “wmidivb64” claim identifies the IV to use with the specified decryption algorithm.

* This claim is required if the wmidalg cipher requires an IV, and the target system must receive a Base64-encoded value. By default, Akamai uses the wmidivhex claim. So, when Akamai is the only recipient of this token, only the ‘hex’ version of the IV needs to be sent.
wmidctb64 WMID Ciphertext Base64 Base64 String *

The "wmidctb64" claim contains the encrypted cipher text of the "wmid."

* This claim is required if the "wmidalg" cipher indicates the "wmid" is encrypted.
wmidoff WMID Pattern Offset 128, 256 Optional The “wmidoff” claim identifies an offset that should be applied to the function that calculates the location in the pattern to use for the current media sequence number (MSN). The offset allows for a prohibitively large pattern to be defined, but only a portion of it sent in the WMT at any given point in time.

The legal values are intentionally large to allow for WMT caching to be effective.
wmidpid WMID Password ID String * The “wmidpid” claim identifies the password to use when generating the decryption key for use with Pattern Encryption.

* This claim is only required if the you've enabled Pattern Encryption in your AMD property. (In this case, the wmidalg cipher would require a decryption key.)
wmidpalg WMID Password Algorithm sha256 * The “wmidpalg” claim identifies the hashing function to use when generating a decryption key from a password.

* This claim is only required if the wmidalg cipher requires a decryption key.