AWS ec2 documentation change
Summary
Complete restructuring of the document: Replaced service-specific API lists with general sections about required knowledge, available APIs, and common query parameters. Added important note about removal of HTTP reason-phrase and detailed tables for Signature Version 4/2 parameters.
Security assessment
The change adds detailed documentation about authentication parameters (X-Amz-Signature, SecurityToken, etc.) and signing methods, which are security features. However, there's no evidence of a specific security vulnerability being addressed. The note about HTTP reason-phrase removal is a compliance update (RFC7230) but doesn't indicate a security incident.
Diff
diff --git a/ec2/latest/devguide/ec2-low-level-api.md b/ec2/latest/devguide/ec2-low-level-api.md index 77b9a66d2..4fceab68f 100644 --- a//ec2/latest/devguide/ec2-low-level-api.md +++ b//ec2/latest/devguide/ec2-low-level-api.md @@ -7 +7 @@ -# Low-level API for Amazon EC2 +Required knowledgeAvailable APIs for Amazon EC2Common query parameters @@ -9 +9 @@ -The low-level API for Amazon EC2 is the protocol-level interface for Amazon EC2. When using the low-level API, you must format every HTTPS request correctly and add a valid digital signature to every request. For more information, see [Making requests to the Amazon EC2 API](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/making-api-requests.html) in the _Amazon EC2 API Reference_. Alternatively, you can use an AWS SDK, which constructs and signs the requests on your behalf. For more information, see [Using an AWS SDK](./sdk-general-information-section.html). +# Using the API for Amazon EC2 @@ -11 +11 @@ The low-level API for Amazon EC2 is the protocol-level interface for Amazon EC2. -The Amazon EC2 API consists of actions and data types for multiple services. To view the actions for each service, see the following pages in the _Amazon EC2 API Reference_. +###### Important @@ -13 +13 @@ The Amazon EC2 API consists of actions and data types for multiple services. To - * [AWS Client VPN actions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/OperationList-query-cvpn.html) +As of **October 14, 2022** , HTTP responses from the Amazon EC2 APIs no longer include a reason-phrase element. As recommended by [RFC7230](https://datatracker.ietf.org/doc/html/rfc7230#section-3.1.2), you should ensure that your applications do not make use of the reason-phrase content. Ensure that your applications use the 3-digit status-code element included in the HTTP response instead. @@ -15 +15 @@ The Amazon EC2 API consists of actions and data types for multiple services. To - * [Amazon EBS actions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/OperationList-query-ebs.html) +We provide the Query API for Amazon EC2, as well as software development kits (SDK) for AWS that enable you to access Amazon EC2 from your preferred programming language. For more information, see the [Amazon EC2 Developer Guide](https://docs.aws.amazon.com/ec2/latest/devguide/). @@ -17 +17 @@ The Amazon EC2 API consists of actions and data types for multiple services. To - * [Amazon EC2 actions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/OperationList-query-ec2.html) +###### Contents @@ -19 +19 @@ The Amazon EC2 API consists of actions and data types for multiple services. To - * [AWS Network Manager actions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/OperationList-query-networkmanager.html) + * Required knowledge @@ -21 +21 @@ The Amazon EC2 API consists of actions and data types for multiple services. To - * [AWS Nitro Enclaves actions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/operation-list-enclave.html) + * Available APIs for Amazon EC2 @@ -23 +23 @@ The Amazon EC2 API consists of actions and data types for multiple services. To - * [AWS Outposts actions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/operation-list-outposts.html) + * [Actions by service](./OperationList-query.html) @@ -25 +25 @@ The Amazon EC2 API consists of actions and data types for multiple services. To - * [AWS PrivateLink actions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/operation-list-privatelink.html) + * [Query requests](./Query-Requests.html) @@ -27 +27 @@ The Amazon EC2 API consists of actions and data types for multiple services. To - * [Recycle Bin actions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/operation-list-rbin.html) + * [CORS support](./cors-support.html) @@ -29 +29 @@ The Amazon EC2 API consists of actions and data types for multiple services. To - * [AWS Site-to-Site VPNactions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/OperationList-query-s2s.html) + * [VM Import Manifest](./manifest.html) @@ -31 +31 @@ The Amazon EC2 API consists of actions and data types for multiple services. To - * [AWS Transit Gateway actions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/operation-list-tgw.html) + * Common query parameters @@ -33 +33 @@ The Amazon EC2 API consists of actions and data types for multiple services. To - * [AWS Verified Access actions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/operation-list-verified-access.html) + * [Permissions](./ec2-api-permissions.html) @@ -35 +35 @@ The Amazon EC2 API consists of actions and data types for multiple services. To - * [VM Import/Export actions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/OperationList-query-vmie.html) + * [Troubleshooting API request errors](./query-api-troubleshooting.html) @@ -37 +37 @@ The Amazon EC2 API consists of actions and data types for multiple services. To - * [Amazon VPC actions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/OperationList-query-vpc.html) + * [Error codes](./errors-overview.html) @@ -39 +38,0 @@ The Amazon EC2 API consists of actions and data types for multiple services. To - * [Amazon VPC IPAM actions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/operation-list-ipam.html) @@ -41 +39,0 @@ The Amazon EC2 API consists of actions and data types for multiple services. To - * [AWS Wavelength actions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/operation-list-wavelength.html) @@ -43,0 +42 @@ The Amazon EC2 API consists of actions and data types for multiple services. To +## Required knowledge @@ -44,0 +44,66 @@ The Amazon EC2 API consists of actions and data types for multiple services. To +If you plan to access Amazon EC2 through an API, you should be familiar with the following: + + * XML + + * Web services + + * HTTP requests + + * One or more programming languages, such as Java, PHP, Perl, Python, Ruby, C#, or C++. + + + + +## Available APIs for Amazon EC2 + +The Amazon EC2 Query API provides HTTP or HTTPS requests that use the HTTP verb GET or POST and a Query parameter named `Action`. + +AWS provides libraries, sample code, tutorials, and other resources for software developers who prefer to build applications using language-specific APIs instead of submitting a request over HTTP or HTTPS. These libraries provide basic functions that automatically take care of tasks such as cryptographically signing your requests, retrying requests, and handling error responses, so that it is easier for you to get started. + +For more information, see [Create Amazon EC2 resources using an AWS SDK](https://docs.aws.amazon.com/ec2/latest/devguide/sdk-general-information-section.html) in the _Amazon EC2 Developer Guide_. + +## Common query parameters + +Most Amazon EC2 API actions support the parameters described in the following tables. The common parameters vary depending on whether you're using Signature Version 2 or Signature Version 4 to sign your requests. For more information, see [Signing AWS API requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) in the _IAM User Guide_. + +###### Contents + + * Parameters for Signature Version 4 + + * Parameters for Signature Version 2 + + + + +### Parameters for Signature Version 4 + +Name | Description | Required +---|---|--- +`Action` | The action to perform. Example: `RunInstances` | Yes +`Version` | The API version to use. | Yes +`X-Amz-Algorithm` | The hash algorithm you use to create the request signature. Example: `AWS4-HMAC-SHA256` | Yes +`X-Amz-Credential` | The credential scope for the request, in the format `access-key-ID`/`YYYYMMDD`/`region`/`service`/`aws4_request` Example: `AKIDEXAMPLE/20140707/us-east-1/ec2/aws4_request` | Yes +`X-Amz-Date` | The date and time at which the request is signed, in the format YYYYMMDDThhmmssZ. The date must match the date that's included in the credential scope for the `X-Amz-Credential` parameter, or the date used in an `Authorization` header (see the note below the table). Example: `20140707T150456Z` | Yes +`X-Amz-SignedHeaders` | The headers you are including as part of the request. At a minimum, you must include the `host` header. If you include an `x-amz-date` header in your request, you must include it in the list of signed headers. Example: `content-type;host;user-agent` | Yes +`X-Amz-Signature` | A signature derived from your secret access key. Example: `ced6826de92d2bdeed8f846f0bf508e8559example` | Yes +`X-Amz-Security-Token` | The temporary security token obtained through a call to AWS Security Token Service. Example: `AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/L` | No +`DryRun` | Checks whether you have the required permissions for the action, without actually making the request. If you have the required permissions, the request returns `DryRunOperation`; otherwise, it returns `UnauthorizedOperation`. | No + +The `X-Amz-Algorithm`, `X-Amz-Credential`, `X-Amz-SignedHeaders`, and `X-Amz-Signature` parameters can either be specified as separate parameters in the query string, or their values can be included in a single `Authorization` header. For more information, see [Signing AWS API requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) in the _IAM User Guide_. + +### Parameters for Signature Version 2 + +Name | Description | Required +---|---|--- +`Action` | The action to perform. Example: `RunInstances` | Yes +`Version` | The API version to use. | Yes +`AWSAccessKeyId` | The access key ID for the request sender. This identifies the account which will be charged for usage of the service. The account that's associated with the access key ID must be signed up for Amazon EC2, or the request isn't accepted. Example: `AKIAIOSFODNN7EXAMPLE` | Yes +`Expires` | The date and time at which the signature included in the request expires, in the format YYYY-MM-DDThh:mm:ssZ. For more information, see [ISO 8601](http://www.w3.org/TR/NOTE-datetime). Example: `2006-07-07T15:04:56Z` | Conditional. Requests must include either `Timestamp` or `Expires`, but cannot contain both. +`Timestamp` | The date and time at which the request is signed, in the format YYYY-MM-DDThh:mm:ssZ. For more information, see [ISO 8601](http://www.w3.org/TR/NOTE-datetime). Example: `2006-07-07T15:04:56Z` | Conditional. Requests must include either `Timestamp` or `Expires`, but cannot contain both. +`Signature` | The request signature. Example: `Qnpl4Qk/7tINHzfXCiT7VEXAMPLE` | Yes +`SignatureMethod` | The hash algorithm you use to create the request signature. Valid values: `HmacSHA256` | `HmacSHA1`. Example: `HmacSHA256` | Yes +`SignatureVersion` | The signature version you use to sign the request. Set this value to `2`. Example: `2` | Yes +`DryRun` | Checks whether you have the required permissions for the action, without actually making the request. If you have the required permissions, the request returns `DryRunOperation`; otherwise, it returns `UnauthorizedOperation`. | No +`SecurityToken` | The temporary security token obtained through a call to AWS Security Token Service. Example: `AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/L` | No + +Parameter values must be URL-encoded. This is true for any Query parameter passed to Amazon EC2 and is typically necessary in the `Signature` parameter. Some clients do this automatically, but this is not the norm. @@ -54 +119 @@ Using an AWS SDK -Console-to-Code +Actions by service