Serving Private Content

You can create a CloudFront origin access identity with a POST on the 2009-12-01/origin-access-identity/cloudfront resource. You must provide a unique caller reference in the request like you do when creating a distribution through the control API. You can optionally provide comments about the identity.

	Note
	The AWS Management Console doesn't yet support the ability to create an origin access identity or to update your distribution to serve private content.

A private content distribution looks like a public content distribution, except it has an OriginAccessIdentity element in the configuration. You must specify the value for the element using the following format: origin-access-identity/cloudfront/ID.

Following is an example request that creates a new private content distribution.

POST /2009-12-01/distribution HTTP/1.1
[Required headers]

<?xml version="1.0" encoding="UTF-8"?>
<DistributionConfig xmlns="http://cloudfront.amazonaws.com/doc/2009-12-01/">
  <Origin>mybucket.s3.amazonaws.com</Origin>   
  <CallerReference>20091130090000</CallerReference>
  <Comment>My comments</Comment>
  <Enabled>true</Enabled>
  <OriginAccessIdentity>origin-access-identity/cloudfront/E74FTE3AJFJ256A</OriginAccessIdentity>
</DistributionConfig>

For more information about updating a distribution, see Updating a Distribution's Configuration.

Once you have a private content distribution, you must grant your CloudFront origin access identity read access to the private content. You do this by modifying the Amazon S3 ACL on each of the objects (not on the bucket). In the object's ACL, you add a grant that gives read permission to the CloudFront origin access identity's canonical user ID (and not the other ID associated with the identity). You can use the Amazon S3 API or your favorite Amazon S3 tool to modify the ACL.

When modifying Amazon S3 ACLs through the Amazon S3 API, you typically first GET the object's ACL, then make your desired changes to the ACL, and finally PUT the modified ACL. For more information about the ACL format and updating an ACL, go to REST Access Control Policy and Access Control Lists in the Amazon Simple Storage Service Developer Guide.

If you've updated a public content distribution to instead serve private content, make sure to remove any grant in the ACL that gives read permission to the public.

	Important
	To ensure there's no disruption to end user access to the content, remove this grant after you've set up the private content distribution and confirmed its state is Deployed.

Signing a URL is the process of creating an RSA digital signature using a special key and a portion of the URL string. This section describes how to get the special key for signing the URLs. What you actually get is a key pair consisting of a private key and a public key. AWS keeps the public key, and you keep the private key (and use it to sign the URLs).

Important

The key pair you need is not an X.509 certificate and private key. It's an RSA key pair. If you're an Amazon EC2 user, you probably already have at least one other RSA key pair, which you use to connect to your instances through SSH or Windows Remote Desktop. You can reuse any of your EC2 key pairs with Amazon CloudFront (see the procedure that follows for uploading your public key to the AWS web site). Note that Amazon EC2 doesn't provide you the public key when you create the key pair; however, it's possible to extract the key from the private key or from the EC2 instance.

You must configure your private content distribution to specify that the URLs must be signed, and who can sign them. You can let up to five AWS accounts other than your own sign URLs for your distribution's private content. Each AWS account owner you authorize must create and use their own key pair (for more information, see Creating a Key Pair). You include the ID for the signing key in the URL so that AWS can identify the signer.

The AWS account number is displayed in the top right corner of the account owner's Account Activity page at http://aws.amazon.com (see the example image below).

Following is an example request that creates a private content distribution, and authorizes you and two other AWS accounts to create signed URLs for the distribution.

POST /2009-12-01/distribution HTTP/1.1
[Required headers]
				
<?xml version="1.0" encoding="UTF-8"?>
<DistributionConfig xmlns="http://cloudfront.amazonaws.com/doc/2009-12-01/">
  <Origin>mybucket.s3.amazonaws.com</Origin>   
  <CallerReference>20091130090000</CallerReference>
  <Comment>My comments</Comment>
  <Enabled>true</Enabled>
  <OriginAccessIdentity>origin-access-identity/cloudfront/E127G7VVVYK51Z</OriginAccessIdentity>
  <TrustedSigners>
    <Self/>
    <AwsAccountNumber>123499998765</AwsAccountNumber>
    <AwsAccountNumber>098711114567</AwsAccountNumber>
  </TrustedSigners>
</DistributionConfig>

Once you've specified the trusted signers, you should check to see which of them are active. For a trusted signer to be active, both of the following must be true:

To determine the active trusted signers for a distribution, get the distribution's information (not just the configuration, but the entire distribution). The response includes an ActiveTrustedSigners element that lists the ID of each active key pair associated with each trusted signer's AWS account. If a trusted signer doesn't have an active key pair that CloudFront is aware of, that signer doesn't have a KeyPairId element listed for it.

The following example response shows that you yourself have two active key pairs, and the AWS account with ID 123499998765 has one active key pair. However, the third trusted signer (with account ID 09871114567) doesn't yet have an active key pair (no KeyPairId appears for that signer) and so can't create working signatures.

200 OK
ETag: E2QWRUHAPOMQZL
x-amz-request-id: request_id

<Distribution xmlns="http://cloudfront.amazonaws.com/doc/2009-12-01/">
   <Id>EDFDVBD632BHDS5</Id>
   <Status>Deployed</Status>
   <LastModifiedTime>2009-11-19T19:37:58Z</LastModifiedTime>
   <DomainName>d604721fxaaqy9.cloudfront.net</DomainName>
   <ActiveTrustedSigners>
      <Signer>
         <Self/>
         <KeyPairId>APKAI72T5DYBXZDKA7TA</KeyPairId>
         <KeyPairId>APKAU72D8DYNXZDKA8DP</KeyPairId>
      </Signer>
      <Signer>
         <AwsAccountNumber>123499998765</AwsAccountNumber>
         <KeyPairId>APKA9ONS7QCOWWZU7BP6</KeyPairId>
      </Signer>
      <Signer>
         <AwsAccountNumber>098711114567</AwsAccountNumber>
      </Signer>
   </ActiveTrustedSigners>			
   <DistributionConfig> 
      <Origin>mybucket.s3.amazonaws.com</Origin>
      <CallerReference>20091130090000</CallerReference>
      <Comment>My comments</Comment>
      <Enabled>true</Enabled>
      <OriginAccessIdentity>E74FTE3AJFJ256A</OriginAccessIdentity>
      <TrustedSigners>
         <Self/>
         <AwsAccountNumber>123499998765</AwsAccountNumber>
         <AwsAccountNumber>098711114567</AwsAccountNumber>
      </TrustedSigners>
   </DistributionConfig>
</Distribution>

A signed URL that uses a canned policy consists of a regular CloudFront URL, plus the three special query parameters listed in the following table.

	Note
	We remove all query parameters (including those required for signed URLs) before recording the URL in the CloudFront access logs. For more information about access logs, see Access Logs.

The Signature value is an RSA-SHA1 digital signature of the following JSON policy, with the RESOURCE and EXPIRES values replaced as described in the table that follows.

{"Statement":[{"Resource":"RESOURCE","Condition":{"DateLessThan":{"AWS:EpochTime":EXPIRES}}}]}

	Important
	For the signature you include in the URL to match the signature CloudFront constructs based on the canned policy, you must make sure the policy you construct looks exactly like the preceding policy. That is, you must use your own valid values for RESOURCE and EXPIRES, and you must remove any white spaces and line feeds.

The following table describes the values to substitute in the policy.

http://d604721fxaaqy9.cloudfront.net/download/horizon.jpg?large=yes&license=yes&Expires=1258237200&Signature=TBD​&Key-Pair-Id=PK123456789754

http://d604721fxaaqy9.cloudfront.net/download/horizon.jpg?large=yes&license=yes

The signature is an RSA-SHA1 digital signature of the policy (with all white space and line feeds removed), using the private key from your key pair.

Signature (Policy) = RSA_Sign(SHA1, Policy, PrivateKey)

	Important
	CloudFront uses an RSA-SHA1 signature, and not an HMAC-SHA1 signature, which is the type Amazon S3 and many other AWS products use. A common mistake is to implement HMAC-SHA1 instead of an RSA-SHA1 in your code for creating signatures for private content.

Use the following translation to make the signature URL safe before including it in the URL.

Url-Safe (m) = CharReplace( Base64(m),  "+=/",  "-_~" )

For an example of a complete URL that uses a canned policy, see Signed URL Examples.

A signed URL that uses a custom policy consists of a regular CloudFront URL, plus the three special query parameters listed in the following table. Notice that no Expires parameter is required (as with canned policies); instead a Policy parameter is required. The presence of the Policy parameter in the URL tells CloudFront that you're using a custom policy instead of a canned policy.

	Note
	We remove all query parameters (including those required for signed URLs) before recording the URL in the CloudFront access logs. For more information about access logs, see Access Logs.

The policy you use to create the signature is a simple JSON document in UTF-8 format that specifies the resource and any conditions for accessing the resource. Use the policy format shown in the following example and the parameters listed in the following table.

Following is an example policy that allows access to the game_download.zip object if the end user's IP address is within the 145.168.143.0/24 IP address range, and if the end user's request for the object comes in before 11/14/2009 at 10:20 p.m. (specified in epoch time in seconds).

{
   "Statement": [{
      "Resource":"http://d604721fxaaqy9.cloudfront.net/game_download.zip",
      "Condition":{
         "IpAddress":{"AWS:SourceIp":"145.168.143.0/24"},
         "DateLessThan":{"AWS:EpochTime":1258237200}      
      }
   }]
}

Note

If you're familiar with Amazon S3 browser-based POSTs, the policy format you use there differs from the policy format you use here for CloudFront private objects. If you're familiar with Amazon SQS access control, you might be familiar with the access policy language Amazon SQS uses. CloudFront uses the same format for its policies, but limits how you can use the language to only the specific cases shown here.

The following table describes the parameters you can specify in the policy.

The parameter names must be specified in the policy exactly as shown in the preceding table (no abbreviations like datelt for DateLessThan are accepted). The order of the parameters in the policy doesn't matter. Make sure you specify the conditions (DateLessthan, DateGreaterThan, and IpAddress) as part of the Condition section in the policy.

The square brackets that enclose the statement's contents (as shown in the preceding example policy) are required for the policy to be considered valid.

For additional policy examples, see Signed URL Examples.

You calculate the Signature query parameter using an RSA-SHA1 digital signature of the raw policy (the policy must be in UTF-8 format before signing).

Signature (RawPolicy) = RSA_Sign(SHA1, RawPolicy, PrivateKey)

	Important
	CloudFront uses an RSA-SHA1 signature, and not an HMAC-SHA1 signature, which is the type Amazon S3 and many other AWS products use. A common mistake is to implement HMAC-SHA1 instead of an RSA-SHA1 in your code for creating signatures for private content.

No special canonicalization of the policy is required. Signing the policy is straightforward and extensible, should we add additional policy conditions that you can use.

Use the following translation to make the policy and the signature URL safe.

Url-Safe (m) = CharReplace( Base64(m),  "+=/",  "-_~" )

This section gives example signatures based on example credentials and policies.

The examples in this section use the (non-working) credentials in the following table.

	Tip
	To make it easier to test your own code, you can get a soft copy of the example credentials (zipped up in the CloudFront_PrivateContent_SignatureExamples.zip file).

-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDA7ki9gI/lRygIoOjV1yymgx6F
YFlzJ+z1ATMaLo57nL57AavWhb68HYY8EA0GJU9xQdMVaHBogF3eiCWYXSUZCWM/
+M5+ZcdQraRRScucmn6g4EvY2K4W2pxbqH8vmUikPxir41EeBPLjMOzKvbzzQy9e
/zzIQVREKSp/7y1mywIDAQAB
-----END PUBLIC KEY-----

-----BEGIN RSA PRIVATE KEY-----
MIICXQIBAAKBgQDA7ki9gI/lRygIoOjV1yymgx6FYFlzJ+z1ATMaLo57nL57AavW
hb68HYY8EA0GJU9xQdMVaHBogF3eiCWYXSUZCWM/+M5+ZcdQraRRScucmn6g4EvY
2K4W2pxbqH8vmUikPxir41EeBPLjMOzKvbzzQy9e/zzIQVREKSp/7y1mywIDAQAB
AoGABc7mp7XYHynuPZxChjWNJZIq+A73gm0ASDv6At7F8Vi9r0xUlQe/v0AQS3yc
N8QlyR4XMbzMLYk3yjxFDXo4ZKQtOGzLGteCU2srANiLv26/imXA8FVidZftTAtL
viWQZBVPTeYIA69ATUYPEq0a5u5wjGyUOij9OWyuy01mbPkCQQDluYoNpPOekQ0Z
WrPgJ5rxc8f6zG37ZVoDBiexqtVShIF5W3xYuWhW5kYb0hliYfkq15cS7t9m95h3
1QJf/xI/AkEA1v9l/WN1a1N3rOK4VGoCokx7kR2SyTMSbZgF9IWJNOugR/WZw7HT
njipO3c9dy1Ms9pUKwUF46d7049ck8HwdQJARgrSKuLWXMyBH+/l1Dx/I4tXuAJI
rlPyo+VmiOc7b5NzHptkSHEPfR9s1OK0VqjknclqCJ3Ig86OMEtEFBzjZQJBAKYz
470hcPkaGk7tKYAgP48FvxRsnzeooptURW5E+M+PQ2W9iDPPOX9739+Xi02hGEWF
B0IGbQoTRFdE4VVcPK0CQQCeS84lODlC0Y2BZv2JxW3Osv/WkUQ4dslfAQl1T303
7uwwr7XTroMv8dIFQIPreoPhRKmd/SbJzbiKfS/4QDhU
-----END RSA PRIVATE KEY-----

Using the OpenSSL package, you can calculate the query parameters as shown in the following examples. For information about OpenSSL, go to http://www.openssl.org.

The following command creates the URL-safe Policy value.

% cat policy | openssl base64 | tr '+=/' '-_~'

The following command creates the URL-safe Signature value.

% cat policy | openssl sha1 -sign private-key.pem | openssl base64 | tr '+=/' '-_~'

http://d604721fxaaqy9.cloudfront.net/horizon.jpg?large=yes&license=yes

{"Statement":[{"Resource":"http://d604721fxaaqy9.cloudfront.net/horizon.jpg​?large=yes&license=yes","Condition":​{"DateLessThan":​{"AWS:EpochTime":1258237200}}}]}

Signature = Nql641NHEUkUaXQHZINK1FZ~SYeUSo​BJMxjdgqrzIdzV​2gyEXPDNv0p​YdWJkflDKJ3xIu​7lbwRpSkG98NBlgP​i4ZJpRRnVX4kX​AJK6tdNx6FucD​B7OVqzcxkxH​sGFd8VCG1Bk​C-Afh9~lOCMIY​HIaiOB6~5jt9​w2EOwi6sIIqrg_

http://d604721fxaaqy9.cloudfront.net/horizon.jpg?large=yes&license=yes&Expires=1258237200&Signature=Nql641NHE​UkUaXQHZINK​1FZ~SYeUSoBJMx​jdgqrzIdzV2gyEX​PDNv0pYdWJkfl​DKJ3xIu7lbwRp​SkG98NBlgPi​4ZJpRRnVX4​kXAJK6tdNx6FucD​B7OVqzcxkxHsG​Fd8VCG1BkC-Afh​9~lOCMIYHI​aiOB6~5jt9w​2EOwi6sIIqrg_&Key-Pair-Id=PK123456789754

Example Custom Policy 1

The following custom policy grants the network 145.168.143.0/24 access to all the objects in the training directory before Sat, 14 Nov 2009 22:20:00 GMT.

Following is the original URL. It specifies a particular object (training/orientation.avi), even though the policy covers multiple objects.

http://d604721fxaaqy9.cloudfront.net/training/orientation.avi

Following is the raw policy to sign.

	Tip
	To make it easier to test your own code, you can get a soft copy of the following policy (zipped up in the CloudFront_PrivateContent_SignatureExamples.zip file). Note that the string used to calculate the signature includes the white space and line feeds shown in the policy.

RawPolicy = 
{ 
   "Statement": [{ 
      "Resource":"http://d604721fxaaqy9.cloudfront.net/training/*", 
      "Condition":{ 
         "IpAddress":{"AWS:SourceIp":"145.168.143.0/24"}, 
         "DateLessThan":{"AWS:EpochTime":1258237200}      
      } 
   }] 
}

Following is the URL-safe policy.

Policy = eyAKICAgIlN0YXRlbWV​udCI6IFt7IAogICAgICAiUmVz​b3VyY2UiOiJodHRwOi8v​ZDYwNDcyMWZ4YWF​xeTkuY2xvdWRmcm9udC5​uZXQvdHJhaW5pbmcv​KiIsIAogICAgICAiQ29uZ​Gl0aW9uIjp7IAogICAgICA​gICAiSXBBZGRyZXNzIj​p7IkFXUzpTb3VyY2V​JcCI6IjE0NS4xNjguMT​QzLjAvMjQifSwgCiAgI​CAgICAgICJEYX​RlTGVzc1RoYW4i​OnsiQVdTOkV​wb2NoVGltZSI6MTI1​ODIzNzIwMH0gICAg​ICAKICAgICAgfSA​KICAgfV0gCn0K

Following is the URL-safe signature.

Signature = cPFtRKvUfYNYmxek​6ZNs6vgKEZP6G3Cb4c​yVt~FjqbHOnMdxd​T7eT6pYmhHYzuDsFH4Jps​ctke2Ux6PCXcKx​UcTIm8SO4b29~1Q​vhMl-CIojki3Hd3~Unxjw​7Cpo1qRjtvrimW0DP​ZBZYHFZtiZXsaPt87​yBP9GWnTQo​aVysMxQ_

Following is the full URL for the end user.

http://d604721fxaaqy9.cloudfront.net/training/orientation.avi?Policy=eyAKICAg​IlN0YXRlbWVudCI6IFt​7IAogICAgICAiUmV​zb3VyY2UiOiJodHRw​Oi8vZDYwNDcyMWZ4Y​WFxeTkuY2xvdWRmcm9udC5u​ZXQvdHJhaW5pbmcv​KiIsIAogICAgICA​iQ29uZGl0aW9uIjp7IAog​ICAgICAgICAiSXBB​ZGRyZXNzIjp7IkF​XUzpTb3VyY2VJcCI​6IjE0NS4xNjguMT​QzLjAvMjQifSwgCiAgI​CAgICAgICJEYXRlTG​Vzc1RoYW4iOns​iQVdTOkVwb2NoVGlt​ZSI6MTI1ODIzNzIwM​H0gICAgICAKICAgI​CAgfSAKICAgfV0g​Cn0K&Signature=cPFtRKvUfYNYmxek6ZNs6v​gKEZP6G3Cb4cyVt~F​jqbHOnMdxdT7eT6p​YmhHYzuDsFH4Jpsctke2U​x6PCXcKxUcTIm8SO​4b29~1QvhMl-​CIojki3Hd3~Unxjw7​Cpo1qRjtvrimW0DPZ​BZYHFZtiZXsaPt87yBP9​GWnTQoaVysMxQ_&Key-Pair-Id=PK123456789754

Example Custom Policy 2

The following custom policy grants the IP address 216.98.35.1/32 access to all the objects belonging to any distribution that the specified key pair ID is associated with. The objects are available only between Thu, 30 Apr 2009 06:43:10 GMT and Fri, 16 Oct 2009 06:31:56 GMT.

Following is the original URL. It specifies a particular object (downloads/pictures.tgz), even though the policy covers potentially many.

http://d84l721fxaaqy9.cloudfront.net/downloads/pictures.tgz

Following is the raw policy to sign.

	Tip
	To make it easier to test your own code, you can get a soft copy of the following policy (zipped up in the CloudFront_PrivateContent_SignatureExamples.zip file). Note that the string used to calculate the signature includes the white space and line feeds shown in the policy.

RawPolicy = 
{ 
   "Statement": [{ 
      "Resource":"http://*",
      "Condition":{ 
         "IpAddress":{"AWS:SourceIp":"216.98.35.1/32"},
         "DateGreaterThan":{"AWS:EpochTime":1241073790},
         "DateLessThan":{"AWS:EpochTime":1255674716}
      } 
   }] 
}

Following is the URL-safe policy.

Policy = eyAKICAgIlN0YXRlbWVud​CI6IFt7IAogICAgICAiUmVzb​3VyY2UiOiJodHRwOi8​vKiIsIAogICAgICAiQ29uZGl0aW​9uIjp7IAogI​CAgICAgICAiSXBB​ZGRyZXNzIjp7IkFXU​zpTb3VyY2VJcCI6IjIx​Ni45OC4zNS4xL​zMyIn0sCiAgICAgICAg​ICJEYXRlR3JlYXRlclR​oYW4iOnsiQV​dTOkVwb2NoVGltZSI6MT​I0MTA3Mzc5MH0sC​iAgICAgICAgI​CJEYXRlTGVzc1Ro​YW4iOnsiQVdTOkVw​b2NoVGltZSI6MTI1NTY3​NDcxNn0KICAgIC​AgfSAKICAgfV0​gCn0K

Following is the URL-safe signature.

Signature = rc~5Qbbm8EJXjUTQ​6Cn0LAxR72g1​DOPrTmdtfbWVVgQN​w0q~KHUAmB​a2Zv1Wjj8dDET4XSL~My​h44CLQdu4d​OH~N9huH7QfPSR~O4tIOS1W​WcP~2JmtVPoQyLlE​c8YHRCuN3nVNZJ0​m4EZcXXNAS-0x6Zco​2SYx~hywTRxWR~5Q_

Following is the full URL for the end user.

http://d84l721fxaaqy9.cloudfront.net/downloads/pictures.tgz?Policy=eyAKICAgIlN0YXRlbWVudCI6IF​t7IAogICAgICAiUmVzb3​VyY2UiOiJodHRw​Oi8vKiIsIAogICAgICAiQ​29uZGl0aW9uIjp7​IAogICAgICAgICAiSXBBZGRyZX​NzIjp7IkFXUzpTb3Vy​Y2VJcCI6IjIxNi45OC​4zNS4xLzMyIn0sC​iAgICAgICAgICJEYXRlR3JlYXRl​clRoYW4iOnsiQVdTOk​Vwb2NoVGltZSI6MTI​0MTA3Mzc5MH0sCiAgI​CAgICAgICJEYXRlT​GVzc1RoYW4iOnsiQVdT​OkVwb2NoV​GltZSI6MTI1NTY3ND​cxNn0KICAgICAgfSAK​ICAgfV0gCn0K&Signature=rc~5Qbbm8EJX​jUTQ6Cn0LAxR72g1D​OPrTmdtfbWVVgQ​Nw0q~KHUAmBa2Zv1Wjj​8dDET4XSL~Myh44C​LQdu4dOH~N9huH7QfPSR~O4tIO​S1WWcP~2JmtVPoQ​yLlEc8YHRCuN3nVNZJ0​m4EZcXXNAS-0x6Zco2S​Yx~hywTRxWR~5Q_&Key-Pair-Id=PK123456789754