Using and extending the open source SPEKE reference server

Secure Packager and Encoder Key Exchange (SPEKE) defines the standard for communication between encryptors and packagers or encoders of media content and digital rights management (DRM) key providers. The specification accommodates encryptors running on-premises and in the AWS Cloud.
The SPEKE Reference Server is an implementation of the SPEKE API and minimal implementation of back-end software to generate AES keys for an encoder or packager. The Reference Server has been donated to open source by Amazon and is available from GitHub for installation, use and customization. The project repository includes source code, project artifacts and some training material. The Reference Server has been tested with AWS Elemental MediaPackage and AWS Elemental MediaConvert. It can be integrated with third-party DRM solutions and other on-premise and cloud IT resources to create a larger DRM protection solution.
The open source project is an AWS serverless implementation of the SPEKE protocol and key server. The solution uses AWS Identity and Access Management (IAM), Amazon API Gateway, AWS Lambda, Amazon S3, Amazon CloudFront, and AWS Secrets Manager. The key server code is implemented as a single Lambda function. The source code is written in Python so it can be reused by a broad audience.

The high-level, end-to-end flow of the Reference Server is:

1. A packager or encoder sends a signed request to the server’s API Gateway endpoint over HTTPS. API Gateway authenticates the request, and sends it on to Lambda. The payload of the request is a CPIX XML document that includes a content ID, key ID, and optionally a certificate and public key to return an encrypted response. The content ID is a look-up index for a stream, channel, show or movie. The key ID is a look-up index for an AES key used to encrypt and decrypt a specific time period of video data.
2. The SPEKE server queries Secrets Manager for key generation salt stored under the content ID (In cryptography, a ‘salt’ is random data that is used as an additional input to a one-way function that “hashes” data, a password or passphrase.) If this is the first time the content ID is encountered, new salt data is generated and stored under the content ID in Secrets Manager.
3. The SPEKE server uses the key ID and salt with a key derivation algorithm to generate a 16-byte AES key. This key will be returned to the packager or encoder in the response.
4. The SPEKE server stores the key in the S3 bucket (cache) under the path content-ID/key-ID. Reading this path from the bucket will return the 16-byte AES key.
5. The key server also creates a URL to the key and adds it to the response. The packager or encoder will use this URL when generating entries in the client manifests. The client player will retrieve the key from the URL to decrypt a specific time period of video data.
6. If the packager or encoder included a certificate and key with the request, the SPEKE server will encrypt the key data before returning it in the response XML document. Otherwise, the key data will be included unencrypted in the XML document.
7. The response is returned from the Lambda to API Gateway and then to the packager or encoder over the original HTTPS connection used to initiate the key request.

Why not generate a random key with every request?

The method used to generate AES keys must be consistent. This means the packager or encoder that provides a content ID and key ID to a SPEKE server must always receive the same AES key in response. The Reference Server uses a simple approach to satisfy this requirement regionally by using the key ID and data from Secrets Manager to create keys. A key server could generate a random key on every new content ID and key ID pair and store that in a database for later reference. The process by which a key is created is up to the implementation of the key server.  SPEKE is concerned with the interface and data exchanged through it, which allows designers to build key servers suited to the needs of the runtime environment and DRM application.

Can I install and use a Reference Server today?

Yes! A CloudFormation template is provided by the project to install a SPEKE Reference Server into a region of an AWS account. There is an additional template to create an encrypted HLS endpoint from an existing AWS Elemental MediaPackage channel and SPEKE server. You should be able to start using and testing a SPEKE server in less than 30 minutes.
The SPEKE Reference Server works with HLS and DASH MediaPackage endpoints. For DASH, you need a license server and other infrastructure for a complete solution. For HLS, which can use Simple-AES encryption,  only the SPEKE server and a packager, such as AWS Elemental MediaPackage are required. You can play back the encrypted stream using a compliant HLS player.

How do I start to modify and test the Reference Server for my own solution?

You should start by installing a Reference Server using the CloudFormation template, and then iteratively update the Lambda zip while you are becoming familiar with the code. This allows you to start from a known working point before applying custom code and changing cloud resources. The Reference Server project uses a tool called Zappa to package the key server source files and dependencies into a single zip file for AWS Lambda. Review the build_and_host.sh script in the root of the project to see how to create a new zip to update an existing SPEKE server.

Can anyone participate in the open source GitHub project?

Yes! Please open questions and ideas in the Issues section, and submit your changes and enhancements using pull requests.

Learn more:
https://docs.aws.amazon.com/speke/latest/documentation/what-is-speke.html
https://github.com/awslabs/speke-reference-server