Using the SOAP API

Amazon EC2: API Version 2007-01-03

previous page next page

Using the SOAP API

WSDL and Schema Definitions

The Amazon EC2 web service can be accessed using the SOAP web services messaging protocol. This interface is described by a Web Services Description Language (WSDL) document which defines the operations and security model for the service. The WSDL references an XML Schema document which strictly defines the datatypes that may appear in SOAP requests and responses. For more information on WSDL and SOAP, please see the references in the section called “Additional Web Services References”.

All schemas have a version number. The version number appears in the URL of a schema file, and in a schema's target namespace. The latest version is 2007-01-03. Upgrading is made easy by differentiating requests based on the version number. In addition to the latest version, the service will support the older versions for some time. Once customer transition to the new version is complete, the older versions will be retired.

The Amazon EC2 services API WSDL can be found at URLs of the form 'http://ec2.amazonaws.com/doc/VERSION/ec2.wsdl' where VERSION indicates the version of the API. The current API version is 2007-01-03 and can thus be found at URL http://ec2.amazonaws.com/doc/2007-01-03/AmazonEC2.wsdl

Making Requests

The Amazon EC2 web service complies with the current WS-Security standard, requiring SOAP request messages to be hashed and signed for integrity and non-repudiation. WS-Security defines profiles which are used to implement various levels of security. Amazon EC2 secure SOAP messages use BinarySecurityToken profile, consisting of an X.509 certificate with an RSA public key.

Programming Language Support in Amazon EC2

Since the SOAP requests and responses in the Amazon EC2 Web Service follow current standards, any programming language with the appropriate library support may be used. Languages known to have such support include C++, C#, Java, Perl, Python and Ruby. Currently we only supply java libraries for our API but expect to release additional language bindings in the future.

Request Authentication

The following is an insecure request to run instances: 

<RunInstances xmlns="http://ec2.amazonaws.com/doc/2007-01-03">
    <instancesSet>
        <item>
            <imageId>ami-60a54009</imageId>
            <minCount>1</minCount>
            <maxCount>3</maxCount>
        </item>
    </instancesSet>
    <groupSet/>
</RunInstances>

In order to secure the request, we must add the BinarySecurityToken element mentioned above. The Java libraries we supply rely on the Apache Axis project for XML security, canonicalization and SOAP support. (The Sun Java Web Service Developer's Pack supplies libraries of equivalent functionality.)

The secure version of the request begins with the following: 

<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">....many, many lines of 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>

Let's take a quick look at the most important elements in case you are matching this against requests generated by Amazon EC2 supplied libraries, or those of another vendor.

  • BinarySecurityToken - contains the X.509 certificate in base64 encoded PEM format.

  • Signature - contains XML digital signature created using the canonicalization, signature algorithm, and digest method described within.

  • Timestamp - Any request is only valid to Amazon EC2 within 5 minutes of this value. Used to prevent replay attacks.

Understanding Responses

In response to a request, the Amazon EC2 web service returns an XML data structure that conforms to an XML schema defined as part of the Amazon EC2 WSDL. The structure of a XML response is specific to the associated request. In general, the response datatypes with be named according to the operation performed and whether the datatype is a container (may have children). Examples of containers include 'groupSet' for security groups and 'instancesSet' for instances. Item elements are children of containers and their contents vary according to the container's role.

An example response is: 

<RunInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2007-01-03">
  <reservationId>r-47a5402e</reservationId>
  <ownerId>UYY3TLBUXIEON5NQVUUX6OMPWBZIQNFM</ownerId>
  <groupSet>
    <item>
      <groupId>default</groupId>
    </item>
  </groupSet>
  <instancesSet>
    <item>
      <instanceId>i-2ba64342</instanceId>
      <imageId>ami-60a54009</imageId>
      <instanceState>
        <code>0</code>
    <name>pending</name>
      </instanceState>
      <dnsName></dnsName>
    </item>
    <item>
      <instanceId>i-2bc64242</instanceId>
      <imageId>ami-60a54009</imageId>
      <instanceState>
        <code>0</code>
    <name>pending</name>
      </instanceState>
      <dnsName>domU-13-35-33-00-00-5C.dc2.compute.amazonaws.com</dnsName>
    </item>
    <item>
      <instanceId>i-2be64332</instanceId>
      <imageId>ami-60a54009</imageId>
      <instanceState>
        <code>0</code>
    <name>pending</name>
      </instanceState>
      <dnsName>domU-12-34-28-00-00-5C.dc2.compute.amazonaws.com</dnsName>
    </item>
  </instancesSet>
</RunInstancesResponse>

Additional Web Services References

previous page start next page