SOAP with WS-Security

When using SOAP with WS-Security, you must use an X.509 certificate (as opposed to your AWS Secret Access Key) to sign the SOAP requests. 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, see 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 on the OASIS-Open web site).

You can use your own X.509 certificate or one generated by AWS. The procedures for uploading your own certificate to AWS and obtaining an AWS-generated certificate are described below. 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), which associates the certificate 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 self-signed certificates with no expiration time.

Each SOAP request must be signed with the private key associated with the X.509 certificate. You create the signature from several parts of the request itself. The parts you use vary depending on whether you're using HTTP or HTTPS to send the request:

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 example below 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 below 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>

Requirements for BinarySecurityToken and Signatures

	The EncodingType attribute for the BinarySecurityToken element must be http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary.
	The ValueType attribute for the BinarySecurityToken element must be http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3 or http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509PKIPathv1.
	The BinarySecurityToken element must contain the base64 encoding of the leaf X.509 certificate if the ValueType is #X509v3, or it must contain the base64 encoding of the full X.509 certificate chain if the ValueType is #X509PKIPathv1.
	The Algorithm attribute of the CanonicalizationMethod element must be http://www.w3.org/2001/10/xml-exc-c14n#.
	The Algorithm attribute of the SignatureMethod element must be http://www.w3.org/2000/09/xmldsig#rsa-sha1.
	The Algorithm attribute of the Transform element for each Reference element must be either http://www.w3.org/2001/10/xml-exc-c14n# or http://www.w3.org/TR/2001/REC-xml-c14n-20010315.
	The Algorithm attribute of the DigestMethod element for each Reference element must be http://www.w3.org/2000/09/xmldsig#sha1.
	The KeyInfo element must contain a SecurityTokenReference element. The SecurityTokenReference element must contain a Reference element with a URI attribute. The URI attribute must use a local particle reference to identify the BinarySecurityToken element that contains the X.509 certificate (for example: the URI attribute equals #CertId-1064304 in the example request above).
	You must include a wsu:Id attribute in any message elements that you sign. You can sign any SOAP header and the entire SOAP Body. Do not sign any other elements (such as children of the Body element). AWS ignores those elements for the purposes of signature validation, even if you include a wsu:ID attribute in them. If you sign elements that shouldn't be signed, the signature validation will fail.