# Serve private content with signed URLs and signed cookies Many companies that distribute content over the internet want to restrict access to documents, business data, media streams, or content that is intended for selected users, for example, users who have paid a fee. To securely serve this private content by using CloudFront, you can do the following: + Require that your users access your private content by using special CloudFront signed URLs or signed cookies. + Require that your users access your content by using CloudFront URLs, not URLs that access content directly on the origin server (for example, Amazon S3 or a private HTTP server). Requiring CloudFront URLs isn't necessary, but we recommend it to prevent users from bypassing the restrictions that you specify in signed URLs or signed cookies. For more information, see [Restrict access to files](private-content-overview.md). ## How to serve private content To configure CloudFront to serve private content, do the following tasks: 1. (Optional but recommended) Require your users to access your content only through CloudFront. The method that you use depends on whether you're using Amazon S3 or custom origins: + **Amazon S3** – See [Restrict access to an Amazon S3 origin](private-content-restricting-access-to-s3.md). + **Custom origin** – See [Restrict access to files on custom origins](private-content-overview.md#forward-custom-headers-restrict-access). Custom origins include Amazon EC2, Amazon S3 buckets configured as website endpoints, Elastic Load Balancing, and your own HTTP web servers. 1. Specify the *trusted key groups* or *trusted signers* that you want to use to create signed URLs or signed cookies. We recommend that you use trusted key groups. For more information, see [Specify signers that can create signed URLs and signed cookies](private-content-trusted-signers.md). 1. Write your application to respond to requests from authorized users either with signed URLs or with `Set-Cookie` headers that set signed cookies. Follow the steps in one of the following topics: + [Use signed URLs](private-content-signed-urls.md) + [Use signed cookies](private-content-signed-cookies.md) If you're not sure which method to use, see [Decide to use signed URLs or signed cookies](private-content-choosing-signed-urls-cookies.md). **Topics** + [ ## How to serve private content ](#private-content-task-list) + [ # Restrict access to files ](private-content-overview.md) + [ # Specify signers that can create signed URLs and signed cookies ](private-content-trusted-signers.md) + [ # Decide to use signed URLs or signed cookies ](private-content-choosing-signed-urls-cookies.md) + [ # Use signed URLs ](private-content-signed-urls.md) + [ # Use signed cookies ](private-content-signed-cookies.md) + [ # Linux commands and OpenSSL for base64 encoding and encryption ](private-content-linux-openssl.md) + [ # Code examples for creating a signature for a signed URL ](PrivateCFSignatureCodeAndExamples.md) # Restrict access to files You can control user access to your private content in two ways: + [Restrict access to files in CloudFront caches](#private-content-overview-edge-caches). + Restrict access to files in your origin by doing one of the following: + [Set up an origin access control (OAC) for your Amazon S3 bucket](private-content-restricting-access-to-s3.md). + [Configure custom headers for a private HTTP server (a custom origin)](#forward-custom-headers-restrict-access). ## Restrict access to files in CloudFront caches You can configure CloudFront to require that users access your files using either *signed URLs* or *signed cookies*. You then develop your application either to create and distribute signed URLs to authenticated users or to send `Set-Cookie` headers that set signed cookies for authenticated users. (To give a few users long-term access to a small number of files, you can also create signed URLs manually.) When you create signed URLs or signed cookies to control access to your files, you can specify the following restrictions: + An ending date and time, after which the URL is no longer valid. + (Optional) The date and time that the URL becomes valid. + (Optional) The IP address or range of addresses of the computers that can be used to access your content. One part of a signed URL or a signed cookie is hashed and signed using the private key from a public–private key pair. When someone uses a signed URL or signed cookie to access a file, CloudFront compares the signed and unsigned portions of the URL or cookie. If they don't match, CloudFront doesn't serve the file. You must use either RSA 2048 or ECDSA 256 private keys for signing URLs or cookies. ## Restrict access to files in Amazon S3 buckets You can optionally secure the content in your Amazon S3 bucket so that users can access it through the specified CloudFront distribution but cannot access it directly by using Amazon S3 URLs. This prevents someone from bypassing CloudFront and using the Amazon S3 URL to get content that you want to restrict access to. This step isn't required to use signed URLs, but we recommend it. To require that users access your content through CloudFront URLs, you do the following tasks: + Give a CloudFront *origin access control* permission to read the files in the S3 bucket. + Create the origin access control and associate it with your CloudFront distribution. + Remove permission for anyone else to use Amazon S3 URLs to read the files. For more information, see [Restrict access to an Amazon S3 origin](private-content-restricting-access-to-s3.md) or [Restrict access to an Amazon S3 Multi-Region Access Point origin](private-content-restricting-access-to-s3-mrap.md). ## Restrict access to files on custom origins If you use a custom origin, you can optionally set up custom headers to restrict access. For CloudFront to get your files from a custom origin, the files must be accessible by CloudFront using a standard HTTP (or HTTPS) request. But by using custom headers, you can further restrict access to your content so that users can access it only through CloudFront, not directly. This step isn't required to use signed URLs, but we recommend it. To require that users access content through CloudFront, change the following settings in your CloudFront distributions: **Origin Custom Headers** Configure CloudFront to forward custom headers to your origin. See [Configure CloudFront to add custom headers to origin requests](add-origin-custom-headers.md#add-origin-custom-headers-configure). **Viewer Protocol Policy** Configure your distribution to require viewers to use HTTPS to access CloudFront. See [Viewer protocol policy](DownloadDistValuesCacheBehavior.md#DownloadDistValuesViewerProtocolPolicy). **Origin Protocol Policy** Configure your distribution to require CloudFront to use the same protocol as viewers to forward requests to the origin. See [Protocol (custom origins only)](DownloadDistValuesOrigin.md#DownloadDistValuesOriginProtocolPolicy). After you've made these changes, update your application on your custom origin to only accept requests that include the custom headers that you’ve configured CloudFront to send. The combination of **Viewer Protocol Policy** and **Origin Protocol Policy** ensure that the custom headers are encrypted in transit. However, we recommend that you periodically do the following to rotate the custom headers that CloudFront forwards to your origin: 1. Update your CloudFront distribution to begin forwarding a new header to your custom origin. 1. Update your application to accept the new header as confirmation that the request is coming from CloudFront. 1. When requests no longer include the header that you're replacing, update your application to no longer accept the old header as confirmation that the request is coming from CloudFront. # Specify signers that can create signed URLs and signed cookies **Topics** + [ ## Choose between trusted key groups (recommended) and AWS accounts ](#choosing-key-groups-or-AWS-accounts) + [ ## Create key pairs for your signers ](#private-content-creating-cloudfront-key-pairs) + [ ## Reformat the private key (.NET and Java only) ](#private-content-reformatting-private-key) + [ ## Add a signer to a distribution ](#private-content-adding-trusted-signers) + [ ## Rotating key pairs ](#private-content-rotating-key-pairs) To create signed URLs or signed cookies, you need a *signer*. A signer is either a trusted key group that you create in CloudFront, or an AWS account that contains a CloudFront key pair. We recommend that you use trusted key groups with signed URLs and signed cookies. For more information, see [Choose between trusted key groups (recommended) and AWS accounts](#choosing-key-groups-or-AWS-accounts). The signer has two purposes: + As soon as you add the signer to your distribution, CloudFront starts to require that viewers use signed URLs or signed cookies to access your files. + When you create signed URLs or signed cookies, you use the private key from the signer’s key pair to sign a portion of the URL or the cookie. When someone requests a restricted file, CloudFront compares the signature in the URL or cookie with the unsigned URL or cookie, to verify that it hasn’t been tampered with. CloudFront also verifies that the URL or cookie is valid, meaning, for example, that the expiration date and time hasn’t passed. When you specify a signer, you also indirectly specify the files that require signed URLs or signed cookies by adding the signer to a cache behavior. If your distribution has only one cache behavior, viewers must use signed URLs or signed cookies to access any file in the distribution. If you create multiple cache behaviors and add signers to some cache behaviors and not to others, you can require that viewers use signed URLs or signed cookies to access some files and not others. To specify the signers (the private keys) that are allowed to create signed URLs or signed cookies, and to add the signers to your CloudFront distribution, do the following tasks: 1. Decide whether to use a trusted key group or an AWS account as the signer. We recommend using a trusted key group. For more information, see [Choose between trusted key groups (recommended) and AWS accounts](#choosing-key-groups-or-AWS-accounts). 1. For the signer that you chose in step 1, create a public–private key pair. For more information, see [Create key pairs for your signers](#private-content-creating-cloudfront-key-pairs). 1. If you’re using .NET or Java to create signed URLs or signed cookies, reformat the private key. For more information, see [Reformat the private key (.NET and Java only)](#private-content-reformatting-private-key). 1. In the distribution for which you’re creating signed URLs or signed cookies, specify the signer. For more information, see [Add a signer to a distribution](#private-content-adding-trusted-signers). ## Choose between trusted key groups (recommended) and AWS accounts To use signed URLs or signed cookies, you need a *signer*. A signer is either a trusted key group that you create in CloudFront, or an AWS account that contains a CloudFront key pair. We recommend that you use trusted key groups, for the following reasons: + With CloudFront key groups, you don’t need to use the AWS account root user to manage the public keys for CloudFront signed URLs and signed cookies. [AWS best practices](https://docs.aws.amazon.com/general/latest/gr/root-vs-iam.html#aws_tasks-that-require-root) recommend that you don’t use the root user when you don’t have to. + With CloudFront key groups, you can manage public keys, key groups, and trusted signers using the CloudFront API. You can use the API to automate key creation and key rotation. When you use the AWS root user, you have to use the AWS Management Console to manage CloudFront key pairs, so you can’t automate the process. + Because you can manage key groups with the CloudFront API, you can also use AWS Identity and Access Management (IAM) permissions policies to limit what different users are allowed to do. For example, you can allow users to upload public keys, but not delete them. Or you can allow users to delete public keys, but only when certain conditions are met, such as using multi-factor authentication, sending the request from a particular network, or sending the request within a particular date and time range. + With CloudFront key groups, you can associate a higher number of public keys with your CloudFront distribution, giving you more flexibility in how you use and manage the public keys. By default, you can associate up to four key groups with a single distribution, and you can have up to five public keys in a key group. When you use the AWS account root user to manage CloudFront key pairs, you can only have up to two active CloudFront key pairs per AWS account. ## Create key pairs for your signers Each signer that you use to create CloudFront signed URLs or signed cookies must have a public–private key pair. The signer uses its private key to sign the URL or cookies, and CloudFront uses the public key to verify the signature. The way that you create a key pair depends on whether you use a trusted key group as the signer (recommended), or a CloudFront key pair. For more information, see the following sections. The key pair that you create must meet the following requirements: + It must be either an SSH-2 RSA 2048 or ECDSA 256 key pair. + It must be in base64-encoded PEM format. To help secure your applications, we recommend that you rotate key pairs periodically. For more information, see [Rotating key pairs](#private-content-rotating-key-pairs). ### Create a key pair for a trusted key group (recommended) To create a key pair for a trusted key group, perform the following steps: 1. Create the public–private key pair. 1. Upload the public key to CloudFront. 1. Add the public key to a CloudFront key group. For more information, see the following procedures. **To create a key pair** **Note** The following steps use OpenSSL as an example of one method for creating a key pair. There are many other ways to create an RSA or ECDSA key pair. 1. Run one of the following example commands: + The following example command uses OpenSSL to generate an RSA key pair with a length of 2048 bits and save to the file named `private_key.pem`. ``` openssl genrsa -out private_key.pem 2048 ``` + The following example command uses OpenSSL to generate an ECDSA key pair with the `prime256v1` curve and save to the file named `private_key.pem`. ``` openssl ecparam -name prime256v1 -genkey -noout -out privatekey.pem ``` 1. The resulting file contains both the public and the private key. The following example command extracts the public key from the file named `private_key.pem`. ``` openssl rsa -pubout -in private_key.pem -out public_key.pem ``` You upload the public key (in the `public_key.pem` file) later, in the following procedure. **To upload the public key to CloudFront** 1. Sign in to the AWS Management Console and open the CloudFront console at [https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home). 1. In the navigation menu, choose **Public keys**. 1. Choose **Create public key**. 1. In the **Create public key** window, do the following: 1. For **Key name**, type a name to identify the public key. 1. For **Key value**, paste the public key. If you followed the steps in the preceding procedure, the public key is in the file named `public_key.pem`. To copy and paste the contents of the public key, you can: + Use the **cat** command on the macOS or Linux command line, like this: ``` cat public_key.pem ``` Copy the output of that command, then paste it into the **Key value** field. + Open the `public_key.pem` file with a plaintext editor like Notepad (on Windows) or TextEdit (on macOS). Copy the contents of the file, then paste it into the **Key value** field. 1. (Optional) For **Comment**, add a comment to describe the public key. When finished, choose **Add**. 1. Record the public key ID. You use it later when you create signed URLs or signed cookies, as the value of the `Key-Pair-Id` field. **To add the public key to a key group** 1. Open the CloudFront console at [https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home). 1. In the navigation menu, choose **Key groups**. 1. Choose **Add key group**. 1. On the **Create key group** page, do the following: 1. For **Key group name**, type a name to identify the key group. 1. (Optional) For **Comment**, type a comment to describe the key group. 1. For **Public keys**, select the public key to add to the key group, then choose **Add**. Repeat this step for each public key that you want to add to the key group. 1. Choose **Create key group**. 1. Record the key group name. You use it later to associate the key group with a cache behavior in a CloudFront distribution. (In the CloudFront API, you use the key group ID to associate the key group with a cache behavior.) ### Create a CloudFront key pair (not recommended, requires the AWS account root user) **Important** We recommend that you create a public key for a trusted key group instead of following these steps. For the recommended way to create public keys for signed URLs and signed cookies, see [Create a key pair for a trusted key group (recommended)](#create-key-pair-and-key-group). You can create a CloudFront key pair in the following ways: + Create a key pair in the AWS Management Console and download the private key. See the following procedure. + Create an RSA key pair by using an application such as OpenSSL, and then upload the public key to the AWS Management Console. For more information about creating an RSA key pair, see [Create a key pair for a trusted key group (recommended)](#create-key-pair-and-key-group). **To create CloudFront key pairs in the AWS Management Console** 1. Sign in to the AWS Management Console using the credentials of the AWS account root user. **Important** IAM users can’t create CloudFront key pairs. You must sign in using root user credentials to create key pairs. 1. Choose your account name, then choose **My Security Credentials**. 1. Choose **CloudFront key pairs**. 1. Confirm that you have no more than one active key pair. You can’t create a key pair if you already have two active key pairs. 1. Choose **Create New Key Pair**. **Note** You can also choose to create your own key pair and upload the public key. CloudFront key pairs support 1024, 2048, or 4096-bit keys. 1. In the **Create Key Pair** dialog box, choose **Download Private Key File**, and then save the file on your computer. **Important** Save the private key for your CloudFront key pair in a secure location, and set permissions on the file so that only the desired administrators can read it. If someone gets your private key, they can generate valid signed URLs and signed cookies and download your content. You cannot get the private key again, so if you lose or delete it, you must create a new CloudFront key pair. 1. Record the key pair ID for your key pair. (In the AWS Management Console, this is called the **Access Key ID**.) You’ll use it when you create signed URLs or signed cookies. ## Reformat the private key (.NET and Java only) If you’re using .NET or Java to create signed URLs or signed cookies, you cannot use the private key from your key pair in the default PEM format to create the signature. Instead, do the following: + **.NET framework** – Convert the private key to the XML format that the .NET framework uses. Several tools are available. + **Java** – Convert the private key to DER format. One way to do this is with the following OpenSSL command. In the following command, `private_key.pem` is the name of the file that contains the PEM-formatted private key, and `private_key.der` is the name of the file that contains the DER-formatted private key after you run the command. ``` openssl pkcs8 -topk8 -nocrypt -in private_key.pem -inform PEM -out private_key.der -outform DER ``` To ensure that the encoder works correctly, add the JAR for the Bouncy Castle Java cryptography APIs to your project and then add the Bouncy Castle provider. ## Add a signer to a distribution A signer is the trusted key group (recommended) or CloudFront key pair that can create signed URLs and signed cookies for a distribution. To use signed URLs or signed cookies with a CloudFront distribution, you must specify a signer. Signers are associated with cache behaviors. This allows you to require signed URLs or signed cookies for some files and not for others in the same distribution. A distribution requires signed URLs or cookies only for files that are associated with the corresponding cache behaviors. Similarly, a signer can only sign URLs or cookies for files that are associated with the corresponding cache behaviors. For example, if you have one signer for one cache behavior and a different signer for a different cache behavior, neither signer can create signed URLs or cookies for files that are associated with the other cache behavior. **Important** Before you add a signer to your distribution, do the following: Define the path patterns in cache behaviors and the sequence of cache behaviors carefully so you don’t give users unintended access to your content or prevent them from accessing content that you want to be available to everyone. For example, suppose a request matches the path pattern for two cache behaviors. The first cache behavior does not require signed URLs or signed cookies and the second cache behavior does. Users will be able to access the files without using signed URLs or signed cookies because CloudFront processes the cache behavior that is associated with the first match. For more information about path patterns, see [Path pattern](DownloadDistValuesCacheBehavior.md#DownloadDistValuesPathPattern). For a distribution that you’re already using to distribute content, make sure you’re ready to start generating signed URLs and signed cookies before you add a signer. When you add a signer, CloudFront rejects requests that don’t include a valid signed URL or signed cookie. You can add signers to your distribution using either the CloudFront console or the CloudFront API. ------ #### [ Console ] The following steps show how to add a trusted key group as a signer. You can also add an AWS account as a trusted signer, but it’s not recommended. **To add a signer to a distribution using the console** 1. Record the key group ID of the key group that you want to use as a trusted signer. For more information, see [Create a key pair for a trusted key group (recommended)](#create-key-pair-and-key-group). 1. Open the CloudFront console at [https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home). 1. Choose the distribution whose files you want to protect with signed URLs or signed cookies. **Note** To add a signer to a new distribution, you specify the same settings that are described in step 6 when you create the distribution. 1. Choose the **Behaviors** tab. 1. Select the cache behavior whose path pattern matches the files that you want to protect with signed URLs or signed cookies, and then choose **Edit**. 1. On the **Edit Behavior** page, do the following: 1. For **Restrict Viewer Access (Use Signed URLs or Signed Cookies)**, choose **Yes**. 1. For **Trusted Key Groups or Trusted Signer**, choose **Trusted Key Groups**. 1. For **Trusted Key Groups**, choose the key group to add, and then choose **Add**. Repeat if you want to add more than one key group. 1. Choose **Yes, Edit** to update the cache behavior. ------ #### [ API ] You can use the CloudFront API to add a trusted key group as a signer. You can add a signer to an existing distribution or to a new distribution. In either case, specify the values in the `TrustedKeyGroups` element. You can also add an AWS account as a trusted signer, but it’s not recommended. See the following topics in the *Amazon CloudFront API Reference*: + **Update an existing distribution** – [UpdateDistribution](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_UpdateDistribution.html) + **Create a new distribution** – [CreateDistribution](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_CreateDistribution.html) ------ ## Rotating key pairs We recommend that you periodically rotate (change) your key pairs for signed URLs and signed cookies. To rotate key pairs that you’re using to create signed URLs or signed cookies without invalidating URLs or cookies that haven’t expired yet, do the following tasks: 1. Create a new key pair, and add the public key to a key group. For more information, see [Create a key pair for a trusted key group (recommended)](#create-key-pair-and-key-group). 1. If you created a new key group in the previous step, [add the key group to the distribution as a signer](#private-content-adding-trusted-signers). **Important** Don’t remove any existing public keys from the key group, or any key groups from the distribution yet. Only add the new ones. 1. Update your application to create signatures using the private key from the new key pair. Confirm that the signed URLs or cookies that are signed with the new private keys are working. 1. Wait until the expiration date has passed in URLs or cookies that were signed using the previous private key. Then remove the old public key from the key group. If you created a new key group in step 2, remove the old key group from your distribution. # Decide to use signed URLs or signed cookies CloudFront signed URLs and signed cookies provide the same basic functionality: they allow you to control who can access your content. If you want to serve private content through CloudFront and you're trying to decide whether to use signed URLs or signed cookies, consider the following. Use signed URLs in the following cases: + You want to restrict access to individual files, for example, an installation download for your application. + Your users are using a client (for example, a custom HTTP client) that doesn't support cookies. Use signed cookies in the following cases: + You want to provide access to multiple restricted files, for example, all of the files for a video in HLS format or all of the files in the subscribers' area of website. + You don't want to change your current URLs. If you are not currently using signed URLs, and if your (unsigned) URLs contain any of the following query string parameters, you cannot use either signed URLs or signed cookies: + `Expires` + `Policy` + `Signature` + `Key-Pair-Id` + `Hash-Algorithm` CloudFront assumes that URLs that contain any of those query string parameters are signed URLs, and therefore won't look at signed cookies. ## Use both signed URLs and signed cookies Signed URLs take precedence over signed cookies. If you use both signed URLs and signed cookies to control access to the same files and a viewer uses a signed URL to request a file, CloudFront determines whether to return the file to the viewer based only on the signed URL. # Use signed URLs A signed URL includes additional information, for example, an expiration date and time, that gives you more control over access to your content. This additional information appears in a policy statement, which is based on either a canned policy or a custom policy. The differences between canned and custom policies are explained in the next two sections. **Note** You can create some signed URLs using canned policies and create some signed URLs using custom policies for the same distribution. **Topics** + [ ## Decide to use canned or custom policies for signed URLs ](#private-content-choosing-canned-custom-policy) + [ ## How signed URLs work ](#private-content-how-signed-urls-work) + [ ## Decide how long signed URLs are valid ](#private-content-overview-choosing-duration) + [ ## When CloudFront checks expiration date and time in a signed URL ](#private-content-check-expiration) + [ ## Example code and third-party tools ](#private-content-overview-sample-code) + [ # Create a signed URL using a canned policy ](private-content-creating-signed-url-canned-policy.md) + [ # Create a signed URL using a custom policy ](private-content-creating-signed-url-custom-policy.md) ## Decide to use canned or custom policies for signed URLs When you create a signed URL, you write a policy statement in JSON format that specifies the restrictions on the signed URL, for example, how long the URL is valid. You can use either a canned policy or a custom policy. Here's how canned and custom policies compare: **** | Description | Canned policy | Custom policy | | --- | --- | --- | | You can reuse the policy statement for multiple files. To reuse the policy statement, you must use wildcard characters in the `Resource` object. For more information, see [Values that you specify in the policy statement for a signed URL that uses a custom policy](private-content-creating-signed-url-custom-policy.md#private-content-custom-policy-statement-values).) | No | Yes | | You can specify the date and time that users can begin to access your content. | No | Yes (optional) | | You can specify the date and time that users can no longer access your content. | Yes | Yes | | You can specify the IP address or range of IP addresses of the users who can access your content. | No | Yes (optional) | | The signed URL includes a base64-encoded version of the policy, which results in a longer URL. | No | Yes | For information about creating signed URLs using a *canned* policy, see [Create a signed URL using a canned policy](private-content-creating-signed-url-canned-policy.md). For information about creating signed URLs using a *custom* policy, see [Create a signed URL using a custom policy](private-content-creating-signed-url-custom-policy.md). ## How signed URLs work Here's an overview of how you configure CloudFront and Amazon S3 for signed URLs and how CloudFront responds when a user uses a signed URL to request a file. 1. In your CloudFront distribution, specify one or more trusted key groups, which contain the public keys that CloudFront can use to verify the URL signature. You use the corresponding private keys to sign the URLs. CloudFront supports signed URLs with RSA 2048 and ECDSA 256 key signatures. For more information, see [Specify signers that can create signed URLs and signed cookies](private-content-trusted-signers.md). 1. Develop your application to determine whether a user should have access to your content and to create signed URLs for the files or parts of your application that you want to restrict access to. For more information, see the following topics: + [Create a signed URL using a canned policy](private-content-creating-signed-url-canned-policy.md) + [Create a signed URL using a custom policy](private-content-creating-signed-url-custom-policy.md) 1. A user requests a file for which you want to require signed URLs. 1. Your application verifies that the user is entitled to access the file: they've signed in, they've paid for access to the content, or they've met some other requirement for access. 1. Your application creates and returns a signed URL to the user. 1. The signed URL allows the user to download or stream the content. This step is automatic; the user usually doesn't have to do anything additional to access the content. For example, if a user is accessing your content in a web browser, your application returns the signed URL to the browser. The browser immediately uses the signed URL to access the file in the CloudFront edge cache without any intervention from the user. 1. CloudFront uses the public key to validate the signature and confirm that the URL hasn't been tampered with. If the signature is invalid, the request is rejected. If the signature is valid, CloudFront looks at the policy statement in the URL (or constructs one if you're using a canned policy) to confirm that the request is still valid. For example, if you specified a beginning and ending date and time for the URL, CloudFront confirms that the user is trying to access your content during the time period that you want to allow access. If the request meets the requirements in the policy statement, CloudFront does the standard operations: determines whether the file is already in the edge cache, forwards the request to the origin if necessary, and returns the file to the user. **Note** If an unsigned URL contains query string parameters, make sure you include them in the portion of the URL that you sign. If you add a query string to a signed URL after signing it, the URL returns an HTTP 403 status. ## Decide how long signed URLs are valid You can distribute private content using a signed URL that is valid for only a short time—possibly for as little as a few minutes. Signed URLs that are valid for such a short period are good for distributing content on-the-fly to a user for a specific purpose, such as distributing movie rentals or music downloads to customers on demand. If your signed URLs will be valid for just a short period, you'll probably want to generate them automatically using an application that you develop. When the user starts to download a file or starts to play a media file, CloudFront compares the expiration time in the URL with the current time to determine whether the URL is still valid. You can also distribute private content using a signed URL that is valid for a longer time, possibly for years. Signed URLs that are valid for a longer period are useful for distributing private content to known users, such as distributing a business plan to investors or distributing training materials to employees. You can develop an application to generate these longer-term signed URLs for you. ## When CloudFront checks expiration date and time in a signed URL CloudFront checks the expiration date and time in a signed URL at the time of the HTTP request. If a client begins to download a large file immediately before the expiration time, the download should complete even if the expiration time passes during the download. If the TCP connection drops and the client tries to restart the download after the expiration time passes, the download will fail. If a client uses Range GETs to get a file in smaller pieces, any GET request that occurs after the expiration time passes will fail. For more information about Range GETs, see [How CloudFront processes partial requests for an object (range GETs)](RangeGETs.md). ## Example code and third-party tools For example code that creates the hashed and signed part of signed URLs, see the following topics: + [Create a URL signature using Perl](CreateURLPerl.md) + [Create a URL signature using PHP](CreateURL_PHP.md) + [Create a URL signature using C\$1 and the .NET Framework](CreateSignatureInCSharp.md) + [Create a URL signature using Java](CFPrivateDistJavaDevelopment.md) # Create a signed URL using a canned policy To create a signed URL using a canned policy, complete the following steps. **To create a signed URL using a canned policy** 1. If you're using .NET or Java to create signed URLs, and if you haven't reformatted the private key for your key pair from the default .pem format to a format compatible with .NET or with Java, do so now. For more information, see [Reformat the private key (.NET and Java only)](private-content-trusted-signers.md#private-content-reformatting-private-key). 1. Concatenate the following values. You can use the format in this example signed URL. ``` https://d111111abcdef8.cloudfront.net/image.jpg?color=red&size=medium&Expires=1767290400&Signature=nitfHRCrtziwO2HwPfWw~yYDhUF5EwRunQA-j19DzZrvDh6hQ73lDx~-ar3UocvvRQVw6EkC~GdpGQyyOSKQim-TxAnW7d8F5Kkai9HVx0FIu-5jcQb0UEmatEXAMPLE3ReXySpLSMj0yCd3ZAB4UcBCAqEijkytL6f3fVYNGQI6&Key-Pair-Id=K2JCJMDEHXQW5F&Hash-Algorithm=SHA256 ``` Remove all empty spaces (including tabs and newline characters). You might have to include escape characters in the string in application code. All values have a type of `String`. **1. *Base URL for the file*** The base URL is the CloudFront URL that you would use to access the file if you were not using signed URLs, including your own query string parameters, if any. In the preceding example, the base URL is `https://d111111abcdef8.cloudfront.net/image.jpg`. For more information about the format of URLs for distributions, see [Customize the URL format for files in CloudFront](LinkFormat.md). + The following CloudFront URL is for an image file in a distribution (using the CloudFront domain name). Note that `image.jpg` is in an `images` directory. The path to the file in the URL must match the path to the file on your HTTP server or in your Amazon S3 bucket. `https://d111111abcdef8.cloudfront.net/images/image.jpg` + The following CloudFront URL includes a query string: `https://d111111abcdef8.cloudfront.net/images/image.jpg?size=large` + The following CloudFront URLs are for image files in a distribution. Both use an alternate domain name. The second one includes a query string: `https://www.example.com/images/image.jpg` `https://www.example.com/images/image.jpg?color=red` + The following CloudFront URL is for an image file in a distribution that uses an alternate domain name and the HTTPS protocol: `https://www.example.com/images/image.jpg` ** 2. `?`** The `?` indicates that query parameters follow the base URL. Include the `?` even if you don't specify any query parameters. You can specify the following query parameters in any order. **3. *Your query string parameters, if any*`&`** (Optional) You can enter your own query string parameters. To do so, add an ampersand (`&`) between each one, such as `color=red&size=medium`. You can specify query string parameters in any order within the URL. Your query string parameters can't be named `Expires`, `Signature`, `Key-Pair-Id`, or `Hash-Algorithm`. ** 4. `Expires=`*date and time in Unix time format (in seconds) and Coordinated Universal Time (UTC)*** The date and time that you want the URL to stop allowing access to the file. Specify the expiration date and time in Unix time format (in seconds) and Coordinated Universal Time (UTC). For example, January 1, 2026 10:00 am UTC converts to `1767290400` in Unix time format, as shown in the example at the start of this topic. To use epoch time, specify a 64-bit integer for a date that's no later than `9223372036854775807` (Friday, April 11, 2262 at 23:47:16.854 UTC). For information about UTC, see [RFC 3339, Date and Time on the Internet: Timestamps](https://tools.ietf.org/html/rfc3339). ** 5. `&Signature=`*hashed and signed version of the policy statement*** A hashed, signed, and base64-encoded version of the JSON policy statement. For more information, see [Create a signature for a signed URL that uses a canned policy](#private-content-canned-policy-creating-signature). ** 6. `&Key-Pair-Id=`*public key ID for the CloudFront public key whose corresponding private key you're using to generate the signature*** The ID for a CloudFront public key, for example, `K2JCJMDEHXQW5F`. The public key ID tells CloudFront which public key to use to validate the signed URL. CloudFront compares the information in the signature with the information in the policy statement to verify that the URL has not been tampered with. This public key must belong to a key group that is a trusted signer in the distribution. For more information, see [Specify signers that can create signed URLs and signed cookies](private-content-trusted-signers.md). ** 7. `&Hash-Algorithm=`*SHA1 or SHA256*** (Optional) The hash algorithm used to create the signature. Supported values are `SHA1` and `SHA256`. If you don't specify this parameter, CloudFront defaults to `SHA1`. ## Create a signature for a signed URL that uses a canned policy To create the signature for a signed URL that uses a canned policy, complete the following procedures. **Topics** + [ ### Create a policy statement for a signed URL that uses a canned policy ](#private-content-canned-policy-creating-policy-statement) + [ ### Create a signature for a signed URL that uses a canned policy ](#private-content-canned-policy-signing-policy-statement) ### Create a policy statement for a signed URL that uses a canned policy When you create a signed URL using a canned policy, the `Signature` parameter is a hashed and signed version of a policy statement. For signed URLs that use a canned policy, you don't include the policy statement in the URL, as you do for signed URLs that use a custom policy. To create the policy statement, do the following procedure. **To create the policy statement for a signed URL that uses a canned policy** 1. Construct the policy statement using the following JSON format and using UTF-8 character encoding. Include all punctuation and other literal values exactly as specified. For information about the `Resource` and `DateLessThan` parameters, see [Values that you specify in the policy statement for a signed URL that uses a canned policy](#private-content-canned-policy-statement-values). ``` { "Statement": [ { "Resource": "base URL or stream name", "Condition": { "DateLessThan": { "AWS:EpochTime": ending date and time in Unix time format and UTC } } } ] } ``` 1. Remove all empty spaces (including tabs and newline characters) from the policy statement. You might have to include escape characters in the string in application code. #### Values that you specify in the policy statement for a signed URL that uses a canned policy When you create a policy statement for a canned policy, you specify the following values. **Resource** You can specify only one value for `Resource`. The base URL including your query strings, if any, but excluding the CloudFront `Expires`, `Signature`, `Key-Pair-Id`, and `Hash-Algorithm` parameters, for example: `https://d111111abcdef8.cloudfront.net/images/horizon.jpg?size=large&license=yes` Note the following: + **Protocol** – The value must begin with `http://` or `https://`. + **Query string parameters** – If you have no query string parameters, omit the question mark. + **Alternate domain names** – If you specify an alternate domain name (CNAME) in the URL, you must specify the alternate domain name when referencing the file in your webpage or application. Do not specify the Amazon S3 URL for the object. **DateLessThan** The expiration date and time for the URL in Unix time format (in seconds) and Coordinated Universal Time (UTC). For example, January 1, 2026 10:00 am UTC converts to 1767290400 in Unix time format. This value must match the value of the `Expires` query string parameter in the signed URL. Do not enclose the value in quotation marks. For more information, see [When CloudFront checks expiration date and time in a signed URL](private-content-signed-urls.md#private-content-check-expiration). #### Example policy statement for a signed URL that uses a canned policy When you use the following example policy statement in a signed URL, a user can access the file `https://d111111abcdef8.cloudfront.net/horizon.jpg` until January 1, 2026 10:00 am UTC: ``` { "Statement": [ { "Resource": "https://d111111abcdef8.cloudfront.net/horizon.jpg?size=large&license=yes", "Condition": { "DateLessThan": { "AWS:EpochTime": 1767290400 } } } ] } ``` ### Create a signature for a signed URL that uses a canned policy To create the value for the `Signature` parameter in a signed URL, you hash and sign the policy statement that you created in [Create a policy statement for a signed URL that uses a canned policy](#private-content-canned-policy-creating-policy-statement). For additional information and examples of how to hash, sign, and encode the policy statement, see: + [Linux commands and OpenSSL for base64 encoding and encryption](private-content-linux-openssl.md) + [Code examples for creating a signature for a signed URL](PrivateCFSignatureCodeAndExamples.md) **Note** The linked examples use SHA-1 by default. To use SHA-256 instead, replace `sha1` with `sha256` in the OpenSSL commands and include the `Hash-Algorithm=SHA256` query parameter in the signed URL. **Option 1: To create a signature by using a canned policy** 1. Use the SHA-1 or SHA-256 hash function and the generated RSA or ECDSA private key to hash and sign the policy statement that you created in the procedure [To create the policy statement for a signed URL that uses a canned policy](#private-content-canned-policy-creating-policy-statement-procedure). Use the version of the policy statement that no longer includes empty spaces. If you use SHA-256, you must include `&Hash-Algorithm=SHA256` in the signed URL. For the private key that is required by the hash function, use a private key whose public key is in an active trusted key group for the distribution. **Note** The method that you use to hash and sign the policy statement depends on your programming language and platform. For sample code, see [Code examples for creating a signature for a signed URL](PrivateCFSignatureCodeAndExamples.md). 1. Remove empty spaces (including tabs and newline characters) from the hashed and signed string. 1. Base64-encode the string using MIME base64 encoding. For more information, see [Section 6.8, Base64 Content-Transfer-Encoding](https://tools.ietf.org/html/rfc2045#section-6.8) in *RFC 2045, MIME (Multipurpose Internet Mail Extensions) Part One: Format of Internet Message Bodies*. 1. Replace characters that are invalid in a URL query string with characters that are valid. The following table lists invalid and valid characters. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-creating-signed-url-canned-policy.html) 1. Append the resulting value to your signed URL after `&Signature=`, and return to [To create a signed URL using a canned policy](#private-content-creating-signed-url-canned-policy-procedure) to finish concatenating the parts of your signed URL. # Create a signed URL using a custom policy To create a signed URL using a custom policy, complete the following procedure. **To create a signed URL using a custom policy** 1. If you're using .NET or Java to create signed URLs, and if you haven't reformatted the private key for your key pair from the default .pem format to a format compatible with .NET or with Java, do so now. For more information, see [Reformat the private key (.NET and Java only)](private-content-trusted-signers.md#private-content-reformatting-private-key). 1. Concatenate the following values. You can use the format in this example signed URL. ``` https://d111111abcdef8.cloudfront.net/image.jpg?color=red&size=medium&Policy=eyANCiAgICEXAMPLEW1lbnQiOiBbeyANCiAgICAgICJSZXNvdXJjZSI6Imh0dHA6Ly9kemJlc3FtN3VuMW0wLmNsb3VkZnJvbnQubmV0L2RlbW8ucGhwIiwgDQogICAgICAiQ29uZGl0aW9uIjp7IA0KICAgICAgICAgIklwQWRkcmVzcyI6eyJBV1M6U291cmNlSXAiOiIyMDcuMTcxLjE4MC4xMDEvMzIifSwNCiAgICAgICAgICJEYXRlR3JlYXRlclRoYW4iOnsiQVdTOkVwb2NoVGltZSI6MTI5Njg2MDE3Nn0sDQogICAgICAgICAiRGF0ZUxlc3NUaGFuIjp7IkFXUzpFcG9jaFRpbWUiOjEyOTY4NjAyMjZ9DQogICAgICB9IA0KICAgfV0gDQp9DQo&Signature=nitfHRCrtziwO2HwPfWw~yYDhUF5EwRunQA-j19DzZrvDh6hQ73lDx~-ar3UocvvRQVw6EkC~GdpGQyyOSKQim-TxAnW7d8F5Kkai9HVx0FIu-5jcQb0UEmatEXAMPLE3ReXySpLSMj0yCd3ZAB4UcBCAqEijkytL6f3fVYNGQI6&Key-Pair-Id=K2JCJMDEHXQW5F&Hash-Algorithm=SHA256 ``` Remove all empty spaces (including tabs and newline characters). You might have to include escape characters in the string in application code. All values have a type of `String`. **1. *Base URL for the file*** The base URL is the CloudFront URL that you would use to access the file if you were not using signed URLs, including your own query string parameters, if any. In the preceding example, the base URL is `https://d111111abcdef8.cloudfront.net/image.jpg`. For more information about the format of URLs for distributions, see [Customize the URL format for files in CloudFront](LinkFormat.md). The following examples show values that you specify for distributions. + The following CloudFront URL is for an image file in a distribution (using the CloudFront domain name). Note that `image.jpg` is in an `images` directory. The path to the file in the URL must match the path to the file on your HTTP server or in your Amazon S3 bucket. `https://d111111abcdef8.cloudfront.net/images/image.jpg` + The following CloudFront URL includes a query string: `https://d111111abcdef8.cloudfront.net/images/image.jpg?size=large` + The following CloudFront URLs are for image files in a distribution. Both use an alternate domain name; the second one includes a query string: `https://www.example.com/images/image.jpg` `https://www.example.com/images/image.jpg?color=red` + The following CloudFront URL is for an image file in a distribution that uses an alternate domain name and the HTTPS protocol: `https://www.example.com/images/image.jpg` **2. `?`** The `?` indicates that query string parameters follow the base URL. Include the `?` even if you don't specify any query parameters. You can specify the following query parameters in any order. **3. *Your query string parameters, if any*`&`** (Optional) You can enter your own query string parameters. To do so, add an ampersand (&) between each one, such as `color=red&size=medium`. You can specify query string parameters in any order within the URL. Your query string parameters can't be named `Policy`, `Signature`, `Key-Pair-Id`, or `Hash-Algorithm`. If you add your own parameters, append an `&` after each one, including the last one. **4. `Policy=`*base64 encoded version of policy statement*** Your policy statement in JSON format, with empty spaces removed, then base64 encoded. For more information, see [Create a policy statement for a signed URL that uses a custom policy](#private-content-custom-policy-statement). The policy statement controls the access that a signed URL grants to a user. It includes the URL of the file, an expiration date and time, an optional date and time that the URL becomes valid, and an optional IP address or range of IP addresses that are allowed to access the file. **5. `&Signature=`*hashed and signed version of the policy statement*** A hashed, signed, and base64-encoded version of the JSON policy statement. For more information, see [Create a signature for a signed URL that uses a custom policy](#private-content-custom-policy-creating-signature). **6. `&Key-Pair-Id=`*public key ID for the CloudFront public key whose corresponding private key you're using to generate the signature*** The ID for a CloudFront public key, for example, `K2JCJMDEHXQW5F`. The public key ID tells CloudFront which public key to use to validate the signed URL. CloudFront compares the information in the signature with the information in the policy statement to verify that the URL has not been tampered with. This public key must belong to a key group that is a trusted signer in the distribution. For more information, see [Specify signers that can create signed URLs and signed cookies](private-content-trusted-signers.md). **7. `&Hash-Algorithm=`*SHA1 or SHA256*** (Optional) The hash algorithm used to create the signature. Supported values are `SHA1` and `SHA256`. If you don't specify this parameter, CloudFront defaults to `SHA1`. ## Create a policy statement for a signed URL that uses a custom policy Complete the following steps to create a policy statement for a signed URL that uses a custom policy. For example policy statements that control access to files in a variety of ways, see [Example policy statements for a signed URL that uses a custom policy](#private-content-custom-policy-statement-examples). **To create the policy statement for a signed URL that uses a custom policy** 1. Construct the policy statement using the following JSON format. Replace the less than (`<`) and greater than (`>`) symbols, and the descriptions within them, with your own values. For more information, see [Values that you specify in the policy statement for a signed URL that uses a custom policy](#private-content-custom-policy-statement-values). ``` { "Statement": [ { "Resource": "", "Condition": { "DateLessThan": { "AWS:EpochTime": }, "DateGreaterThan": { "AWS:EpochTime": }, "IpAddress": { "AWS:SourceIp": "" } } } ] } ``` Note the following: + You can include only one statement in the policy. + Use UTF-8 character encoding. + Include all punctuation and parameter names exactly as specified. Abbreviations for parameter names are not accepted. + The order of the parameters in the `Condition` section doesn't matter. + For information about the values for `Resource`, `DateLessThan`, `DateGreaterThan`, and `IpAddress`, see [Values that you specify in the policy statement for a signed URL that uses a custom policy](#private-content-custom-policy-statement-values). 1. Remove all empty spaces (including tabs and newline characters) from the policy statement. You might have to include escape characters in the string in application code. 1. Base64-encode the policy statement using MIME base64 encoding. For more information, see [Section 6.8, Base64 Content-Transfer-Encoding](https://tools.ietf.org/html/rfc2045#section-6.8) in *RFC 2045, MIME (Multipurpose Internet Mail Extensions) Part One: Format of Internet Message Bodies*. 1. Replace characters that are invalid in a URL query string with characters that are valid. The following table lists invalid and valid characters. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-creating-signed-url-custom-policy.html) 1. Append the resulting value to your signed URL after `Policy=`. 1. Create a signature for the signed URL by hashing, signing, and base64-encoding the policy statement. For more information, see [Create a signature for a signed URL that uses a custom policy](#private-content-custom-policy-creating-signature). ### Values that you specify in the policy statement for a signed URL that uses a custom policy When you create a policy statement for a custom policy, you specify the following values. **Resource** The URL, including any query strings, but excluding the CloudFront `Policy`, `Signature`, `Key-Pair-Id`, and `Hash-Algorithm` parameters. For example: `https://d111111abcdef8.cloudfront.net/images/horizon.jpg\?size=large&license=yes` You can specify only one URL value for `Resource`. You can omit the `Resource` parameter in a policy, but doing so means that anyone with the signed URL can access *all* of the files in *any* distribution that is associated with the key pair that you use to create the signed URL. Note the following: + **Protocol** – The value must begin with `http://`, `https://`, or `*://`. + **Query string parameters** – If the URL has query string parameters, don't use a backslash character (`\`) to escape the question mark character (`?`) that begins the query string. For example: `https://d111111abcdef8.cloudfront.net/images/horizon.jpg?size=large&license=yes` + **Wildcard characters** – You can use wildcard characters in the URL in the policy. The following wildcard characters are supported: + asterisk (`*`), which matches zero or more characters + question mark (`?`), which matches exactly one character When CloudFront matches the URL in the policy to the URL in the HTTP request, the URL in the policy is divided into four sections—protocol, domain, path, and query string—as follows: `[protocol]://[domain]/[path]\?[query string]` When you use a wildcard character in the URL in the policy, the wildcard matching applies only within the boundaries of the section that contains the wildcard. For example, consider this URL in a policy: `https://www.example.com/hello*world` In this example, the asterisk wildcard (`*`) only applies within the path section, so it matches the URLs `https://www.example.com/helloworld` and `https://www.example.com/hello-world`, but it does not match the URL `https://www.example.net/hello?world`. The following exceptions apply to the section boundaries for wildcard matching: + A trailing asterisk in the path section implies an asterisk in the query string section. For example, `http://example.com/hello*` is equivalent to `http://example.com/hello*\?*`. + A trailing asterisk in the domain section implies an asterisk in both the path and query string sections. For example, `http://example.com*` is equivalent to `http://example.com*/*\?*`. + A URL in the policy can omit the protocol section and start with an asterisk in the domain section. In that case, the protocol section is implicitly set to an asterisk. For example, the URL `*example.com` in a policy is equivalent to `*://*example.com/`. + An asterisk by itself (`"Resource": "*"`) matches any URL. For example, the value: `https://d111111abcdef8.cloudfront.net/*game_download.zip*` in a policy matches all of the following URLs: + `https://d111111abcdef8.cloudfront.net/game_download.zip` + `https://d111111abcdef8.cloudfront.net/example_game_download.zip?license=yes` + `https://d111111abcdef8.cloudfront.net/test_game_download.zip?license=temp` + **Alternate domain names** – If you specify an alternate domain name (CNAME) in the URL in the policy, the HTTP request must use the alternate domain name in your webpage or application. Do not specify the Amazon S3 URL for the file in a policy. **DateLessThan** The expiration date and time for the URL in Unix time format (in seconds) and Coordinated Universal Time (UTC). In the policy, do not enclose the value in quotation marks. For information about UTC, see [Date and Time on the Internet: Timestamps](https://tools.ietf.org/html/rfc3339). For example, January 31, 2023 10:00 AM UTC converts to 1675159200 in Unix time format. This is the only required parameter in the `Condition` section. CloudFront requires this value to prevent users from having permanent access to your private content. For more information, see [When CloudFront checks expiration date and time in a signed URL](private-content-signed-urls.md#private-content-check-expiration) **DateGreaterThan (Optional)** An optional start date and time for the URL in Unix time format (in seconds) and Coordinated Universal Time (UTC). Users are not allowed to access the file on or before the specified date and time. Do not enclose the value in quotation marks. **IpAddress (Optional)** The IP address of the client making the HTTP request. Note the following: + To allow any IP address to access the file, omit the `IpAddress` parameter. + You can specify either one IP address or one IP address range. You can't use the policy to allow access if the client's IP address is in one of two separate ranges. + To allow access from a single IP address, you specify: `"`*IPv4 IP address*`/32"` + You must specify IP address ranges in standard IPv4 CIDR format (for example, `192.0.2.0/24`). For more information, see [Classless Inter-domain Routing (CIDR): The Internet Address Assignment and Aggregation Plan](https://tools.ietf.org/html/rfc4632). **Important** IP addresses in IPv6 format, such as 2001:0db8:85a3::8a2e:0370:7334, are not supported. If you're using a custom policy that includes `IpAddress`, do not enable IPv6 for the distribution. If you want to restrict access to some content by IP address and support IPv6 requests for other content, you can create two distributions. For more information, see [Enable IPv6 (viewer requests)](DownloadDistValuesGeneral.md#DownloadDistValuesEnableIPv6) in the topic [All distribution settings reference](distribution-web-values-specify.md). ## Example policy statements for a signed URL that uses a custom policy The following example policy statements show how to control access to a specific file, all of the files in a directory, or all of the files associated with a key pair ID. The examples also show how to control access from an individual IP address or a range of IP addresses, and how to prevent users from using the signed URL after a specified date and time. If you copy and paste any of these examples, remove any empty spaces (including tabs and newline characters), replace the values with your own values, and include a newline character after the closing brace (`}`). For more information, see [Values that you specify in the policy statement for a signed URL that uses a custom policy](#private-content-custom-policy-statement-values). **Topics** + [ ### Example policy statement: Access one file from a range of IP addresses ](#private-content-custom-policy-statement-example-one-object) + [ ### Example policy statement: Access all files in a directory from a range of IP addresses ](#private-content-custom-policy-statement-example-all-objects) + [ ### Example policy statement: Access all files associated with a key pair ID from one IP address ](#private-content-custom-policy-statement-example-one-ip) ### Example policy statement: Access one file from a range of IP addresses The following example custom policy in a signed URL specifies that a user can access the file `https://d111111abcdef8.cloudfront.net/game_download.zip` from IP addresses in the range `192.0.2.0/24` until January 31, 2023 10:00 AM UTC: ``` { "Statement": [ { "Resource": "https://d111111abcdef8.cloudfront.net/game_download.zip", "Condition": { "IpAddress": { "AWS:SourceIp": "192.0.2.0/24" }, "DateLessThan": { "AWS:EpochTime": 1675159200 } } } ] } ``` ### Example policy statement: Access all files in a directory from a range of IP addresses The following example custom policy allows you to create signed URLs for any file in the `training` directory, as indicated by the asterisk wildcard character (`*`) in the `Resource` parameter. Users can access the file from an IP address in the range `192.0.2.0/24` until January 31, 2023 10:00 AM UTC: ``` { "Statement": [ { "Resource": "https://d111111abcdef8.cloudfront.net/training/*", "Condition": { "IpAddress": { "AWS:SourceIp": "192.0.2.0/24" }, "DateLessThan": { "AWS:EpochTime": 1675159200 } } } ] } ``` Each signed URL with which you use this policy has a URL that identifies a specific file, for example: `https://d111111abcdef8.cloudfront.net/training/orientation.pdf` ### Example policy statement: Access all files associated with a key pair ID from one IP address The following example custom policy allows you to create signed URLs for any file associated with any distribution, as indicated by the asterisk wildcard character (`*`) in the `Resource` parameter. The signed URL must use the `https://` protocol, not `http://`. The user must use the IP address `192.0.2.10/32`. (The value `192.0.2.10/32` in CIDR notation refers to a single IP address, `192.0.2.10`.) The files are available only from January 31, 2023 10:00 AM UTC until February 2, 2023 10:00 AM UTC: ``` { "Statement": [ { "Resource": "https://*", "Condition": { "IpAddress": { "AWS:SourceIp": "192.0.2.10/32" }, "DateGreaterThan": { "AWS:EpochTime": 1675159200 }, "DateLessThan": { "AWS:EpochTime": 1675332000 } } } ] } ``` Each signed URL with which you use this policy has a URL that identifies a specific file in a specific CloudFront distribution, for example: `https://d111111abcdef8.cloudfront.net/training/orientation.pdf` The signed URL also includes a key pair ID, which must be associated with a trusted key group in the distribution (d111111abcdef8.cloudfront.net) that you specify in the URL. ## Create a signature for a signed URL that uses a custom policy The signature for a signed URL that uses a custom policy is a hashed, signed, and base64-encoded version of the policy statement. To create a signature for a custom policy, complete the following steps. For additional information and examples of how to hash, sign, and encode the policy statement, see: + [Linux commands and OpenSSL for base64 encoding and encryption](private-content-linux-openssl.md) + [Code examples for creating a signature for a signed URL](PrivateCFSignatureCodeAndExamples.md) **Note** The linked examples use SHA-1 by default. To use SHA-256 instead, replace `sha1` with `sha256` in the OpenSSL commands and include the `Hash-Algorithm=SHA256` query parameter in the signed URL. **Option 1: To create a signature by using a custom policy** 1. Use the SHA-1 or SHA-256 hash function and the generated RSA or ECDSA private key to hash and sign the JSON policy statement that you created in the procedure [To create the policy statement for a signed URL that uses a custom policy](#private-content-custom-policy-creating-policy-procedure). Use the version of the policy statement that no longer includes empty spaces but that has not yet been base64-encoded. If you use SHA-256, you must include `&Hash-Algorithm=SHA256` in the signed URL. For the private key that is required by the hash function, use a private key whose public key is in an active trusted key group for the distribution. **Note** The method that you use to hash and sign the policy statement depends on your programming language and platform. For sample code, see [Code examples for creating a signature for a signed URL](PrivateCFSignatureCodeAndExamples.md). 1. Remove empty spaces (including tabs and newline characters) from the hashed and signed string. 1. Base64-encode the string using MIME base64 encoding. For more information, see [Section 6.8, Base64 Content-Transfer-Encoding](https://tools.ietf.org/html/rfc2045#section-6.8) in *RFC 2045, MIME (Multipurpose Internet Mail Extensions) Part One: Format of Internet Message Bodies*. 1. Replace characters that are invalid in a URL query string with characters that are valid. The following table lists invalid and valid characters. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-creating-signed-url-custom-policy.html) 1. Append the resulting value to your signed URL after `&Signature=`, and return to [To create a signed URL using a custom policy](#private-content-creating-signed-url-custom-policy-procedure) to finish concatenating the parts of your signed URL. # Use signed cookies CloudFront signed cookies allow you to control who can access your content when you don't want to change your current URLs or when you want to provide access to multiple restricted files, for example, all of the files in the subscribers' area of a website. This topic explains the considerations when using signed cookies and describes how to set signed cookies using canned and custom policies. **Topics** + [ ## Decide to use canned or custom policies for signed cookies ](#private-content-choosing-canned-custom-cookies) + [ ## How signed cookies work ](#private-content-how-signed-cookies-work) + [ ## Prevent misuse of signed cookies ](#private-content-signed-cookie-misuse) + [ ## When CloudFront checks expiration date and time in a signed cookie ](#private-content-check-expiration-cookie) + [ ## Sample code and third-party tools ](#private-content-overview-sample-code-cookies) + [ # Set signed cookies using a canned policy ](private-content-setting-signed-cookie-canned-policy.md) + [ # Set signed cookies using a custom policy ](private-content-setting-signed-cookie-custom-policy.md) + [ # Create signed cookies using PHP ](signed-cookies-PHP.md) ## Decide to use canned or custom policies for signed cookies When you create a signed cookie, you write a policy statement in JSON format that specifies the restrictions on the signed cookie, for example, how long the cookie is valid. You can use canned policies or custom policies. The following table compares canned and custom policies: **** | Description | Canned policy | Custom policy | | --- | --- | --- | | You can reuse the policy statement for multiple files. To reuse the policy statement, you must use wildcard characters in the `Resource` object. For more information, see [Values that you specify in the policy statement for a custom policy for signed cookies](private-content-setting-signed-cookie-custom-policy.md#private-content-custom-policy-statement-cookies-values).) | No | Yes | | You can specify the date and time that users can begin to access your content | No | Yes (optional) | | You can specify the date and time that users can no longer access your content | Yes | Yes | | You can specify the IP address or range of IP addresses of the users who can access your content | No | Yes (optional) | For information about creating signed cookies using a canned policy, see [Set signed cookies using a canned policy](private-content-setting-signed-cookie-canned-policy.md). For information about creating signed cookies using a custom policy, see [Set signed cookies using a custom policy](private-content-setting-signed-cookie-custom-policy.md). ## How signed cookies work Here's an overview of how you configure CloudFront for signed cookies and how CloudFront responds when a user submits a request that contains a signed cookie. 1. In your CloudFront distribution, specify one or more trusted key groups, which contain the public keys that CloudFront can use to verify the URL signature. You use the corresponding private keys to sign the URLs. For more information, see [Specify signers that can create signed URLs and signed cookies](private-content-trusted-signers.md). 1. You develop your application to determine whether a user should have access to your content and, if so, to send three `Set-Cookie` headers to the viewer. (Each `Set-Cookie` header can contain only one name-value pair, and a CloudFront signed cookie requires three name-value pairs.) You must send the `Set-Cookie` headers to the viewer before the viewer requests your private content. If you set a short expiration time on the cookie, you might also want to send three more `Set-Cookie` headers in response to subsequent requests, so that the user continues to have access. Typically, your CloudFront distribution will have at least two cache behaviors, one that doesn't require authentication and one that does. The error page for the secure portion of the site includes a redirector or a link to a login page. If you configure your distribution to cache files based on cookies, CloudFront doesn't cache separate files based on the attributes in signed cookies. 1. A user signs in to your website and either pays for content or meets some other requirement for access. 1. Your application returns the `Set-Cookie` headers in the response, and the viewer stores the name-value pairs. 1. The user requests a file. The user's browser or other viewer gets the name-value pairs from step 4 and adds them to the request in a `Cookie` header. This is the signed cookie. 1. CloudFront uses the public key to validate the signature in the signed cookie and to confirm that the cookie hasn't been tampered with. If the signature is invalid, the request is rejected. If the signature in the cookie is valid, CloudFront looks at the policy statement in the cookie (or constructs one if you're using a canned policy) to confirm that the request is still valid. For example, if you specified a beginning and ending date and time for the cookie, CloudFront confirms that the user is trying to access your content during the time period that you want to allow access. If the request meets the requirements in the policy statement, CloudFront serves your content as it does for content that isn't restricted: it determines whether the file is already in the edge cache, forwards the request to the origin if necessary, and returns the file to the user. ## Prevent misuse of signed cookies If you specify the `Domain` parameter in a `Set-Cookie` header, specify the most precise value possible to reduce the potential for access by someone with the same root domain name. For example, app.example.com is preferable to example.com, especially when you don't control example.com. This helps prevent someone from accessing your content from www.example.com. To help prevent this type of attack, do the following: + Exclude the `Expires` and `Max-Age` cookie attributes, so that the `Set-Cookie` header creates a session cookie. Session cookies are automatically deleted when the user closes the browser, which reduces the possibility of someone getting unauthorized access to your content. + Include the `Secure` attribute, so that the cookie is encrypted when a viewer includes it in a request. + When possible, use a custom policy and include the IP address of the viewer. + In the `CloudFront-Expires` attribute, specify the shortest reasonable expiration time based on how long you want users to have access to your content. ## When CloudFront checks expiration date and time in a signed cookie To determine whether a signed cookie is still valid, CloudFront checks the expiration date and time in the cookie at the time of the HTTP request. If a client begins to download a large file immediately before the expiration time, the download should complete even if the expiration time passes during the download. If the TCP connection drops and the client tries to restart the download after the expiration time passes, the download will fail. If a client uses Range GETs to get a file in smaller pieces, any GET request that occurs after the expiration time passes will fail. For more information about Range GETs, see [How CloudFront processes partial requests for an object (range GETs)](RangeGETs.md). ## Sample code and third-party tools The sample code for private content shows only how to create the signature for signed URLs. However, the process for creating a signature for a signed cookie is very similar, so much of the sample code is still relevant. For more information, see the following topics: + [Create a URL signature using Perl](CreateURLPerl.md) + [Create a URL signature using PHP](CreateURL_PHP.md) + [Create a URL signature using C\$1 and the .NET Framework](CreateSignatureInCSharp.md) + [Create a URL signature using Java](CFPrivateDistJavaDevelopment.md) # Set signed cookies using a canned policy To set a signed cookie by using a canned policy, complete the following steps. To create the signature, see [Create a signature for a signed cookie that uses a canned policy](#private-content-canned-policy-signature-cookies). **To set a signed cookie using a canned policy** 1. If you're using .NET or Java to create signed cookies, and if you haven't reformatted the private key for your key pair from the default .pem format to a format compatible with .NET or with Java, do so now. For more information, see [Reformat the private key (.NET and Java only)](private-content-trusted-signers.md#private-content-reformatting-private-key). 1. Program your application to send three `Set-Cookie` headers to approved viewers (or four, if you want to specify a hash algorithm). You need three `Set-Cookie` headers because each `Set-Cookie` header can contain only one name-value pair, and a CloudFront signed cookie requires three name-value pairs. The name-value pairs are: `CloudFront-Expires`, `CloudFront-Signature`, and `CloudFront-Key-Pair-Id`. You can optionally include a fourth name-value pair, `CloudFront-Hash-Algorithm`, to specify the hash algorithm used for the signature. The values must be present on the viewer before a user makes the first request for a file that you want to control access to. **Note** In general, we recommend that you exclude `Expires` and `Max-Age` attributes. Excluding the attributes causes the browser to delete the cookie when the user closes the browser, which reduces the possibility of someone getting unauthorized access to your content. For more information, see [Prevent misuse of signed cookies](private-content-signed-cookies.md#private-content-signed-cookie-misuse). **The names of cookie attributes are case-sensitive**. Line breaks are included only to make the attributes more readable. ``` Set-Cookie: CloudFront-Expires=date and time in Unix time format (in seconds) and Coordinated Universal Time (UTC); Domain=optional domain name; Path=/optional directory path; Secure; HttpOnly Set-Cookie: CloudFront-Signature=hashed and signed version of the policy statement; Domain=optional domain name; Path=/optional directory path; Secure; HttpOnly Set-Cookie: CloudFront-Key-Pair-Id=public key ID for the CloudFront public key whose corresponding private key you're using to generate the signature; Domain=optional domain name; Path=/optional directory path; Secure; HttpOnly Set-Cookie: CloudFront-Hash-Algorithm=SHA1 or SHA256; Domain=optional domain name; Path=/optional directory path; Secure; HttpOnly ``` **(Optional) `Domain`** The domain name for the requested file. If you don't specify a `Domain` attribute, the default value is the domain name in the URL, and it applies only to the specified domain name, not to subdomains. If you specify a `Domain` attribute, it also applies to subdomains. A leading dot in the domain name (for example, `Domain=.example.com`) is optional. In addition, if you specify a `Domain` attribute, the domain name in the URL and the value of the `Domain` attribute must match. You can specify the domain name that CloudFront assigned to your distribution, for example, d111111abcdef8.cloudfront.net, but you can't specify \$1.cloudfront.net for the domain name. If you want to use an alternate domain name such as example.com in URLs, you must add the alternate domain name to your distribution regardless of whether you specify the `Domain` attribute. For more information, see [Alternate domain names (CNAMEs)](DownloadDistValuesGeneral.md#DownloadDistValuesCNAME) in the topic [All distribution settings reference](distribution-web-values-specify.md). **(Optional) `Path`** The path for the requested file. If you don't specify a `Path` attribute, the default value is the path in the URL. **`Secure`** Requires that the viewer encrypt cookies before sending a request. We recommend that you send the `Set-Cookie` header over an HTTPS connection to ensure that the cookie attributes are protected from man-in-the-middle attacks. **`HttpOnly`** Defines how the browser (where supported) interacts with the cookie value. With `HttpOnly`, the cookie values are inaccessible to JavaScript. This precaution can help mitigate cross-site scripting (XSS) attacks. For more information, see [Using HTTP cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies). **`CloudFront-Expires`** Specify the expiration date and time in Unix time format (in seconds) and Coordinated Universal Time (UTC). For example, January 1, 2026 10:00 am UTC converts to 1767290400 in Unix time format. To use epoch time, specify a 64-bit integer for a date that's no later than `9223372036854775807` (Friday, April 11, 2262 at 23:47:16.854 UTC). For information about UTC, see *RFC 3339, Date and Time on the Internet: Timestamps*, [https://tools.ietf.org/html/rfc3339](https://tools.ietf.org/html/rfc3339). **`CloudFront-Signature`** A hashed, signed, and base64-encoded version of a JSON policy statement. For more information, see [Create a signature for a signed cookie that uses a canned policy](#private-content-canned-policy-signature-cookies). **`CloudFront-Key-Pair-Id`** The ID for a CloudFront public key, for example, `K2JCJMDEHXQW5F`. The public key ID tells CloudFront which public key to use to validate the signed URL. CloudFront compares the information in the signature with the information in the policy statement to verify that the URL has not been tampered with. This public key must belong to a key group that is a trusted signer in the distribution. For more information, see [Specify signers that can create signed URLs and signed cookies](private-content-trusted-signers.md). **`CloudFront-Hash-Algorithm`** (Optional) The hash algorithm used to create the signature. Supported values are `SHA1` and `SHA256`. If you don't include this cookie, CloudFront defaults to `SHA1`. The following example shows `Set-Cookie` headers for one signed cookie when you're using the domain name that is associated with your distribution in the URLs for your files: ``` Set-Cookie: CloudFront-Expires=1426500000; Domain=d111111abcdef8.cloudfront.net; Path=/images/*; Secure; HttpOnly Set-Cookie: CloudFront-Signature=yXrSIgyQoeE4FBI4eMKF6ho~CA8_; Domain=d111111abcdef8.cloudfront.net; Path=/images/*; Secure; HttpOnly Set-Cookie: CloudFront-Key-Pair-Id=K2JCJMDEHXQW5F; Domain=d111111abcdef8.cloudfront.net; Path=/images/*; Secure; HttpOnly Set-Cookie: CloudFront-Hash-Algorithm=SHA256; Domain=d111111abcdef8.cloudfront.net; Path=/images/*; Secure; HttpOnly ``` The following example shows `Set-Cookie` headers for one signed cookie when you're using the alternate domain name example.org in the URLs for your files: ``` Set-Cookie: CloudFront-Expires=1426500000; Domain=example.org; Path=/images/*; Secure; HttpOnly Set-Cookie: CloudFront-Signature=yXrSIgyQoeE4FBI4eMKF6ho~CA8_; Domain=example.org; Path=/images/*; Secure; HttpOnly Set-Cookie: CloudFront-Key-Pair-Id=K2JCJMDEHXQW5F; Domain=example.org; Path=/images/*; Secure; HttpOnly Set-Cookie: CloudFront-Hash-Algorithm=SHA256; Domain=example.org; Path=/images/*; Secure; HttpOnly ``` If you want to use an alternate domain name such as example.com in URLs, you must add the alternate domain name to your distribution regardless of whether you specify the `Domain` attribute. For more information, see [Alternate domain names (CNAMEs)](DownloadDistValuesGeneral.md#DownloadDistValuesCNAME) in the topic [All distribution settings reference](distribution-web-values-specify.md). ## Create a signature for a signed cookie that uses a canned policy To create the signature for a signed cookie that uses a canned policy, complete the following procedures. **Topics** + [ ### Create a policy statement for a signed cookie that uses a canned policy ](#private-content-canned-policy-statement-cookies) + [ ### Sign the policy statement to create a signature for a signed cookie that uses a canned policy ](#private-content-canned-policy-cookies-signing-policy-statement) ### Create a policy statement for a signed cookie that uses a canned policy When you set a signed cookie that uses a canned policy, the `CloudFront-Signature` attribute is a hashed and signed version of a policy statement. For signed cookies that use a canned policy, you don't include the policy statement in the `Set-Cookie` header, as you do for signed cookies that use a custom policy. To create the policy statement, complete the following steps. **To create a policy statement for a signed cookie that uses a canned policy** 1. Construct the policy statement using the following JSON format and using UTF-8 character encoding. Include all punctuation and other literal values exactly as specified. For information about the `Resource` and `DateLessThan` parameters, see [Values that you specify in the policy statement for a canned policy for signed cookies](#private-content-canned-policy-statement-cookies-values). ``` { "Statement": [ { "Resource": "base URL or stream name", "Condition": { "DateLessThan": { "AWS:EpochTime": ending date and time in Unix time format and UTC } } } ] } ``` 1. Remove all empty spaces (including tabs and newline characters) from the policy statement. You might have to include escape characters in the string in application code. #### Values that you specify in the policy statement for a canned policy for signed cookies When you create a policy statement for a canned policy, you specify the following values: **Resource** The base URL including your query strings, if any, for example: `https://d111111abcdef8.cloudfront.net/images/horizon.jpg?size=large&license=yes` You can specify only one value for `Resource`. Note the following: + **Protocol** – The value must begin with `http://` or `https://`. + **Query string parameters** – If you have no query string parameters, omit the question mark. + **Alternate domain names** – If you specify an alternate domain name (CNAME) in the URL, you must specify the alternate domain name when referencing the file in your webpage or application. Do not specify the Amazon S3 URL for the file. **DateLessThan** The expiration date and time for the URL in Unix time format (in seconds) and Coordinated Universal Time (UTC). Do not enclose the value in quotation marks. For example, March 16, 2015 10:00 am UTC converts to 1426500000 in Unix time format. This value must match the value of the `CloudFront-Expires` attribute in the `Set-Cookie` header. Do not enclose the value in quotation marks. For more information, see [When CloudFront checks expiration date and time in a signed cookie](private-content-signed-cookies.md#private-content-check-expiration-cookie). #### Example policy statement for a canned policy When you use the following example policy statement in a signed cookie, a user can access the file `https://d111111abcdef8.cloudfront.net/horizon.jpg` until March 16, 2015 10:00 am UTC: ``` { "Statement": [ { "Resource": "https://d111111abcdef8.cloudfront.net/horizon.jpg?size=large&license=yes", "Condition": { "DateLessThan": { "AWS:EpochTime": 1426500000 } } } ] } ``` ### Sign the policy statement to create a signature for a signed cookie that uses a canned policy To create the value for the `CloudFront-Signature` attribute in a `Set-Cookie` header, you hash and sign the policy statement that you created in [To create a policy statement for a signed cookie that uses a canned policy](#private-content-canned-policy-statement-cookies-procedure). For additional information and examples of how to hash, sign, and encode the policy statement, see the following topics: + [Linux commands and OpenSSL for base64 encoding and encryption](private-content-linux-openssl.md) + [Code examples for creating a signature for a signed URL](PrivateCFSignatureCodeAndExamples.md) **Note** The linked examples use SHA-1 by default. To use SHA-256 instead, replace `sha1` with `sha256` in the OpenSSL commands and include the `CloudFront-Hash-Algorithm` cookie with a value of `SHA256`. **To create a signature for a signed cookie using a canned policy** 1. Use the SHA-1 or SHA-256 hash function and RSA to hash and sign the policy statement that you created in the procedure [To create a policy statement for a signed cookie that uses a canned policy](#private-content-canned-policy-statement-cookies-procedure). Use the version of the policy statement that no longer includes empty spaces. If you use SHA-256, you must include the `CloudFront-Hash-Algorithm` cookie with a value of `SHA256`. For the private key that is required by the hash function, use a private key whose public key is in an active trusted key group for the distribution. **Note** The method that you use to hash and sign the policy statement depends on your programming language and platform. For sample code, see [Code examples for creating a signature for a signed URL](PrivateCFSignatureCodeAndExamples.md). 1. Remove empty spaces (including tabs and newline characters) from the hashed and signed string. 1. Base64-encode the string using MIME base64 encoding. For more information, see [Section 6.8, Base64 Content-Transfer-Encoding](https://tools.ietf.org/html/rfc2045#section-6.8) in *RFC 2045, MIME (Multipurpose Internet Mail Extensions) Part One: Format of Internet Message Bodies*. 1. Replace characters that are invalid in a URL query string with characters that are valid. The following table lists invalid and valid characters. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-setting-signed-cookie-canned-policy.html) 1. Include the resulting value in the `Set-Cookie` header for the `CloudFront-Signature` name-value pair. Then return to [To set a signed cookie using a canned policy](#private-content-setting-signed-cookie-canned-policy-procedure) add the `Set-Cookie` header for `CloudFront-Key-Pair-Id`. # Set signed cookies using a custom policy To set a signed cookie that uses a custom policy, complete the following steps. **To set a signed cookie using a custom policy** 1. If you're using .NET or Java to create signed URLs, and if you haven't reformatted the private key for your key pair from the default .pem format to a format compatible with .NET or with Java, do so now. For more information, see [Reformat the private key (.NET and Java only)](private-content-trusted-signers.md#private-content-reformatting-private-key). 1. Program your application to send three `Set-Cookie` headers to approved viewers (or four, if you want to specify a hash algorithm). You need three `Set-Cookie` headers because each `Set-Cookie` header can contain only one name-value pair, and a CloudFront signed cookie requires three name-value pairs. The name-value pairs are: `CloudFront-Policy`, `CloudFront-Signature`, and `CloudFront-Key-Pair-Id`. You can optionally include a fourth name-value pair, `CloudFront-Hash-Algorithm`, to specify the hash algorithm used for the signature. The values must be present on the viewer before a user makes the first request for a file that you want to control access to. **Note** In general, we recommend that you exclude `Expires` and `Max-Age` attributes. This causes the browser to delete the cookie when the user closes the browser, which reduces the possibility of someone getting unauthorized access to your content. For more information, see [Prevent misuse of signed cookies](private-content-signed-cookies.md#private-content-signed-cookie-misuse). **The names of cookie attributes are case-sensitive**. Line breaks are included only to make the attributes more readable. ``` Set-Cookie: CloudFront-Policy=base64 encoded version of the policy statement; Domain=optional domain name; Path=/optional directory path; Secure; HttpOnly Set-Cookie: CloudFront-Signature=hashed and signed version of the policy statement; Domain=optional domain name; Path=/optional directory path; Secure; HttpOnly Set-Cookie: CloudFront-Key-Pair-Id=public key ID for the CloudFront public key whose corresponding private key you're using to generate the signature; Domain=optional domain name; Path=/optional directory path; Secure; HttpOnly Set-Cookie: CloudFront-Hash-Algorithm=SHA1 or SHA256; Domain=optional domain name; Path=/optional directory path; Secure; HttpOnly ``` **(Optional) `Domain`** The domain name for the requested file. If you don't specify a `Domain` attribute, the default value is the domain name in the URL, and it applies only to the specified domain name, not to subdomains. If you specify a `Domain` attribute, it also applies to subdomains. A leading dot in the domain name (for example, `Domain=.example.com`) is optional. In addition, if you specify a `Domain` attribute, the domain name in the URL and the value of the `Domain` attribute must match. You can specify the domain name that CloudFront assigned to your distribution, for example, d111111abcdef8.cloudfront.net, but you can't specify \$1.cloudfront.net for the domain name. If you want to use an alternate domain name such as example.com in URLs, you must add the alternate domain name to your distribution regardless of whether you specify the `Domain` attribute. For more information, see [Alternate domain names (CNAMEs)](DownloadDistValuesGeneral.md#DownloadDistValuesCNAME) in the topic [All distribution settings reference](distribution-web-values-specify.md). **(Optional) `Path`** The path for the requested file. If you don't specify a `Path` attribute, the default value is the path in the URL. **`Secure`** Requires that the viewer encrypt cookies before sending a request. We recommend that you send the `Set-Cookie` header over an HTTPS connection to ensure that the cookie attributes are protected from man-in-the-middle attacks. **`HttpOnly`** Requires that the viewer send the cookie only in HTTP or HTTPS requests. **`CloudFront-Policy`** Your policy statement in JSON format, with empty spaces removed, then base64 encoded. For more information, see [Create a signature for a signed cookie that uses a custom policy](#private-content-custom-policy-signature-cookies). The policy statement controls the access that a signed cookie grants to a user. It includes the files that the user can access, an expiration date and time, an optional date and time that the URL becomes valid, and an optional IP address or range of IP addresses that are allowed to access the file. **`CloudFront-Signature`** A hashed, signed, and base64-encoded version of the JSON policy statement. For more information, see [Create a signature for a signed cookie that uses a custom policy](#private-content-custom-policy-signature-cookies). **`CloudFront-Key-Pair-Id`** The ID for a CloudFront public key, for example, `K2JCJMDEHXQW5F`. The public key ID tells CloudFront which public key to use to validate the signed URL. CloudFront compares the information in the signature with the information in the policy statement to verify that the URL has not been tampered with. This public key must belong to a key group that is a trusted signer in the distribution. For more information, see [Specify signers that can create signed URLs and signed cookies](private-content-trusted-signers.md). **`CloudFront-Hash-Algorithm`** (Optional) The hash algorithm used to create the signature. Supported values are `SHA1` and `SHA256`. If you don't include this cookie, CloudFront defaults to `SHA1`. ## Example `Set-Cookie` headers for custom policies See the following examples of `Set-Cookie` header pairs. If you want to use an alternate domain name such as example.org in URLs, you must add the alternate domain name to your distribution regardless of whether you specify the `Domain` attribute. For more information, see [Alternate domain names (CNAMEs)](DownloadDistValuesGeneral.md#DownloadDistValuesCNAME) in the topic [All distribution settings reference](distribution-web-values-specify.md). **Example 1** You can use the `Set-Cookie` headers for one signed cookie when you're using the domain name that is associated with your distribution in the URLs for your files. ``` Set-Cookie: CloudFront-Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cDovL2QxMTExMTFhYmNkZWY4LmNsb3VkZnJvbnQubmV0L2dhbWVfZG93bmxvYWQuemlwIiwiQ29uZGl0aW9uIjp7IklwQWRkcmVzcyI6eyJBV1M6U291cmNlSXAiOiIxOTIuMC4yLjAvMjQifSwiRGF0ZUxlc3NUaGFuIjp7IkFXUzpFcG9jaFRpbWUiOjE0MjY1MDAwMDB9fX1dfQ__; Domain=d111111abcdef8.cloudfront.net; Path=/; Secure; HttpOnly Set-Cookie: CloudFront-Signature=dtKhpJ3aUYxqDIwepczPiDb9NXQ_; Domain=d111111abcdef8.cloudfront.net; Path=/; Secure; HttpOnly Set-Cookie: CloudFront-Key-Pair-Id=K2JCJMDEHXQW5F; Domain=d111111abcdef8.cloudfront.net; Path=/; Secure; HttpOnly Set-Cookie: CloudFront-Hash-Algorithm=SHA256; Domain=d111111abcdef8.cloudfront.net; Path=/; Secure; HttpOnly ``` **Example 2** You can use the `Set-Cookie` headers for one signed cookie when you're using an alternate domain name (example.org) in the URLs for your files. ``` Set-Cookie: CloudFront-Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cDovL2QxMTExMTFhYmNkZWY4LmNsb3VkZnJvbnQubmV0L2dhbWVfZG93bmxvYWQuemlwIiwiQ29uZGl0aW9uIjp7IklwQWRkcmVzcyI6eyJBV1M6U291cmNlSXAiOiIxOTIuMC4yLjAvMjQifSwiRGF0ZUxlc3NUaGFuIjp7IkFXUzpFcG9jaFRpbWUiOjE0MjY1MDAwMDB9fX1dfQ__; Domain=example.org; Path=/; Secure; HttpOnly Set-Cookie: CloudFront-Signature=dtKhpJ3aUYxqDIwepczPiDb9NXQ_; Domain=example.org; Path=/; Secure; HttpOnly Set-Cookie: CloudFront-Key-Pair-Id=K2JCJMDEHXQW5F; Domain=example.org; Path=/; Secure; HttpOnly Set-Cookie: CloudFront-Hash-Algorithm=SHA256; Domain=example.org; Path=/; Secure; HttpOnly ``` **Example 3** You can use the `Set-Cookie` header pairs for a signed request when you're using the domain name that is associated with your distribution in the URLs for your files. ``` Set-Cookie: CloudFront-Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cDovL2QxMTExMTFhYmNkZWY4LmNsb3VkZnJvbnQubmV0L2dhbWVfZG93bmxvYWQuemlwIiwiQ29uZGl0aW9uIjp7IklwQWRkcmVzcyI6eyJBV1M6U291cmNlSXAiOiIxOTIuMC4yLjAvMjQifSwiRGF0ZUxlc3NUaGFuIjp7IkFXUzpFcG9jaFRpbWUiOjE0MjY1MDAwMDB9fX1dfQ__; Domain=d111111abcdef8.cloudfront.net; Path=/; Secure; HttpOnly Set-Cookie: CloudFront-Signature=dtKhpJ3aUYxqDIwepczPiDb9NXQ_; Domain=d111111abcdef8.cloudfront.net; Path=/; Secure; HttpOnly Set-Cookie: CloudFront-Key-Pair-Id=K2JCJMDEHXQW5F; Domain=dd111111abcdef8.cloudfront.net; Path=/; Secure; HttpOnly Set-Cookie: CloudFront-Hash-Algorithm=SHA256; Domain=d111111abcdef8.cloudfront.net; Path=/; Secure; HttpOnly ``` **Example 4** You can use the `Set-Cookie` header pairs for one signed request when you're using an alternate domain name (example.org) that is associated with your distribution in the URLs for your files. ``` Set-Cookie: CloudFront-Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cDovL2QxMTExMTFhYmNkZWY4LmNsb3VkZnJvbnQubmV0L2dhbWVfZG93bmxvYWQuemlwIiwiQ29uZGl0aW9uIjp7IklwQWRkcmVzcyI6eyJBV1M6U291cmNlSXAiOiIxOTIuMC4yLjAvMjQifSwiRGF0ZUxlc3NUaGFuIjp7IkFXUzpFcG9jaFRpbWUiOjE0MjY1MDAwMDB9fX1dfQ__; Domain=example.org; Path=/; Secure; HttpOnly Set-Cookie: CloudFront-Signature=dtKhpJ3aUYxqDIwepczPiDb9NXQ_; Domain=example.org; Path=/; Secure; HttpOnly Set-Cookie: CloudFront-Key-Pair-Id=K2JCJMDEHXQW5F; Domain=example.org; Path=/; Secure; HttpOnly Set-Cookie: CloudFront-Hash-Algorithm=SHA256; Domain=example.org; Path=/; Secure; HttpOnly ``` ## Create a policy statement for a signed cookie that uses a custom policy To create a policy statement for a custom policy, complete the following steps. For several example policy statements that control access to files in a variety of ways, see [Example policy statements for a signed cookie that uses a custom policy](#private-content-custom-policy-statement-signed-cookies-examples). **To create the policy statement for a signed cookie that uses a custom policy** 1. Construct the policy statement using the following JSON format. ``` { "Statement": [ { "Resource": "URL of the file", "Condition": { "DateLessThan": { "AWS:EpochTime":required ending date and time in Unix time format and UTC }, "DateGreaterThan": { "AWS:EpochTime":optional beginning date and time in Unix time format and UTC }, "IpAddress": { "AWS:SourceIp": "optional IP address" } } } ] } ``` Note the following: + You can include only one statement. + Use UTF-8 character encoding. + Include all punctuation and parameter names exactly as specified. Abbreviations for parameter names are not accepted. + The order of the parameters in the `Condition` section doesn't matter. + For information about the values for `Resource`, `DateLessThan`, `DateGreaterThan`, and `IpAddress`, see [Values that you specify in the policy statement for a custom policy for signed cookies](#private-content-custom-policy-statement-cookies-values). 1. Remove all empty spaces (including tabs and newline characters) from the policy statement. You might have to include escape characters in the string in application code. 1. Base64-encode the policy statement using MIME base64 encoding. For more information, see [Section 6.8, Base64 Content-Transfer-Encoding](https://tools.ietf.org/html/rfc2045#section-6.8) in *RFC 2045, MIME (Multipurpose Internet Mail Extensions) Part One: Format of Internet Message Bodies*. 1. Replace characters that are invalid in a URL query string with characters that are valid. The following table lists invalid and valid characters. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-setting-signed-cookie-custom-policy.html) 1. Include the resulting value in your `Set-Cookie` header after `CloudFront-Policy=`. 1. Create a signature for the `Set-Cookie` header for `CloudFront-Signature` by hashing, signing, and base64-encoding the policy statement. For more information, see [Create a signature for a signed cookie that uses a custom policy](#private-content-custom-policy-signature-cookies). ### Values that you specify in the policy statement for a custom policy for signed cookies When you create a policy statement for a custom policy, you specify the following values. **Resource** The base URL including your query strings, if any: `https://d111111abcdef8.cloudfront.net/images/horizon.jpg?size=large&license=yes` If you omit the `Resource` parameter, users can access all of the files associated with any distribution that is associated with the key pair that you use to create the signed URL. You can specify only one value for `Resource`. Note the following: + **Protocol** – The value must begin with `http://` or `https://`. + **Query string parameters** – If you have no query string parameters, omit the question mark. + **Wildcards** – You can use the wildcard character that matches zero or more characters (\$1) or the wild-card character that matches exactly one character (?) anywhere in the string. For example, the value: `https://d111111abcdef8.cloudfront.net/*game_download.zip*` would include (for example) the following files: + `https://d111111abcdef8.cloudfront.net/game_download.zip` + `https://d111111abcdef8.cloudfront.net/example_game_download.zip?license=yes` + `https://d111111abcdef8.cloudfront.net/test_game_download.zip?license=temp` + **Alternate domain names** – If you specify an alternate domain name (CNAME) in the URL, you must specify the alternate domain name when referencing the file in your webpage or application. Do not specify the Amazon S3 URL for the file. **DateLessThan** The expiration date and time for the URL in Unix time format (in seconds) and Coordinated Universal Time (UTC). Do not enclose the value in quotation marks. For example, March 16, 2015 10:00 am UTC converts to 1426500000 in Unix time format. For more information, see [When CloudFront checks expiration date and time in a signed cookie](private-content-signed-cookies.md#private-content-check-expiration-cookie). **DateGreaterThan (Optional)** An optional start date and time for the URL in Unix time format (in seconds) and Coordinated Universal Time (UTC). Users are not allowed to access the file on or before the specified date and time. Do not enclose the value in quotation marks. **IpAddress (Optional)** The IP address of the client making the GET request. Note the following: + To allow any IP address to access the file, omit the `IpAddress` parameter. + You can specify either one IP address or one IP address range. For example, you can't set the policy to allow access if the client's IP address is in one of two separate ranges. + To allow access from a single IP address, you specify: `"`*IPv4 IP address*`/32"` + You must specify IP address ranges in standard IPv4 CIDR format (for example, `192.0.2.0/24`). For more information, go to *RFC 4632, Classless Inter-domain Routing (CIDR): The Internet Address Assignment and Aggregation Plan*, [https://tools.ietf.org/html/rfc4632](https://tools.ietf.org/html/rfc4632). **Important** IP addresses in IPv6 format, such as 2001:0db8:85a3::8a2e:0370:7334, are not supported. If you're using a custom policy that includes `IpAddress`, do not enable IPv6 for the distribution. If you want to restrict access to some content by IP address and support IPv6 requests for other content, you can create two distributions. For more information, see [Enable IPv6 (viewer requests)](DownloadDistValuesGeneral.md#DownloadDistValuesEnableIPv6) in the topic [All distribution settings reference](distribution-web-values-specify.md). ## Example policy statements for a signed cookie that uses a custom policy The following example policy statements show how to control access to a specific file, all of the files in a directory, or all of the files associated with a key pair ID. The examples also show how to control access from an individual IP address or a range of IP addresses, and how to prevent users from using the signed cookie after a specified date and time. If you copy and paste any of these examples, remove any empty spaces (including tabs and newline characters), replace the values with your own values, and include a newline character after the closing brace ( \$1 ). For more information, see [Values that you specify in the policy statement for a custom policy for signed cookies](#private-content-custom-policy-statement-cookies-values). **Topics** + [ ### Example policy statement: Access one file from a range of IP addresses ](#private-content-custom-policy-statement-signed-cookies-example-one-object) + [ ### Example policy statement: Access all files in a directory from a range of IP addresses ](#private-content-custom-policy-statement-signed-cookies-example-all-objects) + [ ### Example policy statement: Access all files associated with a key pair ID from one IP address ](#private-content-custom-policy-statement-signed-cookies-example-one-ip) ### Example policy statement: Access one file from a range of IP addresses The following example custom policy in a signed cookie specifies that a user can access the file `https://d111111abcdef8.cloudfront.net/game_download.zip` from IP addresses in the range `192.0.2.0/24` until January 1, 2023 10:00 am UTC: ``` { "Statement": [ { "Resource": "https://d111111abcdef8.cloudfront.net/game_download.zip", "Condition": { "IpAddress": { "AWS:SourceIp": "192.0.2.0/24" }, "DateLessThan": { "AWS:EpochTime": 1767290400 } } } ] } ``` ### Example policy statement: Access all files in a directory from a range of IP addresses The following example custom policy allows you to create signed cookies for any file in the `training` directory, as indicated by the \$1 wildcard character in the `Resource` parameter. Users can access the file from an IP address in the range `192.0.2.0/24` until January 1, 2013 10:00 am UTC: ``` { "Statement": [ { "Resource": "https://d111111abcdef8.cloudfront.net/training/*", "Condition": { "IpAddress": { "AWS:SourceIp": "192.0.2.0/24" }, "DateLessThan": { "AWS:EpochTime": 1767290400 } } } ] } ``` Each signed cookie in which you use this policy includes a base URL that identifies a specific file, for example: `https://d111111abcdef8.cloudfront.net/training/orientation.pdf` ### Example policy statement: Access all files associated with a key pair ID from one IP address The following sample custom policy allows you to set signed cookies for any file associated with any distribution, as indicated by the \$1 wildcard character in the `Resource` parameter. The user must use the IP address `192.0.2.10/32`. (The value `192.0.2.10/32` in CIDR notation refers to a single IP address, `192.0.2.10`.) The files are available only from January 1, 2013 10:00 am UTC until January 2, 2013 10:00 am UTC: ``` { "Statement": [ { "Resource": "https://*", "Condition": { "IpAddress": { "AWS:SourceIp": "192.0.2.10/32" }, "DateGreaterThan": { "AWS:EpochTime": 1767290400 }, "DateLessThan": { "AWS:EpochTime": 1767376800 } } } ] } ``` Each signed cookie in which you use this policy includes a base URL that identifies a specific file in a specific CloudFront distribution, for example: `https://d111111abcdef8.cloudfront.net/training/orientation.pdf` The signed cookie also includes a key pair ID, which must be associated with a trusted key group in the distribution (d111111abcdef8.cloudfront.net) that you specify in the base URL. ## Create a signature for a signed cookie that uses a custom policy The signature for a signed cookie that uses a custom policy is a hashed, signed, and base64-encoded version of the policy statement. For additional information and examples of how to hash, sign, and encode the policy statement, see: + [Linux commands and OpenSSL for base64 encoding and encryption](private-content-linux-openssl.md) + [Code examples for creating a signature for a signed URL](PrivateCFSignatureCodeAndExamples.md) **Note** The linked examples use SHA-1 by default. To use SHA-256 instead, replace `sha1` with `sha256` in the OpenSSL commands and include the `CloudFront-Hash-Algorithm` cookie with a value of `SHA256`. **To create a signature for a signed cookie by using a custom policy** 1. Use the SHA-1 or SHA-256 hash function and RSA to hash and sign the JSON policy statement that you created in the procedure [To create the policy statement for a signed URL that uses a custom policy](private-content-creating-signed-url-custom-policy.md#private-content-custom-policy-creating-policy-procedure). Use the version of the policy statement that no longer includes empty spaces but that has not yet been base64-encoded. If you use SHA-256, you must include the `CloudFront-Hash-Algorithm` cookie with a value of `SHA256`. For the private key that is required by the hash function, use a private key whose public key is in an active trusted key group for the distribution. **Note** The method that you use to hash and sign the policy statement depends on your programming language and platform. For sample code, see [Code examples for creating a signature for a signed URL](PrivateCFSignatureCodeAndExamples.md). 1. Remove empty spaces (including tabs and newline characters) from the hashed and signed string. 1. Base64-encode the string using MIME base64 encoding. For more information, see [Section 6.8, Base64 Content-Transfer-Encoding](https://tools.ietf.org/html/rfc2045#section-6.8) in *RFC 2045, MIME (Multipurpose Internet Mail Extensions) Part One: Format of Internet Message Bodies*. 1. Replace characters that are invalid in a URL query string with characters that are valid. The following table lists invalid and valid characters. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-setting-signed-cookie-custom-policy.html) 1. Include the resulting value in the `Set-Cookie` header for the `CloudFront-Signature=` name-value pair, and return to [To set a signed cookie using a custom policy](#private-content-setting-signed-cookie-custom-policy-procedure) to add the `Set-Cookie` header for `CloudFront-Key-Pair-Id`. # Create signed cookies using PHP The following code example is similar to the example in the [Create a URL signature using PHP](CreateURL_PHP.md) in that it creates a link to a video. However, instead of signing the URL in the code, this example signs the cookies with the `create_signed_cookies()` function. The client-side player uses the cookies to authenticate each request to the CloudFront distribution. This approach is useful to stream content, such as HTTP Live Streaming (HLS) or Dynamic Adaptive Streaming over HTTP (DASH), where the client needs to make multiple requests to retrieve the manifest, segments, and related playback assets. By using signed cookies, the client can authenticate each request without needing to generate a new signed URL for each segment. **Note** Creating a URL signature is just one part of the process of serving private content using signed cookies. For more information, see [Use signed cookies](private-content-signed-cookies.md). **Topics** + [ ## Create the RSA SHA-1 or SHA-256 signature ](#create-rsa-sha-1signature-cookies) + [ ## Create the signed cookies ](#create-the-signed-cookie) + [ ## Full code ](#full-code-signed-cookies) The following sections breaks down the code example into individual parts. You can find the complete [code sample](#full-code-signed-cookies) below. ## Create the RSA SHA-1 or SHA-256 signature This code example does the following: 1. The function `rsa_sha1_sign` hashes and signs the policy statement using SHA-1. To use SHA-256 instead, use the rsa\$1sha256\$1sign function shown below. The arguments required are a policy statement and the private key that corresponds with a public key that’s in a trusted key group for your distribution. 1. Next, the `url_safe_base64_encode` function creates a URL-safe version of the signature. ``` function rsa_sha1_sign($policy, $private_key_filename) { $signature = ""; $fp = fopen($private_key_filename, "r"); $priv_key = fread($fp, 8192); fclose($fp); $pkeyid = openssl_get_privatekey($priv_key); openssl_sign($policy, $signature, $pkeyid); openssl_free_key($pkeyid); return $signature; } function url_safe_base64_encode($value) { $encoded = base64_encode($value); return str_replace( array('+', '=', '/'), array('-', '_', '~'), $encoded); } ``` The following function uses SHA-256 instead of SHA-1: ``` function rsa_sha256_sign($policy, $private_key_filename) { $signature = ""; $fp = fopen($private_key_filename, "r"); $priv_key = fread($fp, 8192); fclose($fp); $pkeyid = openssl_get_privatekey($priv_key); openssl_sign($policy, $signature, $pkeyid, OPENSSL_ALGO_SHA256); openssl_free_key($pkeyid); return $signature; } ``` The `rsa_sha256_sign` function is the same as `rsa_sha1_sign`, except that it passes `OPENSSL_ALGO_SHA256` to `openssl_sign`. When you use SHA-256, include the `CloudFront-Hash-Algorithm` cookie with a value of `SHA256`. ## Create the signed cookies The following code constructs a creates the signed cookies, using the following cookie attributes: `CloudFront-Expires`, `CloudFront-Signature`, `CloudFront-Key-Pair-Id` and `CloudFront-Hash-Algorithm`. The code uses a custom policy. ``` function create_signed_cookies($resource, $private_key_filename, $key_pair_id, $expires, $client_ip = null, $hash_algorithm = 'SHA1') { $policy = array( 'Statement' => array( array( 'Resource' => $resource, 'Condition' => array( 'DateLessThan' => array('AWS:EpochTime' => $expires) ) ) ) ); if ($client_ip) { $policy['Statement'][0]['Condition']['IpAddress'] = array('AWS:SourceIp' => $client_ip . '/32'); } $policy = json_encode($policy); $encoded_policy = url_safe_base64_encode($policy); if ($hash_algorithm === 'SHA256') { $signature = rsa_sha256_sign($policy, $private_key_filename); } else { $signature = rsa_sha1_sign($policy, $private_key_filename); } $encoded_signature = url_safe_base64_encode($signature); $cookies = array( 'CloudFront-Policy' => $encoded_policy, 'CloudFront-Signature' => $encoded_signature, 'CloudFront-Key-Pair-Id' => $key_pair_id ); if ($hash_algorithm === 'SHA256') { $cookies['CloudFront-Hash-Algorithm'] = 'SHA256'; } return $cookies; } ``` For more information, see [Set signed cookies using a custom policy](private-content-setting-signed-cookie-custom-policy.md). ## Full code The following example code provides a complete demonstration of creating CloudFront signed cookies with PHP. You can download the full example from the [demo-php.zip](samples/demo-php.zip) file. In the following example, you can modify the `$policy Condition` element to allow both IPv4 and IPv6 address ranges. For an example, see [Using IPv6 addresses in IAM policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ipv6-access.html#ipv6-access-iam) in the *Amazon Simple Storage Service User Guide*. ``` array( array( 'Resource' => $resource, 'Condition' => array( 'DateLessThan' => array('AWS:EpochTime' => $expires) ) ) ) ); if ($client_ip) { $policy['Statement'][0]['Condition']['IpAddress'] = array('AWS:SourceIp' => $client_ip . '/32'); } $policy = json_encode($policy); $encoded_policy = url_safe_base64_encode($policy); if ($hash_algorithm === 'SHA256') { $signature = rsa_sha256_sign($policy, $private_key_filename); } else { $signature = rsa_sha1_sign($policy, $private_key_filename); } $encoded_signature = url_safe_base64_encode($signature); $cookies = array( 'CloudFront-Policy' => $encoded_policy, 'CloudFront-Signature' => $encoded_signature, 'CloudFront-Key-Pair-Id' => $key_pair_id ); if ($hash_algorithm === 'SHA256') { $cookies['CloudFront-Hash-Algorithm'] = 'SHA256'; } return $cookies; } $private_key_filename = '/home/test/secure/example-priv-key.pem'; $key_pair_id = 'K2JCJMDEHXQW5F'; $base_url = 'https://d1234.cloudfront.net'; $expires = time() + 3600; // 1 hour from now // Get the viewer real IP from the x-forward-for header as $_SERVER['REMOTE_ADDR'] will return viewer facing IP. An alternative option is to use CloudFront-Viewer-Address header. Note that this header is a trusted CloudFront immutable header. Example format: IP:PORT ("CloudFront-Viewer-Address": "1.2.3.4:12345") $client_ip = $_SERVER['HTTP_X_FORWARDED_FOR']; // For HLS manifest and segments (using wildcard) $hls_resource = $base_url . '/sign/*'; $signed_cookies = create_signed_cookies($hls_resource, $private_key_filename, $key_pair_id, $expires, $client_ip, 'SHA256'); // Set the cookies $cookie_domain = parse_url($base_url, PHP_URL_HOST); foreach ($signed_cookies as $name => $value) { setcookie($name, $value, $expires, '/', $cookie_domain, true, true); } ?> CloudFront Signed HLS Stream with Cookies

Amazon CloudFront Signed HLS Stream with Cookies

Expires at only viewable by IP

``` Instead of using signed cookies, you can use signed URLs. For more information, see [Create a URL signature using PHP](CreateURL_PHP.md). # Linux commands and OpenSSL for base64 encoding and encryption You can use the following Linux command-line command and OpenSSL to hash and sign the policy statement, base64-encode the signature, and replace characters that are not valid in URL query string parameters with characters that are valid. For information about OpenSSL, go to [https://www.openssl.org](https://www.openssl.org). SHA-1 (default): ``` cat policy | tr -d "\n" | tr -d " \t\n\r" | openssl sha1 -sign private_key.pem | openssl base64 -A | tr -- '+=/' '-_~' ``` SHA-256: ``` cat policy | tr -d "\n" | tr -d " \t\n\r" | openssl sha256 -sign private_key.pem | openssl base64 -A | tr -- '+=/' '-_~' ``` In the preceding command: + `cat` reads the `policy` file. + `tr -d "\n" | tr -d " \t\n\r"` removes the empty spaces and newline character that were added by `cat`. + OpenSSL hashes the file using SHA-1 (or SHA-256) and signs it using the private key file `private_key.pem`. The private key signature can be either RSA 2048 or ECDSA 256. If you use SHA-256, include the `Hash-Algorithm=SHA256` query parameter in the signed URL, or the `CloudFront-Hash-Algorithm=SHA256` cookie for signed cookies. + OpenSSL base64-encodes the hashed and signed policy statement. + `tr` replaces characters that are not valid in URL query string parameters with characters that are valid. For more code examples that demonstrate creating a signature, see [Code examples for creating a signature for a signed URL](PrivateCFSignatureCodeAndExamples.md). # Code examples for creating a signature for a signed URL This section includes downloadable application examples that demonstrate how to create signatures for signed URLs. Examples are available in Perl, PHP, C\$1, and Java. You can use any of the examples to create signed URLs. The Perl script runs on Linux and macOS platforms. The PHP example will work on any server that runs PHP. The C\$1 example uses the .NET Framework. The examples in this section use SHA-1 to hash and sign the policy statement. You can also use SHA-256. To use SHA-256, update the hash algorithm in the signing function (for example, replace `sha1` with `sha256` in OpenSSL calls, or use the equivalent SHA-256 constant in your language's cryptographic library). When you use SHA-256, include the `Hash-Algorithm=SHA256` query parameter in the signed URL. For example code in JavaScript (Node.js), see [Creating Amazon CloudFront Signed URLs in Node.js](https://aws.amazon.com/blogs/developer/creating-amazon-cloudfront-signed-urls-in-node-js/) on the AWS Developer Blog. For example code in Python, see [Generate a signed URL for Amazon CloudFront](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/cloudfront.html#examples) in the *AWS SDK for Python (Boto3) API Reference* and [this example code](https://github.com/boto/boto3/blob/develop/boto3/examples/cloudfront.rst) in the Boto3 GitHub repository. **Topics** + [ # Create a URL signature using Perl ](CreateURLPerl.md) + [ # Create a URL signature using PHP ](CreateURL_PHP.md) + [ # Create a URL signature using C\$1 and the .NET Framework ](CreateSignatureInCSharp.md) + [ # Create a URL signature using Java ](CFPrivateDistJavaDevelopment.md) # Create a URL signature using Perl This section includes a Perl script for Linux/Mac platforms that you can use to create the signature for private content. To create the signature, run the script with command line arguments that specify the CloudFront URL, the path to the private key of the signer, the key ID, and an expiration date for the URL. The tool can also decode signed URLs. **Notes** Creating a URL signature is just one part of the process of serving private content using a signed URL. For more information about the end-to-end process, see [Use signed URLs](private-content-signed-urls.md). In the signing command, note that `sha1` can be replaced with `sha256` in the `openssl dgst` call. **Topics** + [ ## Source for the Perl script to create a signed URL ](#CreateURLPerlScriptSource) ## Source for the Perl script to create a signed URL The following Perl source code can be used to create a signed URL for CloudFront. Comments in the code include information about the command line switches and the features of the tool. ``` #!/usr/bin/perl -w # Copyright 2008 Amazon Technologies, Inc. Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. You may obtain a copy of the License at: # # https://aws.amazon.com/apache2.0 # # This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and limitations under the License. =head1 cfsign.pl cfsign.pl - A tool to generate and verify Amazon CloudFront signed URLs =head1 SYNOPSIS This script uses an existing RSA key pair to sign and verify Amazon CloudFront signed URLs View the script source for details as to which CPAN packages are required beforehand. For help, try: cfsign.pl --help URL signing examples: cfsign.pl --action encode --url https://images.my-website.com/gallery1.zip --policy sample_policy.json --private-key privkey.pem --key-pair-id mykey cfsign.pl --action encode --url https://images.my-website.com/gallery1.zip --expires 1257439868 --private-key privkey.pem --key-pair-id mykey URL decode example: cfsign.pl --action decode --url "http//mydist.cloudfront.net/?Signature=AGO-PgxkYo99MkJFHvjfGXjG1QDEXeaDb4Qtzmy85wqyJjK7eKojQWa4BCRcow__&Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cDovLypicmFkbS5qcGciLCJDb25kaXRpb24iOnsiSXBBZGRyZXNzIjp7IkFXUzpTb3VyY2VJcCI6IjEwLjUyLjE3LjkvMCJ9LCJEYXRlR3JlYXRlclRoYW4iOnsiQVdTOkVwb2NoVGltZSI6MTI1MjUyMDgzMH19fV19Cg__&Key-Pair-Id=mykey" To generate an RSA key pair, you can use openssl and the following commands: # Generate a 2048 bit key pair openssl genrsa -out private-key.pem 2048 openssl rsa -in private-key.pem -pubout -out public-key.pem =head1 OPTIONS =over 8 =item B<--help> Print a help message and exits. =item B<--action> [action] The action to execute. action can be one of: encode - Generate a signed URL (using a canned policy or a user policy) decode - Decode a signed URL =item B<--url> The URL to en/decode =item B<--stream> The stream to en/decode =item B<--private-key> The path to your private key. =item B<--key-pair-id> The key pair identifier. =item B<--policy> The CloudFront policy document. =item B<--expires> The Unix epoch time when the URL is to expire. If both this option and the --policy option are specified, --policy will be used. Otherwise, this option alone will use a canned policy. =back =cut use strict; use warnings; # you might need to use CPAN to get these modules. # run perl -MCPAN -e "install " to get them. # The openssl command line will also need to be in your $PATH. use File::Temp qw/tempfile/; use File::Slurp; use Getopt::Long; use IPC::Open2; use MIME::Base64 qw(encode_base64 decode_base64); use Pod::Usage; use URI; my $CANNED_POLICY = '{"Statement":[{"Resource":"","Condition":{"DateLessThan":{"AWS:EpochTime":}}}]}'; my $POLICY_PARAM = "Policy"; my $EXPIRES_PARAM = "Expires"; my $SIGNATURE_PARAM = "Signature"; my $KEY_PAIR_ID_PARAM = "Key-Pair-Id"; my $verbose = 0; my $policy_filename = ""; my $expires_epoch = 0; my $action = ""; my $help = 0; my $key_pair_id = ""; my $url = ""; my $stream = ""; my $private_key_filename = ""; my $result = GetOptions("action=s" => \$action, "policy=s" => \$policy_filename, "expires=i" => \$expires_epoch, "private-key=s" => \$private_key_filename, "key-pair-id=s" => \$key_pair_id, "verbose" => \$verbose, "help" => \$help, "url=s" => \$url, "stream=s" => \$stream, ); if ($help or !$result) { pod2usage(1); exit; } if ($url eq "" and $stream eq "") { print STDERR "Must include a stream or a URL to encode or decode with the --stream or --url option\n"; exit; } if ($url ne "" and $stream ne "") { print STDERR "Only one of --url and --stream may be specified\n"; exit; } if ($url ne "" and !is_url_valid($url)) { exit; } if ($stream ne "") { exit unless is_stream_valid($stream); # The signing mechanism is identical, so from here on just pretend we're # dealing with a URL $url = $stream; } if ($action eq "encode") { # The encode action will generate a private content URL given a base URL, # a policy file (or an expires timestamp) and a key pair id parameter my $private_key; my $public_key; my $public_key_file; my $policy; if ($policy_filename eq "") { if ($expires_epoch == 0) { print STDERR "Must include policy filename with --policy argument or an expires" . "time using --expires\n"; } $policy = $CANNED_POLICY; $policy =~ s//$expires_epoch/g; $policy =~ s//$url/g; } else { if (! -e $policy_filename) { print STDERR "Policy file $policy_filename does not exist\n"; exit; } $expires_epoch = 0; # ignore if set $policy = read_file($policy_filename); } if ($private_key_filename eq "") { print STDERR "You must specific the path to your private key file with --private-key\n"; exit; } if (! -e $private_key_filename) { print STDERR "Private key file $private_key_filename does not exist\n"; exit; } if ($key_pair_id eq "") { print STDERR "You must specify a key pair id with --key-pair-id\n"; exit; } my $encoded_policy = url_safe_base64_encode($policy); my $signature = rsa_sha1_sign($policy, $private_key_filename); my $encoded_signature = url_safe_base64_encode($signature); my $generated_url = create_url($url, $encoded_policy, $encoded_signature, $key_pair_id, $expires_epoch); if ($stream ne "") { print "Encoded stream (for use within a swf):\n" . $generated_url . "\n"; print "Encoded and escaped stream (for use on a webpage):\n" . escape_url_for_webpage($generated_url) . "\n"; } else { print "Encoded URL:\n" . $generated_url . "\n"; } } elsif ($action eq "decode") { my $decoded = decode_url($url); if (!$decoded) { print STDERR "Improperly formed URL\n"; exit; } print_decoded_url($decoded); } else { # No action specified, print help. But only if this is run as a program (caller will be empty) pod2usage(1) unless caller(); } # Decode a private content URL into its component parts sub decode_url { my $url = shift; if ($url =~ /(.*)\?(.*)/) { my $base_url = $1; my $params = $2; my @unparsed_params = split(/&/, $params); my %params = (); foreach my $param (@unparsed_params) { my ($key, $val) = split(/=/, $param); $params{$key} = $val; } my $encoded_signature = ""; if (exists $params{$SIGNATURE_PARAM}) { $encoded_signature = $params{"Signature"}; } else { print STDERR "Missing Signature URL parameter\n"; return 0; } my $encoded_policy = ""; if (exists $params{$POLICY_PARAM}) { $encoded_policy = $params{$POLICY_PARAM}; } else { if (!exists $params{$EXPIRES_PARAM}) { print STDERR "Either the Policy or Expires URL parameter needs to be specified\n"; return 0; } my $expires = $params{$EXPIRES_PARAM}; my $policy = $CANNED_POLICY; $policy =~ s//$expires/g; my $url_without_cf_params = $url; $url_without_cf_params =~ s/$SIGNATURE_PARAM=[^&]*&?//g; $url_without_cf_params =~ s/$POLICY_PARAM=[^&]*&?//g; $url_without_cf_params =~ s/$EXPIRES_PARAM=[^&]*&?//g; $url_without_cf_params =~ s/$KEY_PAIR_ID_PARAM=[^&]*&?//g; if ($url_without_cf_params =~ /(.*)\?$/) { $url_without_cf_params = $1; } $policy =~ s//$url_without_cf_params/g; $encoded_policy = url_safe_base64_encode($policy); } my $key = ""; if (exists $params{$KEY_PAIR_ID_PARAM}) { $key = $params{$KEY_PAIR_ID_PARAM}; } else { print STDERR "Missing $KEY_PAIR_ID_PARAM parameter\n"; return 0; } my $policy = url_safe_base64_decode($encoded_policy); my %ret = (); $ret{"base_url"} = $base_url; $ret{"policy"} = $policy; $ret{"key"} = $key; return \%ret; } else { return 0; } } # Print a decoded URL out sub print_decoded_url { my $decoded = shift; print "Base URL: \n" . $decoded->{"base_url"} . "\n"; print "Policy: \n" . $decoded->{"policy"} . "\n"; print "Key: \n" . $decoded->{"key"} . "\n"; } # Encode a string with base 64 encoding and replace some invalid URL characters sub url_safe_base64_encode { my ($value) = @_; my $result = encode_base64($value); $result =~ tr|+=/|-_~|; return $result; } # Decode a string with base 64 encoding. URL-decode the string first # followed by reversing any special character ("+=/") translation. sub url_safe_base64_decode { my ($value) = @_; $value =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg; $value =~ tr|-_~|+=/|; my $result = decode_base64($value); return $result; } # Create a private content URL sub create_url { my ($path, $policy, $signature, $key_pair_id, $expires) = @_; my $result; my $separator = $path =~ /\?/ ? '&' : '?'; if ($expires) { $result = "$path$separator$EXPIRES_PARAM=$expires&$SIGNATURE_PARAM=$signature&$KEY_PAIR_ID_PARAM=$key_pair_id"; } else { $result = "$path$separator$POLICY_PARAM=$policy&$SIGNATURE_PARAM=$signature&$KEY_PAIR_ID_PARAM=$key_pair_id"; } $result =~ s/\n//g; return $result; } # Sign a document with given private key file. # The first argument is the document to sign # The second argument is the name of the private key file sub rsa_sha1_sign { my ($to_sign, $pvkFile) = @_; print "openssl sha1 -sign $pvkFile $to_sign\n"; return write_to_program($pvkFile, $to_sign); } # Helper function to write data to a program sub write_to_program { my ($keyfile, $data) = @_; unlink "temp_policy.dat" if (-e "temp_policy.dat"); unlink "temp_sign.dat" if (-e "temp_sign.dat"); write_file("temp_policy.dat", $data); system("openssl dgst -sha1 -sign \"$keyfile\" -out temp_sign.dat temp_policy.dat"); my $output = read_file("temp_sign.dat"); return $output; } # Read a file into a string and return the string sub read_file { my ($file) = @_; open(INFILE, "<$file") or die("Failed to open $file: $!"); my $str = join('', ); close INFILE; return $str; } sub is_url_valid { my ($url) = @_; # HTTP distributions start with http[s]:// and are the correct thing to sign if ($url =~ /^https?:\/\//) { return 1; } else { print STDERR "CloudFront requires absolute URLs for HTTP distributions\n"; return 0; } } sub is_stream_valid { my ($stream) = @_; if ($stream =~ /^rtmp:\/\// or $stream =~ /^\/?cfx\/st/) { print STDERR "Streaming distributions require that only the stream name is signed.\n"; print STDERR "The stream name is everything after, but not including, cfx/st/\n"; return 0; } else { return 1; } } # flash requires that the query parameters in the stream name are url # encoded when passed in through javascript, etc. This sub handles the minimal # required url encoding. sub escape_url_for_webpage { my ($url) = @_; $url =~ s/\?/%3F/g; $url =~ s/=/%3D/g; $url =~ s/&/%26/g; return $url; } 1; ``` # Create a URL signature using PHP Any web server that runs PHP can use this PHP example code to create policy statements and signatures for private CloudFront distributions. The full example creates a functioning webpage with signed URL links that play a video stream using CloudFront streaming. You can download the full example from the [demo-php.zip](samples/demo-php.zip) file. **Notes** Creating a URL signature is just one part of the process of serving private content using a signed URL. For more information about the entire process, see [Use signed URLs](private-content-signed-urls.md). You can also create signed URLs by using the `UrlSigner` class in the AWS SDK for PHP. For more information, see [Class UrlSigner](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.CloudFront.UrlSigner.html) in the *AWS SDK for PHP API Reference*. In the `openssl_sign` call, note that passing `OPENSSL_ALGO_SHA256` as the fourth argument switches to SHA-256. (See also the [Create signed cookies using PHP](signed-cookies-PHP.md) for a full example.) **Topics** + [ ## Create the RSA SHA-1 signature ](#sample-rsa-sign) + [ ## Create a canned policy ](#sample-canned-policy) + [ ## Create a custom policy ](#sample-custom-policy) + [ ## Full code example ](#full-example) The following sections breaks down the code example into individual parts. You can find the [Full code example](#full-example) below. ## Create the RSA SHA-1 signature This code example does the following: + The function `rsa_sha1_sign` hashes and signs the policy statement. The arguments required are a policy statement and the private key that corresponds with a public key that’s in a trusted key group for your distribution. + Next, the `url_safe_base64_encode` function creates a URL-safe version of the signature. ``` function rsa_sha1_sign($policy, $private_key_filename) { $signature = ""; // load the private key $fp = fopen($private_key_filename, "r"); $priv_key = fread($fp, 8192); fclose($fp); $pkeyid = openssl_get_privatekey($priv_key); // compute signature openssl_sign($policy, $signature, $pkeyid); // free the key from memory openssl_free_key($pkeyid); return $signature; } function url_safe_base64_encode($value) { $encoded = base64_encode($value); // replace unsafe characters +, = and / with // the safe characters -, _ and ~ return str_replace( array('+', '=', '/'), array('-', '_', '~'), $encoded); } ``` The following code snippet uses the functions `get_canned_policy_stream_name()` and `get_custom_policy_stream_name()` to create a canned and custom policy. CloudFront uses the policies to create the URL for streaming the video, including specifying the expiration time. You can then used a canned policy or a custom policy to determine how to manage access to your content. For more information about which one to choose, see the [Decide to use canned or custom policies for signed URLs](private-content-signed-urls.md#private-content-choosing-canned-custom-policy) section. ## Create a canned policy The following example code constructs a *canned* policy statement for the signature. **Note** The `$expires` variable is a date/time stamp that must be an integer, not a string. ``` function get_canned_policy_stream_name($video_path, $private_key_filename, $key_pair_id, $expires) { // this policy is well known by CloudFront, but you still need to sign it, since it contains your parameters $canned_policy = '{"Statement":[{"Resource":"' . $video_path . '","Condition":{"DateLessThan":{"AWS:EpochTime":'. $expires . '}}}]}'; // the policy contains characters that cannot be part of a URL, so we base64 encode it $encoded_policy = url_safe_base64_encode($canned_policy); // sign the original policy, not the encoded version $signature = rsa_sha1_sign($canned_policy, $private_key_filename); // make the signature safe to be included in a URL $encoded_signature = url_safe_base64_encode($signature); // combine the above into a stream name $stream_name = create_stream_name($video_path, null, $encoded_signature, $key_pair_id, $expires); // URL-encode the query string characters return $stream_name; } ``` For more information about canned policies, see [Create a signed URL using a canned policy](private-content-creating-signed-url-canned-policy.md). ## Create a custom policy The following example code constructs a *custom* policy statement for the signature. ``` function get_custom_policy_stream_name($video_path, $private_key_filename, $key_pair_id, $policy) { // the policy contains characters that cannot be part of a URL, so we base64 encode it $encoded_policy = url_safe_base64_encode($policy); // sign the original policy, not the encoded version $signature = rsa_sha1_sign($policy, $private_key_filename); // make the signature safe to be included in a URL $encoded_signature = url_safe_base64_encode($signature); // combine the above into a stream name $stream_name = create_stream_name($video_path, $encoded_policy, $encoded_signature, $key_pair_id, null); // URL-encode the query string characters return $stream_name; } ``` For more information about custom policies, see [Create a signed URL using a custom policy](private-content-creating-signed-url-custom-policy.md). ## Full code example The following example code provides a complete demonstration of creating CloudFront signed URLs with PHP. You can download the full example from the [demo-php.zip](samples/demo-php.zip) file. In the following example, you can modify the `$policy` `Condition` element to allow both IPv4 and IPv6 address ranges. For an example, see [Using IPv6 addresses in IAM policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ipv6-access.html#ipv6-access-iam) in the *Amazon Simple Storage Service User Guide*. ``` CloudFront

Amazon CloudFront

Canned Policy

Expires at

The canned policy video will be here:

Custom Policy

Expires at only viewable by IP

The custom policy video will be here:

``` For additional URL signature examples, see the following topics: + [Create a URL signature using Perl](CreateURLPerl.md) + [Create a URL signature using C\$1 and the .NET Framework](CreateSignatureInCSharp.md) + [Create a URL signature using Java](CFPrivateDistJavaDevelopment.md) Instead of using signed URLs to create the signature, you can use signed cookies. For more information, see [Create signed cookies using PHP](signed-cookies-PHP.md). # Create a URL signature using C\$1 and the .NET Framework The C\$1 examples in this section implement an example application that demonstrates how to create the signatures for CloudFront private distributions using canned and custom policy statements. The examples include utility functions based on the [AWS SDK for .NET](https://aws.amazon.com/sdkfornet) that can be useful in .NET applications. You can also create signed URLs and signed cookies by using the SDK for .NET. In the *SDK for .NET API Reference*, see the following topics: + **Signed URLs** – [AmazonCloudFrontUrlSigner](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CloudFront/TCloudFrontUrlSigner.html) + **Signed cookies** – [AmazonCloudFrontCookieSigner](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CloudFront/TCloudFrontCookieSigner.html) To download the code, go to [Signature Code in C\$1](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/samples/AWS_PrivateCF_Distributions.zip). **Notes** The `AmazonCloudFrontUrlSigner` and `AmazonCloudFrontCookieSigner` classes have moved to a separate package. For more information about using them, see [CookieSigner and UrlSigner](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html#net-dg-v4-CookieSigner-UrlSigner) in the *AWS SDK for .NET (V4) Developer Guide*. Creating a URL signature is just one part of the process of serving private content using a signed URL. For more information, see [Use signed URLs](private-content-signed-urls.md). For more information about using signed cookies, see [Use signed cookies](private-content-signed-cookies.md). In the RSA signing call, note that `SHA1` can be replaced with `SHA256` in the hash algorithm parameter. ## Use an RSA key in the .NET Framework To use an RSA key in the .NET Framework, you must convert the AWS supplied .pem file to the XML format that the .NET Framework uses. After conversion, the RSA private key file is in the following format: **Example : RSA private key in the XML .NET Framework format** ``` wO5IvYCP5UcoCKDo1dcspoMehWBZcyfs9QEzGi6Oe5y+ewGr1oW+vB2GPB ANBiVPcUHTFWhwaIBd3oglmF0lGQljP/jOfmXHUK2kUUnLnJp+oOBL2NiuFtqcW6h/L5lIpD8Yq+NRHg Ty4zDsyr2880MvXv88yEFURCkqEXAMPLE= AQAB

5bmKDaTz npENGVqz4Cea8XPH+sxt+2VaAwYnsarVUoSBeVt8WLloVuZGG9IZYmH5KteXEu7fZveYd9UEXAMPLE==

1v9l/WN1a1N3rOK4VGoCokx7kR2SyTMSbZgF9IWJNOugR/WZw7HTnjipO3c9dy1Ms9pUKwUF4 6d7049EXAMPLE== RgrSKuLWXMyBH+/l1Dx/I4tXuAJIrlPyo+VmiOc7b5NzHptkSHEPfR9s1 OK0VqjknclqCJ3Ig86OMEtEXAMPLE== pjPjvSFw+RoaTu0pgCA/jwW/FGyfN6iim1RFbkT4 z49DZb2IM885f3vf35eLTaEYRYUHQgZtChNEV0TEXAMPLE== nkvOJTg5QtGNgWb9i cVtzrL/1pFEOHbJXwEJdU99N+7sMK+1066DL/HSBUCD63qD4USpnf0myc24in0EXAMPLE== Bc7mp7XYHynuPZxChjWNJZIq+A73gm0ASDv6At7F8Vi9r0xUlQe/v0AQS3ycN8QlyR4XMbzMLYk 3yjxFDXo4ZKQtOGzLGteCU2srANiLv26/imXA8FVidZftTAtLviWQZBVPTeYIA69ATUYPEq0a5u5wjGy UOij9OWyuEXAMPLE= ``` ## Canned policy signing method in C\$1 The following C\$1 code creates a signed URL that uses a canned policy by doing the following: + Creates a policy statement. + Hashes the policy statement using SHA1, and signs the result using RSA and the private key whose corresponding public key is in a trusted key group. + Base64-encodes the hashed and signed policy statement and replaces special characters to make the string safe to use as a URL request parameter. + Concatenates the values. For the complete implementation, see the example at [Signature Code in C\$1](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/samples/AWS_PrivateCF_Distributions.zip). **Note** The `keyId` is returned when you upload a public key to CloudFront. For more information, see ![\[6\]](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/images/callouts/6.png)[ &Key-Pair-Id](private-content-creating-signed-url-canned-policy.md). **Example : Canned policy signing method in C\$1** ``` public static string ToUrlSafeBase64String(byte[] bytes) { return System.Convert.ToBase64String(bytes) .Replace('+', '-') .Replace('=', '_') .Replace('/', '~'); } public static string CreateCannedPrivateURL(string urlString, string durationUnits, string durationNumber, string pathToPolicyStmnt, string pathToPrivateKey, string keyId) { // args[] 0-thisMethod, 1-resourceUrl, 2-seconds-minutes-hours-days // to expiration, 3-numberOfPreviousUnits, 4-pathToPolicyStmnt, // 5-pathToPrivateKey, 6-keyId TimeSpan timeSpanInterval = GetDuration(durationUnits, durationNumber); // Create the policy statement. string strPolicy = CreatePolicyStatement(pathToPolicyStmnt, urlString, DateTime.Now, DateTime.Now.Add(timeSpanInterval), "0.0.0.0/0"); if ("Error!" == strPolicy) return "Invalid time frame." + "Start time cannot be greater than end time."; // Copy the expiration time defined by policy statement. string strExpiration = CopyExpirationTimeFromPolicy(strPolicy); // Read the policy into a byte buffer. byte[] bufferPolicy = Encoding.ASCII.GetBytes(strPolicy); // Initialize the SHA1CryptoServiceProvider object and hash the policy data. using (SHA1CryptoServiceProvider cryptoSHA1 = new SHA1CryptoServiceProvider()) { bufferPolicy = cryptoSHA1.ComputeHash(bufferPolicy); // Initialize the RSACryptoServiceProvider object. RSACryptoServiceProvider providerRSA = new RSACryptoServiceProvider(); XmlDocument xmlPrivateKey = new XmlDocument(); // Load your private key, which you created by converting your // .pem file to the XML format that the .NET framework uses. // Several tools are available. xmlPrivateKey.Load(pathToPrivateKey); // Format the RSACryptoServiceProvider providerRSA and // create the signature. providerRSA.FromXmlString(xmlPrivateKey.InnerXml); RSAPKCS1SignatureFormatter rsaFormatter = new RSAPKCS1SignatureFormatter(providerRSA); rsaFormatter.SetHashAlgorithm("SHA1"); byte[] signedPolicyHash = rsaFormatter.CreateSignature(bufferPolicy); // Convert the signed policy to URL-safe base64 encoding and // replace unsafe characters + = / with the safe characters - _ ~ string strSignedPolicy = ToUrlSafeBase64String(signedPolicyHash); // Concatenate the URL, the timestamp, the signature, // and the key pair ID to form the signed URL. return urlString + "?Expires=" + strExpiration + "&Signature=" + strSignedPolicy + "&Key-Pair-Id=" + keyId; } } ``` ## Custom policy signing method in C\$1 The following C\$1 code creates a signed URL that uses a custom policy by doing the following: 1. Creates a policy statement. 1. Base64-encodes the policy statement and replaces special characters to make the string safe to use as a URL request parameter. 1. Hashes the policy statement using SHA1, and encrypts the result using RSA and the private key whose corresponding public key is in a trusted key group. 1. Base64-encodes the hashed policy statement and replacing special characters to make the string safe to use as a URL request parameter. 1. Concatenates the values. For the complete implementation, see the example at [Signature Code in C\$1](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/samples/AWS_PrivateCF_Distributions.zip). **Note** The `keyId` is returned when you upload a public key to CloudFront. For more information, see ![\[6\]](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/images/callouts/6.png)[ &Key-Pair-Id](private-content-creating-signed-url-canned-policy.md). **Example : Custom policy signing method in C\$1** ``` public static string ToUrlSafeBase64String(byte[] bytes) { return System.Convert.ToBase64String(bytes) .Replace('+', '-') .Replace('=', '_') .Replace('/', '~'); } public static string CreateCustomPrivateURL(string urlString, string durationUnits, string durationNumber, string startIntervalFromNow, string ipaddress, string pathToPolicyStmnt, string pathToPrivateKey, string keyId) { // args[] 0-thisMethod, 1-resourceUrl, 2-seconds-minutes-hours-days // to expiration, 3-numberOfPreviousUnits, 4-starttimeFromNow, // 5-ip_address, 6-pathToPolicyStmt, 7-pathToPrivateKey, 8-keyId TimeSpan timeSpanInterval = GetDuration(durationUnits, durationNumber); TimeSpan timeSpanToStart = GetDurationByUnits(durationUnits, startIntervalFromNow); if (null == timeSpanToStart) return "Invalid duration units." + "Valid options: seconds, minutes, hours, or days"; string strPolicy = CreatePolicyStatement( pathToPolicyStmnt, urlString, DateTime.Now.Add(timeSpanToStart), DateTime.Now.Add(timeSpanInterval), ipaddress); // Read the policy into a byte buffer. byte[] bufferPolicy = Encoding.ASCII.GetBytes(strPolicy); // Convert the policy statement to URL-safe base64 encoding and // replace unsafe characters + = / with the safe characters - _ ~ string urlSafePolicy = ToUrlSafeBase64String(bufferPolicy); // Initialize the SHA1CryptoServiceProvider object and hash the policy data. byte[] bufferPolicyHash; using (SHA1CryptoServiceProvider cryptoSHA1 = new SHA1CryptoServiceProvider()) { bufferPolicyHash = cryptoSHA1.ComputeHash(bufferPolicy); // Initialize the RSACryptoServiceProvider object. RSACryptoServiceProvider providerRSA = new RSACryptoServiceProvider(); XmlDocument xmlPrivateKey = new XmlDocument(); // Load your private key, which you created by converting your // .pem file to the XML format that the .NET framework uses. // Several tools are available. xmlPrivateKey.Load(pathToPrivateKey); // Format the RSACryptoServiceProvider providerRSA // and create the signature. providerRSA.FromXmlString(xmlPrivateKey.InnerXml); RSAPKCS1SignatureFormatter RSAFormatter = new RSAPKCS1SignatureFormatter(providerRSA); RSAFormatter.SetHashAlgorithm("SHA1"); byte[] signedHash = RSAFormatter.CreateSignature(bufferPolicyHash); // Convert the signed policy to URL-safe base64 encoding and // replace unsafe characters + = / with the safe characters - _ ~ string strSignedPolicy = ToUrlSafeBase64String(signedHash); return urlString + "?Policy=" + urlSafePolicy + "&Signature=" + strSignedPolicy + "&Key-Pair-Id=" + keyId; } } ``` ## Utility methods for signature generation The following methods get the policy statement from a file and parse time intervals for signature generation. **Example : Utility methods for signature generation** ``` public static string CreatePolicyStatement(string policyStmnt, string resourceUrl, DateTime startTime, DateTime endTime, string ipAddress) { // Create the policy statement. FileStream streamPolicy = new FileStream(policyStmnt, FileMode.Open, FileAccess.Read); using (StreamReader reader = new StreamReader(streamPolicy)) { string strPolicy = reader.ReadToEnd(); TimeSpan startTimeSpanFromNow = (startTime - DateTime.Now); TimeSpan endTimeSpanFromNow = (endTime - DateTime.Now); TimeSpan intervalStart = (DateTime.UtcNow.Add(startTimeSpanFromNow)) - new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc); TimeSpan intervalEnd = (DateTime.UtcNow.Add(endTimeSpanFromNow)) - new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc); int startTimestamp = (int)intervalStart.TotalSeconds; // START_TIME int endTimestamp = (int)intervalEnd.TotalSeconds; // END_TIME if (startTimestamp > endTimestamp) return "Error!"; // Replace variables in the policy statement. strPolicy = strPolicy.Replace("RESOURCE", resourceUrl); strPolicy = strPolicy.Replace("START_TIME", startTimestamp.ToString()); strPolicy = strPolicy.Replace("END_TIME", endTimestamp.ToString()); strPolicy = strPolicy.Replace("IP_ADDRESS", ipAddress); strPolicy = strPolicy.Replace("EXPIRES", endTimestamp.ToString()); return strPolicy; } } public static TimeSpan GetDuration(string units, string numUnits) { TimeSpan timeSpanInterval = new TimeSpan(); switch (units) { case "seconds": timeSpanInterval = new TimeSpan(0, 0, 0, int.Parse(numUnits)); break; case "minutes": timeSpanInterval = new TimeSpan(0, 0, int.Parse(numUnits), 0); break; case "hours": timeSpanInterval = new TimeSpan(0, int.Parse(numUnits), 0 ,0); break; case "days": timeSpanInterval = new TimeSpan(int.Parse(numUnits),0 ,0 ,0); break; default: Console.WriteLine("Invalid time units;" + "use seconds, minutes, hours, or days"); break; } return timeSpanInterval; } private static TimeSpan GetDurationByUnits(string durationUnits, string startIntervalFromNow) { switch (durationUnits) { case "seconds": return new TimeSpan(0, 0, int.Parse(startIntervalFromNow)); case "minutes": return new TimeSpan(0, int.Parse(startIntervalFromNow), 0); case "hours": return new TimeSpan(int.Parse(startIntervalFromNow), 0, 0); case "days": return new TimeSpan(int.Parse(startIntervalFromNow), 0, 0, 0); default: return new TimeSpan(0, 0, 0, 0); } } public static string CopyExpirationTimeFromPolicy(string policyStatement) { int startExpiration = policyStatement.IndexOf("EpochTime"); string strExpirationRough = policyStatement.Substring(startExpiration + "EpochTime".Length); char[] digits = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9' }; List listDigits = new List(digits); StringBuilder buildExpiration = new StringBuilder(20); foreach (char c in strExpirationRough) { if (listDigits.Contains(c)) buildExpiration.Append(c); } return buildExpiration.ToString(); } ``` See also + [Create a URL signature using Perl](CreateURLPerl.md) + [Create a URL signature using PHP](CreateURL_PHP.md) + [Create a URL signature using Java](CFPrivateDistJavaDevelopment.md) # Create a URL signature using Java In addition to the following code example, you can use [the `CloudFrontUrlSigner` utility class in the AWS SDK for Java (version 1)](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/cloudfront/CloudFrontUrlSigner.html) to create [CloudFront signed URLs](private-content-signed-urls.md). For more examples, see [Create signed URLs and cookies using an AWS SDK](https://docs.aws.amazon.com/code-library/latest/ug/cloudfront_example_cloudfront_CloudFrontUtilities_section.html) in the *AWS SDK Code Examples Code Library*. **Notes** Creating a signed URL is just one part of the process of [serving private content with CloudFront](PrivateContent.md). For more information about the entire process, see [Use signed URLs](private-content-signed-urls.md). In the `Signature.getInstance` call, note that `SHA1withRSA` can be replaced with `SHA256withRSA`. **Example Java policy and signature encryption methods** ``` package org.example; import java.time.Instant; import java.time.temporal.ChronoUnit; import software.amazon.awssdk.services.cloudfront.CloudFrontUtilities; import software.amazon.awssdk.services.cloudfront.model.CannedSignerRequest; import software.amazon.awssdk.services.cloudfront.url.SignedUrl; public class Main { public static void main(String[] args) throws Exception { CloudFrontUtilities cloudFrontUtilities = CloudFrontUtilities.create(); Instant expirationDate = Instant.now().plus(7, ChronoUnit.DAYS); String resourceUrl = "https://a1b2c3d4e5f6g7.cloudfront.net"; String keyPairId = "K1UA3WV15I7JSD"; CannedSignerRequest cannedRequest = CannedSignerRequest.builder() .resourceUrl(resourceUrl) .privateKey(new java.io.File("/path/to/private_key.pem").toPath()) .keyPairId(keyPairId) .expirationDate(expirationDate) .build(); SignedUrl signedUrl = cloudFrontUtilities.getSignedUrlWithCannedPolicy(cannedRequest); String url = signedUrl.url(); System.out.println(url); } } ``` **Example Canned Policy Signing with SHA256 in Java** ``` package org.example; import java.io.File; import java.nio.file.Files; import java.security.KeyFactory; import java.security.PrivateKey; import java.security.Signature; import java.security.spec.PKCS8EncodedKeySpec; import java.time.Instant; import java.time.temporal.ChronoUnit; import java.util.Base64; public class Main { public static void main(String[] args) throws Exception { String resourceUrl = "https://a1b2c3d4e5f6g7.cloudfront.net/myfile.html"; String keyPairId = "K1UA3WV15I7JSD"; Instant expiration = Instant.now().plus(7, ChronoUnit.DAYS); PrivateKey privateKey = loadPrivateKey("/path/to/private_key.der"); System.out.println(createSignedUrl(resourceUrl, keyPairId, privateKey, expiration, "SHA1")); System.out.println(createSignedUrl(resourceUrl, keyPairId, privateKey, expiration, "SHA256")); } static String createSignedUrl(String resourceUrl, String keyPairId, PrivateKey privateKey, Instant expiration, String hashAlgorithm) throws Exception { long epochSeconds = expiration.getEpochSecond(); String policy = "{\"Statement\":[{\"Resource\":\"" + resourceUrl + "\",\"Condition\":{\"DateLessThan\":{\"AWS:EpochTime\":" + epochSeconds + "}}}]}"; String jcaAlgorithm = hashAlgorithm.equals("SHA256") ? "SHA256withRSA" : "SHA1withRSA"; Signature sig = Signature.getInstance(jcaAlgorithm); sig.initSign(privateKey); sig.update(policy.getBytes("UTF-8")); String signature = base64UrlEncode(sig.sign()); String url = resourceUrl + (resourceUrl.contains("?") ? "&" : "?") + "Expires=" + epochSeconds + "&Signature=" + signature + "&Key-Pair-Id=" + keyPairId; if (hashAlgorithm.equals("SHA256")) { url += "&Hash-Algorithm=SHA256"; } return url; } static String base64UrlEncode(byte[] bytes) { return Base64.getEncoder().encodeToString(bytes) .replace('+', '-') .replace('=', '_') .replace('/', '~'); } static PrivateKey loadPrivateKey(String path) throws Exception { byte[] keyBytes = Files.readAllBytes(new File(path).toPath()); return KeyFactory.getInstance("RSA") .generatePrivate(new PKCS8EncodedKeySpec(keyBytes)); } } ``` See also: + [Create a URL signature using Perl](CreateURLPerl.md) + [Create a URL signature using PHP](CreateURL_PHP.md) + [Create a URL signature using C\$1 and the .NET Framework](CreateSignatureInCSharp.md)