SOAP with WS-Security

For the purposes of request security and integrity, you must send all SOAP requests over HTTPS.

When using SOAP with WS-Security, you must use an X.509 certificate for authentication (as opposed to your AWS Secret Access Key). An X.509 certificate is a security token designed to carry a public key and bind that key to an identity. X.509 certificates are used in a public key infrastructure (PKI), which is a framework for allowing trusted third parties to vouch for a party's identity. PKIs are commonly used in situations that require authentication. For more information about PKIs and X.509 certificates, go to the techencyclopedia.com entries for digital certificate and PKI.

	Note
	AWS does not implement a full public key infrastructure. The certificate information is used only to authenticate requests to AWS. AWS uses X.509 certificates only as carriers for public keys and does not trust or use in any way any identity binding that might be included in an X.509 certificate.

The WS-Security 1.0 specification requires you to sign the SOAP message with the private key associated with the X.509 certificate and include the X.509 certificate in the SOAP message header. Specifically, you must represent the X.509 certificate as a BinarySecurityToken as described in the WS-Security X.509 token profile (also available if you go to the OASIS-Open web site).

You can use your own X.509 certificate or one generated by AWS. Following are the procedures for uploading your own certificate to AWS and obtaining an AWS-generated certificate. To obtain an X.509 certificate generated by an external certificate authority, follow the instructions provided by that CA.

If you have an X.509 certificate you want to use, you can upload the certificate to AWS (without the private key value). Uploading the certificate automatically associates it with your AWS account.

AWS accepts any syntactically and cryptographically valid X.509 certificate. Certificates can be self-signed or signed by any key. The certificate must be in Privacy Enhanced Mail (PEM) format and include a base64 encoded Distinguished Encoding Rules (DER) certificate body.

	Important
	When you upload the certificate, AWS checks the certificate's contents to confirm that the certificate has not expired. AWS doesn't check certificate revocation lists (CRLs) to determine if the certificate has been revoked, nor does AWS validate the certificate with a certificate authority (CA) or any trusted third parties.

If you don't already have an X.509 certificate, or if you want a new certificate to use with AWS, you can have AWS generate one and automatically associate it with your AWS account. Certificates generated by AWS are signed by an AWS internal certificate authority.

Each SOAP request must be signed with the private key associated with the X.509 certificate. To create the signature, you sign the Timestamp element, and if you're using WS-Addressing, we recommend you also sign the Action header element. In addition, you can optionally sign the Body and the To header element.

AWS requires request messages to expire so they can't be used in malicious replay attacks. The best practice for specifying the expiration of SOAP/WS-Security requests is to include a Timestamp element with an Expires child element. In this case, the message expires at the time established in the Expires element.

If no Timestamp element is present in the request, the request is rejected as invalid. If you include a Timestamp element with a Created child element but no Expires child element, the message expires 15 minutes after the value of the Created element.

The following example shows the initial portion of a SOAP request that uses WS-Security with an X.509 certificate. If you're using a SOAP toolkit that supports WS-Security and X.509 certificates, the toolkit constructs the request automatically for you, so you don't have to create a request like this yourself. The example is included here as a reference to use if you're troubleshooting authentication issues with your SOAP requests. Several requirements are listed following the example; the numbers highlight where in the example the requirements are satisfied.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header>
  <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">

  <wsse:BinarySecurityToken
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
     EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
     ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"
    wsu:Id="CertId-1064304">
        [Your base64 encoded X.509 certificate…]
  </wsse:BinarySecurityToken>


  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <ds:SignedInfo>
      <ds:CanonicalizationMethod  http://www.w3.org/2001/10/xml-exc-c14n#"></ds:CanonicalizationMethod>
      <ds:SignatureMethod  Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:SignatureMethod>

     <ds:Reference URI="#id-17984263">
        <ds:Transforms>
          <ds:Transform  Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform>
        </ds:Transforms>
        <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
        <ds:DigestValue>0pjZ1+TvgPf6uG7o+Yp3l2YdGZ4=</ds:DigestValue>
     </ds:Reference>

    <ds:Reference URI="#id-15778003">
      <ds:Transforms>
        <ds:Transform  Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform>
      </ds:Transforms>
      <ds:DigestMethod  Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
      <ds:DigestValue>HhRbxBBmc2OO348f8nLNZyo4AOM=</ds:DigestValue>
    </ds:Reference>

    </ds:SignedInfo>

    <ds:SignatureValue>bmVx24Qom4kd9QQtclxWIlgLk4QsQBPaKESi79x479xgbO9PEStXMiHZuBAi9luuKdNTcfQ8UE/d
       jjHKZKEQRCOlLVy0Dn5ZL1RlMHsv+OzJzzvIJFTq3LQKNrzJzsNe</ds:SignatureValue>

    <ds:KeyInfo Id="KeyId-17007273">
       <wsse:SecurityTokenReference
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" 
        wsu:Id="STRId-22438818">
        <wsse:Reference URI="#CertId-1064304"
           ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3">
        </wsse:Reference>
      </wsse:SecurityTokenReference>
    </ds:KeyInfo>

  </ds:Signature>


  <wsu:Timestamp
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" 
    wsu:Id="id-17984263">
    <wsu:Created>2006-06-09T10:57:35Z</wsu:Created>
    <wsu:Expires>2006-06-09T11:02:35Z</wsu:Expires>
  </wsu:Timestamp>

  </wsse:Security>
</SOAP-ENV:Header>