{"id":26779,"date":"2025-09-02T03:30:50","date_gmt":"2025-09-02T10:30:50","guid":{"rendered":"https:\/\/www.expressplay.com\/?page_id=26779"},"modified":"2025-09-02T03:30:50","modified_gmt":"2025-09-02T10:30:50","slug":"skm-rest-api","status":"publish","type":"page","link":"https:\/\/www.expressplay.com\/es\/skm-api-documentation\/skm-rest-api\/","title":{"rendered":"SKM REST API"},"content":{"rendered":"The SKM API is an interface to a remote or local storage and management of cryptographic keys (media encryption keys for example). Each Key object has a unique key ID (KID) and a value (typically a 16-byte random number, like an AES-128 cipher key). Keys are stored encrypted with a KEK (Key Encryption Key) using a key wrapping algorithm (AES Key Wrap, RFC 3394). Each KEK has a corresponding KEKID (Key Encryption Key ID) which can be caller-assigned, or automatically computed by the server by deriving from the KEK value using a one way function. The server does not store the KEKs. Keys can be stored and retrieved in their encrypted form (in this case it is up to the caller of the API to perform the key wrapping and\/or unwrapping), or they can be stored and retrieved in clear-text form by passing the KEK as an API parameter whenever needed (this this case, it is the server that performs the key wrapping and\/or unwrapping).
\n <\/p>\n
Data Model<\/h2>\n
\nA Key object has the following properties:<\/strong><\/p>\n\n- KID (Unique)<\/li>\n
- Key Value (byte array, encrypted with KEK). This value is not stored on the server<\/li>\n
- EK (encrypted representation of the Value). This is stored on the server<\/li>\n
- KEK_ID (String that identifies a KEK. May be derived from KEK through a one-way function)<\/li>\n
- Info (arbitrary string)<\/li>\n
- Content ID (arbitrary string used to remember the association of the key with a specific content\/file)<\/li>\n
- Expiration (if not null, the date\/time at which the Key object expired; it may be removed automatically by the server)<\/li>\n
- Last Update (date\/time at which the Key object was last updated)<\/li>\n<\/ul>\n
\nJSON representation<\/strong>
\n{\"kid\": \/\/ (KID, 32 hex chars
\n \"k\": \/\/ Key Value (not stored in DB, dynamically computed from \"ek\")
\n \"ek\": \/\/ Key Value encrypted with KEK using AES Key Wrap
\n \"kekId\": \/\/ KEK identifier
\n \"info\": \/\/ (optional)
\n \"contentId\": \/\/ (optional)
\n \"expiration\": \/\/ (optional) expiration date of the object (ISO 8601 Extended Format)
\n \"lastUpdate\": \/\/ (server-assigned) (ISO 8601 Extended Format)
\n<\/span>}<\/code><\/p>\n <\/p>\n
Encrypted vs Clear-text Key Values<\/h2>\n
\nKeys are always stored on the server in their encrypted form. When Key values are exchanged through the API (either sent or received), they may be expressed either in their encrypted form (AES Key Wrap with a KEK), or in their raw clear-text form. If Key values are exchanged in their encrypted form, it is up to the caller to wrap or unwrap the key values with the appropriate KEK. If a kek URL query parameter is present, the server will automatically perform the Key value wrapping or unwrapping.<\/p>\n
<\/p>\n
REST API<\/h2>\nCommon API parameters<\/h3>\n
\n\n| kek:<\/td>\n | (optional). When specified, this parameter contains the 16-byte KEK used to unwrap the key value, in hexadecimal (32 hex characters)<\/td>\n<\/tr>\n<\/table>\nOptional API parameters and extensions<\/h3>\n\n Some implementations of the SKM API require API callers to authenticate themselves. This may be implemented in a number of different ways, including using a URL query parameter (like for example an API key passed in a query parameter, named apiKey, customerAuthenticator, or something similar). URL query parameters must be separated with an & character.<\/p><\/blockquote>\n <\/p>\n Special KID syntax<\/h3>\nIn order to facilitate the work of API clients, a 16-byte KID can be replaced by a ^ character followed by a string. In that case, the KID is simply computed as the 16-byte truncated SHA1 hash of the string.<\/p>\n For example, if the KID is specified as the string ^kid1, the actual KID value is 80ea8bc8a58f990ad1f76bc665b30bfa.<\/p>\n <\/p>\n Root URL<\/h3>\n\n Note: The URLs below are relative to a root URL for the Key Management Service on a server. In these examples, the root URL path is \/. But a server may use a different root URL path. For example, if the Key Management Service on a server named api.service.expressplay.com is at a root URL path \/keystore, then the URL relative path keys\/{kid} would result in a final URL https:\/\/api.service.expressplay.com\/keystore\/keys\/{kid} if accessed with HTTPS.<\/p><\/blockquote>\n <\/p>\n API URLs<\/h3>\n\n POST \/keys<\/p><\/blockquote>\n Create a new Key object<\/p>\n The POST body is either empty, in which case a brand new object, with a random KID, is created and returned (a KEK must be supplied through the kek URL query parameter), or contain a JSON object with a partial or complete Key object.<\/p>\n A partial Key object is one where not all fields are set. Fields that are not set are automatically generated by the server as follows:<\/p>\n <\/p>\n \n\nkid<\/strong><\/td>\n| If the KID is not specified, a new random KID is chosen by the server. If the KID is specified, a new object is created with the specified KID, unless a Key object with the same KID already exists, in which case the rest of the POST body is ignored and the existing Key object is returned with an HTTP 200 status code.<\/td>\n<\/tr>\n | \nk<\/strong><\/td>\n| If the clear-text Key Value is not specified, a new random key value will be chosen, using a cryptographically-strong random number generator.<\/td>\n<\/tr>\n | \nek<\/strong><\/td>\n| If the encrypted Key Value is not specified, a new random key value will be chosen, using a cryptographically-strong random number generator.<\/td>\n<\/tr>\n | \nkekId<\/strong><\/td>\n| If a KEK ID is not specified, the server generates a KEKID value uniquely identifying the KEK<\/td>\n<\/tr>\n | \ninfo<\/strong><\/td>\n| If the Key Info is not specified, this field remains empty<\/td>\n<\/tr>\n | \ncontentId<\/strong><\/td>\n| If the Content ID is not specified, this field remains empty<\/td>\n<\/tr>\n | \nexpiration<\/strong><\/td>\n| If no Expiration is specified, the expiration field is not set and the object does not expire.<\/td>\n<\/tr>\n<\/table>\n <\/p>\n The response contains a JSON object representing the Key object that was created or found.<\/p>\n \n Note: It is important to set the Content-Type HTTP header to application\/json when issuing a POST request with a JSON body<\/p><\/blockquote>\n
\nExample Request: create a new random Key object<\/strong><\/p>\nPOST \/keys?kek=000102030405060708090a0b0c0d0e0f HTTP\/1.1<\/code><\/p>\n
\nResponse<\/strong><\/p>\nHTTP\/1.1 201 Created
\nContent-Type: application\/json
\nLocation: \/keys\/4e2df6b45e8257e187b2802b22ae7418
\n
\n{\"kid\": \"4e2df6b45e8257e187b2802b22ae7418\",
\n \"k\": \"a9b9033df0b9ca5447839e3d074817a0\",
\n \"ek\": \"5dbd06c0056b42fe0b8cf406679620c31bd619732730433d\",
\n \"kekId\": \"#1.afe008a381bdac03b412a92d54b92ddf\"
\n<\/span>}<\/code><\/p>\n
\nExample Request: create a new Key object with all fields already set<\/strong><\/p>\nPOST \/keys?kek=000102030405060708090a0b0c0d0e0f HTTP\/1.1
\n
\n{\"kid\": \"4e2df6b45e8257e187b2802b22ae7418\",
\n \"k\": \"a9b9033df0b9ca5447839e3d074817a0\",
\n \"kekId\": \"my-kek-id-1\",
\n \"contentId\": \"urn:mynamespace:my-content-id-1234\",
\n \"info\": \"some comment\"
\n<\/span>}<\/code><\/p>\n
\nResponse<\/strong><\/p>\nHTTP\/1.1 201 Created
\nContent-Type: application\/json
\nLocation: \/keys\/4e2df6b45e8257e187b2802b22ae7418
\n
\n{\"kid\": \"4e2df6b45e8257e187b2802b22ae7418\",
\n \"k\": \"a9b9033df0b9ca5447839e3d074817a0\",
\n \"ek\": \"5dbd06c0056b42fe0b8cf406679620c31bd619732730433d\",
\n \"kekId\": \"my-kek-id-1\",
\n \"contentId\": \"urn:mynamespace:my-content-id-1234\",
\n \"info\": \"some comment\"
\n<\/span>}<\/code><\/p>\n <\/p>\n \n\nQuery Parameters:<\/strong><\/td>\n\n\n- kek<\/strong> \u2013 (optional) KEK used to unwrap the key value<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n
\nRequest JSON Object:<\/strong><\/td>\n\n\n- kid<\/strong> (string) \u2013 KID (32 hex characters)<\/li>\n
- k<\/strong> (string) \u2013 Clear-text Key value (hex) [requires that the \u2018kek\u2019 query parameter be passed]<\/li>\n
- ek<\/strong> (string) \u2013 Encrypted Key value (hex) [mutually exclusive with the presence of a \u2018k\u2019 field]<\/li>\n
- kekId<\/strong> (string) \u2013 (optional) KEK Id<\/li>\n
- info<\/strong> (string) \u2013 (optional) Key info <\/li>\n
- contentId<\/strong> (string) \u2013 (optional) contentId<\/li>\n
- expiration <\/strong> (string) \u2013 (optional) Object expiration data\/time<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n
\nStatus Codes:<\/strong><\/td>\n\n\n- 200 OK \u2013 an existing Key object was found and returned<\/li>\n
- 201 Created \u2013 a new Key object successfully created<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n<\/table>\n
<\/p>\n PUT \/keys\/{kid}<\/p><\/blockquote>\n Update a Key object<\/p>\n The PUT body must contain a JSON object for a partial or complete Key object. Fields that are not specified in the body will not be updated. The kid field, if present in the body, is ignored.<\/p>\n <\/p>\n Note: It is important to set the Content-Type HTTP header to application\/json when issuing a PUT request with a JSON body<\/p><\/blockquote>\n
\nExample Request: change the contentId of a Key object<\/strong>
\nPUT \/keys\/11a48707853ed5f13485f161523ffdc4 HTTP\/1.1
\n
\n{\"contentId\": \"urn:namespace:x1234yyu\"<\/span>}<\/code><\/p>\n
\nResponse<\/strong>
\nHTTP\/1.1 200 OK<\/code><\/p>\n <\/p>\n \n\nQuery Parameters:<\/strong><\/td>\n\n\n- kek<\/strong> \u2013 (optional) KEK used to unwrap the key value<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n
\nRequest JSON Object:<\/strong><\/td>\n\n\n- k<\/strong> (string) \u2013 Clear-text Key value (hex) [requires that the \u2018kek\u2019 query parameter be passed]<\/li>\n
- ek<\/strong> (string) \u2013 Encrypted Key value (hex) [mutually exclusive with the presence of a \u2018k\u2019 field]<\/li>\n
- kekId<\/strong> (string) \u2013 (optional) KEK Id<\/li>\n
- info<\/strong> (string) \u2013 (optional) Key info <\/li>\n
- contentId<\/strong> (string) \u2013 (optional) contentId<\/li>\n
- expiration <\/strong> (string) \u2013 (optional) Object expiration data\/time<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n
\nStatus Codes:<\/strong><\/td>\n\n\n- 200 OK \u2013 no error<\/li>\n
- 404 Not Found \u2013 key not found<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n<\/table>\n
<\/p>\n GET \/keys\/{kid}<\/p><\/blockquote>\n Returns one Key object
\n
\nExample Request (without specifying the KEK)<\/strong>
\nGET \/keys\/11a48707853ed5f13485f161523ffdc4 HTTP\/1.1<\/code><\/p>\n <\/p>\n Example Response<\/strong>
\nHTTP\/1.1 200 OK
\nContent-Type: application\/json
\n
\n{\"kid\": \"11a48707853ed5f13485f161523ffdc4\",
\n \"ek\": \"b6862c586af0d70fdc594deb7b254bb38937113dbc6411ea\",
\n \"kekId\": \"#1.afe008a381bdac03b412a92d54b92ddf\"
\n<\/span>}<\/code><\/p>\n
\nExample Request (with KEK)<\/strong>
\nGET \/keys\/11a48707853ed5f13485f161523ffdc4?kek=000102030405060708090a0b0c0d0e0f HTTP\/1.1<\/code><\/p>\n
\nExample Response<\/strong>
\nHTTP\/1.1 200 OK
\nContent-Type: application\/json
\n
\n{\"kid\": \"11a48707853ed5f13485f161523ffdc4\",
\n \"k\": \"d4783a651c96a872daa145ce1a378153\",
\n \"kekId\": \"#1.afe008a381bdac03b412a92d54b92ddf\"
\n<\/span>}<\/code><\/p>\n <\/p>\n \n\nQuery Parameters:<\/strong><\/td>\n\n\n- kek<\/strong> \u2013 (optional) KEK used to unwrap the key value<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n
\nStatus Codes:<\/strong><\/td>\n\n\n- 200 OK \u2013 no error<\/li>\n
- 400 Bad Request \u2013 bad request (ex: wrong KEK passed)\/li>\n
- 404 Not Found \u2013 key not found<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n<\/table>\n
<\/p>\n GET \/keys\/{kid}\/value<\/p><\/blockquote>\n Returns one Key value<\/p>\n Instead of returning a complete JSON Key object, this request returns only the Key Value, as a hex string. If a KEK is passed in the kek query parameter, the response body contains the raw clear-text value of the Key object. If no KEK is passed, the response body contains the encrypted Key Value, prefixed with a # character<\/p>\n
\nExample Request (with KEK)<\/strong>
\nGET \/keys\/00112233445566778899aabbccddeefc\/value?kek=00112233445566778899aabbccddeeff HTTP\/1.1<\/code><\/p>\n
\nExample Response<\/strong>
\nHTTP\/1.1 200 OK
\nContent-Type: text\/plain
\n
\n12341234123412341234123412341234
\n<\/code><\/p>\n
\nExample Request (without KEK)<\/strong>
\nGET \/keys\/00112233445566778899aabbccddeefc\/value HTTP\/1.1<\/code><\/p>\n
\nExample Response<\/strong>
\nHTTP\/1.1 200 OK
\nContent-Type: text\/plain
\n
\n#ffaf1dae9201d1adf62770dca5ddb77ad773a79369e39986<\/code><\/p>\n <\/p>\n \n\nQuery Parameters:<\/strong><\/td>\n\n\n- kek<\/strong> \u2013 (optional) KEK used to unwrap the key value<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n
\nStatus Codes:<\/strong><\/td>\n\n\n- 200 OK \u2013 no error<\/li>\n
- 400 Bad Request \u2013 bad request (ex: wrong KEK passed)\/li>\n
- 404 Not Found \u2013 key not found<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n<\/table>\n
<\/p>\n GET \/keys\/{kid1},{kid2},…<\/p><\/blockquote>\n Returns mutliple Key objects<\/p>\n When multiple KIDs are specified, separated by \u2018,\u2019 characters, multiple Key objects can be retrieved with a single request. Just like for other requests, each KID may be expressed as a 32-character hex string, or a \u2018^\u2019 followed by an arbitrary string. The response body contains a JSON array of Key objects<\/p>\n
\nExample Request<\/strong>
\nGET \/keys\/00112233445566778899aabbccddeefb,00112233445566778899aabbccddeefa,00112233445566778899aabbccddeeff\/value?kek=000102030405060708090a0b0c0d0e0f HTTP\/1.1<\/code><\/p>\n
\nExample Response<\/strong>
\nHTTP\/1.1 200 OK
\nContent-Type: application\/json
\n
\n[{\"kid\": \"00112233445566778899aabbccddeeff\",
\n \"k\": \"ea85a33da18d55ffead60509a5666ad1\"
\n <\/span>},
\n {\"kid\": \"00112233445566778899aabbccddeefa\",
\n \"k\": \"0ae81ee0bc16917f3758324c151f7010\"
\n <\/span>},
\n {
\n \"kid\": \"00112233445566778899aabbccddeefb\",
\n \"k\": \"a0a1a2a3a4a5a6a7a8a9aaabacadaeaf\"
\n <\/span>}
\n<\/span>]<\/code><\/p>\n <\/p>\n \n\nQuery Parameters:<\/strong><\/td>\n\n\n- kek<\/strong> \u2013 (optional) KEK used to unwrap the key value<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n
\nStatus Codes:<\/strong><\/td>\n\n\n- 200 OK \u2013 no error<\/li>\n
- 400 Bad Request \u2013 bad request (ex: wrong KEK passed)\/li>\n
- 404 Not Found \u2013 key not found<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n<\/table>\n
<\/p>\n GET \/keys\/{kid1},{kid2},…\/value<\/p><\/blockquote>\n Returns multiple Key object values<\/p>\n This variant of the multiple-KID request returns the key values only instead of an array of JSON Key objects. As with the single-KID Key value request, the response body contains Key values either in raw clear-text form (when a KEK is passed), or in wrapped form (prefixed with ‘#’). The Key values in the response body are separated by ‘,’ characters<\/p>\n <\/p>\n Example Request (with KEK)<\/strong>
\nGET \/keys\/00112233445566778899aabbccddeefb,00112233445566778899aabbccddeefa,00112233445566778899aabbccddeeff\/value?kek=000102030405060708090a0b0c0d0e0f HTTP\/1.1<\/code><\/p>\n <\/p>\n Example Response<\/strong>
\nHTTP\/1.1 200 OK
\nContent-Type: text\/plain
\n
\na0a1a2a3a4a5a6a7a8a9aaabacadaeaf,0ae81ee0bc16917f3758324c151f7010,ea85a33da18d55ffead60509a5666ad1<\/code><\/p>\n <\/p>\n Example Request (without KEK)<\/strong>
\nGET \/keys\/00112233445566778899aabbccddeefb,00112233445566778899aabbccddeefa,00112233445566778899aabbccddeeff\/value HTTP\/1.1<\/code><\/p>\n <\/p>\n Example Response<\/strong>
\nHTTP\/1.1 200 OK
\nContent-Type: text\/plain
\n
\n#7c98f3e4d60636d4aef4977d12dbfe75611dbd03e54dffef,#83017d13dc5067c1cff0ecab23184fd721832ad61f79ebfc,#81cf23495abdc2e6395a527c20a0bdc39e21549cfe0914f4
\n<\/code>
\n <\/p>\n\n\nQuery Parameters:<\/strong><\/td>\n\n\n- kek<\/strong> \u2013 (optional) KEK used to unwrap the key value<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n
\nStatus Codes:<\/strong><\/td>\n\n\n- 200 OK \u2013 no error<\/li>\n
- 400 Bad Request \u2013 bad request (ex: wrong KEK passed)\/li>\n
- 404 Not Found \u2013 key not found<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n<\/table>\n
<\/p>\n DELETE \/keys\/{kid}<\/p><\/blockquote>\n Delete a Key object<\/p>\n <\/p>\n Example Request<\/strong>
\nDELETE \/keys\/00112233445566778899aabbccddeefb HTTP\/1.1<\/code><\/p>\n <\/p>\n Example Response<\/strong>
| | | |
| | | |
| | | |
| | | |
| | | | | |
| | | | | |
| | | | | | | |
|