Using SOAP with WS-Security

Product Advertising API: 2009-11-01

previous page next page

Using SOAP with WS-Security

WS-Security, which is officially called Web Services Security: SOAP Message Security, is an open standard published by OASIS that defines mechanisms for signing and encrypting SOAP messages. Product Advertising API supports version 1.0 of the WS-Security specification. For more information and a link to the WS-Security 1.0 specification, go to the OASIS-Open web site for WS-Security.

	Tip
	The easiest way to comply with the WS-Security requirements is to use a SOAP toolkit that supports WS-Security 1.0 and X.509 certificates.

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

X.509 Certificates

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
	Product Advertising API does not implement a full public key infrastructure. The certificate information is used only to authenticate requests to Product Advertising API. Product Advertising API 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.

Using Your Own Certificate

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.

To upload your own X.509 certificate

Go to the Amazon Web Services web site at http://aws.amazon.com.
Point to Your Web Services Account to display a list of options.
Click View Access Key Identifiers and log in to your AWS account.

The AWS Access Key Identifiers page is displayed.
Scroll down to the X.509 Certificate area of the page and click Upload.
Follow the instructions on the subsequent pages to upload your certificate.

Using a Certificate Generated by AWS

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.

To have AWS create an X.509 certificate for you

Go to the Amazon Web Services web site at http://aws.amazon.com.
Point to Your Web Services Account to display a list of options.
Click View Access Key Identifiers and log in to your AWS account.

The AWS Access Key Identifiers page is displayed.
Scroll down to the X.509 Certificate area of the page and click Create New.

The Create a New Certificate page is displayed.
Read the information on the page and click Yes to create your certificate.

The Create Success page is displayed.

Download your private key file and X.509 certificate file.

	Important
	Don't close the browser window before you download the certificate, otherwise you'll have to create a new certificate.

What Needs to Be Signed

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.

Example Request to Use When Troubleshooting

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 Algorithm="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 preceding example request).
	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.

previous page start next page