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.
Component | Example | Notes |
---|---|---|
JWT Header |
|
"RS256" (RSA Signature with SHA-256) is the algorithm that's used to hash encrypt the JWT Signature. |
JWT Payload |
|
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 |
|
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.
|
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. |