Amazon CloudFront
Developer Guide (API Version 2014-10-21)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

Creating a Signed URL Using a Custom Policy

To create a signed URL using a custom policy, perform 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 Reformatting the CloudFront Private Key (.NET and Java Only).

  2. Concatenate the following values in the specified order, and remove the whitespace between the parts. You might have to include escape characters in the string in application code. All values have a type of String. Each part is keyed by number (1) to the two examples that follow.

    Base URL for the object

    This is the URL that you use to access the object if you aren't using a signed URL, for example:

    • Web distribution: http://d111111abcdef8.cloudfront.net/images/image.jpg

    • RTMP distribution: videos/mediafile.flv

    ?

    The ? indicates that query string parameters follow the base URL. Include the ? even if you don't have any query string parameters of your own.

    Your query string parameters, if any&

    This value is optional. If you want to add your own query string parameters, for example:

    color=red&size=medium

    then add them after the ? (see 2) and before the Policy parameter.

    Important

    Your parameters cannot be named Policy, Signature, or Key-Pair-Id.

    If you add your own parameters, append an & after each one, including the last one.

    Policy=policy statement

    Your policy statement in JSON format, with white space removed. For more information, see Creating a Policy Statement for a Custom Policy.

    &Signature=hashed and signed version of the policy statement

    A hashed and signed version of the policy statement. For more information, see Creating a Signature for a Custom Policy.

    &Key-Pair-Id=active CloudFront key pair Id for the key pair that you are using to sign the policy statement

    The ID for an active CloudFront key pair, for example, APKA9ONS7QCOWEXAMPLE:

    • Web distributions: The key pair must be associated with an AWS account that is one of the trusted signers for the applicable cache behavior.

    • RTMP distributions: The key pair must be associated with an AWS account that is one of the trusted signers for the distribution.

    For more information, see Specifying the AWS Accounts That Can Create Signed URLs (Trusted Signers).

Example signed URL for a web distribution:

1http://d111111abcdef8.cloudfront.net/image.jpg 2? 3color=red&size=medium& 4Policy=eyANCiAgICEXAMPLEW1lbnQiOiBbeyANCiAgICAgICJSZXNvdXJjZSI6Imh0dHA 6Ly9kemJlc3FtN3VuMW0wLmNsb3VkZnJvbnQubmV0L2RlbW8ucGhwIiwgDQogICAgICAiQ 29uZGl0aW9uIjp7IA0KICAgICAgICAgIklwQWRkcmVzcyI6eyJBV1M6U291cmNlSXAiOiI yMDcuMTcxLjE4MC4xMDEvMzIifSwNCiAgICAgICAgICJEYXRlR3JlYXRlclRoYW4iOnsiQ VdTOkVwb2NoVGltZSI6MTI5Njg2MDE3Nn0sDQogICAgICAgICAiRGF0ZUxlc3NUaGFuIjp 7IkFXUzpFcG9jaFRpbWUiOjEyOTY4NjAyMjZ9DQogICAgICB9IA0KICAgfV0gDQp9DQo 5&Signature=nitfHRCrtziwO2HwPfWw~yYDhUF5EwRunQA-j19DzZrvDh6hQ73lDx~ -ar3UocvvRQVw6EkC~GdpGQyyOSKQim-TxAnW7d8F5Kkai9HVx0FIu-5jcQb0UEmat EXAMPLE3ReXySpLSMj0yCd3ZAB4UcBCAqEijkytL6f3fVYNGQI6 6&Key-Pair-Id=APKA9ONS7QCOWEXAMPLE

Example signed URL for an RTMP distribution:

1videos/mediafile.flv 2? 3color=red&size=medium& 4Policy=eyANCiAgICEXAMPLEW1lbnQiOiBbeyANCiAgICAgICJSZXNvdXJjZSI6Imh0dHA 6Ly9kemJlc3FtN3VuMW0wLmNsb3VkZnJvbnQubmV0L2RlbW8ucGhwIiwgDQogICAgICAiQ 29uZGl0aW9uIjp7IA0KICAgICAgICAgIklwQWRkcmVzcyI6eyJBV1M6U291cmNlSXAiOiI yMDcuMTcxLjE4MC4xMDEvMzIifSwNCiAgICAgICAgICJEYXRlR3JlYXRlclRoYW4iOnsiQ VdTOkVwb2NoVGltZSI6MTI5Njg2MDE3Nn0sDQogICAgICAgICAiRGF0ZUxlc3NUaGFuIjp 7IkFXUzpFcG9jaFRpbWUiOjEyOTY4NjAyMjZ9DQogICAgICB9IA0KICAgfV0gDQp9DQo 5&Signature=nitfHRCrtziwO2HwPfWw~yYDhUF5EwRunQA-j19DzZrvDh6hQ73lDx~ -ar3UocvvRQVw6EkC~GdpGQyyOSKQim-TxAnW7d8F5Kkai9HVx0FIu-5jcQb0UEmat EXAMPLE3ReXySpLSMj0yCd3ZAB4UcBCAqEijkytL6f3fVYNGQI6 6&Key-Pair-Id=APKA9ONS7QCOWEXAMPLE

Creating a Policy Statement for a Custom Policy

To create a policy statement for a custom policy, perform the following procedure. For several example policy statements that control access to objects in a variety of ways, see Example Policy Statements for a Custom Policy.

To create the policy statement for a signed URL that uses a custom policy

  1. Construct the policy statement using the following JSON format.

    {
       "Statement": [{
          "Resource":"URL or stream name of the object",
          "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:

    • 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 the descriptions after this procedure.

  2. Remove any whitespace from the policy statement. You might have to include escape characters in the string in application code.

  3. Append the resulting value to your signed URL after Policy=.

  4. Create a signature for the signed URL by hashing, signing, and Base64-encoding the policy statement. For more information, see Creating a Signature for a Custom Policy.

Resource

  • Web distributions (optional but recommended): The base URL including your query strings, if any, but excluding the CloudFront Policy, Signature, and Key-Pair-Id parameters, for example:

    http://d111111abcdef8.cloudfront.net/images/horizon.jpg?size=large&license=yes

    Caution

    If you omit the Resource parameter for a web distribution, end users can access all of the objects associated with any distribution that is associated with the key pair that you use to create the signed URL.

    Note the following:

    • The value must begin with http://, https://, or *.

    • If you have no query string parameters, omit the question mark.

    • You can use the wild card character that matches zero or more characters (*) or the wild-card character that matches exactly one character (?) anywhere in the string. For example, the value:

      http*://d111111abcdef8.cloudfront.net/*game_download.zip*

      would include (for example), the following objects:

      http://d111111abcdef8.cloudfront.net/example_game_download.zip?license=yes

      https://d111111abcdef8.cloudfront.net/example_game_download.zip?license=yes

      http://d111111abcdef8.cloudfront.net/test_game_download.zip?license=temp

      https://d111111abcdef8.cloudfront.net/test_game_download.zip?license=temp

    • If you specify an alternate domain name (CNAME) in the URL, you must specify the alternate domain name when referencing the object in your web page or application. Do not specify the Amazon S3 URL for the object.

  • RTMP distributions: Include only the stream name. For example, if the full URL for a streaming video is:

    rtmp://s5c39gqb8ow64r.cloudfront.net/videos/mp3_name.mp3

    then use the following value for Resource:

    videos/mp3_name

    Do not include a prefix such as mp3: or mp4:. Also, depending on the player you're using, you might have to omit the file extension from the value of Resource. For example, you might need to use sydney-vacation instead of sydney-vacation.flv.

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 information about UTC, see RFC 3339, Date and Time on the Internet: Timestamps, http://tools.ietf.org/html/rfc3339.

For example, January 1, 2013 10:00 am UTC converts to 1357034400 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 Does CloudFront Check the Expiration Date and Time in a Signed URL?

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 object 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. To allow any IP address to access the object, omit this parameter.

IP address ranges must be in standard IPv4 CIDR format (for example, 10.52.176.0/24). For more information, go to RFC 4632, Classless Inter-domain Routing (CIDR): The Internet Address Assignment and Aggregation Plan, http://tools.ietf.org/html/rfc4632.

You can specify only a single value for the condition. For example, you can't set the policy to allow access if the client's IP address is in one of two separate ranges.

Example Policy Statements for a Custom Policy

The following example policy statements show how to control access to a specific object, all of the objects in a directory, or all of the objects 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 whitespace, replace the applicable values with your own values, and include a newline character after the closing brace ( } ).

Example Policy Statement: Accessing One Object from a Range of IP Addresses

The following example custom policy in a signed URL specifies that an end user can access the object http://d111111abcdef8.cloudfront.net/game_download.zip from IP addresses in the range 192.0.2.0/24 until January 1, 2013 10:00 am UTC:

{
   "Statement": [{
      "Resource":"http://d111111abcdef8.cloudfront.net/game_download.zip",
      "Condition":{
         "IpAddress":{"AWS:SourceIp":"192.0.2.0/24"},
         "DateLessThan":{"AWS:EpochTime":1357034400}
      }
   }]
}

Example Policy Statement: Accessing All Objects in a Directory from a Range of IP Addresses

The following example custom policy allows you to create signed URLs for any object in the training directory, as indicated by the * wildcard character in the Resource parameter. End users can access the object from an IP address in the range 192.0.2.0/24 until January 1, 2013 10:00 am UTC:

{ 
   "Statement": [{ 
      "Resource":"http://d111111abcdef8.cloudfront.net/training/*", 
      "Condition":{ 
         "IpAddress":{"AWS:SourceIp":"192.0.2.0/24"}, 
         "DateLessThan":{"AWS:EpochTime":1357034400}
      } 
   }] 
}

Each signed URL in which you use this policy includes a base URL that identifies a specific object, for example:

http://d111111abcdef8.cloudfront.net/training/orientation.pdf

Example Policy Statement: Accessing All Objects Associated with a Key Pair ID from One IP Address

The following sample custom policy allows you to create signed URLs for any object associated with any distribution, as indicated by the * wildcard character in the Resource parameter. The end 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 objects are available only from January 1, 2013 10:00 am UTC until January 2, 2013 10:00 am UTC:

{ 
   "Statement": [{ 
      "Resource":"http://*",
      "Condition":{ 
         "IpAddress":{"AWS:SourceIp":"192.0.2.10/32"},
         "DateGreaterThan":{"AWS:EpochTime":1357034400},
         "DateLessThan":{"AWS:EpochTime":1357120800}
      } 
   }] 
}

Each signed URL in which you use this policy includes a base URL that identifies a specific object in a specific CloudFront distribution, for example:

http://d111111abcdef8.cloudfront.net/training/orientation.pdf

The signed URL also includes a key pair ID, which must be associated with a trusted signer in the distribution (d111111abcdef8.cloudfront.net) that you specify in the base URL.

Creating a Signature for 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, perform the applicable procedure. The version that you choose depends on your distribution type (web or RTMP) and, for RTMP distributions, the media player that you're using (Adobe Flash Player or another media player):

For additional information and examples of how to hash, sign, and encode the policy statement, see:

Option 1: To create a signature for a web distribution or for an RTMP distribution (without Adobe Flash Player) by using a custom policy

  1. Use the SHA-1 hash function to hash and sign the policy statement that you created in the To create the policy statement for a signed URL that uses a custom policy procedure. For the private key that is required by the hash function, use the private key that is associated with the applicable active trusted signer.

    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 and Examples for Creating a Signature for a Signed URL.

  2. Remove whitespace from the hashed and signed string.

  3. Base64-encode the string.

  4. Replace characters that are invalid in a URL query string with characters that are valid. The following table lists invalid and valid characters.

    Replace these invalid charactersWith these valid characters

    +

    - (hyphen)

    =

    _ (underscore)

    /

    ~ (tilde)

  5. Append the resulting value to your signed URL after &Signature=, and return to To create a signed URL using a custom policy to finish concatenating the parts of your signed URL.

Option 2: To create a signature for an RTMP distribution by using a custom policy (Adobe Flash Player)

  1. Use the SHA-1 hash function to hash and sign the policy statement that you created in the To create the policy statement for a signed URL that uses a custom policy procedure. For the private key that is required by the hash function, use the private key that is associated with the applicable active trusted signer.

    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 and Examples for Creating a Signature for a Signed URL.

  2. Remove whitespace from the hashed and signed string.

    Continue on to Step 3 if the stream name is passed in from a web page.

    If the stream name is not passed in from a web page, skip the rest of this procedure. For example, if you wrote your own player that fetches stream names from within the Adobe Flash .swf file, skip the rest of this procedure.

  3. Base64-encode the string.

  4. Replace characters that are invalid in a URL query string with characters that are valid. The following table lists invalid and valid characters.

    Replace these invalid charactersWith these valid characters

    +

    - (hyphen)

    =

    _ (underscore)

    /

    ~ (tilde)

  5. Some versions of Adobe Flash Player require that you URL-encode the characters ?, =, and &. For information about whether your version of Adobe Flash Player requires this character substitution, refer to the Adobe website.

    If your version of Adobe Flash Player does not require that you URL-encode the characters ?, =, and &, skip to Step 6.

    If your version of Adobe Flash Player requires URL-encoding those characters, replace them as indicated in the following table. (You already replaced = in the previous step.)

    Replace these invalid charactersWith this URL encoding

    ?

    %3F

    &

    %26

  6. Append the resulting value to your signed URL after &Signature=, and return to To create a signed URL using a custom policy to finish concatenating the parts of your signed URL.