The BatchGetItem operation returns the attributes of one or more items\n from one or more tables. You identify requested items by primary key.
A single operation can retrieve up to 16 MB of data, which can contain as many as 100\n items. BatchGetItem returns a partial result if the response size limit is\n exceeded, the table's provisioned throughput is exceeded, more than 1MB per partition is requested,\n or an internal processing failure occurs. If a partial result is returned, the operation returns a value for\n UnprocessedKeys. You can use this value to retry the operation starting\n with the next item to get.
If you request more than 100 items, BatchGetItem returns a\n ValidationException with the message \"Too many items requested for\n the BatchGetItem call.\"
For example, if you ask to retrieve 100 items, but each individual item is 300 KB in\n size, the system returns 52 items (so as not to exceed the 16 MB limit). It also returns\n an appropriate UnprocessedKeys value so you can get the next page of\n results. If desired, your application can include its own logic to assemble the pages of\n results into one dataset.
If none of the items can be processed due to insufficient\n provisioned throughput on all of the tables in the request, then\n BatchGetItem returns a\n ProvisionedThroughputExceededException. If at least\n one of the items is successfully processed, then\n BatchGetItem completes successfully, while returning the keys of the\n unread items in UnprocessedKeys.
If DynamoDB returns any unprocessed items, you should retry the batch operation on\n those items. However, we strongly recommend that you use an exponential\n backoff algorithm. If you retry the batch operation immediately, the\n underlying read or write requests can still fail due to throttling on the individual\n tables. If you delay the batch operation using exponential backoff, the individual\n requests in the batch are much more likely to succeed.
\nFor more information, see Batch Operations and Error Handling in the Amazon DynamoDB\n Developer Guide.
\nBy default, BatchGetItem performs eventually consistent reads on every\n table in the request. If you want strongly consistent reads instead, you can set\n ConsistentRead to true for any or all tables.
In order to minimize response latency, BatchGetItem may retrieve items in\n parallel.
When designing your application, keep in mind that DynamoDB does not return items in\n any particular order. To help parse the response by item, include the primary key values\n for the items in your request in the ProjectionExpression parameter.
If a requested item does not exist, it is not returned in the result. Requests for\n nonexistent items consume the minimum read capacity units according to the type of read.\n For more information, see Working with Tables in the Amazon DynamoDB Developer\n Guide.
" + "smithy.api#documentation": "The BatchGetItem operation returns the attributes of one or more items\n from one or more tables. You identify requested items by primary key.
A single operation can retrieve up to 16 MB of data, which can contain as many as 100\n items. BatchGetItem returns a partial result if the response size limit is\n exceeded, the table's provisioned throughput is exceeded, more than 1MB per partition is requested,\n or an internal processing failure occurs. If a partial result is returned, the operation returns a value for\n UnprocessedKeys. You can use this value to retry the operation starting\n with the next item to get.
If you request more than 100 items, BatchGetItem returns a\n ValidationException with the message \"Too many items requested for\n the BatchGetItem call.\"
For example, if you ask to retrieve 100 items, but each individual item is 300 KB in\n size, the system returns 52 items (so as not to exceed the 16 MB limit). It also returns\n an appropriate UnprocessedKeys value so you can get the next page of\n results. If desired, your application can include its own logic to assemble the pages of\n results into one dataset.
If none of the items can be processed due to insufficient\n provisioned throughput on all of the tables in the request, then\n BatchGetItem returns a\n ProvisionedThroughputExceededException. If at least\n one of the items is successfully processed, then\n BatchGetItem completes successfully, while returning the keys of the\n unread items in UnprocessedKeys.
If DynamoDB returns any unprocessed items, you should retry the batch operation on\n those items. However, we strongly recommend that you use an exponential\n backoff algorithm. If you retry the batch operation immediately, the\n underlying read or write requests can still fail due to throttling on the individual\n tables. If you delay the batch operation using exponential backoff, the individual\n requests in the batch are much more likely to succeed.
\nFor more information, see Batch Operations and Error Handling in the Amazon DynamoDB\n Developer Guide.
\nBy default, BatchGetItem performs eventually consistent reads on every\n table in the request. If you want strongly consistent reads instead, you can set\n ConsistentRead to true for any or all tables.
In order to minimize response latency, BatchGetItem may retrieve items in\n parallel.
When designing your application, keep in mind that DynamoDB does not return items in\n any particular order. To help parse the response by item, include the primary key values\n for the items in your request in the ProjectionExpression parameter.
If a requested item does not exist, it is not returned in the result. Requests for\n nonexistent items consume the minimum read capacity units according to the type of read.\n For more information, see Working with Tables in the Amazon DynamoDB Developer\n Guide.
", + "smithy.api#examples": [ + { + "title": "To retrieve multiple items from a table", + "documentation": "This example reads multiple items from the Music table using a batch of three GetItem requests. Only the AlbumTitle attribute is returned.", + "input": { + "RequestItems": { + "Music": { + "Keys": [ + { + "Artist": { + "S": "No One You Know" + }, + "SongTitle": { + "S": "Call Me Today" + } + }, + { + "Artist": { + "S": "Acme Band" + }, + "SongTitle": { + "S": "Happy Day" + } + }, + { + "Artist": { + "S": "No One You Know" + }, + "SongTitle": { + "S": "Scared of My Shadow" + } + } + ], + "ProjectionExpression": "AlbumTitle" + } + } + }, + "output": { + "Responses": { + "Music": [ + { + "AlbumTitle": { + "S": "Somewhat Famous" + } + }, + { + "AlbumTitle": { + "S": "Blue Sky Blues" + } + }, + { + "AlbumTitle": { + "S": "Louder Than Ever" + } + } + ] + } + } + } + ] } }, "com.amazonaws.dynamodb#BatchGetItemInput": { @@ -1094,7 +1154,65 @@ "aws.api#clientDiscoveredEndpoint": { "required": false }, - "smithy.api#documentation": "The BatchWriteItem operation puts or deletes multiple items in one or\n more tables. A single call to BatchWriteItem can transmit up to 16MB of\n data over the network, consisting of up to 25 item put or delete operations. While\n individual items can be up to 400 KB once stored, it's important to note that an item's\n representation might be greater than 400KB while being sent in DynamoDB's JSON format\n for the API call. For more details on this distinction, see Naming Rules and Data Types.
\n BatchWriteItem cannot update items. If you perform a BatchWriteItem\n operation on an existing item, that item's values will be overwritten by the\n operation and it will appear like it was updated. To update items, we recommend you\n use the UpdateItem action.
The individual PutItem and DeleteItem operations specified\n in BatchWriteItem are atomic; however BatchWriteItem as a\n whole is not. If any requested operations fail because the table's provisioned\n throughput is exceeded or an internal processing failure occurs, the failed operations\n are returned in the UnprocessedItems response parameter. You can\n investigate and optionally resend the requests. Typically, you would call\n BatchWriteItem in a loop. Each iteration would check for unprocessed\n items and submit a new BatchWriteItem request with those unprocessed items\n until all items have been processed.
If none of the items can be processed due to insufficient\n provisioned throughput on all of the tables in the request, then\n BatchWriteItem returns a\n ProvisionedThroughputExceededException.
If DynamoDB returns any unprocessed items, you should retry the batch operation on\n those items. However, we strongly recommend that you use an exponential\n backoff algorithm. If you retry the batch operation immediately, the\n underlying read or write requests can still fail due to throttling on the individual\n tables. If you delay the batch operation using exponential backoff, the individual\n requests in the batch are much more likely to succeed.
\nFor more information, see Batch Operations and Error Handling in the Amazon DynamoDB\n Developer Guide.
\nWith BatchWriteItem, you can efficiently write or delete large amounts of\n data, such as from Amazon EMR, or copy data from another database into DynamoDB. In\n order to improve performance with these large-scale operations,\n BatchWriteItem does not behave in the same way as individual\n PutItem and DeleteItem calls would. For example, you\n cannot specify conditions on individual put and delete requests, and\n BatchWriteItem does not return deleted items in the response.
If you use a programming language that supports concurrency, you can use threads to\n write items in parallel. Your application must include the necessary logic to manage the\n threads. With languages that don't support threading, you must update or delete the\n specified items one at a time. In both situations, BatchWriteItem performs\n the specified put and delete operations in parallel, giving you the power of the thread\n pool approach without having to introduce complexity into your application.
Parallel processing reduces latency, but each specified put and delete request\n consumes the same number of write capacity units whether it is processed in parallel or\n not. Delete operations on nonexistent items consume one write capacity unit.
\nIf one or more of the following is true, DynamoDB rejects the entire batch write\n operation:
\nOne or more tables specified in the BatchWriteItem request does\n not exist.
Primary key attributes specified on an item in the request do not match those\n in the corresponding table's primary key schema.
\nYou try to perform multiple operations on the same item in the same\n BatchWriteItem request. For example, you cannot put and delete\n the same item in the same BatchWriteItem request.
Your request contains at least two items with identical hash and range keys\n (which essentially is two put operations).
\nThere are more than 25 requests in the batch.
\nAny individual item in a batch exceeds 400 KB.
\nThe total request size exceeds 16 MB.
\nThe BatchWriteItem operation puts or deletes multiple items in one or\n more tables. A single call to BatchWriteItem can transmit up to 16MB of\n data over the network, consisting of up to 25 item put or delete operations. While\n individual items can be up to 400 KB once stored, it's important to note that an item's\n representation might be greater than 400KB while being sent in DynamoDB's JSON format\n for the API call. For more details on this distinction, see Naming Rules and Data Types.
\n BatchWriteItem cannot update items. If you perform a BatchWriteItem\n operation on an existing item, that item's values will be overwritten by the\n operation and it will appear like it was updated. To update items, we recommend you\n use the UpdateItem action.
The individual PutItem and DeleteItem operations specified\n in BatchWriteItem are atomic; however BatchWriteItem as a\n whole is not. If any requested operations fail because the table's provisioned\n throughput is exceeded or an internal processing failure occurs, the failed operations\n are returned in the UnprocessedItems response parameter. You can\n investigate and optionally resend the requests. Typically, you would call\n BatchWriteItem in a loop. Each iteration would check for unprocessed\n items and submit a new BatchWriteItem request with those unprocessed items\n until all items have been processed.
If none of the items can be processed due to insufficient\n provisioned throughput on all of the tables in the request, then\n BatchWriteItem returns a\n ProvisionedThroughputExceededException.
If DynamoDB returns any unprocessed items, you should retry the batch operation on\n those items. However, we strongly recommend that you use an exponential\n backoff algorithm. If you retry the batch operation immediately, the\n underlying read or write requests can still fail due to throttling on the individual\n tables. If you delay the batch operation using exponential backoff, the individual\n requests in the batch are much more likely to succeed.
\nFor more information, see Batch Operations and Error Handling in the Amazon DynamoDB\n Developer Guide.
\nWith BatchWriteItem, you can efficiently write or delete large amounts of\n data, such as from Amazon EMR, or copy data from another database into DynamoDB. In\n order to improve performance with these large-scale operations,\n BatchWriteItem does not behave in the same way as individual\n PutItem and DeleteItem calls would. For example, you\n cannot specify conditions on individual put and delete requests, and\n BatchWriteItem does not return deleted items in the response.
If you use a programming language that supports concurrency, you can use threads to\n write items in parallel. Your application must include the necessary logic to manage the\n threads. With languages that don't support threading, you must update or delete the\n specified items one at a time. In both situations, BatchWriteItem performs\n the specified put and delete operations in parallel, giving you the power of the thread\n pool approach without having to introduce complexity into your application.
Parallel processing reduces latency, but each specified put and delete request\n consumes the same number of write capacity units whether it is processed in parallel or\n not. Delete operations on nonexistent items consume one write capacity unit.
\nIf one or more of the following is true, DynamoDB rejects the entire batch write\n operation:
\nOne or more tables specified in the BatchWriteItem request does\n not exist.
Primary key attributes specified on an item in the request do not match those\n in the corresponding table's primary key schema.
\nYou try to perform multiple operations on the same item in the same\n BatchWriteItem request. For example, you cannot put and delete\n the same item in the same BatchWriteItem request.
Your request contains at least two items with identical hash and range keys\n (which essentially is two put operations).
\nThere are more than 25 requests in the batch.
\nAny individual item in a batch exceeds 400 KB.
\nThe total request size exceeds 16 MB.
\nDeletes a single item in a table by primary key. You can perform a conditional delete\n operation that deletes the item if it exists, or if it has an expected attribute\n value.
\nIn addition to deleting an item, you can also return the item's attribute values in\n the same operation, using the ReturnValues parameter.
Unless you specify conditions, the DeleteItem is an idempotent operation;\n running it multiple times on the same item or attribute does not\n result in an error response.
Conditional deletes are useful for deleting items only if specific conditions are met.\n If those conditions are met, DynamoDB performs the delete. Otherwise, the item is not\n deleted.
" + "smithy.api#documentation": "Deletes a single item in a table by primary key. You can perform a conditional delete\n operation that deletes the item if it exists, or if it has an expected attribute\n value.
\nIn addition to deleting an item, you can also return the item's attribute values in\n the same operation, using the ReturnValues parameter.
Unless you specify conditions, the DeleteItem is an idempotent operation;\n running it multiple times on the same item or attribute does not\n result in an error response.
Conditional deletes are useful for deleting items only if specific conditions are met.\n If those conditions are met, DynamoDB performs the delete. Otherwise, the item is not\n deleted.
", + "smithy.api#examples": [ + { + "title": "To delete an item", + "documentation": "This example deletes an item from the Music table.", + "input": { + "TableName": "Music", + "Key": { + "Artist": { + "S": "No One You Know" + }, + "SongTitle": { + "S": "Scared of My Shadow" + } + } + }, + "output": { + "ConsumedCapacity": { + "CapacityUnits": 1, + "TableName": "Music" + } + } + } + ] } }, "com.amazonaws.dynamodb#DeleteItemInput": { @@ -2467,7 +2608,29 @@ "aws.api#clientDiscoveredEndpoint": { "required": false }, - "smithy.api#documentation": "The DeleteTable operation deletes a table and all of its items. After a\n DeleteTable request, the specified table is in the\n DELETING state until DynamoDB completes the deletion. If the table is\n in the ACTIVE state, you can delete it. If a table is in\n CREATING or UPDATING states, then DynamoDB returns a\n ResourceInUseException. If the specified table does not exist, DynamoDB\n returns a ResourceNotFoundException. If table is already in the\n DELETING state, no error is returned.
This operation only applies to Version 2019.11.21 (Current) \n of global tables.\n
\nDynamoDB might continue to accept data read and write operations, such as\n GetItem and PutItem, on a table in the\n DELETING state until the table deletion is complete.
When you delete a table, any indexes on that table are also deleted.
\nIf you have DynamoDB Streams enabled on the table, then the corresponding stream on\n that table goes into the DISABLED state, and the stream is automatically\n deleted after 24 hours.
Use the DescribeTable action to check the status of the table.
The DeleteTable operation deletes a table and all of its items. After a\n DeleteTable request, the specified table is in the\n DELETING state until DynamoDB completes the deletion. If the table is\n in the ACTIVE state, you can delete it. If a table is in\n CREATING or UPDATING states, then DynamoDB returns a\n ResourceInUseException. If the specified table does not exist, DynamoDB\n returns a ResourceNotFoundException. If table is already in the\n DELETING state, no error is returned.
This operation only applies to Version 2019.11.21 (Current) \n of global tables.\n
\nDynamoDB might continue to accept data read and write operations, such as\n GetItem and PutItem, on a table in the\n DELETING state until the table deletion is complete.
When you delete a table, any indexes on that table are also deleted.
\nIf you have DynamoDB Streams enabled on the table, then the corresponding stream on\n that table goes into the DISABLED state, and the stream is automatically\n deleted after 24 hours.
Use the DescribeTable action to check the status of the table.
Returns the current provisioned-capacity quotas for your Amazon Web Services account in\n a Region, both for the Region as a whole and for any one DynamoDB table that you create\n there.
\nWhen you establish an Amazon Web Services account, the account has initial quotas on\n the maximum read capacity units and write capacity units that you can provision across\n all of your DynamoDB tables in a given Region. Also, there are per-table\n quotas that apply when you create a table there. For more information, see Service,\n Account, and Table Quotas page in the Amazon DynamoDB\n Developer Guide.
\nAlthough you can increase these quotas by filing a case at Amazon Web Services Support Center, obtaining the\n increase is not instantaneous. The DescribeLimits action lets you write\n code to compare the capacity you are currently using to those quotas imposed by your\n account so that you have enough time to apply for an increase before you hit a\n quota.
For example, you could use one of the Amazon Web Services SDKs to do the\n following:
\nCall DescribeLimits for a particular Region to obtain your\n current account quotas on provisioned capacity there.
Create a variable to hold the aggregate read capacity units provisioned for\n all your tables in that Region, and one to hold the aggregate write capacity\n units. Zero them both.
\nCall ListTables to obtain a list of all your DynamoDB\n tables.
For each table name listed by ListTables, do the\n following:
Call DescribeTable with the table name.
Use the data returned by DescribeTable to add the read\n capacity units and write capacity units provisioned for the table itself\n to your variables.
If the table has one or more global secondary indexes (GSIs), loop\n over these GSIs and add their provisioned capacity values to your\n variables as well.
\nReport the account quotas for that Region returned by\n DescribeLimits, along with the total current provisioned\n capacity levels you have calculated.
This will let you see whether you are getting close to your account-level\n quotas.
\nThe per-table quotas apply only when you are creating a new table. They restrict the\n sum of the provisioned capacity of the new table itself and all its global secondary\n indexes.
\nFor existing tables and their GSIs, DynamoDB doesn't let you increase provisioned\n capacity extremely rapidly, but the only quota that applies is that the aggregate\n provisioned capacity over all your tables and GSIs cannot exceed either of the\n per-account quotas.
\n\n DescribeLimits should only be called periodically. You can expect\n throttling errors if you call it more than once in a minute.
The DescribeLimits Request element has no content.
Returns the current provisioned-capacity quotas for your Amazon Web Services account in\n a Region, both for the Region as a whole and for any one DynamoDB table that you create\n there.
\nWhen you establish an Amazon Web Services account, the account has initial quotas on\n the maximum read capacity units and write capacity units that you can provision across\n all of your DynamoDB tables in a given Region. Also, there are per-table\n quotas that apply when you create a table there. For more information, see Service,\n Account, and Table Quotas page in the Amazon DynamoDB\n Developer Guide.
\nAlthough you can increase these quotas by filing a case at Amazon Web Services Support Center, obtaining the\n increase is not instantaneous. The DescribeLimits action lets you write\n code to compare the capacity you are currently using to those quotas imposed by your\n account so that you have enough time to apply for an increase before you hit a\n quota.
For example, you could use one of the Amazon Web Services SDKs to do the\n following:
\nCall DescribeLimits for a particular Region to obtain your\n current account quotas on provisioned capacity there.
Create a variable to hold the aggregate read capacity units provisioned for\n all your tables in that Region, and one to hold the aggregate write capacity\n units. Zero them both.
\nCall ListTables to obtain a list of all your DynamoDB\n tables.
For each table name listed by ListTables, do the\n following:
Call DescribeTable with the table name.
Use the data returned by DescribeTable to add the read\n capacity units and write capacity units provisioned for the table itself\n to your variables.
If the table has one or more global secondary indexes (GSIs), loop\n over these GSIs and add their provisioned capacity values to your\n variables as well.
\nReport the account quotas for that Region returned by\n DescribeLimits, along with the total current provisioned\n capacity levels you have calculated.
This will let you see whether you are getting close to your account-level\n quotas.
\nThe per-table quotas apply only when you are creating a new table. They restrict the\n sum of the provisioned capacity of the new table itself and all its global secondary\n indexes.
\nFor existing tables and their GSIs, DynamoDB doesn't let you increase provisioned\n capacity extremely rapidly, but the only quota that applies is that the aggregate\n provisioned capacity over all your tables and GSIs cannot exceed either of the\n per-account quotas.
\n\n DescribeLimits should only be called periodically. You can expect\n throttling errors if you call it more than once in a minute.
The DescribeLimits Request element has no content.
The GetItem operation returns a set of attributes for the item with the\n given primary key. If there is no matching item, GetItem does not return\n any data and there will be no Item element in the response.
\n GetItem provides an eventually consistent read by default. If your\n application requires a strongly consistent read, set ConsistentRead to\n true. Although a strongly consistent read might take more time than an\n eventually consistent read, it always returns the last updated value.
The GetItem operation returns a set of attributes for the item with the\n given primary key. If there is no matching item, GetItem does not return\n any data and there will be no Item element in the response.
\n GetItem provides an eventually consistent read by default. If your\n application requires a strongly consistent read, set ConsistentRead to\n true. Although a strongly consistent read might take more time than an\n eventually consistent read, it always returns the last updated value.
Returns an array of table names associated with the current account and endpoint. The\n output from ListTables is paginated, with each page returning a maximum of\n 100 table names.
Creates a new item, or replaces an old item with a new item. If an item that has the\n same primary key as the new item already exists in the specified table, the new item\n completely replaces the existing item. You can perform a conditional put operation (add\n a new item if one with the specified primary key doesn't exist), or replace an existing\n item if it has certain attribute values. You can return the item's attribute values in\n the same operation, using the ReturnValues parameter.
When you add an item, the primary key attributes are the only required attributes.\n
\nEmpty String and Binary attribute values are allowed. Attribute values of type String\n and Binary must have a length greater than zero if the attribute is used as a key\n attribute for a table or index. Set type attributes cannot be empty.
\nInvalid Requests with empty values will be rejected with a\n ValidationException exception.
To prevent a new item from replacing an existing item, use a conditional\n expression that contains the attribute_not_exists function with the\n name of the attribute being used as the partition key for the table. Since every\n record must contain that attribute, the attribute_not_exists function\n will only succeed if no matching item exists.
For more information about PutItem, see Working with\n Items in the Amazon DynamoDB Developer Guide.
Creates a new item, or replaces an old item with a new item. If an item that has the\n same primary key as the new item already exists in the specified table, the new item\n completely replaces the existing item. You can perform a conditional put operation (add\n a new item if one with the specified primary key doesn't exist), or replace an existing\n item if it has certain attribute values. You can return the item's attribute values in\n the same operation, using the ReturnValues parameter.
When you add an item, the primary key attributes are the only required attributes.\n
\nEmpty String and Binary attribute values are allowed. Attribute values of type String\n and Binary must have a length greater than zero if the attribute is used as a key\n attribute for a table or index. Set type attributes cannot be empty.
\nInvalid Requests with empty values will be rejected with a\n ValidationException exception.
To prevent a new item from replacing an existing item, use a conditional\n expression that contains the attribute_not_exists function with the\n name of the attribute being used as the partition key for the table. Since every\n record must contain that attribute, the attribute_not_exists function\n will only succeed if no matching item exists.
For more information about PutItem, see Working with\n Items in the Amazon DynamoDB Developer Guide.
You must provide the name of the partition key attribute and a single value for that\n attribute. Query returns all items with that partition key value.\n Optionally, you can provide a sort key attribute and use a comparison operator to refine\n the search results.
Use the KeyConditionExpression parameter to provide a specific value for\n the partition key. The Query operation will return all of the items from\n the table or index with that partition key value. You can optionally narrow the scope of\n the Query operation by specifying a sort key value and a comparison\n operator in KeyConditionExpression. To further refine the\n Query results, you can optionally provide a\n FilterExpression. A FilterExpression determines which\n items within the results should be returned to you. All of the other results are\n discarded.
A Query operation always returns a result set. If no matching items are\n found, the result set will be empty. Queries that do not return results consume the\n minimum number of read capacity units for that type of read operation.
DynamoDB calculates the number of read capacity units consumed based on item\n size, not on the amount of data that is returned to an application. The number of\n capacity units consumed will be the same whether you request all of the attributes\n (the default behavior) or just some of them (using a projection expression). The\n number will also be the same whether or not you use a FilterExpression.\n
\n Query results are always sorted by the sort key value. If the data type of\n the sort key is Number, the results are returned in numeric order; otherwise, the\n results are returned in order of UTF-8 bytes. By default, the sort order is ascending.\n To reverse the order, set the ScanIndexForward parameter to false.
A single Query operation will read up to the maximum number of items set\n (if using the Limit parameter) or a maximum of 1 MB of data and then apply\n any filtering to the results using FilterExpression. If\n LastEvaluatedKey is present in the response, you will need to paginate\n the result set. For more information, see Paginating\n the Results in the Amazon DynamoDB Developer Guide.
\n FilterExpression is applied after a Query finishes, but before\n the results are returned. A FilterExpression cannot contain partition key\n or sort key attributes. You need to specify those attributes in the\n KeyConditionExpression.
A Query operation can return an empty result set and a\n LastEvaluatedKey if all the items read for the page of results are\n filtered out.
You can query a table, a local secondary index, or a global secondary index. For a\n query on a table or on a local secondary index, you can set the\n ConsistentRead parameter to true and obtain a strongly\n consistent result. Global secondary indexes support eventually consistent reads only, so\n do not specify ConsistentRead when querying a global secondary\n index.
The Scan operation returns one or more items and item attributes by\n accessing every item in a table or a secondary index. To have DynamoDB return fewer\n items, you can provide a FilterExpression operation.
If the total size of scanned items exceeds the maximum dataset size limit of 1 MB,\n the scan completes and results are returned to the user. The LastEvaluatedKey \n value is also returned and the requestor can use the LastEvaluatedKey to continue \n the scan in a subsequent operation. Each scan response also includes number of items that were \n scanned (ScannedCount) as part of the request. If using a FilterExpression, a scan result \n can result in no items meeting the criteria and the Count will result in zero. If \n you did not use a FilterExpression in the scan request, then Count is \n the same as ScannedCount.
\n Count and ScannedCount only return the count of items specific to a \n single scan request and, unless the table is less than 1MB, do not represent the total number \n of items in the table.\n
A single Scan operation first reads up to the maximum number of items set (if\n using the Limit parameter) or a maximum of 1 MB of data and then applies any\n filtering to the results if a FilterExpression is provided. If\n LastEvaluatedKey is present in the response, pagination is required to complete the\n full table scan. For more information, see Paginating the\n Results in the Amazon DynamoDB Developer Guide.
\n Scan operations proceed sequentially; however, for faster performance on\n a large table or secondary index, applications can request a parallel Scan\n operation by providing the Segment and TotalSegments\n parameters. For more information, see Parallel\n Scan in the Amazon DynamoDB Developer Guide.
By default, a Scan uses eventually consistent reads when accessing the items in a table. \n Therefore, the results from an eventually consistent Scan may not include the latest item \n changes at the time the scan iterates through each item in the table. If you require a strongly consistent \n read of each item as the scan iterates through the items in the table, you can set the ConsistentRead \n parameter to true. Strong consistency only relates to the consistency of the read at the item level.
\n DynamoDB does not provide snapshot isolation for a scan operation when the ConsistentRead \n parameter is set to true. Thus, a DynamoDB scan operation does not guarantee that all reads in a scan \n see a consistent snapshot of the table when the scan operation was requested.\n
Edits an existing item's attributes, or adds a new item to the table if it does not\n already exist. You can put, delete, or add attribute values. You can also perform a\n conditional update on an existing item (insert a new attribute name-value pair if it\n doesn't exist, or replace an existing name-value pair if it has certain expected\n attribute values).
\nYou can also return the item's attribute values in the same UpdateItem\n operation using the ReturnValues parameter.
Edits an existing item's attributes, or adds a new item to the table if it does not\n already exist. You can put, delete, or add attribute values. You can also perform a\n conditional update on an existing item (insert a new attribute name-value pair if it\n doesn't exist, or replace an existing name-value pair if it has certain expected\n attribute values).
\nYou can also return the item's attribute values in the same UpdateItem\n operation using the ReturnValues parameter.
(Interface and Gateway Load Balancer endpoints) The IDs of the subnets in which to create an endpoint\n network interface. For a Gateway Load Balancer endpoint, you can specify only one subnet.
", + "smithy.api#documentation": "(Interface and Gateway Load Balancer endpoints) The IDs of the subnets in which to create endpoint\n network interfaces. For a Gateway Load Balancer endpoint, you can specify only one subnet.
", "smithy.api#xmlName": "SubnetId" } }, "SecurityGroupIds": { "target": "com.amazonaws.ec2#VpcEndpointSecurityGroupIdList", "traits": { - "smithy.api#documentation": "(Interface endpoint) The IDs of the security groups to associate with the\n endpoint network interface. If this parameter is not specified, we use the default \n security group for the VPC.
", + "smithy.api#documentation": "(Interface endpoint) The IDs of the security groups to associate with the\n endpoint network interfaces. If this parameter is not specified, we use the default \n security group for the VPC.
", "smithy.api#xmlName": "SecurityGroupId" } }, @@ -20547,6 +20547,13 @@ "smithy.api#documentation": "The tags to associate with the endpoint.
", "smithy.api#xmlName": "TagSpecification" } + }, + "SubnetConfigurations": { + "target": "com.amazonaws.ec2#SubnetConfigurationsList", + "traits": { + "smithy.api#documentation": "The subnet configurations for the endpoint.
", + "smithy.api#xmlName": "SubnetConfiguration" + } } }, "traits": { @@ -22556,7 +22563,7 @@ "target": "com.amazonaws.ec2#DeleteKeyPairRequest" }, "output": { - "target": "smithy.api#Unit" + "target": "com.amazonaws.ec2#DeleteKeyPairResult" }, "traits": { "smithy.api#documentation": "Deletes the specified key pair, by removing the public key from Amazon EC2.
", @@ -22601,6 +22608,32 @@ "smithy.api#input": {} } }, + "com.amazonaws.ec2#DeleteKeyPairResult": { + "type": "structure", + "members": { + "Return": { + "target": "com.amazonaws.ec2#Boolean", + "traits": { + "aws.protocols#ec2QueryName": "Return", + "smithy.api#clientOptional": {}, + "smithy.api#default": false, + "smithy.api#documentation": "Is true if the request succeeds, and an error otherwise.
The ID of the key pair.
", + "smithy.api#xmlName": "keyPairId" + } + } + }, + "traits": { + "smithy.api#output": {} + } + }, "com.amazonaws.ec2#DeleteLaunchTemplate": { "type": "operation", "input": { @@ -51693,7 +51726,7 @@ } }, "PasswordData": { - "target": "com.amazonaws.ec2#String", + "target": "com.amazonaws.ec2#PasswordData", "traits": { "aws.protocols#ec2QueryName": "PasswordData", "smithy.api#documentation": "The password of the instance. Returns an empty string if the password is not\n available.
", @@ -63551,6 +63584,102 @@ "traits": { "smithy.api#enumValue": "m7i-flex.8xlarge" } + }, + "m7a_medium": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "m7a.medium" + } + }, + "m7a_large": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "m7a.large" + } + }, + "m7a_xlarge": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "m7a.xlarge" + } + }, + "m7a_2xlarge": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "m7a.2xlarge" + } + }, + "m7a_4xlarge": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "m7a.4xlarge" + } + }, + "m7a_8xlarge": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "m7a.8xlarge" + } + }, + "m7a_12xlarge": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "m7a.12xlarge" + } + }, + "m7a_16xlarge": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "m7a.16xlarge" + } + }, + "m7a_24xlarge": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "m7a.24xlarge" + } + }, + "m7a_32xlarge": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "m7a.32xlarge" + } + }, + "m7a_48xlarge": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "m7a.48xlarge" + } + }, + "m7a_metal_48xl": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "m7a.metal-48xl" + } + }, + "hpc7a_12xlarge": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "hpc7a.12xlarge" + } + }, + "hpc7a_24xlarge": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "hpc7a.24xlarge" + } + }, + "hpc7a_48xlarge": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "hpc7a.48xlarge" + } + }, + "hpc7a_96xlarge": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "hpc7a.96xlarge" + } } } }, @@ -75267,14 +75396,14 @@ "AddSecurityGroupIds": { "target": "com.amazonaws.ec2#VpcEndpointSecurityGroupIdList", "traits": { - "smithy.api#documentation": "(Interface endpoint) The IDs of the security groups to associate with the network interface.
", + "smithy.api#documentation": "(Interface endpoint) The IDs of the security groups to associate with the endpoint network interfaces.
", "smithy.api#xmlName": "AddSecurityGroupId" } }, "RemoveSecurityGroupIds": { "target": "com.amazonaws.ec2#VpcEndpointSecurityGroupIdList", "traits": { - "smithy.api#documentation": "(Interface endpoint) The IDs of the security groups to disassociate from the network interface.
", + "smithy.api#documentation": "(Interface endpoint) The IDs of the security groups to disassociate from the endpoint network interfaces.
", "smithy.api#xmlName": "RemoveSecurityGroupId" } }, @@ -75295,7 +75424,14 @@ "traits": { "smithy.api#clientOptional": {}, "smithy.api#default": false, - "smithy.api#documentation": "(Interface endpoint) Indicates whether a private hosted zone is associated with the\n VPC.
" + "smithy.api#documentation": "(Interface endpoint) Indicates whether a private hosted zone is associated with the VPC.
" + } + }, + "SubnetConfigurations": { + "target": "com.amazonaws.ec2#SubnetConfigurationsList", + "traits": { + "smithy.api#documentation": "The subnet configurations for the endpoint.
", + "smithy.api#xmlName": "SubnetConfiguration" } } }, @@ -79166,6 +79302,12 @@ } } }, + "com.amazonaws.ec2#PasswordData": { + "type": "string", + "traits": { + "smithy.api#sensitive": {} + } + }, "com.amazonaws.ec2#PathComponent": { "type": "structure", "members": { @@ -88936,7 +89078,7 @@ } }, "UploadPolicySignature": { - "target": "com.amazonaws.ec2#String", + "target": "com.amazonaws.ec2#S3StorageUploadPolicySignature", "traits": { "aws.protocols#ec2QueryName": "UploadPolicySignature", "smithy.api#documentation": "The signature of the JSON document.
", @@ -88948,6 +89090,12 @@ "smithy.api#documentation": "Describes the storage parameters for Amazon S3 and Amazon S3 buckets for an instance store-backed AMI.
" } }, + "com.amazonaws.ec2#S3StorageUploadPolicySignature": { + "type": "string", + "traits": { + "smithy.api#sensitive": {} + } + }, "com.amazonaws.ec2#SSEType": { "type": "enum", "members": { @@ -94270,6 +94418,41 @@ } } }, + "com.amazonaws.ec2#SubnetConfiguration": { + "type": "structure", + "members": { + "SubnetId": { + "target": "com.amazonaws.ec2#SubnetId", + "traits": { + "smithy.api#documentation": "The ID of the subnet.
" + } + }, + "Ipv4": { + "target": "com.amazonaws.ec2#String", + "traits": { + "smithy.api#documentation": "The IPv4 address to assign to the endpoint network interface in the subnet. You must provide \n an IPv4 address if the VPC endpoint supports IPv4.
\nIf you specify an IPv4 address when modifying a VPC endpoint, we replace the existing \n endpoint network interface with a new endpoint network interface with this IP address. \n This process temporarily disconnects the subnet and the VPC endpoint.
" + } + }, + "Ipv6": { + "target": "com.amazonaws.ec2#String", + "traits": { + "smithy.api#documentation": "The IPv6 address to assign to the endpoint network interface in the subnet. You must provide \n an IPv6 address if the VPC endpoint supports IPv6.
\nIf you specify an IPv6 address when modifying a VPC endpoint, we replace the existing \n endpoint network interface with a new endpoint network interface with this IP address. \n This process temporarily disconnects the subnet and the VPC endpoint.
" + } + } + }, + "traits": { + "smithy.api#documentation": "Describes the configuration of a subnet for a VPC endpoint.
" + } + }, + "com.amazonaws.ec2#SubnetConfigurationsList": { + "type": "list", + "member": { + "target": "com.amazonaws.ec2#SubnetConfiguration", + "traits": { + "smithy.api#xmlName": "item" + } + } + }, "com.amazonaws.ec2#SubnetId": { "type": "string" }, diff --git a/aws/sdk/aws-models/iam.json b/aws/sdk/aws-models/iam.json index d1b5c5e6220b86a98c7882e64b221b9e0fa4c6ca..8ad03eb52813f489eabca01610f5891b6c27fd01 100644 --- a/aws/sdk/aws-models/iam.json +++ b/aws/sdk/aws-models/iam.json @@ -588,52 +588,56 @@ "type": "error" }, { - "conditions": [], - "type": "tree", - "rules": [ + "conditions": [ { - "conditions": [ + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - true - ] - } - ], - "error": "Invalid Configuration: Dualstack and custom endpoint are not supported", - "type": "error" - }, - { - "conditions": [], - "endpoint": { - "url": { - "ref": "Endpoint" + "ref": "UseDualStack" }, - "properties": {}, - "headers": {} - }, - "type": "endpoint" + true + ] } - ] + ], + "error": "Invalid Configuration: Dualstack and custom endpoint are not supported", + "type": "error" + }, + { + "conditions": [], + "endpoint": { + "url": { + "ref": "Endpoint" + }, + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] }, { - "conditions": [], + "conditions": [ + { + "fn": "isSet", + "argv": [ + { + "ref": "Region" + } + ] + } + ], "type": "tree", "rules": [ { "conditions": [ { - "fn": "isSet", + "fn": "aws.partition", "argv": [ { "ref": "Region" } - ] + ], + "assign": "PartitionResult" } ], "type": "tree", @@ -641,597 +645,557 @@ { "conditions": [ { - "fn": "aws.partition", + "fn": "stringEquals", "argv": [ { - "ref": "Region" - } - ], - "assign": "PartitionResult" - } - ], - "type": "tree", - "rules": [ - { - "conditions": [ - { - "fn": "stringEquals", + "fn": "getAttr", "argv": [ { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "name" - ] + "ref": "PartitionResult" }, - "aws" + "name" ] }, + "aws" + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseFIPS" - }, - false - ] + "ref": "UseFIPS" }, + false + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - false - ] - } - ], - "endpoint": { - "url": "https://iam.amazonaws.com", - "properties": { - "authSchemes": [ - { - "name": "sigv4", - "signingName": "iam", - "signingRegion": "us-east-1" - } - ] + "ref": "UseDualStack" }, - "headers": {} - }, - "type": "endpoint" + false + ] + } + ], + "endpoint": { + "url": "https://iam.amazonaws.com", + "properties": { + "authSchemes": [ + { + "name": "sigv4", + "signingName": "iam", + "signingRegion": "us-east-1" + } + ] }, + "headers": {} + }, + "type": "endpoint" + }, + { + "conditions": [ { - "conditions": [ + "fn": "stringEquals", + "argv": [ { - "fn": "stringEquals", + "fn": "getAttr", "argv": [ { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "name" - ] + "ref": "PartitionResult" }, - "aws" + "name" ] }, + "aws" + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseFIPS" - }, - true - ] + "ref": "UseFIPS" }, + true + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - false - ] - } - ], - "endpoint": { - "url": "https://iam-fips.amazonaws.com", - "properties": { - "authSchemes": [ - { - "name": "sigv4", - "signingName": "iam", - "signingRegion": "us-east-1" - } - ] + "ref": "UseDualStack" }, - "headers": {} - }, - "type": "endpoint" + false + ] + } + ], + "endpoint": { + "url": "https://iam-fips.amazonaws.com", + "properties": { + "authSchemes": [ + { + "name": "sigv4", + "signingName": "iam", + "signingRegion": "us-east-1" + } + ] }, + "headers": {} + }, + "type": "endpoint" + }, + { + "conditions": [ { - "conditions": [ + "fn": "stringEquals", + "argv": [ { - "fn": "stringEquals", + "fn": "getAttr", "argv": [ { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "name" - ] + "ref": "PartitionResult" }, - "aws-cn" + "name" ] }, + "aws-cn" + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseFIPS" - }, - false - ] + "ref": "UseFIPS" }, + false + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - false - ] - } - ], - "endpoint": { - "url": "https://iam.cn-north-1.amazonaws.com.cn", - "properties": { - "authSchemes": [ - { - "name": "sigv4", - "signingName": "iam", - "signingRegion": "cn-north-1" - } - ] + "ref": "UseDualStack" }, - "headers": {} - }, - "type": "endpoint" + false + ] + } + ], + "endpoint": { + "url": "https://iam.cn-north-1.amazonaws.com.cn", + "properties": { + "authSchemes": [ + { + "name": "sigv4", + "signingName": "iam", + "signingRegion": "cn-north-1" + } + ] }, + "headers": {} + }, + "type": "endpoint" + }, + { + "conditions": [ { - "conditions": [ + "fn": "stringEquals", + "argv": [ { - "fn": "stringEquals", + "fn": "getAttr", "argv": [ { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "name" - ] + "ref": "PartitionResult" }, - "aws-us-gov" + "name" ] }, + "aws-us-gov" + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseFIPS" - }, - false - ] + "ref": "UseFIPS" }, + false + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - false - ] - } - ], - "endpoint": { - "url": "https://iam.us-gov.amazonaws.com", - "properties": { - "authSchemes": [ - { - "name": "sigv4", - "signingName": "iam", - "signingRegion": "us-gov-west-1" - } - ] + "ref": "UseDualStack" }, - "headers": {} - }, - "type": "endpoint" + false + ] + } + ], + "endpoint": { + "url": "https://iam.us-gov.amazonaws.com", + "properties": { + "authSchemes": [ + { + "name": "sigv4", + "signingName": "iam", + "signingRegion": "us-gov-west-1" + } + ] }, + "headers": {} + }, + "type": "endpoint" + }, + { + "conditions": [ { - "conditions": [ + "fn": "stringEquals", + "argv": [ { - "fn": "stringEquals", + "fn": "getAttr", "argv": [ { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "name" - ] + "ref": "PartitionResult" }, - "aws-us-gov" + "name" ] }, + "aws-us-gov" + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", + "ref": "UseFIPS" + }, + true + ] + }, + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseDualStack" + }, + false + ] + } + ], + "endpoint": { + "url": "https://iam.us-gov.amazonaws.com", + "properties": { + "authSchemes": [ + { + "name": "sigv4", + "signingName": "iam", + "signingRegion": "us-gov-west-1" + } + ] + }, + "headers": {} + }, + "type": "endpoint" + }, + { + "conditions": [ + { + "fn": "stringEquals", + "argv": [ + { + "fn": "getAttr", "argv": [ { - "ref": "UseFIPS" + "ref": "PartitionResult" }, - true + "name" ] }, + "aws-iso" + ] + }, + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseFIPS" + }, + false + ] + }, + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseDualStack" + }, + false + ] + } + ], + "endpoint": { + "url": "https://iam.us-iso-east-1.c2s.ic.gov", + "properties": { + "authSchemes": [ + { + "name": "sigv4", + "signingName": "iam", + "signingRegion": "us-iso-east-1" + } + ] + }, + "headers": {} + }, + "type": "endpoint" + }, + { + "conditions": [ + { + "fn": "stringEquals", + "argv": [ { - "fn": "booleanEquals", + "fn": "getAttr", "argv": [ { - "ref": "UseDualStack" + "ref": "PartitionResult" }, - false - ] - } - ], - "endpoint": { - "url": "https://iam.us-gov.amazonaws.com", - "properties": { - "authSchemes": [ - { - "name": "sigv4", - "signingName": "iam", - "signingRegion": "us-gov-west-1" - } + "name" ] }, - "headers": {} - }, - "type": "endpoint" + "aws-iso-b" + ] }, { - "conditions": [ + "fn": "booleanEquals", + "argv": [ { - "fn": "stringEquals", - "argv": [ - { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "name" - ] - }, - "aws-iso" - ] + "ref": "UseFIPS" }, + false + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseFIPS" - }, - false - ] + "ref": "UseDualStack" }, + false + ] + } + ], + "endpoint": { + "url": "https://iam.us-isob-east-1.sc2s.sgov.gov", + "properties": { + "authSchemes": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - false - ] + "name": "sigv4", + "signingName": "iam", + "signingRegion": "us-isob-east-1" } - ], - "endpoint": { - "url": "https://iam.us-iso-east-1.c2s.ic.gov", - "properties": { - "authSchemes": [ - { - "name": "sigv4", - "signingName": "iam", - "signingRegion": "us-iso-east-1" - } - ] + ] + }, + "headers": {} + }, + "type": "endpoint" + }, + { + "conditions": [ + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseFIPS" }, - "headers": {} - }, - "type": "endpoint" + true + ] }, + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseDualStack" + }, + true + ] + } + ], + "type": "tree", + "rules": [ { "conditions": [ { - "fn": "stringEquals", + "fn": "booleanEquals", "argv": [ + true, { "fn": "getAttr", "argv": [ { "ref": "PartitionResult" }, - "name" + "supportsFIPS" ] - }, - "aws-iso-b" - ] - }, - { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseFIPS" - }, - false - ] - }, - { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - false - ] - } - ], - "endpoint": { - "url": "https://iam.us-isob-east-1.sc2s.sgov.gov", - "properties": { - "authSchemes": [ - { - "name": "sigv4", - "signingName": "iam", - "signingRegion": "us-isob-east-1" } ] }, - "headers": {} - }, - "type": "endpoint" - }, - { - "conditions": [ - { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseFIPS" - }, - true - ] - }, { "fn": "booleanEquals", "argv": [ + true, { - "ref": "UseDualStack" - }, - true - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [ - { - "fn": "booleanEquals", - "argv": [ - true, - { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsFIPS" - ] - } - ] - }, - { - "fn": "booleanEquals", + "fn": "getAttr", "argv": [ - true, - { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsDualStack" - ] - } - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [], - "type": "tree", - "rules": [ { - "conditions": [], - "endpoint": { - "url": "https://iam-fips.{Region}.{PartitionResult#dualStackDnsSuffix}", - "properties": {}, - "headers": {} - }, - "type": "endpoint" - } + "ref": "PartitionResult" + }, + "supportsDualStack" ] } ] - }, + } + ], + "type": "tree", + "rules": [ { "conditions": [], - "error": "FIPS and DualStack are enabled, but this partition does not support one or both", - "type": "error" + "endpoint": { + "url": "https://iam-fips.{Region}.{PartitionResult#dualStackDnsSuffix}", + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] }, + { + "conditions": [], + "error": "FIPS and DualStack are enabled, but this partition does not support one or both", + "type": "error" + } + ] + }, + { + "conditions": [ + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseFIPS" + }, + true + ] + } + ], + "type": "tree", + "rules": [ { "conditions": [ { "fn": "booleanEquals", "argv": [ + true, { - "ref": "UseFIPS" - }, - true - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [ - { - "fn": "booleanEquals", + "fn": "getAttr", "argv": [ - true, { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsFIPS" - ] - } - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [], - "type": "tree", - "rules": [ - { - "conditions": [], - "endpoint": { - "url": "https://iam-fips.{Region}.{PartitionResult#dnsSuffix}", - "properties": {}, - "headers": {} - }, - "type": "endpoint" - } + "ref": "PartitionResult" + }, + "supportsFIPS" ] } ] - }, + } + ], + "type": "tree", + "rules": [ { "conditions": [], - "error": "FIPS is enabled but this partition does not support FIPS", - "type": "error" + "endpoint": { + "url": "https://iam-fips.{Region}.{PartitionResult#dnsSuffix}", + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] }, + { + "conditions": [], + "error": "FIPS is enabled but this partition does not support FIPS", + "type": "error" + } + ] + }, + { + "conditions": [ + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseDualStack" + }, + true + ] + } + ], + "type": "tree", + "rules": [ { "conditions": [ { "fn": "booleanEquals", "argv": [ + true, { - "ref": "UseDualStack" - }, - true - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [ - { - "fn": "booleanEquals", + "fn": "getAttr", "argv": [ - true, - { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsDualStack" - ] - } - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [], - "type": "tree", - "rules": [ { - "conditions": [], - "endpoint": { - "url": "https://iam.{Region}.{PartitionResult#dualStackDnsSuffix}", - "properties": {}, - "headers": {} - }, - "type": "endpoint" - } + "ref": "PartitionResult" + }, + "supportsDualStack" ] } ] - }, - { - "conditions": [], - "error": "DualStack is enabled but this partition does not support DualStack", - "type": "error" } - ] - }, - { - "conditions": [], + ], "type": "tree", "rules": [ { "conditions": [], "endpoint": { - "url": "https://iam.{Region}.{PartitionResult#dnsSuffix}", + "url": "https://iam.{Region}.{PartitionResult#dualStackDnsSuffix}", "properties": {}, "headers": {} }, "type": "endpoint" } ] + }, + { + "conditions": [], + "error": "DualStack is enabled but this partition does not support DualStack", + "type": "error" } ] + }, + { + "conditions": [], + "endpoint": { + "url": "https://iam.{Region}.{PartitionResult#dnsSuffix}", + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] - }, - { - "conditions": [], - "error": "Invalid Configuration: Missing Region", - "type": "error" } ] + }, + { + "conditions": [], + "error": "Invalid Configuration: Missing Region", + "type": "error" } ] }, @@ -1978,7 +1942,17 @@ } ], "traits": { - "smithy.api#documentation": "Adds a new client ID (also known as audience) to the list of client IDs already\n registered for the specified IAM OpenID Connect (OIDC) provider resource.
\nThis operation is idempotent; it does not fail or return an error if you add an\n existing client ID to the provider.
" + "smithy.api#documentation": "Adds a new client ID (also known as audience) to the list of client IDs already\n registered for the specified IAM OpenID Connect (OIDC) provider resource.
\nThis operation is idempotent; it does not fail or return an error if you add an\n existing client ID to the provider.
", + "smithy.api#examples": [ + { + "title": "To add a client ID (audience) to an Open-ID Connect (OIDC) provider", + "documentation": "The following add-client-id-to-open-id-connect-provider command adds the client ID my-application-ID to the OIDC provider named server.example.com:", + "input": { + "ClientID": "my-application-ID", + "OpenIDConnectProviderArn": "arn:aws:iam::123456789012:oidc-provider/server.example.com" + } + } + ] } }, "com.amazonaws.iam#AddClientIDToOpenIDConnectProviderRequest": { @@ -2029,7 +2003,17 @@ } ], "traits": { - "smithy.api#documentation": "Adds the specified IAM role to the specified instance profile. An instance profile\n can contain only one role, and this quota cannot be increased. You can remove the\n existing role and then add a different role to an instance profile. You must then wait\n for the change to appear across all of Amazon Web Services because of eventual\n consistency. To force the change, you must disassociate the instance profile and then associate the\n instance profile, or you can stop your instance and then restart it.
\nThe caller of this operation must be granted the PassRole permission\n on the IAM role by a permissions policy.
For more information about roles, see IAM roles in the\n IAM User Guide. For more information about instance profiles,\n see Using\n instance profiles in the IAM User Guide.
" + "smithy.api#documentation": "Adds the specified IAM role to the specified instance profile. An instance profile\n can contain only one role, and this quota cannot be increased. You can remove the\n existing role and then add a different role to an instance profile. You must then wait\n for the change to appear across all of Amazon Web Services because of eventual\n consistency. To force the change, you must disassociate the instance profile and then associate the\n instance profile, or you can stop your instance and then restart it.
\nThe caller of this operation must be granted the PassRole permission\n on the IAM role by a permissions policy.
For more information about roles, see IAM roles in the\n IAM User Guide. For more information about instance profiles,\n see Using\n instance profiles in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To add a role to an instance profile", + "documentation": "The following command adds the role named S3Access to the instance profile named Webserver:", + "input": { + "RoleName": "S3Access", + "InstanceProfileName": "Webserver" + } + } + ] } }, "com.amazonaws.iam#AddRoleToInstanceProfileRequest": { @@ -2074,7 +2058,17 @@ } ], "traits": { - "smithy.api#documentation": "Adds the specified user to the specified group.
" + "smithy.api#documentation": "Adds the specified user to the specified group.
", + "smithy.api#examples": [ + { + "title": "To add a user to an IAM group", + "documentation": "The following command adds an IAM user named Bob to the IAM group named Admins:", + "input": { + "UserName": "Bob", + "GroupName": "Admins" + } + } + ] } }, "com.amazonaws.iam#AddUserToGroupRequest": { @@ -2131,7 +2125,17 @@ } ], "traits": { - "smithy.api#documentation": "Attaches the specified managed policy to the specified IAM group.
\nYou use this operation to attach a managed policy to a group. To embed an inline\n policy in a group, use \n PutGroupPolicy\n .
As a best practice, you can validate your IAM policies. \n To learn more, see Validating IAM policies \n in the IAM User Guide.
\nFor more information about policies, see Managed policies and inline\n policies in the IAM User Guide.
" + "smithy.api#documentation": "Attaches the specified managed policy to the specified IAM group.
\nYou use this operation to attach a managed policy to a group. To embed an inline\n policy in a group, use \n PutGroupPolicy\n .
As a best practice, you can validate your IAM policies. \n To learn more, see Validating IAM policies \n in the IAM User Guide.
\nFor more information about policies, see Managed policies and inline\n policies in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To attach a managed policy to an IAM group", + "documentation": "The following command attaches the AWS managed policy named ReadOnlyAccess to the IAM group named Finance.", + "input": { + "GroupName": "Finance", + "PolicyArn": "arn:aws:iam::aws:policy/ReadOnlyAccess" + } + } + ] } }, "com.amazonaws.iam#AttachGroupPolicyRequest": { @@ -2185,7 +2189,17 @@ } ], "traits": { - "smithy.api#documentation": "Attaches the specified managed policy to the specified IAM role. When you attach a\n managed policy to a role, the managed policy becomes part of the role's permission\n (access) policy.
\nYou cannot use a managed policy as the role's trust policy. The role's trust\n policy is created at the same time as the role, using \n CreateRole\n . You can update a role's trust policy using\n \n UpdateAssumerolePolicy\n .
Use this operation to attach a managed policy to a role. To embed\n an inline policy in a role, use \n PutRolePolicy\n . For more information about policies, see Managed\n policies and inline policies in the\n IAM User Guide.
As a best practice, you can validate your IAM policies. \n To learn more, see Validating IAM policies \n in the IAM User Guide.
" + "smithy.api#documentation": "Attaches the specified managed policy to the specified IAM role. When you attach a\n managed policy to a role, the managed policy becomes part of the role's permission\n (access) policy.
\nYou cannot use a managed policy as the role's trust policy. The role's trust\n policy is created at the same time as the role, using \n CreateRole\n . You can update a role's trust policy using\n \n UpdateAssumerolePolicy\n .
Use this operation to attach a managed policy to a role. To embed\n an inline policy in a role, use \n PutRolePolicy\n . For more information about policies, see Managed\n policies and inline policies in the\n IAM User Guide.
As a best practice, you can validate your IAM policies. \n To learn more, see Validating IAM policies \n in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To attach a managed policy to an IAM role", + "documentation": "The following command attaches the AWS managed policy named ReadOnlyAccess to the IAM role named ReadOnlyRole.", + "input": { + "RoleName": "ReadOnlyRole", + "PolicyArn": "arn:aws:iam::aws:policy/ReadOnlyAccess" + } + } + ] } }, "com.amazonaws.iam#AttachRolePolicyRequest": { @@ -2236,7 +2250,17 @@ } ], "traits": { - "smithy.api#documentation": "Attaches the specified managed policy to the specified user.
\nYou use this operation to attach a managed policy to a user. To\n embed an inline policy in a user, use \n PutUserPolicy\n .
As a best practice, you can validate your IAM policies. \n To learn more, see Validating IAM policies \n in the IAM User Guide.
\nFor more information about policies, see Managed policies and inline\n policies in the IAM User Guide.
" + "smithy.api#documentation": "Attaches the specified managed policy to the specified user.
\nYou use this operation to attach a managed policy to a user. To\n embed an inline policy in a user, use \n PutUserPolicy\n .
As a best practice, you can validate your IAM policies. \n To learn more, see Validating IAM policies \n in the IAM User Guide.
\nFor more information about policies, see Managed policies and inline\n policies in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To attach a managed policy to an IAM user", + "documentation": "The following command attaches the AWS managed policy named AdministratorAccess to the IAM user named Alice.", + "input": { + "UserName": "Alice", + "PolicyArn": "arn:aws:iam::aws:policy/AdministratorAccess" + } + } + ] } }, "com.amazonaws.iam#AttachUserPolicyRequest": { @@ -2362,7 +2386,17 @@ } ], "traits": { - "smithy.api#documentation": "Changes the password of the IAM user who is calling this operation. This operation\n can be performed using the CLI, the Amazon Web Services API, or the My\n Security Credentials page in the Amazon Web Services Management Console. The Amazon Web Services account root user password is\n not affected by this operation.
\nUse UpdateLoginProfile to use the CLI, the Amazon Web Services API, or the\n Users page in the IAM console to change the\n password for any IAM user. For more information about modifying passwords, see Managing\n passwords in the IAM User Guide.
" + "smithy.api#documentation": "Changes the password of the IAM user who is calling this operation. This operation\n can be performed using the CLI, the Amazon Web Services API, or the My\n Security Credentials page in the Amazon Web Services Management Console. The Amazon Web Services account root user password is\n not affected by this operation.
\nUse UpdateLoginProfile to use the CLI, the Amazon Web Services API, or the\n Users page in the IAM console to change the\n password for any IAM user. For more information about modifying passwords, see Managing\n passwords in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To change the password for your IAM user", + "documentation": "The following command changes the password for the current IAM user.", + "input": { + "NewPassword": "]35d/{pB9Fo9wJ", + "OldPassword": "3s0K_;xh4~8XXI" + } + } + ] } }, "com.amazonaws.iam#ChangePasswordRequest": { @@ -2566,7 +2600,25 @@ } ], "traits": { - "smithy.api#documentation": " Creates a new Amazon Web Services secret access key and corresponding Amazon Web Services access key ID for the\n specified user. The default status for new keys is Active.
If you do not specify a user name, IAM determines the user name implicitly based on\n the Amazon Web Services access key ID signing the request. This operation works for access keys under\n the Amazon Web Services account. Consequently, you can use this operation to manage Amazon Web Services account root\n user credentials. This is true even if the Amazon Web Services account has no associated users.
\nFor information about quotas on the number of keys you can create, see IAM and STS\n quotas in the IAM User Guide.
\nTo ensure the security of your Amazon Web Services account, the secret access key is accessible\n only during key and user creation. You must save the key (for example, in a text\n file) if you want to be able to access it again. If a secret key is lost, you can\n delete the access keys for the associated user and then create new keys.
\n Creates a new Amazon Web Services secret access key and corresponding Amazon Web Services access key ID for the\n specified user. The default status for new keys is Active.
If you do not specify a user name, IAM determines the user name implicitly based on\n the Amazon Web Services access key ID signing the request. This operation works for access keys under\n the Amazon Web Services account. Consequently, you can use this operation to manage Amazon Web Services account root\n user credentials. This is true even if the Amazon Web Services account has no associated users.
\nFor information about quotas on the number of keys you can create, see IAM and STS\n quotas in the IAM User Guide.
\nTo ensure the security of your Amazon Web Services account, the secret access key is accessible\n only during key and user creation. You must save the key (for example, in a text\n file) if you want to be able to access it again. If a secret key is lost, you can\n delete the access keys for the associated user and then create new keys.
\nCreates an alias for your Amazon Web Services account. For information about using an Amazon Web Services account\n alias, see Creating, deleting, and\n listing an Amazon Web Services account alias in the Amazon Web Services Sign-In User\n Guide.
" + "smithy.api#documentation": "Creates an alias for your Amazon Web Services account. For information about using an Amazon Web Services account\n alias, see Creating, deleting, and\n listing an Amazon Web Services account alias in the Amazon Web Services Sign-In User\n Guide.
", + "smithy.api#examples": [ + { + "title": "To create an account alias", + "documentation": "The following command associates the alias examplecorp to your AWS account.", + "input": { + "AccountAlias": "examplecorp" + } + } + ] } }, "com.amazonaws.iam#CreateAccountAliasRequest": { @@ -2663,7 +2724,25 @@ } ], "traits": { - "smithy.api#documentation": "Creates a new group.
\nFor information about the number of groups you can create, see IAM and STS\n quotas in the IAM User Guide.
" + "smithy.api#documentation": "Creates a new group.
\nFor information about the number of groups you can create, see IAM and STS\n quotas in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To create an IAM group", + "documentation": "The following command creates an IAM group named Admins.", + "input": { + "GroupName": "Admins" + }, + "output": { + "Group": { + "Path": "/", + "CreateDate": "2015-03-09T20:30:24.940Z", + "GroupId": "AIDGPMS9RO4H3FEXAMPLE", + "Arn": "arn:aws:iam::123456789012:group/Admins", + "GroupName": "Admins" + } + } + } + ] } }, "com.amazonaws.iam#CreateGroupRequest": { @@ -2729,7 +2808,26 @@ } ], "traits": { - "smithy.api#documentation": "Creates a new instance profile. For information about instance profiles, see Using\n roles for applications on Amazon EC2 in the\n IAM User Guide, and Instance profiles in the Amazon EC2 User Guide.
\nFor information about the number of instance profiles you can create, see IAM object\n quotas in the IAM User Guide.
" + "smithy.api#documentation": "Creates a new instance profile. For information about instance profiles, see Using\n roles for applications on Amazon EC2 in the\n IAM User Guide, and Instance profiles in the Amazon EC2 User Guide.
\nFor information about the number of instance profiles you can create, see IAM object\n quotas in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To create an instance profile", + "documentation": "The following command creates an instance profile named Webserver that is ready to have a role attached and then be associated with an EC2 instance.", + "input": { + "InstanceProfileName": "Webserver" + }, + "output": { + "InstanceProfile": { + "InstanceProfileId": "AIPAJMBYC7DLSPEXAMPLE", + "Roles": [], + "CreateDate": "2015-03-09T20:33:19.626Z", + "InstanceProfileName": "Webserver", + "Path": "/", + "Arn": "arn:aws:iam::123456789012:instance-profile/Webserver" + } + } + } + ] } }, "com.amazonaws.iam#CreateInstanceProfileRequest": { @@ -2801,7 +2899,25 @@ } ], "traits": { - "smithy.api#documentation": "Creates a password for the specified IAM user. A password allows an IAM user to\n access Amazon Web Services services through the Amazon Web Services Management Console.
\nYou can use the CLI, the Amazon Web Services API, or the Users\n page in the IAM console to create a password for any IAM user. Use ChangePassword to update your own existing password in the My Security Credentials page in the Amazon Web Services Management Console.
\nFor more information about managing passwords, see Managing passwords in the\n IAM User Guide.
" + "smithy.api#documentation": "Creates a password for the specified IAM user. A password allows an IAM user to\n access Amazon Web Services services through the Amazon Web Services Management Console.
\nYou can use the CLI, the Amazon Web Services API, or the Users\n page in the IAM console to create a password for any IAM user. Use ChangePassword to update your own existing password in the My Security Credentials page in the Amazon Web Services Management Console.
\nFor more information about managing passwords, see Managing passwords in the\n IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To create an instance profile", + "documentation": "The following command changes IAM user Bob's password and sets the flag that required Bob to change the password the next time he signs in.", + "input": { + "UserName": "Bob", + "Password": "h]6EszR}vJ*m", + "PasswordResetRequired": true + }, + "output": { + "LoginProfile": { + "UserName": "Bob", + "CreateDate": "2015-03-10T20:55:40.274Z", + "PasswordResetRequired": true + } + } + } + ] } }, "com.amazonaws.iam#CreateLoginProfileRequest": { @@ -2875,7 +2991,25 @@ } ], "traits": { - "smithy.api#documentation": "Creates an IAM entity to describe an identity provider (IdP) that supports OpenID Connect (OIDC).
\nThe OIDC provider that you create with this operation can be used as a principal in a\n role's trust policy. Such a policy establishes a trust relationship between Amazon Web Services and\n the OIDC provider.
\nIf you are using an OIDC identity provider from Google, Facebook, or Amazon Cognito, you don't\n need to create a separate IAM identity provider. These OIDC identity providers are\n already built-in to Amazon Web Services and are available for your use. Instead, you can move directly\n to creating new roles using your identity provider. To learn more, see Creating\n a role for web identity or OpenID connect federation in the IAM\n User Guide.
\nWhen you create the IAM OIDC provider, you specify the following:
\nThe URL of the OIDC identity provider (IdP) to trust
\nA list of client IDs (also known as audiences) that identify the application\n or applications allowed to authenticate using the OIDC provider
\nA list of tags that are attached to the specified IAM OIDC provider
\nA list of thumbprints of one or more server certificates that the IdP\n uses
\nYou get all of this information from the OIDC IdP you want to use to access\n Amazon Web Services.
\nAmazon Web Services secures communication with some OIDC identity providers (IdPs) through our\n library of trusted root certificate authorities (CAs) instead of using a certificate\n thumbprint to verify your IdP server certificate. These OIDC IdPs include Auth0, GitHub,\n Google, and those that use an Amazon S3 bucket to host a JSON Web Key Set (JWKS) endpoint. In\n these cases, your legacy thumbprint remains in your configuration, but is no longer used\n for validation.
\nThe trust for the OIDC provider is derived from the IAM provider that this\n operation creates. Therefore, it is best to limit access to the CreateOpenIDConnectProvider operation to highly privileged\n users.
\nCreates an IAM entity to describe an identity provider (IdP) that supports OpenID Connect (OIDC).
\nThe OIDC provider that you create with this operation can be used as a principal in a\n role's trust policy. Such a policy establishes a trust relationship between Amazon Web Services and\n the OIDC provider.
\nIf you are using an OIDC identity provider from Google, Facebook, or Amazon Cognito, you don't\n need to create a separate IAM identity provider. These OIDC identity providers are\n already built-in to Amazon Web Services and are available for your use. Instead, you can move directly\n to creating new roles using your identity provider. To learn more, see Creating\n a role for web identity or OpenID connect federation in the IAM\n User Guide.
\nWhen you create the IAM OIDC provider, you specify the following:
\nThe URL of the OIDC identity provider (IdP) to trust
\nA list of client IDs (also known as audiences) that identify the application\n or applications allowed to authenticate using the OIDC provider
\nA list of tags that are attached to the specified IAM OIDC provider
\nA list of thumbprints of one or more server certificates that the IdP\n uses
\nYou get all of this information from the OIDC IdP you want to use to access\n Amazon Web Services.
\nAmazon Web Services secures communication with some OIDC identity providers (IdPs) through our\n library of trusted root certificate authorities (CAs) instead of using a certificate\n thumbprint to verify your IdP server certificate. These OIDC IdPs include Auth0, GitHub,\n Google, and those that use an Amazon S3 bucket to host a JSON Web Key Set (JWKS) endpoint. In\n these cases, your legacy thumbprint remains in your configuration, but is no longer used\n for validation.
\nThe trust for the OIDC provider is derived from the IAM provider that this\n operation creates. Therefore, it is best to limit access to the CreateOpenIDConnectProvider operation to highly privileged\n users.
\nCreates a new role for your Amazon Web Services account.
\nFor more information about roles, see IAM roles in the\n IAM User Guide. For information about quotas for role names\n and the number of roles you can create, see IAM and STS quotas in the\n IAM User Guide.
" + "smithy.api#documentation": "Creates a new role for your Amazon Web Services account.
\nFor more information about roles, see IAM roles in the\n IAM User Guide. For information about quotas for role names\n and the number of roles you can create, see IAM and STS quotas in the\n IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To create an IAM role", + "documentation": "The following command creates a role named Test-Role and attaches a trust policy that you must convert from JSON to a string. Upon success, the response includes the same policy as a URL-encoded JSON string.", + "input": { + "AssumeRolePolicyDocument": "Creates a new IAM user for your Amazon Web Services account.
\nFor information about quotas for the number of IAM users you can create, see IAM and STS\n quotas in the IAM User Guide.
" + "smithy.api#documentation": "Creates a new IAM user for your Amazon Web Services account.
\nFor information about quotas for the number of IAM users you can create, see IAM and STS\n quotas in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To create an IAM user", + "documentation": "The following create-user command creates an IAM user named Bob in the current account.", + "input": { + "UserName": "Bob" + }, + "output": { + "User": { + "UserName": "Bob", + "Path": "/", + "CreateDate": "2013-06-08T03:20:41.270Z", + "UserId": "AKIAIOSFODNN7EXAMPLE", + "Arn": "arn:aws:iam::123456789012:user/Bob" + } + } + } + ] } }, "com.amazonaws.iam#CreateUserRequest": { @@ -3671,7 +3844,17 @@ } ], "traits": { - "smithy.api#documentation": "Deletes the access key pair associated with the specified IAM user.
\nIf you do not specify a user name, IAM determines the user name implicitly based on\n the Amazon Web Services access key ID signing the request. This operation works for access keys under\n the Amazon Web Services account. Consequently, you can use this operation to manage Amazon Web Services account root\n user credentials even if the Amazon Web Services account has no associated users.
" + "smithy.api#documentation": "Deletes the access key pair associated with the specified IAM user.
\nIf you do not specify a user name, IAM determines the user name implicitly based on\n the Amazon Web Services access key ID signing the request. This operation works for access keys under\n the Amazon Web Services account. Consequently, you can use this operation to manage Amazon Web Services account root\n user credentials even if the Amazon Web Services account has no associated users.
", + "smithy.api#examples": [ + { + "title": "To delete an access key for an IAM user", + "documentation": "The following command deletes one access key (access key ID and secret access key) assigned to the IAM user named Bob.", + "input": { + "UserName": "Bob", + "AccessKeyId": "AKIDPMS9RO4H3FEXAMPLE" + } + } + ] } }, "com.amazonaws.iam#DeleteAccessKeyRequest": { @@ -3718,7 +3901,16 @@ } ], "traits": { - "smithy.api#documentation": "Deletes the specified Amazon Web Services account alias. For information about using an Amazon Web Services\n account alias, see Creating, deleting, and\n listing an Amazon Web Services account alias in the Amazon Web Services Sign-In User\n Guide.
" + "smithy.api#documentation": "Deletes the specified Amazon Web Services account alias. For information about using an Amazon Web Services\n account alias, see Creating, deleting, and\n listing an Amazon Web Services account alias in the Amazon Web Services Sign-In User\n Guide.
", + "smithy.api#examples": [ + { + "title": "To delete an account alias", + "documentation": "The following command removes the alias mycompany from the current AWS account:", + "input": { + "AccountAlias": "mycompany" + } + } + ] } }, "com.amazonaws.iam#DeleteAccountAliasRequest": { @@ -3756,7 +3948,13 @@ } ], "traits": { - "smithy.api#documentation": "Deletes the password policy for the Amazon Web Services account. There are no parameters.
" + "smithy.api#documentation": "Deletes the password policy for the Amazon Web Services account. There are no parameters.
", + "smithy.api#examples": [ + { + "title": "To delete the current account password policy", + "documentation": "The following command removes the password policy from the current AWS account:" + } + ] } }, "com.amazonaws.iam#DeleteConflictException": { @@ -3822,7 +4020,17 @@ } ], "traits": { - "smithy.api#documentation": "Deletes the specified inline policy that is embedded in the specified IAM\n group.
\nA group can also have managed policies attached to it. To detach a managed policy from\n a group, use DetachGroupPolicy. For more information about policies,\n refer to Managed policies and inline\n policies in the IAM User Guide.
" + "smithy.api#documentation": "Deletes the specified inline policy that is embedded in the specified IAM\n group.
\nA group can also have managed policies attached to it. To detach a managed policy from\n a group, use DetachGroupPolicy. For more information about policies,\n refer to Managed policies and inline\n policies in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To delete a policy from an IAM group", + "documentation": "The following command deletes the policy named ExamplePolicy from the group named Admins:", + "input": { + "GroupName": "Admins", + "PolicyName": "ExamplePolicy" + } + } + ] } }, "com.amazonaws.iam#DeleteGroupPolicyRequest": { @@ -3885,7 +4093,16 @@ } ], "traits": { - "smithy.api#documentation": "Deletes the specified instance profile. The instance profile must not have an\n associated role.
\nMake sure that you do not have any Amazon EC2 instances running with the instance\n profile you are about to delete. Deleting a role or instance profile that is\n associated with a running instance will break any applications running on the\n instance.
\nFor more information about instance profiles, see Using\n instance profiles in the IAM User Guide.
" + "smithy.api#documentation": "Deletes the specified instance profile. The instance profile must not have an\n associated role.
\nMake sure that you do not have any Amazon EC2 instances running with the instance\n profile you are about to delete. Deleting a role or instance profile that is\n associated with a running instance will break any applications running on the\n instance.
\nFor more information about instance profiles, see Using\n instance profiles in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To delete an instance profile", + "documentation": "The following command deletes the instance profile named ExampleInstanceProfile", + "input": { + "InstanceProfileName": "ExampleInstanceProfile" + } + } + ] } }, "com.amazonaws.iam#DeleteInstanceProfileRequest": { @@ -3926,7 +4143,16 @@ } ], "traits": { - "smithy.api#documentation": "Deletes the password for the specified IAM user, For more information, see Managing\n passwords for IAM users.
\nYou can use the CLI, the Amazon Web Services API, or the Users\n page in the IAM console to delete a password for any IAM user. You can use ChangePassword to update, but not delete, your own password in the\n My Security Credentials page in the\n Amazon Web Services Management Console.
\nDeleting a user's password does not prevent a user from accessing Amazon Web Services through\n the command line interface or the API. To prevent all user access, you must also\n either make any access keys inactive or delete them. For more information about\n making keys inactive or deleting them, see UpdateAccessKey and\n DeleteAccessKey.
\nDeletes the password for the specified IAM user, For more information, see Managing\n passwords for IAM users.
\nYou can use the CLI, the Amazon Web Services API, or the Users\n page in the IAM console to delete a password for any IAM user. You can use ChangePassword to update, but not delete, your own password in the\n My Security Credentials page in the\n Amazon Web Services Management Console.
\nDeleting a user's password does not prevent a user from accessing Amazon Web Services through\n the command line interface or the API. To prevent all user access, you must also\n either make any access keys inactive or delete them. For more information about\n making keys inactive or deleting them, see UpdateAccessKey and\n DeleteAccessKey.
\nDeletes the specified role. Unlike the Amazon Web Services Management Console, when you delete a role\n programmatically, you must delete the items attached to the role manually, or the\n deletion fails. For more information, see Deleting an IAM role. Before attempting to delete a role, remove the\n following attached items:
\nInline policies (DeleteRolePolicy)
\nAttached managed policies (DetachRolePolicy)
\nInstance profile (RemoveRoleFromInstanceProfile)
\nOptional – Delete instance profile after detaching from role for\n resource clean up (DeleteInstanceProfile)
\nMake sure that you do not have any Amazon EC2 instances running with the role you\n are about to delete. Deleting a role or instance profile that is associated with a\n running instance will break any applications running on the instance.
\nDeletes the specified role. Unlike the Amazon Web Services Management Console, when you delete a role\n programmatically, you must delete the items attached to the role manually, or the\n deletion fails. For more information, see Deleting an IAM role. Before attempting to delete a role, remove the\n following attached items:
\nInline policies (DeleteRolePolicy)
\nAttached managed policies (DetachRolePolicy)
\nInstance profile (RemoveRoleFromInstanceProfile)
\nOptional – Delete instance profile after detaching from role for\n resource clean up (DeleteInstanceProfile)
\nMake sure that you do not have any Amazon EC2 instances running with the role you\n are about to delete. Deleting a role or instance profile that is associated with a\n running instance will break any applications running on the instance.
\nDeletes the specified inline policy that is embedded in the specified IAM\n role.
\nA role can also have managed policies attached to it. To detach a managed policy from\n a role, use DetachRolePolicy. For more information about policies,\n refer to Managed policies and inline\n policies in the IAM User Guide.
" + "smithy.api#documentation": "Deletes the specified inline policy that is embedded in the specified IAM\n role.
\nA role can also have managed policies attached to it. To detach a managed policy from\n a role, use DetachRolePolicy. For more information about policies,\n refer to Managed policies and inline\n policies in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To remove a policy from an IAM role", + "documentation": "The following command removes the policy named ExamplePolicy from the role named Test-Role.", + "input": { + "RoleName": "Test-Role", + "PolicyName": "ExamplePolicy" + } + } + ] } }, "com.amazonaws.iam#DeleteRolePolicyRequest": { @@ -4445,7 +4690,17 @@ } ], "traits": { - "smithy.api#documentation": "Deletes a signing certificate associated with the specified IAM user.
\nIf you do not specify a user name, IAM determines the user name implicitly based on\n the Amazon Web Services access key ID signing the request. This operation works for access keys under\n the Amazon Web Services account. Consequently, you can use this operation to manage Amazon Web Services account root\n user credentials even if the Amazon Web Services account has no associated IAM users.
" + "smithy.api#documentation": "Deletes a signing certificate associated with the specified IAM user.
\nIf you do not specify a user name, IAM determines the user name implicitly based on\n the Amazon Web Services access key ID signing the request. This operation works for access keys under\n the Amazon Web Services account. Consequently, you can use this operation to manage Amazon Web Services account root\n user credentials even if the Amazon Web Services account has no associated IAM users.
", + "smithy.api#examples": [ + { + "title": "To delete a signing certificate for an IAM user", + "documentation": "The following command deletes the specified signing certificate for the IAM user named Anika.", + "input": { + "UserName": "Anika", + "CertificateId": "TA7SMP42TDN5Z26OBPJE7EXAMPLE" + } + } + ] } }, "com.amazonaws.iam#DeleteSigningCertificateRequest": { @@ -4495,7 +4750,16 @@ } ], "traits": { - "smithy.api#documentation": "Deletes the specified IAM user. Unlike the Amazon Web Services Management Console, when you delete a user\n programmatically, you must delete the items attached to the user manually, or the\n deletion fails. For more information, see Deleting an IAM\n user. Before attempting to delete a user, remove the following items:
\nPassword (DeleteLoginProfile)
\nAccess keys (DeleteAccessKey)
\nSigning certificate (DeleteSigningCertificate)
\nSSH public key (DeleteSSHPublicKey)
\nGit credentials (DeleteServiceSpecificCredential)
\nMulti-factor authentication (MFA) device (DeactivateMFADevice, DeleteVirtualMFADevice)
\nInline policies (DeleteUserPolicy)
\nAttached managed policies (DetachUserPolicy)
\nGroup memberships (RemoveUserFromGroup)
\nDeletes the specified IAM user. Unlike the Amazon Web Services Management Console, when you delete a user\n programmatically, you must delete the items attached to the user manually, or the\n deletion fails. For more information, see Deleting an IAM\n user. Before attempting to delete a user, remove the following items:
\nPassword (DeleteLoginProfile)
\nAccess keys (DeleteAccessKey)
\nSigning certificate (DeleteSigningCertificate)
\nSSH public key (DeleteSSHPublicKey)
\nGit credentials (DeleteServiceSpecificCredential)
\nMulti-factor authentication (MFA) device (DeactivateMFADevice, DeleteVirtualMFADevice)
\nInline policies (DeleteUserPolicy)
\nAttached managed policies (DetachUserPolicy)
\nGroup memberships (RemoveUserFromGroup)
\nDeletes the specified inline policy that is embedded in the specified IAM\n user.
\nA user can also have managed policies attached to it. To detach a managed policy from\n a user, use DetachUserPolicy. For more information about policies,\n refer to Managed policies and inline\n policies in the IAM User Guide.
" + "smithy.api#documentation": "Deletes the specified inline policy that is embedded in the specified IAM\n user.
\nA user can also have managed policies attached to it. To detach a managed policy from\n a user, use DetachUserPolicy. For more information about policies,\n refer to Managed policies and inline\n policies in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To remove a policy from an IAM user", + "documentation": "The following delete-user-policy command removes the specified policy from the IAM user named Juan:", + "input": { + "UserName": "Juan", + "PolicyName": "ExamplePolicy" + } + } + ] } }, "com.amazonaws.iam#DeleteUserPolicyRequest": { @@ -4619,7 +4893,16 @@ } ], "traits": { - "smithy.api#documentation": "Deletes a virtual MFA device.
\nYou must deactivate a user's virtual MFA device before you can delete it. For\n information about deactivating MFA devices, see DeactivateMFADevice.
\nDeletes a virtual MFA device.
\nYou must deactivate a user's virtual MFA device before you can delete it. For\n information about deactivating MFA devices, see DeactivateMFADevice.
\nGenerates a report for service last accessed data for Organizations. You can generate a\n report for any entities (organization root, organizational unit, or account) or policies\n in your organization.
\nTo call this operation, you must be signed in using your Organizations management account\n credentials. You can use your long-term IAM user or root user credentials, or temporary\n credentials from assuming an IAM role. SCPs must be enabled for your organization\n root. You must have the required IAM and Organizations permissions. For more information, see\n Refining permissions using service last accessed data in the\n IAM User Guide.
\nYou can generate a service last accessed data report for entities by specifying only\n the entity's path. This data includes a list of services that are allowed by any service\n control policies (SCPs) that apply to the entity.
\nYou can generate a service last accessed data report for a policy by specifying an\n entity's path and an optional Organizations policy ID. This data includes a list of services that\n are allowed by the specified SCP.
\nFor each service in both report types, the data includes the most recent account\n activity that the policy allows to account principals in the entity or the entity's\n children. For important information about the data, reporting period, permissions\n required, troubleshooting, and supported Regions see Reducing permissions using\n service last accessed data in the\n IAM User Guide.
\nThe data includes all attempts to access Amazon Web Services, not just the successful ones. This\n includes all attempts that were made using the Amazon Web Services Management Console, the Amazon Web Services API through any\n of the SDKs, or any of the command line tools. An unexpected entry in the service\n last accessed data does not mean that an account has been compromised, because the\n request might have been denied. Refer to your CloudTrail logs as the authoritative\n source for information about all API calls and whether they were successful or\n denied access. For more information, see Logging IAM events with\n CloudTrail in the IAM User Guide.
\nThis operation returns a JobId. Use this parameter in the \n GetOrganizationsAccessReport\n operation to check the status of\n the report generation. To check the status of this request, use the JobId\n parameter in the \n GetOrganizationsAccessReport\n operation\n and test the JobStatus response parameter. When the job is complete, you\n can retrieve the report.
To generate a service last accessed data report for entities, specify an entity path\n without specifying the optional Organizations policy ID. The type of entity that you specify\n determines the data returned in the report.
\n\n Root – When you specify the\n organizations root as the entity, the resulting report lists all of the services\n allowed by SCPs that are attached to your root. For each service, the report\n includes data for all accounts in your organization except the\n management account, because the management account is not limited by SCPs.
\n\n OU – When you specify an\n organizational unit (OU) as the entity, the resulting report lists all of the\n services allowed by SCPs that are attached to the OU and its parents. For each\n service, the report includes data for all accounts in the OU or its children.\n This data excludes the management account, because the management account is not\n limited by SCPs.
\n\n management account – When you specify the\n management account, the resulting report lists all Amazon Web Services services, because the\n management account is not limited by SCPs. For each service, the report includes\n data for only the management account.
\n\n Account – When you specify another\n account as the entity, the resulting report lists all of the services allowed by\n SCPs that are attached to the account and its parents. For each service, the\n report includes data for only the specified account.
\nTo generate a service last accessed data report for policies, specify an entity path\n and the optional Organizations policy ID. The type of entity that you specify determines the data\n returned for each service.
\n\n Root – When you specify the root\n entity and a policy ID, the resulting report lists all of the services that are\n allowed by the specified SCP. For each service, the report includes data for all\n accounts in your organization to which the SCP applies. This data excludes the\n management account, because the management account is not limited by SCPs. If the\n SCP is not attached to any entities in the organization, then the report will\n return a list of services with no data.
\n\n OU – When you specify an OU entity and\n a policy ID, the resulting report lists all of the services that are allowed by\n the specified SCP. For each service, the report includes data for all accounts\n in the OU or its children to which the SCP applies. This means that other\n accounts outside the OU that are affected by the SCP might not be included in\n the data. This data excludes the management account, because the\n management account is not limited by SCPs. If the SCP is not attached to the OU\n or one of its children, the report will return a list of services with no\n data.
\n\n management account – When you specify the\n management account, the resulting report lists all Amazon Web Services services, because the\n management account is not limited by SCPs. If you specify a policy ID in the CLI\n or API, the policy is ignored. For each service, the report includes data for\n only the management account.
\n\n Account – When you specify another\n account entity and a policy ID, the resulting report lists all of the services\n that are allowed by the specified SCP. For each service, the report includes\n data for only the specified account. This means that other accounts in the\n organization that are affected by the SCP might not be included in the data. If\n the SCP is not attached to the account, the report will return a list of\n services with no data.
\nService last accessed data does not use other policy types when determining\n whether a principal could access a service. These other policy types include\n identity-based policies, resource-based policies, access control lists, IAM\n permissions boundaries, and STS assume role policies. It only applies SCP logic.\n For more about the evaluation of policy types, see Evaluating policies in the\n IAM User Guide.
\nFor more information about service last accessed data, see Reducing policy scope by\n viewing user activity in the IAM User Guide.
" + "smithy.api#documentation": "Generates a report for service last accessed data for Organizations. You can generate a\n report for any entities (organization root, organizational unit, or account) or policies\n in your organization.
\nTo call this operation, you must be signed in using your Organizations management account\n credentials. You can use your long-term IAM user or root user credentials, or temporary\n credentials from assuming an IAM role. SCPs must be enabled for your organization\n root. You must have the required IAM and Organizations permissions. For more information, see\n Refining permissions using service last accessed data in the\n IAM User Guide.
\nYou can generate a service last accessed data report for entities by specifying only\n the entity's path. This data includes a list of services that are allowed by any service\n control policies (SCPs) that apply to the entity.
\nYou can generate a service last accessed data report for a policy by specifying an\n entity's path and an optional Organizations policy ID. This data includes a list of services that\n are allowed by the specified SCP.
\nFor each service in both report types, the data includes the most recent account\n activity that the policy allows to account principals in the entity or the entity's\n children. For important information about the data, reporting period, permissions\n required, troubleshooting, and supported Regions see Reducing permissions using\n service last accessed data in the\n IAM User Guide.
\nThe data includes all attempts to access Amazon Web Services, not just the successful ones. This\n includes all attempts that were made using the Amazon Web Services Management Console, the Amazon Web Services API through any\n of the SDKs, or any of the command line tools. An unexpected entry in the service\n last accessed data does not mean that an account has been compromised, because the\n request might have been denied. Refer to your CloudTrail logs as the authoritative\n source for information about all API calls and whether they were successful or\n denied access. For more information, see Logging IAM events with\n CloudTrail in the IAM User Guide.
\nThis operation returns a JobId. Use this parameter in the \n GetOrganizationsAccessReport\n operation to check the status of\n the report generation. To check the status of this request, use the JobId\n parameter in the \n GetOrganizationsAccessReport\n operation\n and test the JobStatus response parameter. When the job is complete, you\n can retrieve the report.
To generate a service last accessed data report for entities, specify an entity path\n without specifying the optional Organizations policy ID. The type of entity that you specify\n determines the data returned in the report.
\n\n Root – When you specify the\n organizations root as the entity, the resulting report lists all of the services\n allowed by SCPs that are attached to your root. For each service, the report\n includes data for all accounts in your organization except the\n management account, because the management account is not limited by SCPs.
\n\n OU – When you specify an\n organizational unit (OU) as the entity, the resulting report lists all of the\n services allowed by SCPs that are attached to the OU and its parents. For each\n service, the report includes data for all accounts in the OU or its children.\n This data excludes the management account, because the management account is not\n limited by SCPs.
\n\n management account – When you specify the\n management account, the resulting report lists all Amazon Web Services services, because the\n management account is not limited by SCPs. For each service, the report includes\n data for only the management account.
\n\n Account – When you specify another\n account as the entity, the resulting report lists all of the services allowed by\n SCPs that are attached to the account and its parents. For each service, the\n report includes data for only the specified account.
\nTo generate a service last accessed data report for policies, specify an entity path\n and the optional Organizations policy ID. The type of entity that you specify determines the data\n returned for each service.
\n\n Root – When you specify the root\n entity and a policy ID, the resulting report lists all of the services that are\n allowed by the specified SCP. For each service, the report includes data for all\n accounts in your organization to which the SCP applies. This data excludes the\n management account, because the management account is not limited by SCPs. If the\n SCP is not attached to any entities in the organization, then the report will\n return a list of services with no data.
\n\n OU – When you specify an OU entity and\n a policy ID, the resulting report lists all of the services that are allowed by\n the specified SCP. For each service, the report includes data for all accounts\n in the OU or its children to which the SCP applies. This means that other\n accounts outside the OU that are affected by the SCP might not be included in\n the data. This data excludes the management account, because the\n management account is not limited by SCPs. If the SCP is not attached to the OU\n or one of its children, the report will return a list of services with no\n data.
\n\n management account – When you specify the\n management account, the resulting report lists all Amazon Web Services services, because the\n management account is not limited by SCPs. If you specify a policy ID in the CLI\n or API, the policy is ignored. For each service, the report includes data for\n only the management account.
\n\n Account – When you specify another\n account entity and a policy ID, the resulting report lists all of the services\n that are allowed by the specified SCP. For each service, the report includes\n data for only the specified account. This means that other accounts in the\n organization that are affected by the SCP might not be included in the data. If\n the SCP is not attached to the account, the report will return a list of\n services with no data.
\nService last accessed data does not use other policy types when determining\n whether a principal could access a service. These other policy types include\n identity-based policies, resource-based policies, access control lists, IAM\n permissions boundaries, and STS assume role policies. It only applies SCP logic.\n For more about the evaluation of policy types, see Evaluating policies in the\n IAM User Guide.
\nFor more information about service last accessed data, see Reducing policy scope by\n viewing user activity in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To generate a service last accessed data report for an organizational unit", + "documentation": "The following operation generates a report for the organizational unit ou-rge0-awexample", + "input": { + "EntityPath": "o-a1b2c3d4e5/r-f6g7h8i9j0example/ou-1a2b3c-k9l8m7n6o5example" + }, + "output": { + "JobId": "examplea-1234-b567-cde8-90fg123abcd4" + } + } + ] } }, "com.amazonaws.iam#GenerateOrganizationsAccessReportRequest": { @@ -5298,7 +5593,19 @@ } ], "traits": { - "smithy.api#documentation": "Generates a report that includes details about when an IAM resource (user, group,\n role, or policy) was last used in an attempt to access Amazon Web Services services. Recent activity\n usually appears within four hours. IAM reports activity for at least the last 400\n days, or less if your Region began supporting this feature within the last year. For\n more information, see Regions where data is tracked.
\nThe service last accessed data includes all attempts to access an Amazon Web Services API, not\n just the successful ones. This includes all attempts that were made using the\n Amazon Web Services Management Console, the Amazon Web Services API through any of the SDKs, or any of the command line tools.\n An unexpected entry in the service last accessed data does not mean that your\n account has been compromised, because the request might have been denied. Refer to\n your CloudTrail logs as the authoritative source for information about all API calls\n and whether they were successful or denied access. For more information, see Logging\n IAM events with CloudTrail in the\n IAM User Guide.
\nThe GenerateServiceLastAccessedDetails operation returns a\n JobId. Use this parameter in the following operations to retrieve the\n following details from your report:
\n GetServiceLastAccessedDetails – Use this operation\n for users, groups, roles, or policies to list every Amazon Web Services service that the\n resource could access using permissions policies. For each service, the response\n includes information about the most recent access attempt.
\nThe JobId returned by\n GenerateServiceLastAccessedDetail must be used by the same role\n within a session, or by the same user when used to call\n GetServiceLastAccessedDetail.
\n GetServiceLastAccessedDetailsWithEntities – Use this\n operation for groups and policies to list information about the associated\n entities (users or roles) that attempted to access a specific Amazon Web Services service.\n
\nTo check the status of the GenerateServiceLastAccessedDetails request,\n use the JobId parameter in the same operations and test the\n JobStatus response parameter.
For additional information about the permissions policies that allow an identity\n (user, group, or role) to access specific services, use the ListPoliciesGrantingServiceAccess operation.
\nService last accessed data does not use other policy types when determining\n whether a resource could access a service. These other policy types include\n resource-based policies, access control lists, Organizations policies, IAM permissions\n boundaries, and STS assume role policies. It only applies permissions policy\n logic. For more about the evaluation of policy types, see Evaluating policies in the\n IAM User Guide.
\nFor more information about service and action last accessed data, see Reducing permissions using service last accessed data in the\n IAM User Guide.
" + "smithy.api#documentation": "Generates a report that includes details about when an IAM resource (user, group,\n role, or policy) was last used in an attempt to access Amazon Web Services services. Recent activity\n usually appears within four hours. IAM reports activity for at least the last 400\n days, or less if your Region began supporting this feature within the last year. For\n more information, see Regions where data is tracked.
\nThe service last accessed data includes all attempts to access an Amazon Web Services API, not\n just the successful ones. This includes all attempts that were made using the\n Amazon Web Services Management Console, the Amazon Web Services API through any of the SDKs, or any of the command line tools.\n An unexpected entry in the service last accessed data does not mean that your\n account has been compromised, because the request might have been denied. Refer to\n your CloudTrail logs as the authoritative source for information about all API calls\n and whether they were successful or denied access. For more information, see Logging\n IAM events with CloudTrail in the\n IAM User Guide.
\nThe GenerateServiceLastAccessedDetails operation returns a\n JobId. Use this parameter in the following operations to retrieve the\n following details from your report:
\n GetServiceLastAccessedDetails – Use this operation\n for users, groups, roles, or policies to list every Amazon Web Services service that the\n resource could access using permissions policies. For each service, the response\n includes information about the most recent access attempt.
\nThe JobId returned by\n GenerateServiceLastAccessedDetail must be used by the same role\n within a session, or by the same user when used to call\n GetServiceLastAccessedDetail.
\n GetServiceLastAccessedDetailsWithEntities – Use this\n operation for groups and policies to list information about the associated\n entities (users or roles) that attempted to access a specific Amazon Web Services service.\n
\nTo check the status of the GenerateServiceLastAccessedDetails request,\n use the JobId parameter in the same operations and test the\n JobStatus response parameter.
For additional information about the permissions policies that allow an identity\n (user, group, or role) to access specific services, use the ListPoliciesGrantingServiceAccess operation.
\nService last accessed data does not use other policy types when determining\n whether a resource could access a service. These other policy types include\n resource-based policies, access control lists, Organizations policies, IAM permissions\n boundaries, and STS assume role policies. It only applies permissions policy\n logic. For more about the evaluation of policy types, see Evaluating policies in the\n IAM User Guide.
\nFor more information about service and action last accessed data, see Reducing permissions using service last accessed data in the\n IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To generate a service last accessed data report for a policy", + "documentation": "The following operation generates a report for the policy: ExamplePolicy1", + "input": { + "Arn": "arn:aws:iam::123456789012:policy/ExamplePolicy1" + }, + "output": { + "JobId": "examplef-1305-c245-eba4-71fe298bcda7" + } + } + ] } }, "com.amazonaws.iam#GenerateServiceLastAccessedDetailsRequest": { @@ -5500,7 +5807,27 @@ } ], "traits": { - "smithy.api#documentation": "Retrieves the password policy for the Amazon Web Services account. This tells you the complexity\n requirements and mandatory rotation periods for the IAM user passwords in your account.\n For more information about using a password policy, see Managing an IAM password\n policy.
" + "smithy.api#documentation": "Retrieves the password policy for the Amazon Web Services account. This tells you the complexity\n requirements and mandatory rotation periods for the IAM user passwords in your account.\n For more information about using a password policy, see Managing an IAM password\n policy.
", + "smithy.api#examples": [ + { + "title": "To see the current account password policy", + "documentation": "The following command displays details about the password policy for the current AWS account.", + "output": { + "PasswordPolicy": { + "AllowUsersToChangePassword": false, + "RequireNumbers": true, + "RequireLowercaseCharacters": false, + "RequireUppercaseCharacters": false, + "MinimumPasswordLength": 8, + "RequireSymbols": true, + "ExpirePasswords": false, + "PasswordReusePrevention": 12, + "MaxPasswordAge": 90, + "HardExpiry": false + } + } + } + ] } }, "com.amazonaws.iam#GetAccountPasswordPolicyResponse": { @@ -5533,7 +5860,43 @@ } ], "traits": { - "smithy.api#documentation": "Retrieves information about IAM entity usage and IAM quotas in the Amazon Web Services\n account.
\nFor information about IAM quotas, see IAM and STS quotas in the\n IAM User Guide.
" + "smithy.api#documentation": "Retrieves information about IAM entity usage and IAM quotas in the Amazon Web Services\n account.
\nFor information about IAM quotas, see IAM and STS quotas in the\n IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To get information about IAM entity quotas and usage in the current account", + "documentation": "The following command returns information about the IAM entity quotas and usage in the current AWS account.", + "output": { + "SummaryMap": { + "Users": 27, + "UsersQuota": 5000, + "Groups": 15, + "GroupsQuota": 100, + "Policies": 8, + "PoliciesQuota": 1000, + "PolicySizeQuota": 5120, + "PolicyVersionsInUse": 22, + "PolicyVersionsInUseQuota": 10000, + "VersionsPerPolicyQuota": 5, + "ServerCertificates": 1, + "ServerCertificatesQuota": 20, + "UserPolicySizeQuota": 2048, + "GroupPolicySizeQuota": 5120, + "GroupsPerUserQuota": 10, + "GlobalEndpointTokenVersion": 2, + "SigningCertificatesPerUserQuota": 2, + "AccessKeysPerUserQuota": 2, + "MFADevices": 6, + "MFADevicesInUse": 3, + "AccountMFAEnabled": 0, + "AccountAccessKeysPresent": 1, + "AccountSigningCertificatesPresent": 0, + "AttachedPoliciesPerGroupQuota": 10, + "AttachedPoliciesPerRoleQuota": 10, + "AttachedPoliciesPerUserQuota": 10 + } + } + } + ] } }, "com.amazonaws.iam#GetAccountSummaryResponse": { @@ -5870,6 +6233,34 @@ ], "traits": { "smithy.api#documentation": "Retrieves information about the specified instance profile, including the instance\n profile's path, GUID, ARN, and role. For more information about instance profiles, see\n Using\n instance profiles in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To get information about an instance profile", + "documentation": "The following command gets information about the instance profile named ExampleInstanceProfile.", + "input": { + "InstanceProfileName": "ExampleInstanceProfile" + }, + "output": { + "InstanceProfile": { + "InstanceProfileId": "AID2MAB8DPLSRHEXAMPLE", + "Roles": [ + { + "AssumeRolePolicyDocument": "Retrieves the user name for the specified IAM user. A login profile is created when\n you create a password for the user to access the Amazon Web Services Management Console. If the user does not exist\n or does not have a password, the operation returns a 404 (NoSuchEntity)\n error.
If you create an IAM user with access to the console, the CreateDate\n reflects the date you created the initial password for the user.
If you create an IAM user with programmatic access, and then later add a password\n for the user to access the Amazon Web Services Management Console, the CreateDate reflects the initial\n password creation date. A user with programmatic access does not have a login profile\n unless you create a password for the user to access the Amazon Web Services Management Console.
Retrieves the user name for the specified IAM user. A login profile is created when\n you create a password for the user to access the Amazon Web Services Management Console. If the user does not exist\n or does not have a password, the operation returns a 404 (NoSuchEntity)\n error.
If you create an IAM user with access to the console, the CreateDate\n reflects the date you created the initial password for the user.
If you create an IAM user with programmatic access, and then later add a password\n for the user to access the Amazon Web Services Management Console, the CreateDate reflects the initial\n password creation date. A user with programmatic access does not have a login profile\n unless you create a password for the user to access the Amazon Web Services Management Console.
Retrieves the service last accessed data report for Organizations that was previously\n generated using the \n GenerateOrganizationsAccessReport\n \n operation. This operation retrieves the status of your report job and the report\n contents.
Depending on the parameters that you passed when you generated the report, the data\n returned could include different information. For details, see GenerateOrganizationsAccessReport.
\nTo call this operation, you must be signed in to the management account in your\n organization. SCPs must be enabled for your organization root. You must have permissions\n to perform this operation. For more information, see Refining permissions using\n service last accessed data in the\n IAM User Guide.
\nFor each service that principals in an account (root user, IAM users, or IAM roles)\n could access using SCPs, the operation returns details about the most recent access\n attempt. If there was no attempt, the service is listed without details about the most\n recent attempt to access the service. If the operation fails, it returns the reason that\n it failed.
\nBy default, the list is sorted by service namespace.
" + "smithy.api#documentation": "Retrieves the service last accessed data report for Organizations that was previously\n generated using the \n GenerateOrganizationsAccessReport\n \n operation. This operation retrieves the status of your report job and the report\n contents.
Depending on the parameters that you passed when you generated the report, the data\n returned could include different information. For details, see GenerateOrganizationsAccessReport.
\nTo call this operation, you must be signed in to the management account in your\n organization. SCPs must be enabled for your organization root. You must have permissions\n to perform this operation. For more information, see Refining permissions using\n service last accessed data in the\n IAM User Guide.
\nFor each service that principals in an account (root user, IAM users, or IAM roles)\n could access using SCPs, the operation returns details about the most recent access\n attempt. If there was no attempt, the service is listed without details about the most\n recent attempt to access the service. If the operation fails, it returns the reason that\n it failed.
\nBy default, the list is sorted by service namespace.
", + "smithy.api#examples": [ + { + "title": "To get details from a previously generated organizational unit report", + "documentation": "The following operation gets details about the report with the job ID: examplea-1234-b567-cde8-90fg123abcd4", + "input": { + "JobId": "examplea-1234-b567-cde8-90fg123abcd4" + }, + "output": { + "IsTruncated": false, + "JobCompletionDate": "2019-06-18T19:47:35.241Z", + "JobCreationDate": "2019-06-18T19:47:31.466Z", + "JobStatus": "COMPLETED", + "NumberOfServicesAccessible": 3, + "NumberOfServicesNotAccessed": 1, + "AccessDetails": [ + { + "EntityPath": "o-a1b2c3d4e5/r-f6g7h8i9j0example/ou-1a2b3c-k9l8m7n6o5example/111122223333", + "LastAuthenticatedTime": "2019-05-25T16:29:52Z", + "Region": "us-east-1", + "ServiceName": "Amazon DynamoDB", + "ServiceNamespace": "dynamodb", + "TotalAuthenticatedEntities": 2 + }, + { + "EntityPath": "o-a1b2c3d4e5/r-f6g7h8i9j0example/ou-1a2b3c-k9l8m7n6o5example/123456789012", + "LastAuthenticatedTime": "2019-06-15T13:12:06Z", + "Region": "us-east-1", + "ServiceName": "AWS Identity and Access Management", + "ServiceNamespace": "iam", + "TotalAuthenticatedEntities": 4 + }, + { + "ServiceName": "Amazon Simple Storage Service", + "ServiceNamespace": "s3", + "TotalAuthenticatedEntities": 0 + } + ] + } + } + ] } }, "com.amazonaws.iam#GetOrganizationsAccessReportRequest": { @@ -6389,6 +6835,30 @@ ], "traits": { "smithy.api#documentation": "Retrieves information about the specified role, including the role's path, GUID, ARN,\n and the role's trust policy that grants permission to assume the role. For more\n information about roles, see IAM roles in the\n IAM User Guide.
\nPolicies returned by this operation are URL-encoded compliant \n with RFC 3986. You can use a URL \n decoding method to convert the policy back to plain JSON text. For example, if you use Java, you \n can use the decode method of the java.net.URLDecoder utility class in \n the Java SDK. Other languages and SDKs provide similar functionality.
Retrieves a service last accessed report that was created using the\n GenerateServiceLastAccessedDetails operation. You can use the\n JobId parameter in GetServiceLastAccessedDetails to\n retrieve the status of your report job. When the report is complete, you can retrieve\n the generated report. The report includes a list of Amazon Web Services services that the resource\n (user, group, role, or managed policy) can access.
Service last accessed data does not use other policy types when determining\n whether a resource could access a service. These other policy types include\n resource-based policies, access control lists, Organizations policies, IAM permissions\n boundaries, and STS assume role policies. It only applies permissions policy\n logic. For more about the evaluation of policy types, see Evaluating policies in the\n IAM User Guide.
\nFor each service that the resource could access using permissions policies, the\n operation returns details about the most recent access attempt. If there was no attempt,\n the service is listed without details about the most recent attempt to access the\n service. If the operation fails, the GetServiceLastAccessedDetails\n operation returns the reason that it failed.
The GetServiceLastAccessedDetails operation returns a list of services.\n This list includes the number of entities that have attempted to access the service and\n the date and time of the last attempt. It also returns the ARN of the following entity,\n depending on the resource ARN that you used to generate the report:
\n User – Returns the user ARN that you\n used to generate the report
\n\n Group – Returns the ARN of the group\n member (user) that last attempted to access the service
\n\n Role – Returns the role ARN that you\n used to generate the report
\n\n Policy – Returns the ARN of the user\n or role that last used the policy to attempt to access the service
\nBy default, the list is sorted by service namespace.
\nIf you specified ACTION_LEVEL granularity when you generated the report,\n this operation returns service and action last accessed data. This includes the most\n recent access attempt for each tracked action within a service. Otherwise, this\n operation returns only service data.
For more information about service and action last accessed data, see Reducing permissions using service last accessed data in the\n IAM User Guide.
" + "smithy.api#documentation": "Retrieves a service last accessed report that was created using the\n GenerateServiceLastAccessedDetails operation. You can use the\n JobId parameter in GetServiceLastAccessedDetails to\n retrieve the status of your report job. When the report is complete, you can retrieve\n the generated report. The report includes a list of Amazon Web Services services that the resource\n (user, group, role, or managed policy) can access.
Service last accessed data does not use other policy types when determining\n whether a resource could access a service. These other policy types include\n resource-based policies, access control lists, Organizations policies, IAM permissions\n boundaries, and STS assume role policies. It only applies permissions policy\n logic. For more about the evaluation of policy types, see Evaluating policies in the\n IAM User Guide.
\nFor each service that the resource could access using permissions policies, the\n operation returns details about the most recent access attempt. If there was no attempt,\n the service is listed without details about the most recent attempt to access the\n service. If the operation fails, the GetServiceLastAccessedDetails\n operation returns the reason that it failed.
The GetServiceLastAccessedDetails operation returns a list of services.\n This list includes the number of entities that have attempted to access the service and\n the date and time of the last attempt. It also returns the ARN of the following entity,\n depending on the resource ARN that you used to generate the report:
\n User – Returns the user ARN that you\n used to generate the report
\n\n Group – Returns the ARN of the group\n member (user) that last attempted to access the service
\n\n Role – Returns the role ARN that you\n used to generate the report
\n\n Policy – Returns the ARN of the user\n or role that last used the policy to attempt to access the service
\nBy default, the list is sorted by service namespace.
\nIf you specified ACTION_LEVEL granularity when you generated the report,\n this operation returns service and action last accessed data. This includes the most\n recent access attempt for each tracked action within a service. Otherwise, this\n operation returns only service data.
For more information about service and action last accessed data, see Reducing permissions using service last accessed data in the\n IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To get details from a previously-generated report", + "documentation": "The following operation gets details about the report with the job ID: examplef-1305-c245-eba4-71fe298bcda7", + "input": { + "JobId": "examplef-1305-c245-eba4-71fe298bcda7" + }, + "output": { + "JobStatus": "COMPLETED", + "JobCreationDate": "2018-10-24T19:47:31.466Z", + "ServicesLastAccessed": [ + { + "TotalAuthenticatedEntities": 2, + "LastAuthenticated": "2018-10-24T19:11:00Z", + "ServiceNamespace": "iam", + "LastAuthenticatedEntity": "arn:aws:iam::123456789012:user/AWSExampleUser01", + "ServiceName": "AWS Identity and Access Management" + }, + { + "TotalAuthenticatedEntities": 0, + "ServiceNamespace": "s3", + "ServiceName": "Amazon Simple Storage Service" + } + ], + "JobCompletionDate": "2018-10-24T19:47:35.241Z", + "IsTruncated": false + } + } + ] } }, "com.amazonaws.iam#GetServiceLastAccessedDetailsRequest": { @@ -6827,7 +7326,44 @@ } ], "traits": { - "smithy.api#documentation": "After you generate a group or policy report using the\n GenerateServiceLastAccessedDetails operation, you can use the\n JobId parameter in\n GetServiceLastAccessedDetailsWithEntities. This operation retrieves the\n status of your report job and a list of entities that could have used group or policy\n permissions to access the specified service.
\n Group – For a group report, this\n operation returns a list of users in the group that could have used the group’s\n policies in an attempt to access the service.
\n\n Policy – For a policy report, this\n operation returns a list of entities (users or roles) that could have used the\n policy in an attempt to access the service.
\nYou can also use this operation for user or role reports to retrieve details about\n those entities.
\nIf the operation fails, the GetServiceLastAccessedDetailsWithEntities\n operation returns the reason that it failed.
By default, the list of associated entities is sorted by date, with the most recent\n access listed first.
" + "smithy.api#documentation": "After you generate a group or policy report using the\n GenerateServiceLastAccessedDetails operation, you can use the\n JobId parameter in\n GetServiceLastAccessedDetailsWithEntities. This operation retrieves the\n status of your report job and a list of entities that could have used group or policy\n permissions to access the specified service.
\n Group – For a group report, this\n operation returns a list of users in the group that could have used the group’s\n policies in an attempt to access the service.
\n\n Policy – For a policy report, this\n operation returns a list of entities (users or roles) that could have used the\n policy in an attempt to access the service.
\nYou can also use this operation for user or role reports to retrieve details about\n those entities.
\nIf the operation fails, the GetServiceLastAccessedDetailsWithEntities\n operation returns the reason that it failed.
By default, the list of associated entities is sorted by date, with the most recent\n access listed first.
", + "smithy.api#examples": [ + { + "title": "To get sntity details from a previously-generated report", + "documentation": "The following operation returns details about the entities that attempted to access the IAM service.", + "input": { + "JobId": "examplef-1305-c245-eba4-71fe298bcda7", + "ServiceNamespace": "iam" + }, + "output": { + "JobStatus": "COMPLETED", + "JobCreationDate": "2018-10-24T19:47:31.466Z", + "JobCompletionDate": "2018-10-24T19:47:35.241Z", + "EntityDetailsList": [ + { + "EntityInfo": { + "Id": "AIDAEX2EXAMPLEB6IGCDC", + "Name": "AWSExampleUser01", + "Type": "USER", + "Path": "/", + "Arn": "arn:aws:iam::123456789012:user/AWSExampleUser01" + }, + "LastAuthenticated": "2018-10-24T19:10:00Z" + }, + { + "EntityInfo": { + "Id": "AROAEAEXAMPLEIANXSIU4", + "Name": "AWSExampleRole01", + "Type": "ROLE", + "Path": "/", + "Arn": "arn:aws:iam::123456789012:role/AWSExampleRole01" + } + } + ], + "IsTruncated": false + } + } + ] } }, "com.amazonaws.iam#GetServiceLastAccessedDetailsWithEntitiesRequest": { @@ -6996,6 +7532,24 @@ ], "traits": { "smithy.api#documentation": "Retrieves information about the specified IAM user, including the user's creation\n date, path, unique ID, and ARN.
\nIf you do not specify a user name, IAM determines the user name implicitly based on\n the Amazon Web Services access key ID used to sign the request to this operation.
", + "smithy.api#examples": [ + { + "title": "To get information about an IAM user", + "documentation": "The following command gets information about the IAM user named Bob.", + "input": { + "UserName": "Bob" + }, + "output": { + "User": { + "UserName": "Bob", + "Path": "/", + "CreateDate": "2012-09-21T23:03:13Z", + "UserId": "AKIAIOSFODNN7EXAMPLE", + "Arn": "arn:aws:iam::123456789012:user/Bob" + } + } + } + ], "smithy.api#suppress": [ "WaitableTraitInvalidErrorType" ], @@ -7411,6 +7965,31 @@ ], "traits": { "smithy.api#documentation": "Returns information about the access key IDs associated with the specified IAM user.\n If there is none, the operation returns an empty list.
\nAlthough each user is limited to a small number of keys, you can still paginate the\n results using the MaxItems and Marker parameters.
If the UserName is not specified, the user name is determined implicitly\n based on the Amazon Web Services access key ID used to sign the request. If a temporary access key is\n used, then UserName is required. If a long-term key is assigned to the\n user, then UserName is not required. This operation works for access keys\n under the Amazon Web Services account. Consequently, you can use this operation to manage Amazon Web Services account root user\n credentials even if the Amazon Web Services account has no associated users.
To ensure the security of your Amazon Web Services account, the secret access key is accessible\n only during key and user creation.
\nLists the account alias associated with the Amazon Web Services account (Note: you can have only\n one). For information about using an Amazon Web Services account alias, see Creating,\n deleting, and listing an Amazon Web Services account alias in the Amazon Web Services Sign-In\n User Guide.
", + "smithy.api#examples": [ + { + "title": "To list account aliases", + "documentation": "The following command lists the aliases for the current account.", + "output": { + "AccountAliases": [ + "exmaple-corporation" + ] + } + } + ], "smithy.api#paginated": { "inputToken": "Marker", "outputToken": "Marker", @@ -7947,6 +8537,21 @@ ], "traits": { "smithy.api#documentation": "Lists the names of the inline policies that are embedded in the specified IAM\n group.
\nAn IAM group can also have managed policies attached to it. To list the managed\n policies that are attached to a group, use ListAttachedGroupPolicies.\n For more information about policies, see Managed policies and inline\n policies in the IAM User Guide.
\nYou can paginate the results using the MaxItems and Marker\n parameters. If there are no inline policies embedded with the specified group, the\n operation returns an empty list.
Lists the IAM groups that have the specified path prefix.
\n You can paginate the results using the MaxItems and Marker\n parameters.
Lists the IAM groups that the specified IAM user belongs to.
\nYou can paginate the results using the MaxItems and Marker\n parameters.
Retrieves a list of policies that the IAM identity (user, group, or role) can use to\n access each specified service.
\nThis operation does not use other policy types when determining whether a resource\n could access a service. These other policy types include resource-based policies,\n access control lists, Organizations policies, IAM permissions boundaries, and STS\n assume role policies. It only applies permissions policy logic. For more about the\n evaluation of policy types, see Evaluating policies in the\n IAM User Guide.
\nThe list of policies returned by the operation depends on the ARN of the identity that\n you provide.
\n\n User – The list of policies includes\n the managed and inline policies that are attached to the user directly. The list\n also includes any additional managed and inline policies that are attached to\n the group to which the user belongs.
\n\n Group – The list of policies includes\n only the managed and inline policies that are attached to the group directly.\n Policies that are attached to the group’s user are not included.
\n\n Role – The list of policies includes\n only the managed and inline policies that are attached to the role.
\nFor each managed policy, this operation returns the ARN and policy name. For each\n inline policy, it returns the policy name and the entity to which it is attached. Inline\n policies do not have an ARN. For more information about these policy types, see Managed policies and inline policies in the\n IAM User Guide.
\nPolicies that are attached to users and roles as permissions boundaries are not\n returned. To view which managed policy is currently used to set the permissions boundary\n for a user or role, use the GetUser or GetRole\n operations.
" + "smithy.api#documentation": "Retrieves a list of policies that the IAM identity (user, group, or role) can use to\n access each specified service.
\nThis operation does not use other policy types when determining whether a resource\n could access a service. These other policy types include resource-based policies,\n access control lists, Organizations policies, IAM permissions boundaries, and STS\n assume role policies. It only applies permissions policy logic. For more about the\n evaluation of policy types, see Evaluating policies in the\n IAM User Guide.
\nThe list of policies returned by the operation depends on the ARN of the identity that\n you provide.
\n\n User – The list of policies includes\n the managed and inline policies that are attached to the user directly. The list\n also includes any additional managed and inline policies that are attached to\n the group to which the user belongs.
\n\n Group – The list of policies includes\n only the managed and inline policies that are attached to the group directly.\n Policies that are attached to the group’s user are not included.
\n\n Role – The list of policies includes\n only the managed and inline policies that are attached to the role.
\nFor each managed policy, this operation returns the ARN and policy name. For each\n inline policy, it returns the policy name and the entity to which it is attached. Inline\n policies do not have an ARN. For more information about these policy types, see Managed policies and inline policies in the\n IAM User Guide.
\nPolicies that are attached to users and roles as permissions boundaries are not\n returned. To view which managed policy is currently used to set the permissions boundary\n for a user or role, use the GetUser or GetRole\n operations.
", + "smithy.api#examples": [ + { + "title": "To list policies that allow access to a service", + "documentation": "The following operation lists policies that allow ExampleUser01 to access IAM or EC2.", + "input": { + "Arn": "arn:aws:iam::123456789012:user/ExampleUser01", + "ServiceNamespaces": [ + "iam", + "ec2" + ] + }, + "output": { + "IsTruncated": false, + "PoliciesGrantingServiceAccess": [ + { + "Policies": [ + { + "PolicyArn": "arn:aws:iam::123456789012:policy/ExampleIamPolicy", + "PolicyType": "MANAGED", + "PolicyName": "ExampleIamPolicy" + }, + { + "EntityName": "AWSExampleGroup1", + "EntityType": "GROUP", + "PolicyType": "INLINE", + "PolicyName": "ExampleGroup1Policy" + } + ], + "ServiceNamespace": "iam" + }, + { + "Policies": [ + { + "PolicyArn": "arn:aws:iam::123456789012:policy/ExampleEc2Policy", + "PolicyType": "MANAGED", + "PolicyName": "ExampleEc2Policy" + } + ], + "ServiceNamespace": "ec2" + } + ] + } + } + ] } }, "com.amazonaws.iam#ListPoliciesGrantingServiceAccessEntry": { @@ -9160,6 +9867,28 @@ ], "traits": { "smithy.api#documentation": "Lists the tags that are attached to the specified role. The returned list of tags is\n sorted by tag key. For more information about tagging, see Tagging IAM resources in the\n IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To list the tags attached to an IAM role", + "documentation": "The following example shows how to list the tags attached to a role.", + "input": { + "RoleName": "taggedrole1" + }, + "output": { + "Tags": [ + { + "Key": "Dept", + "Value": "12345" + }, + { + "Key": "Team", + "Value": "Accounting" + } + ], + "IsTruncated": false + } + } + ], "smithy.api#paginated": { "inputToken": "Marker", "outputToken": "Marker", @@ -9732,6 +10461,26 @@ ], "traits": { "smithy.api#documentation": "Returns information about the signing certificates associated with the specified IAM\n user. If none exists, the operation returns an empty list.
\nAlthough each user is limited to a small number of signing certificates, you can still\n paginate the results using the MaxItems and Marker\n parameters.
If the UserName field is not specified, the user name is determined\n implicitly based on the Amazon Web Services access key ID used to sign the request for this operation.\n This operation works for access keys under the Amazon Web Services account. Consequently, you can use\n this operation to manage Amazon Web Services account root user credentials even if the Amazon Web Services account has no\n associated users.
Lists the tags that are attached to the specified IAM user. The returned list of tags is sorted by tag key. For more information about tagging, see Tagging IAM resources in the\n IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To list the tags attached to an IAM user", + "documentation": "The following example shows how to list the tags attached to a user.", + "input": { + "UserName": "anika" + }, + "output": { + "Tags": [ + { + "Key": "Dept", + "Value": "12345" + }, + { + "Key": "Team", + "Value": "Accounting" + } + ], + "IsTruncated": false + } + } + ], "smithy.api#paginated": { "inputToken": "Marker", "outputToken": "Marker", @@ -9973,6 +10744,32 @@ ], "traits": { "smithy.api#documentation": "Lists the IAM users that have the specified path prefix. If no path prefix is\n specified, the operation returns all users in the Amazon Web Services account. If there are none, the\n operation returns an empty list.
\nIAM resource-listing operations return a subset of the available \n attributes for the resource. This operation does not return the following attributes, even though they are an attribute of the returned object:
\nPermissionsBoundary
\nTags
\nTo view all of the information for a user, see GetUser.
\nYou can paginate the results using the MaxItems and Marker\n parameters.
Lists the virtual MFA devices defined in the Amazon Web Services account by assignment status. If\n you do not specify an assignment status, the operation returns a list of all virtual MFA\n devices. Assignment status can be Assigned, Unassigned, or\n Any.
IAM resource-listing operations return a subset of the available \n attributes for the resource. For example, this operation does not return tags, even though they are an attribute of the returned object. To view tag information for a virtual MFA device, see ListMFADeviceTags.
\nYou can paginate the results using the MaxItems and Marker\n parameters.
Adds or updates an inline policy document that is embedded in the specified IAM\n group.
\nA user can also have managed policies attached to it. To attach a managed policy to a\n group, use \n AttachGroupPolicy\n . To create a new managed policy, use\n \n CreatePolicy\n . For information about policies, see Managed\n policies and inline policies in the\n IAM User Guide.
For information about the maximum number of inline policies that you can embed in a\n group, see IAM and STS quotas in the IAM User Guide.
\nBecause policy documents can be large, you should use POST rather than GET when\n calling PutGroupPolicy. For general information about using the Query\n API with IAM, see Making query requests in the\n IAM User Guide.
Adds or updates an inline policy document that is embedded in the specified IAM\n group.
\nA user can also have managed policies attached to it. To attach a managed policy to a\n group, use \n AttachGroupPolicy\n . To create a new managed policy, use\n \n CreatePolicy\n . For information about policies, see Managed\n policies and inline policies in the\n IAM User Guide.
For information about the maximum number of inline policies that you can embed in a\n group, see IAM and STS quotas in the IAM User Guide.
\nBecause policy documents can be large, you should use POST rather than GET when\n calling PutGroupPolicy. For general information about using the Query\n API with IAM, see Making query requests in the\n IAM User Guide.
Adds or updates an inline policy document that is embedded in the specified IAM\n role.
\nWhen you embed an inline policy in a role, the inline policy is used as part of the\n role's access (permissions) policy. The role's trust policy is created at the same time\n as the role, using \n CreateRole\n .\n You can update a role's trust policy using \n UpdateAssumeRolePolicy\n . For more information about roles,\n see IAM\n roles in the IAM User Guide.
A role can also have a managed policy attached to it. To attach a managed policy to a\n role, use \n AttachRolePolicy\n . To create a new managed policy, use\n \n CreatePolicy\n . For information about policies, see Managed\n policies and inline policies in the\n IAM User Guide.
For information about the maximum number of inline policies that you can embed with a\n role, see IAM and STS quotas in the IAM User Guide.
\nBecause policy documents can be large, you should use POST rather than GET when\n calling PutRolePolicy. For general information about using the Query\n API with IAM, see Making query requests in the\n IAM User Guide.
Adds or updates an inline policy document that is embedded in the specified IAM\n role.
\nWhen you embed an inline policy in a role, the inline policy is used as part of the\n role's access (permissions) policy. The role's trust policy is created at the same time\n as the role, using \n CreateRole\n .\n You can update a role's trust policy using \n UpdateAssumeRolePolicy\n . For more information about roles,\n see IAM\n roles in the IAM User Guide.
A role can also have a managed policy attached to it. To attach a managed policy to a\n role, use \n AttachRolePolicy\n . To create a new managed policy, use\n \n CreatePolicy\n . For information about policies, see Managed\n policies and inline policies in the\n IAM User Guide.
For information about the maximum number of inline policies that you can embed with a\n role, see IAM and STS quotas in the IAM User Guide.
\nBecause policy documents can be large, you should use POST rather than GET when\n calling PutRolePolicy. For general information about using the Query\n API with IAM, see Making query requests in the\n IAM User Guide.
Adds or updates an inline policy document that is embedded in the specified IAM\n user.
\nAn IAM user can also have a managed policy attached to it. To attach a managed\n policy to a user, use \n AttachUserPolicy\n . To create a new managed policy, use\n \n CreatePolicy\n . For information about policies, see Managed\n policies and inline policies in the\n IAM User Guide.
For information about the maximum number of inline policies that you can embed in a\n user, see IAM and STS quotas in the IAM User Guide.
\nBecause policy documents can be large, you should use POST rather than GET when\n calling PutUserPolicy. For general information about using the Query\n API with IAM, see Making query requests in the\n IAM User Guide.
Adds or updates an inline policy document that is embedded in the specified IAM\n user.
\nAn IAM user can also have a managed policy attached to it. To attach a managed\n policy to a user, use \n AttachUserPolicy\n . To create a new managed policy, use\n \n CreatePolicy\n . For information about policies, see Managed\n policies and inline policies in the\n IAM User Guide.
For information about the maximum number of inline policies that you can embed in a\n user, see IAM and STS quotas in the IAM User Guide.
\nBecause policy documents can be large, you should use POST rather than GET when\n calling PutUserPolicy. For general information about using the Query\n API with IAM, see Making query requests in the\n IAM User Guide.
Removes the specified IAM role from the specified EC2 instance profile.
\nMake sure that you do not have any Amazon EC2 instances running with the role you\n are about to remove from the instance profile. Removing a role from an instance\n profile that is associated with a running instance might break any applications\n running on the instance.
\nFor more information about roles, see IAM roles in the\n IAM User Guide. For more information about instance profiles,\n see Using\n instance profiles in the IAM User Guide.
" + "smithy.api#documentation": "Removes the specified IAM role from the specified EC2 instance profile.
\nMake sure that you do not have any Amazon EC2 instances running with the role you\n are about to remove from the instance profile. Removing a role from an instance\n profile that is associated with a running instance might break any applications\n running on the instance.
\nFor more information about roles, see IAM roles in the\n IAM User Guide. For more information about instance profiles,\n see Using\n instance profiles in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To remove a role from an instance profile", + "documentation": "The following command removes the role named Test-Role from the instance profile named ExampleInstanceProfile.", + "input": { + "RoleName": "Test-Role", + "InstanceProfileName": "ExampleInstanceProfile" + } + } + ] } }, "com.amazonaws.iam#RemoveRoleFromInstanceProfileRequest": { @@ -11257,7 +12113,17 @@ } ], "traits": { - "smithy.api#documentation": "Removes the specified user from the specified group.
" + "smithy.api#documentation": "Removes the specified user from the specified group.
", + "smithy.api#examples": [ + { + "title": "To remove a user from an IAM group", + "documentation": "The following command removes the user named Bob from the IAM group named Admins.", + "input": { + "UserName": "Bob", + "GroupName": "Admins" + } + } + ] } }, "com.amazonaws.iam#RemoveUserFromGroupRequest": { @@ -12225,7 +13091,16 @@ } ], "traits": { - "smithy.api#documentation": "Sets the specified version of the global endpoint token as the token version used for\n the Amazon Web Services account.
\nBy default, Security Token Service (STS) is available as a global service, and all STS requests\n go to a single endpoint at https://sts.amazonaws.com. Amazon Web Services recommends\n using Regional STS endpoints to reduce latency, build in redundancy, and increase\n session token availability. For information about Regional endpoints for STS, see\n Security Token Service\n endpoints and quotas in the Amazon Web Services General Reference.
If you make an STS call to the global endpoint, the resulting session tokens might\n be valid in some Regions but not others. It depends on the version that is set in this\n operation. Version 1 tokens are valid only in Amazon Web Services Regions that are\n available by default. These tokens do not work in manually enabled Regions, such as Asia\n Pacific (Hong Kong). Version 2 tokens are valid in all Regions. However, version 2\n tokens are longer and might affect systems where you temporarily store tokens. For\n information, see Activating and\n deactivating STS in an Amazon Web Services Region in the\n IAM User Guide.
\nTo view the current session token version, see the\n GlobalEndpointTokenVersion entry in the response of the GetAccountSummary operation.
Sets the specified version of the global endpoint token as the token version used for\n the Amazon Web Services account.
\nBy default, Security Token Service (STS) is available as a global service, and all STS requests\n go to a single endpoint at https://sts.amazonaws.com. Amazon Web Services recommends\n using Regional STS endpoints to reduce latency, build in redundancy, and increase\n session token availability. For information about Regional endpoints for STS, see\n Security Token Service\n endpoints and quotas in the Amazon Web Services General Reference.
If you make an STS call to the global endpoint, the resulting session tokens might\n be valid in some Regions but not others. It depends on the version that is set in this\n operation. Version 1 tokens are valid only in Amazon Web Services Regions that are\n available by default. These tokens do not work in manually enabled Regions, such as Asia\n Pacific (Hong Kong). Version 2 tokens are valid in all Regions. However, version 2\n tokens are longer and might affect systems where you temporarily store tokens. For\n information, see Activating and\n deactivating STS in an Amazon Web Services Region in the\n IAM User Guide.
\nTo view the current session token version, see the\n GlobalEndpointTokenVersion entry in the response of the GetAccountSummary operation.
Adds one or more tags to an IAM role. The role can be a regular role or a\n service-linked role. If a tag with the same key name already exists, then that tag is\n overwritten with the new value.
\nA tag consists of a key name and an associated value. By assigning tags to your\n resources, you can do the following:
\n\n Administrative grouping and discovery - Attach\n tags to resources to aid in organization and search. For example, you could search for all\n resources with the key name Project and the value\n MyImportantProject. Or search for all resources with the key name\n Cost Center and the value 41200.
\n\n Access control - Include tags in IAM user-based\n and resource-based policies. You can use tags to restrict access to only an IAM role\n that has a specified tag attached. You can also restrict access to only those resources\n that have a certain tag attached. For examples of policies that show how to use tags to\n control access, see Control access using IAM tags in the\n IAM User Guide.
\n\n Cost allocation - Use tags to help track which\n individuals and teams are using which Amazon Web Services resources.
\nIf any one of the tags is invalid or if you exceed the allowed maximum number of tags, then the entire request \n fails and the resource is not created. For more information about tagging, see Tagging IAM resources in the\n IAM User Guide.
\nAmazon Web Services always interprets the tag Value as a single string. If you\n need to store an array, you can store comma-separated values in the string. However, you\n must interpret the value in your code.
For more information about tagging, see Tagging IAM identities in the\n IAM User Guide.
" + "smithy.api#documentation": "Adds one or more tags to an IAM role. The role can be a regular role or a\n service-linked role. If a tag with the same key name already exists, then that tag is\n overwritten with the new value.
\nA tag consists of a key name and an associated value. By assigning tags to your\n resources, you can do the following:
\n\n Administrative grouping and discovery - Attach\n tags to resources to aid in organization and search. For example, you could search for all\n resources with the key name Project and the value\n MyImportantProject. Or search for all resources with the key name\n Cost Center and the value 41200.
\n\n Access control - Include tags in IAM user-based\n and resource-based policies. You can use tags to restrict access to only an IAM role\n that has a specified tag attached. You can also restrict access to only those resources\n that have a certain tag attached. For examples of policies that show how to use tags to\n control access, see Control access using IAM tags in the\n IAM User Guide.
\n\n Cost allocation - Use tags to help track which\n individuals and teams are using which Amazon Web Services resources.
\nIf any one of the tags is invalid or if you exceed the allowed maximum number of tags, then the entire request \n fails and the resource is not created. For more information about tagging, see Tagging IAM resources in the\n IAM User Guide.
\nAmazon Web Services always interprets the tag Value as a single string. If you\n need to store an array, you can store comma-separated values in the string. However, you\n must interpret the value in your code.
For more information about tagging, see Tagging IAM identities in the\n IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To add a tag key and value to an IAM role", + "documentation": "The following example shows how to add tags to an existing role.", + "input": { + "RoleName": "taggedrole", + "Tags": [ + { + "Key": "Dept", + "Value": "Accounting" + }, + { + "Key": "CostCenter", + "Value": "12345" + } + ] + } + } + ] } }, "com.amazonaws.iam#TagRoleRequest": { @@ -12974,7 +13868,26 @@ } ], "traits": { - "smithy.api#documentation": "Adds one or more tags to an IAM user. If a tag with the same key name already exists,\n then that tag is overwritten with the new value.
\nA tag consists of a key name and an associated value. By assigning tags to your\n resources, you can do the following:
\n\n Administrative grouping and discovery - Attach\n tags to resources to aid in organization and search. For example, you could search for all\n resources with the key name Project and the value\n MyImportantProject. Or search for all resources with the key name\n Cost Center and the value 41200.
\n\n Access control - Include tags in IAM identity-based\n and resource-based policies. You can use tags to restrict access to only an IAM\n requesting user that has a specified tag attached. You can also restrict access to only\n those resources that have a certain tag attached. For examples of policies that show how\n to use tags to control access, see Control access using IAM tags in the\n IAM User Guide.
\n\n Cost allocation - Use tags to help track which\n individuals and teams are using which Amazon Web Services resources.
\nIf any one of the tags is invalid or if you exceed the allowed maximum number of tags, then the entire request \n fails and the resource is not created. For more information about tagging, see Tagging IAM resources in the\n IAM User Guide.
\nAmazon Web Services always interprets the tag Value as a single string. If you\n need to store an array, you can store comma-separated values in the string. However, you\n must interpret the value in your code.
For more information about tagging, see Tagging IAM identities in the\n IAM User Guide.
" + "smithy.api#documentation": "Adds one or more tags to an IAM user. If a tag with the same key name already exists,\n then that tag is overwritten with the new value.
\nA tag consists of a key name and an associated value. By assigning tags to your\n resources, you can do the following:
\n\n Administrative grouping and discovery - Attach\n tags to resources to aid in organization and search. For example, you could search for all\n resources with the key name Project and the value\n MyImportantProject. Or search for all resources with the key name\n Cost Center and the value 41200.
\n\n Access control - Include tags in IAM identity-based\n and resource-based policies. You can use tags to restrict access to only an IAM\n requesting user that has a specified tag attached. You can also restrict access to only\n those resources that have a certain tag attached. For examples of policies that show how\n to use tags to control access, see Control access using IAM tags in the\n IAM User Guide.
\n\n Cost allocation - Use tags to help track which\n individuals and teams are using which Amazon Web Services resources.
\nIf any one of the tags is invalid or if you exceed the allowed maximum number of tags, then the entire request \n fails and the resource is not created. For more information about tagging, see Tagging IAM resources in the\n IAM User Guide.
\nAmazon Web Services always interprets the tag Value as a single string. If you\n need to store an array, you can store comma-separated values in the string. However, you\n must interpret the value in your code.
For more information about tagging, see Tagging IAM identities in the\n IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To add a tag key and value to an IAM user", + "documentation": "The following example shows how to add tags to an existing user.", + "input": { + "UserName": "anika", + "Tags": [ + { + "Key": "Dept", + "Value": "Accounting" + }, + { + "Key": "CostCenter", + "Value": "12345" + } + ] + } + } + ] } }, "com.amazonaws.iam#TagUserRequest": { @@ -13280,7 +14193,19 @@ } ], "traits": { - "smithy.api#documentation": "Removes the specified tags from the role. For more information about tagging, see Tagging IAM resources in the\n IAM User Guide.
" + "smithy.api#documentation": "Removes the specified tags from the role. For more information about tagging, see Tagging IAM resources in the\n IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To remove a tag from an IAM role", + "documentation": "The following example shows how to remove a tag with the key 'Dept' from a role named 'taggedrole'.", + "input": { + "RoleName": "taggedrole", + "TagKeys": [ + "Dept" + ] + } + } + ] } }, "com.amazonaws.iam#UntagRoleRequest": { @@ -13421,7 +14346,19 @@ } ], "traits": { - "smithy.api#documentation": "Removes the specified tags from the user. For more information about tagging, see Tagging IAM resources in the\n IAM User Guide.
" + "smithy.api#documentation": "Removes the specified tags from the user. For more information about tagging, see Tagging IAM resources in the\n IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To remove a tag from an IAM user", + "documentation": "The following example shows how to remove tags that are attached to a user named 'anika'.", + "input": { + "UserName": "anika", + "TagKeys": [ + "Dept" + ] + } + } + ] } }, "com.amazonaws.iam#UntagUserRequest": { @@ -13466,7 +14403,18 @@ } ], "traits": { - "smithy.api#documentation": "Changes the status of the specified access key from Active to Inactive, or vice versa.\n This operation can be used to disable a user's key as part of a key rotation\n workflow.
\nIf the UserName is not specified, the user name is determined implicitly\n based on the Amazon Web Services access key ID used to sign the request. If a temporary access key is\n used, then UserName is required. If a long-term key is assigned to the\n user, then UserName is not required. This operation works for access keys\n under the Amazon Web Services account. Consequently, you can use this operation to manage Amazon Web Services account root user\n credentials even if the Amazon Web Services account has no associated users.
For information about rotating keys, see Managing keys and certificates\n in the IAM User Guide.
" + "smithy.api#documentation": "Changes the status of the specified access key from Active to Inactive, or vice versa.\n This operation can be used to disable a user's key as part of a key rotation\n workflow.
\nIf the UserName is not specified, the user name is determined implicitly\n based on the Amazon Web Services access key ID used to sign the request. If a temporary access key is\n used, then UserName is required. If a long-term key is assigned to the\n user, then UserName is not required. This operation works for access keys\n under the Amazon Web Services account. Consequently, you can use this operation to manage Amazon Web Services account root user\n credentials even if the Amazon Web Services account has no associated users.
For information about rotating keys, see Managing keys and certificates\n in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To activate or deactivate an access key for an IAM user", + "documentation": "The following command deactivates the specified access key (access key ID and secret access key) for the IAM user named Bob.", + "input": { + "UserName": "Bob", + "Status": "Inactive", + "AccessKeyId": "AKIAIOSFODNN7EXAMPLE" + } + } + ] } }, "com.amazonaws.iam#UpdateAccessKeyRequest": { @@ -13520,7 +14468,17 @@ } ], "traits": { - "smithy.api#documentation": "Updates the password policy settings for the Amazon Web Services account.
\nThis operation does not support partial updates. No parameters are required, but\n if you do not specify a parameter, that parameter's value reverts to its default\n value. See the Request Parameters section for each\n parameter's default value. Also note that some parameters do not allow the default\n parameter to be explicitly set. Instead, to invoke the default value, do not include\n that parameter when you invoke the operation.
\nFor more information about using a password policy, see Managing an IAM password\n policy in the IAM User Guide.
" + "smithy.api#documentation": "Updates the password policy settings for the Amazon Web Services account.
\nThis operation does not support partial updates. No parameters are required, but\n if you do not specify a parameter, that parameter's value reverts to its default\n value. See the Request Parameters section for each\n parameter's default value. Also note that some parameters do not allow the default\n parameter to be explicitly set. Instead, to invoke the default value, do not include\n that parameter when you invoke the operation.
\nFor more information about using a password policy, see Managing an IAM password\n policy in the IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To set or change the current account password policy", + "documentation": "The following command sets the password policy to require a minimum length of eight characters and to require one or more numbers in the password:", + "input": { + "MinimumPasswordLength": 8, + "RequireNumbers": true + } + } + ] } }, "com.amazonaws.iam#UpdateAccountPasswordPolicyRequest": { @@ -13616,7 +14574,17 @@ } ], "traits": { - "smithy.api#documentation": "Updates the policy that grants an IAM entity permission to assume a role. This is\n typically referred to as the \"role trust policy\". For more information about roles, see\n Using roles to\n delegate permissions and federate identities.
" + "smithy.api#documentation": "Updates the policy that grants an IAM entity permission to assume a role. This is\n typically referred to as the \"role trust policy\". For more information about roles, see\n Using roles to\n delegate permissions and federate identities.
", + "smithy.api#examples": [ + { + "title": "To update the trust policy for an IAM role", + "documentation": "The following command updates the role trust policy for the role named Test-Role:", + "input": { + "PolicyDocument": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":[\"ec2.amazonaws.com\"]},\"Action\":[\"sts:AssumeRole\"]}]}", + "RoleName": "S3AccessForEC2Instances" + } + } + ] } }, "com.amazonaws.iam#UpdateAssumeRolePolicyRequest": { @@ -13664,7 +14632,17 @@ } ], "traits": { - "smithy.api#documentation": "Updates the name and/or the path of the specified IAM group.
\nYou should understand the implications of changing a group's path or name. For\n more information, see Renaming users and\n groups in the IAM User Guide.
\nThe person making the request (the principal), must have permission to change the\n role group with the old name and the new name. For example, to change the group\n named Managers to MGRs, the principal must have a policy\n that allows them to update both groups. If the principal has permission to update\n the Managers group, but not the MGRs group, then the\n update fails. For more information about permissions, see Access management.\n
Updates the name and/or the path of the specified IAM group.
\nYou should understand the implications of changing a group's path or name. For\n more information, see Renaming users and\n groups in the IAM User Guide.
\nThe person making the request (the principal), must have permission to change the\n role group with the old name and the new name. For example, to change the group\n named Managers to MGRs, the principal must have a policy\n that allows them to update both groups. If the principal has permission to update\n the Managers group, but not the MGRs group, then the\n update fails. For more information about permissions, see Access management.\n
Changes the password for the specified IAM user. You can use the CLI, the Amazon Web Services\n API, or the Users page in the IAM console to change\n the password for any IAM user. Use ChangePassword to change your own\n password in the My Security Credentials page in the\n Amazon Web Services Management Console.
\nFor more information about modifying passwords, see Managing passwords in the\n IAM User Guide.
" + "smithy.api#documentation": "Changes the password for the specified IAM user. You can use the CLI, the Amazon Web Services\n API, or the Users page in the IAM console to change\n the password for any IAM user. Use ChangePassword to change your own\n password in the My Security Credentials page in the\n Amazon Web Services Management Console.
\nFor more information about modifying passwords, see Managing passwords in the\n IAM User Guide.
", + "smithy.api#examples": [ + { + "title": "To change the password for an IAM user", + "documentation": "The following command creates or changes the password for the IAM user named Bob.", + "input": { + "UserName": "Bob", + "Password": "SomeKindOfPassword123!@#" + } + } + ] } }, "com.amazonaws.iam#UpdateLoginProfileRequest": { @@ -14138,7 +15126,18 @@ } ], "traits": { - "smithy.api#documentation": "Changes the status of the specified user signing certificate from active to disabled,\n or vice versa. This operation can be used to disable an IAM user's signing\n certificate as part of a certificate rotation work flow.
\nIf the UserName field is not specified, the user name is determined\n implicitly based on the Amazon Web Services access key ID used to sign the request. This operation\n works for access keys under the Amazon Web Services account. Consequently, you can use this operation\n to manage Amazon Web Services account root user credentials even if the Amazon Web Services account has no associated\n users.
Changes the status of the specified user signing certificate from active to disabled,\n or vice versa. This operation can be used to disable an IAM user's signing\n certificate as part of a certificate rotation work flow.
\nIf the UserName field is not specified, the user name is determined\n implicitly based on the Amazon Web Services access key ID used to sign the request. This operation\n works for access keys under the Amazon Web Services account. Consequently, you can use this operation\n to manage Amazon Web Services account root user credentials even if the Amazon Web Services account has no associated\n users.
Updates the name and/or the path of the specified IAM user.
\nYou should understand the implications of changing an IAM user's path or\n name. For more information, see Renaming an IAM\n user and Renaming an IAM\n group in the IAM User Guide.
\nTo change a user name, the requester must have appropriate permissions on both\n the source object and the target object. For example, to change Bob to Robert, the\n entity making the request must have permission on Bob and Robert, or must have\n permission on all (*). For more information about permissions, see Permissions and policies.
\nUpdates the name and/or the path of the specified IAM user.
\nYou should understand the implications of changing an IAM user's path or\n name. For more information, see Renaming an IAM\n user and Renaming an IAM\n group in the IAM User Guide.
\nTo change a user name, the requester must have appropriate permissions on both\n the source object and the target object. For example, to change Bob to Robert, the\n entity making the request must have permission on Bob and Robert, or must have\n permission on all (*). For more information about permissions, see Permissions and policies.
\nUploads a server certificate entity for the Amazon Web Services account. The server certificate\n entity includes a public key certificate, a private key, and an optional certificate\n chain, which should all be PEM-encoded.
\nWe recommend that you use Certificate Manager to\n provision, manage, and deploy your server certificates. With ACM you can request a\n certificate, deploy it to Amazon Web Services resources, and let ACM handle certificate renewals for\n you. Certificates provided by ACM are free. For more information about using ACM,\n see the Certificate Manager User\n Guide.
\nFor more information about working with server certificates, see Working\n with server certificates in the IAM User Guide. This\n topic includes a list of Amazon Web Services services that can use the server certificates that you\n manage with IAM.
\nFor information about the number of server certificates you can upload, see IAM and STS\n quotas in the IAM User Guide.
\nBecause the body of the public key certificate, private key, and the certificate\n chain can be large, you should use POST rather than GET when calling\n UploadServerCertificate. For information about setting up\n signatures and authorization through the API, see Signing Amazon Web Services API\n requests in the Amazon Web Services General Reference. For general\n information about using the Query API with IAM, see Calling the API by making HTTP query\n requests in the IAM User Guide.
Uploads a server certificate entity for the Amazon Web Services account. The server certificate\n entity includes a public key certificate, a private key, and an optional certificate\n chain, which should all be PEM-encoded.
\nWe recommend that you use Certificate Manager to\n provision, manage, and deploy your server certificates. With ACM you can request a\n certificate, deploy it to Amazon Web Services resources, and let ACM handle certificate renewals for\n you. Certificates provided by ACM are free. For more information about using ACM,\n see the Certificate Manager User\n Guide.
\nFor more information about working with server certificates, see Working\n with server certificates in the IAM User Guide. This\n topic includes a list of Amazon Web Services services that can use the server certificates that you\n manage with IAM.
\nFor information about the number of server certificates you can upload, see IAM and STS\n quotas in the IAM User Guide.
\nBecause the body of the public key certificate, private key, and the certificate\n chain can be large, you should use POST rather than GET when calling\n UploadServerCertificate. For information about setting up\n signatures and authorization through the API, see Signing Amazon Web Services API\n requests in the Amazon Web Services General Reference. For general\n information about using the Query API with IAM, see Calling the API by making HTTP query\n requests in the IAM User Guide.
Uploads an X.509 signing certificate and associates it with the specified IAM user.\n Some Amazon Web Services services require you to use certificates to validate requests that are signed\n with a corresponding private key. When you upload the certificate, its default status is\n Active.
For information about when you would use an X.509 signing certificate, see Managing\n server certificates in IAM in the\n IAM User Guide.
\nIf the UserName is not specified, the IAM user name is determined\n implicitly based on the Amazon Web Services access key ID used to sign the request. This operation\n works for access keys under the Amazon Web Services account. Consequently, you can use this operation\n to manage Amazon Web Services account root user credentials even if the Amazon Web Services account has no associated\n users.
Because the body of an X.509 certificate can be large, you should use POST rather\n than GET when calling UploadSigningCertificate. For information about\n setting up signatures and authorization through the API, see Signing\n Amazon Web Services API requests in the Amazon Web Services General Reference. For\n general information about using the Query API with IAM, see Making query\n requests in the IAM User Guide.
Uploads an X.509 signing certificate and associates it with the specified IAM user.\n Some Amazon Web Services services require you to use certificates to validate requests that are signed\n with a corresponding private key. When you upload the certificate, its default status is\n Active.
For information about when you would use an X.509 signing certificate, see Managing\n server certificates in IAM in the\n IAM User Guide.
\nIf the UserName is not specified, the IAM user name is determined\n implicitly based on the Amazon Web Services access key ID used to sign the request. This operation\n works for access keys under the Amazon Web Services account. Consequently, you can use this operation\n to manage Amazon Web Services account root user credentials even if the Amazon Web Services account has no associated\n users.
Because the body of an X.509 certificate can be large, you should use POST rather\n than GET when calling UploadSigningCertificate. For information about\n setting up signatures and authorization through the API, see Signing\n Amazon Web Services API requests in the Amazon Web Services General Reference. For\n general information about using the Query API with IAM, see Making query\n requests in the IAM User Guide.
Cancels the deletion of a KMS key. When this operation succeeds, the key state of the KMS\n key is Disabled. To enable the KMS key, use EnableKey.
For more information about scheduling and canceling deletion of a KMS key, see Deleting KMS keys in the\n Key Management Service Developer Guide.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:CancelKeyDeletion (key policy)
\n\n Related operations: ScheduleKeyDeletion\n
" + "smithy.api#documentation": "Cancels the deletion of a KMS key. When this operation succeeds, the key state of the KMS\n key is Disabled. To enable the KMS key, use EnableKey.
For more information about scheduling and canceling deletion of a KMS key, see Deleting KMS keys in the\n Key Management Service Developer Guide.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:CancelKeyDeletion (key policy)
\n\n Related operations: ScheduleKeyDeletion\n
", + "smithy.api#examples": [ + { + "title": "To cancel deletion of a KMS key", + "documentation": "The following example cancels deletion of the specified KMS key.", + "input": { + "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab" + }, + "output": { + "KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" + } + } + ] } }, "com.amazonaws.kms#CancelKeyDeletionRequest": { @@ -350,7 +362,17 @@ } ], "traits": { - "smithy.api#documentation": "Connects or reconnects a custom key store to its backing key store. For an CloudHSM key\n store, ConnectCustomKeyStore connects the key store to its associated CloudHSM\n cluster. For an external key store, ConnectCustomKeyStore connects the key store\n to the external key store proxy that communicates with your external key manager.
The custom key store must be connected before you can create KMS keys in the key store or\n use the KMS keys it contains. You can disconnect and reconnect a custom key store at any\n time.
\nThe connection process for a custom key store can take an extended amount of time to\n complete. This operation starts the connection process, but it does not wait for it to\n complete. When it succeeds, this operation quickly returns an HTTP 200 response and a JSON\n object with no properties. However, this response does not indicate that the custom key store\n is connected. To get the connection state of the custom key store, use the DescribeCustomKeyStores operation.
\nThis operation is part of the custom key stores feature in KMS, which\ncombines the convenience and extensive integration of KMS with the isolation and control of a\nkey store that you own and manage.
\nThe ConnectCustomKeyStore operation might fail for various reasons. To find\n the reason, use the DescribeCustomKeyStores operation and see the\n ConnectionErrorCode in the response. For help interpreting the\n ConnectionErrorCode, see CustomKeyStoresListEntry.
To fix the failure, use the DisconnectCustomKeyStore operation to\n disconnect the custom key store, correct the error, use the UpdateCustomKeyStore operation if necessary, and then use\n ConnectCustomKeyStore again.
\n CloudHSM key store\n
\nDuring the connection process for an CloudHSM key store, KMS finds the CloudHSM cluster that\n is associated with the custom key store, creates the connection infrastructure, connects to\n the cluster, logs into the CloudHSM client as the kmsuser CU, and rotates its\n password.
To connect an CloudHSM key store, its associated CloudHSM cluster must have at least one active\n HSM. To get the number of active HSMs in a cluster, use the DescribeClusters operation. To add HSMs\n to the cluster, use the CreateHsm operation. Also, the \n kmsuser crypto\n user (CU) must not be logged into the cluster. This prevents KMS from using this\n account to log in.
If you are having trouble connecting or disconnecting a CloudHSM key store, see Troubleshooting an CloudHSM key\n store in the Key Management Service Developer Guide.
\n\n External key store\n
\nWhen you connect an external key store that uses public endpoint connectivity, KMS tests\n its ability to communicate with your external key manager by sending a request via the\n external key store proxy.
\nWhen you connect to an external key store that uses VPC endpoint service connectivity,\n KMS establishes the networking elements that it needs to communicate with your external key\n manager via the external key store proxy. This includes creating an interface endpoint to the\n VPC endpoint service and a private hosted zone for traffic between KMS and the VPC endpoint\n service.
\nTo connect an external key store, KMS must be able to connect to the external key store\n proxy, the external key store proxy must be able to communicate with your external key\n manager, and the external key manager must be available for cryptographic operations.
\nIf you are having trouble connecting or disconnecting an external key store, see Troubleshooting an external\n key store in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.
\n\n Required permissions: kms:ConnectCustomKeyStore (IAM policy)
\n\n Related operations\n
\n\n CreateCustomKeyStore\n
\n\n DeleteCustomKeyStore\n
\n\n UpdateCustomKeyStore\n
\nConnects or reconnects a custom key store to its backing key store. For an CloudHSM key\n store, ConnectCustomKeyStore connects the key store to its associated CloudHSM\n cluster. For an external key store, ConnectCustomKeyStore connects the key store\n to the external key store proxy that communicates with your external key manager.
The custom key store must be connected before you can create KMS keys in the key store or\n use the KMS keys it contains. You can disconnect and reconnect a custom key store at any\n time.
\nThe connection process for a custom key store can take an extended amount of time to\n complete. This operation starts the connection process, but it does not wait for it to\n complete. When it succeeds, this operation quickly returns an HTTP 200 response and a JSON\n object with no properties. However, this response does not indicate that the custom key store\n is connected. To get the connection state of the custom key store, use the DescribeCustomKeyStores operation.
\nThis operation is part of the custom key stores feature in KMS, which\ncombines the convenience and extensive integration of KMS with the isolation and control of a\nkey store that you own and manage.
\nThe ConnectCustomKeyStore operation might fail for various reasons. To find\n the reason, use the DescribeCustomKeyStores operation and see the\n ConnectionErrorCode in the response. For help interpreting the\n ConnectionErrorCode, see CustomKeyStoresListEntry.
To fix the failure, use the DisconnectCustomKeyStore operation to\n disconnect the custom key store, correct the error, use the UpdateCustomKeyStore operation if necessary, and then use\n ConnectCustomKeyStore again.
\n CloudHSM key store\n
\nDuring the connection process for an CloudHSM key store, KMS finds the CloudHSM cluster that\n is associated with the custom key store, creates the connection infrastructure, connects to\n the cluster, logs into the CloudHSM client as the kmsuser CU, and rotates its\n password.
To connect an CloudHSM key store, its associated CloudHSM cluster must have at least one active\n HSM. To get the number of active HSMs in a cluster, use the DescribeClusters operation. To add HSMs\n to the cluster, use the CreateHsm operation. Also, the \n kmsuser crypto\n user (CU) must not be logged into the cluster. This prevents KMS from using this\n account to log in.
If you are having trouble connecting or disconnecting a CloudHSM key store, see Troubleshooting an CloudHSM key\n store in the Key Management Service Developer Guide.
\n\n External key store\n
\nWhen you connect an external key store that uses public endpoint connectivity, KMS tests\n its ability to communicate with your external key manager by sending a request via the\n external key store proxy.
\nWhen you connect to an external key store that uses VPC endpoint service connectivity,\n KMS establishes the networking elements that it needs to communicate with your external key\n manager via the external key store proxy. This includes creating an interface endpoint to the\n VPC endpoint service and a private hosted zone for traffic between KMS and the VPC endpoint\n service.
\nTo connect an external key store, KMS must be able to connect to the external key store\n proxy, the external key store proxy must be able to communicate with your external key\n manager, and the external key manager must be available for cryptographic operations.
\nIf you are having trouble connecting or disconnecting an external key store, see Troubleshooting an external\n key store in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.
\n\n Required permissions: kms:ConnectCustomKeyStore (IAM policy)
\n\n Related operations\n
\n\n CreateCustomKeyStore\n
\n\n DeleteCustomKeyStore\n
\n\n UpdateCustomKeyStore\n
\nDescribeCustomKeyStores operation.",
+ "input": {
+ "CustomKeyStoreId": "cks-1234567890abcdef0"
+ },
+ "output": {}
+ }
+ ]
}
},
"com.amazonaws.kms#ConnectCustomKeyStoreRequest": {
@@ -555,7 +577,17 @@
}
],
"traits": {
- "smithy.api#documentation": "Creates a friendly name for a KMS key.
\nAdding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see ABAC for KMS in the Key Management Service Developer Guide.
\nYou can use an alias to identify a KMS key in the KMS console, in the DescribeKey operation and in cryptographic operations, such as Encrypt and\n GenerateDataKey. You can also change the KMS key that's associated with\n the alias (UpdateAlias) or delete the alias (DeleteAlias)\n at any time. These operations don't affect the underlying KMS key.
\nYou can associate the alias with any customer managed key in the same Amazon Web Services Region. Each\n alias is associated with only one KMS key at a time, but a KMS key can have multiple aliases.\n A valid KMS key is required. You can't create an alias without a KMS key.
\nThe alias must be unique in the account and Region, but you can have aliases with the same\n name in different Regions. For detailed information about aliases, see Using aliases in the\n Key Management Service Developer Guide.
\nThis operation does not return a response. To get the alias that you created, use the\n ListAliases operation.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on an alias in a different Amazon Web Services account.
\n\n Required permissions\n
\n\n kms:CreateAlias on\n the alias (IAM policy).
\n\n kms:CreateAlias on\n the KMS key (key policy).
\nFor details, see Controlling access to aliases in the\n Key Management Service Developer Guide.
\n\n Related operations:\n
\n\n DeleteAlias\n
\n\n ListAliases\n
\n\n UpdateAlias\n
\nCreates a friendly name for a KMS key.
\nAdding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see ABAC for KMS in the Key Management Service Developer Guide.
\nYou can use an alias to identify a KMS key in the KMS console, in the DescribeKey operation and in cryptographic operations, such as Encrypt and\n GenerateDataKey. You can also change the KMS key that's associated with\n the alias (UpdateAlias) or delete the alias (DeleteAlias)\n at any time. These operations don't affect the underlying KMS key.
\nYou can associate the alias with any customer managed key in the same Amazon Web Services Region. Each\n alias is associated with only one KMS key at a time, but a KMS key can have multiple aliases.\n A valid KMS key is required. You can't create an alias without a KMS key.
\nThe alias must be unique in the account and Region, but you can have aliases with the same\n name in different Regions. For detailed information about aliases, see Using aliases in the\n Key Management Service Developer Guide.
\nThis operation does not return a response. To get the alias that you created, use the\n ListAliases operation.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on an alias in a different Amazon Web Services account.
\n\n Required permissions\n
\n\n kms:CreateAlias on\n the alias (IAM policy).
\n\n kms:CreateAlias on\n the KMS key (key policy).
\nFor details, see Controlling access to aliases in the\n Key Management Service Developer Guide.
\n\n Related operations:\n
\n\n DeleteAlias\n
\n\n ListAliases\n
\n\n UpdateAlias\n
\nCreates a custom key store backed by a key store that you own and manage. When you use a\n KMS key in a custom key store for a cryptographic operation, the cryptographic operation is\n actually performed in your key store using your keys. KMS supports CloudHSM key stores\n backed by an CloudHSM cluster\n and external key\n stores backed by an external key store proxy and external key manager outside of\n Amazon Web Services.
\nThis operation is part of the custom key stores feature in KMS, which\ncombines the convenience and extensive integration of KMS with the isolation and control of a\nkey store that you own and manage.
\nBefore you create the custom key store, the required elements must be in place and\n operational. We recommend that you use the test tools that KMS provides to verify the\n configuration your external key store proxy. For details about the required elements and\n verification tests, see Assemble the prerequisites (for\n CloudHSM key stores) or Assemble the prerequisites (for\n external key stores) in the Key Management Service Developer Guide.
\nTo create a custom key store, use the following parameters.
\nTo create an CloudHSM key store, specify the CustomKeyStoreName,\n CloudHsmClusterId, KeyStorePassword, and\n TrustAnchorCertificate. The CustomKeyStoreType parameter is\n optional for CloudHSM key stores. If you include it, set it to the default value,\n AWS_CLOUDHSM. For help with failures, see Troubleshooting an CloudHSM key store in the\n Key Management Service Developer Guide.
To create an external key store, specify the CustomKeyStoreName and a\n CustomKeyStoreType of EXTERNAL_KEY_STORE. Also, specify values\n for XksProxyConnectivity, XksProxyAuthenticationCredential,\n XksProxyUriEndpoint, and XksProxyUriPath. If your\n XksProxyConnectivity value is VPC_ENDPOINT_SERVICE, specify\n the XksProxyVpcEndpointServiceName parameter. For help with failures, see\n Troubleshooting\n an external key store in the Key Management Service Developer Guide.
For external key stores:
\nSome external key managers provide a simpler method for creating an external key store.\n For details, see your external key manager documentation.
\nWhen creating an external key store in the KMS console, you can upload a JSON-based\n proxy configuration file with the desired values. You cannot use a proxy configuration with\n the CreateCustomKeyStore operation. However, you can use the values in the file\n to help you determine the correct values for the CreateCustomKeyStore\n parameters.
When the operation completes successfully, it returns the ID of the new custom key store.\n Before you can use your new custom key store, you need to use the ConnectCustomKeyStore operation to connect a new CloudHSM key store to its CloudHSM\n cluster, or to connect a new external key store to the external key store proxy for your\n external key manager. Even if you are not going to use your custom key store immediately, you\n might want to connect it to verify that all settings are correct and then disconnect it until\n you are ready to use it.
\nFor help with failures, see Troubleshooting a custom key store in the\n Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.
\n\n Required permissions: kms:CreateCustomKeyStore (IAM policy).
\n\n Related operations:\n
\n\n DeleteCustomKeyStore\n
\n\n UpdateCustomKeyStore\n
\nCreates a custom key store backed by a key store that you own and manage. When you use a\n KMS key in a custom key store for a cryptographic operation, the cryptographic operation is\n actually performed in your key store using your keys. KMS supports CloudHSM key stores\n backed by an CloudHSM cluster\n and external key\n stores backed by an external key store proxy and external key manager outside of\n Amazon Web Services.
\nThis operation is part of the custom key stores feature in KMS, which\ncombines the convenience and extensive integration of KMS with the isolation and control of a\nkey store that you own and manage.
\nBefore you create the custom key store, the required elements must be in place and\n operational. We recommend that you use the test tools that KMS provides to verify the\n configuration your external key store proxy. For details about the required elements and\n verification tests, see Assemble the prerequisites (for\n CloudHSM key stores) or Assemble the prerequisites (for\n external key stores) in the Key Management Service Developer Guide.
\nTo create a custom key store, use the following parameters.
\nTo create an CloudHSM key store, specify the CustomKeyStoreName,\n CloudHsmClusterId, KeyStorePassword, and\n TrustAnchorCertificate. The CustomKeyStoreType parameter is\n optional for CloudHSM key stores. If you include it, set it to the default value,\n AWS_CLOUDHSM. For help with failures, see Troubleshooting an CloudHSM key store in the\n Key Management Service Developer Guide.
To create an external key store, specify the CustomKeyStoreName and a\n CustomKeyStoreType of EXTERNAL_KEY_STORE. Also, specify values\n for XksProxyConnectivity, XksProxyAuthenticationCredential,\n XksProxyUriEndpoint, and XksProxyUriPath. If your\n XksProxyConnectivity value is VPC_ENDPOINT_SERVICE, specify\n the XksProxyVpcEndpointServiceName parameter. For help with failures, see\n Troubleshooting\n an external key store in the Key Management Service Developer Guide.
For external key stores:
\nSome external key managers provide a simpler method for creating an external key store.\n For details, see your external key manager documentation.
\nWhen creating an external key store in the KMS console, you can upload a JSON-based\n proxy configuration file with the desired values. You cannot use a proxy configuration with\n the CreateCustomKeyStore operation. However, you can use the values in the file\n to help you determine the correct values for the CreateCustomKeyStore\n parameters.
When the operation completes successfully, it returns the ID of the new custom key store.\n Before you can use your new custom key store, you need to use the ConnectCustomKeyStore operation to connect a new CloudHSM key store to its CloudHSM\n cluster, or to connect a new external key store to the external key store proxy for your\n external key manager. Even if you are not going to use your custom key store immediately, you\n might want to connect it to verify that all settings are correct and then disconnect it until\n you are ready to use it.
\nFor help with failures, see Troubleshooting a custom key store in the\n Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.
\n\n Required permissions: kms:CreateCustomKeyStore (IAM policy).
\n\n Related operations:\n
\n\n DeleteCustomKeyStore\n
\n\n UpdateCustomKeyStore\n
\nAdds a grant to a KMS key.
\nA grant is a policy instrument that allows Amazon Web Services principals to use\n KMS keys in cryptographic operations. It also can allow them to view a KMS key (DescribeKey) and create and manage grants. When authorizing access to a KMS key,\n grants are considered along with key policies and IAM policies. Grants are often used for\n temporary permissions because you can create one, use its permissions, and delete it without\n changing your key policies or IAM policies.
\nFor detailed information about grants, including grant terminology, see Grants in KMS in the\n \n Key Management Service Developer Guide\n . For examples of working with grants in several\n programming languages, see Programming grants.
\nThe CreateGrant operation returns a GrantToken and a\n GrantId.
When you create, retire, or revoke a grant, there might be a brief delay, usually less than five minutes, until the grant is available throughout KMS. This state is known as eventual consistency. Once the grant has achieved eventual consistency, the grantee\n principal can use the permissions in the grant without identifying the grant.
\nHowever, to use the permissions in the grant immediately, use the\n GrantToken that CreateGrant returns. For details, see Using a\n grant token in the \n Key Management Service Developer Guide\n .
The CreateGrant operation also returns a GrantId. You can\n use the GrantId and a key identifier to identify the grant in the RetireGrant and RevokeGrant operations. To find the grant\n ID, use the ListGrants or ListRetirableGrants\n operations.
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation on a KMS key in a different Amazon Web Services account, specify the key\n ARN in the value of the KeyId parameter.
\n Required permissions: kms:CreateGrant (key policy)
\n\n Related operations:\n
\n\n ListGrants\n
\n\n ListRetirableGrants\n
\n\n RetireGrant\n
\n\n RevokeGrant\n
\nAdds a grant to a KMS key.
\nA grant is a policy instrument that allows Amazon Web Services principals to use\n KMS keys in cryptographic operations. It also can allow them to view a KMS key (DescribeKey) and create and manage grants. When authorizing access to a KMS key,\n grants are considered along with key policies and IAM policies. Grants are often used for\n temporary permissions because you can create one, use its permissions, and delete it without\n changing your key policies or IAM policies.
\nFor detailed information about grants, including grant terminology, see Grants in KMS in the\n \n Key Management Service Developer Guide\n . For examples of working with grants in several\n programming languages, see Programming grants.
\nThe CreateGrant operation returns a GrantToken and a\n GrantId.
When you create, retire, or revoke a grant, there might be a brief delay, usually less than five minutes, until the grant is available throughout KMS. This state is known as eventual consistency. Once the grant has achieved eventual consistency, the grantee\n principal can use the permissions in the grant without identifying the grant.
\nHowever, to use the permissions in the grant immediately, use the\n GrantToken that CreateGrant returns. For details, see Using a\n grant token in the \n Key Management Service Developer Guide\n .
The CreateGrant operation also returns a GrantId. You can\n use the GrantId and a key identifier to identify the grant in the RetireGrant and RevokeGrant operations. To find the grant\n ID, use the ListGrants or ListRetirableGrants\n operations.
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation on a KMS key in a different Amazon Web Services account, specify the key\n ARN in the value of the KeyId parameter.
\n Required permissions: kms:CreateGrant (key policy)
\n\n Related operations:\n
\n\n ListGrants\n
\n\n ListRetirableGrants\n
\n\n RetireGrant\n
\n\n RevokeGrant\n
\nDecrypts ciphertext that was encrypted by a KMS key using any of the following\n operations:
\n\n Encrypt\n
\n\n GenerateDataKey\n
\n\n GenerateDataKeyPair\n
\nYou can use this operation to decrypt ciphertext that was encrypted under a symmetric\n encryption KMS key or an asymmetric encryption KMS key. When the KMS key is asymmetric, you\n must specify the KMS key and the encryption algorithm that was used to encrypt the ciphertext.\n For information about asymmetric KMS keys, see Asymmetric KMS keys in the Key Management Service Developer Guide.
\nThe Decrypt operation also decrypts ciphertext that was encrypted outside of\n KMS by the public key in an KMS asymmetric KMS key. However, it cannot decrypt symmetric\n ciphertext produced by other libraries, such as the Amazon Web Services Encryption SDK or Amazon S3 client-side encryption.\n These libraries return a ciphertext format that is incompatible with KMS.
If the ciphertext was encrypted under a symmetric encryption KMS key, the\n KeyId parameter is optional. KMS can get this information from metadata that\n it adds to the symmetric ciphertext blob. This feature adds durability to your implementation\n by ensuring that authorized users can decrypt ciphertext decades after it was encrypted, even\n if they've lost track of the key ID. However, specifying the KMS key is always recommended as\n a best practice. When you use the KeyId parameter to specify a KMS key, KMS\n only uses the KMS key you specify. If the ciphertext was encrypted under a different KMS key,\n the Decrypt operation fails. This practice ensures that you use the KMS key that\n you intend.
Whenever possible, use key policies to give users permission to call the\n Decrypt operation on a particular KMS key, instead of using &IAM; policies.\n Otherwise, you might create an &IAM; policy that gives the user Decrypt\n permission on all KMS keys. This user could decrypt ciphertext that was encrypted by KMS keys\n in other accounts if the key policy for the cross-account KMS key permits it. If you must use\n an IAM policy for Decrypt permissions, limit the user to particular KMS keys or\n particular trusted accounts. For details, see Best practices for IAM\n policies in the Key Management Service Developer Guide.
\n Decrypt also supports Amazon Web Services Nitro Enclaves, which provide an\n isolated compute environment in Amazon EC2. To call Decrypt for a Nitro enclave, use\n the Amazon Web Services Nitro Enclaves SDK or any Amazon Web Services SDK. Use the Recipient parameter to provide the\n attestation document for the enclave. Instead of the plaintext data, the response includes the\n plaintext data encrypted with the public key from the attestation document\n (CiphertextForRecipient).For information about the interaction between KMS and Amazon Web Services Nitro Enclaves, see How Amazon Web Services Nitro Enclaves uses KMS in the Key Management Service Developer Guide..
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. If you use the KeyId\n parameter to identify a KMS key in a different Amazon Web Services account, specify the key ARN or the alias\n ARN of the KMS key.
\n Required permissions: kms:Decrypt (key policy)
\n\n Related operations:\n
\n\n Encrypt\n
\n\n GenerateDataKey\n
\n\n GenerateDataKeyPair\n
\n\n ReEncrypt\n
\nDecrypts ciphertext that was encrypted by a KMS key using any of the following\n operations:
\n\n Encrypt\n
\n\n GenerateDataKey\n
\n\n GenerateDataKeyPair\n
\nYou can use this operation to decrypt ciphertext that was encrypted under a symmetric\n encryption KMS key or an asymmetric encryption KMS key. When the KMS key is asymmetric, you\n must specify the KMS key and the encryption algorithm that was used to encrypt the ciphertext.\n For information about asymmetric KMS keys, see Asymmetric KMS keys in the Key Management Service Developer Guide.
\nThe Decrypt operation also decrypts ciphertext that was encrypted outside of\n KMS by the public key in an KMS asymmetric KMS key. However, it cannot decrypt symmetric\n ciphertext produced by other libraries, such as the Amazon Web Services Encryption SDK or Amazon S3 client-side encryption.\n These libraries return a ciphertext format that is incompatible with KMS.
If the ciphertext was encrypted under a symmetric encryption KMS key, the\n KeyId parameter is optional. KMS can get this information from metadata that\n it adds to the symmetric ciphertext blob. This feature adds durability to your implementation\n by ensuring that authorized users can decrypt ciphertext decades after it was encrypted, even\n if they've lost track of the key ID. However, specifying the KMS key is always recommended as\n a best practice. When you use the KeyId parameter to specify a KMS key, KMS\n only uses the KMS key you specify. If the ciphertext was encrypted under a different KMS key,\n the Decrypt operation fails. This practice ensures that you use the KMS key that\n you intend.
Whenever possible, use key policies to give users permission to call the\n Decrypt operation on a particular KMS key, instead of using &IAM; policies.\n Otherwise, you might create an &IAM; policy that gives the user Decrypt\n permission on all KMS keys. This user could decrypt ciphertext that was encrypted by KMS keys\n in other accounts if the key policy for the cross-account KMS key permits it. If you must use\n an IAM policy for Decrypt permissions, limit the user to particular KMS keys or\n particular trusted accounts. For details, see Best practices for IAM\n policies in the Key Management Service Developer Guide.
\n Decrypt also supports Amazon Web Services Nitro Enclaves, which provide an\n isolated compute environment in Amazon EC2. To call Decrypt for a Nitro enclave, use\n the Amazon Web Services Nitro Enclaves SDK or any Amazon Web Services SDK. Use the Recipient parameter to provide the\n attestation document for the enclave. Instead of the plaintext data, the response includes the\n plaintext data encrypted with the public key from the attestation document\n (CiphertextForRecipient).For information about the interaction between KMS and Amazon Web Services Nitro Enclaves, see How Amazon Web Services Nitro Enclaves uses KMS in the Key Management Service Developer Guide..
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. If you use the KeyId\n parameter to identify a KMS key in a different Amazon Web Services account, specify the key ARN or the alias\n ARN of the KMS key.
\n Required permissions: kms:Decrypt (key policy)
\n\n Related operations:\n
\n\n Encrypt\n
\n\n GenerateDataKey\n
\n\n GenerateDataKeyPair\n
\n\n ReEncrypt\n
\nDeletes the specified alias.
\nAdding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see ABAC for KMS in the Key Management Service Developer Guide.
\nBecause an alias is not a property of a KMS key, you can delete and change the aliases of\n a KMS key without affecting the KMS key. Also, aliases do not appear in the response from the\n DescribeKey operation. To get the aliases of all KMS keys, use the ListAliases operation.
\nEach KMS key can have multiple aliases. To change the alias of a KMS key, use DeleteAlias to delete the current alias and CreateAlias to\n create a new alias. To associate an existing alias with a different KMS key, call UpdateAlias.
\n\n Cross-account use: No. You cannot perform this operation on an alias in a different Amazon Web Services account.
\n\n Required permissions\n
\n\n kms:DeleteAlias on\n the alias (IAM policy).
\n\n kms:DeleteAlias on\n the KMS key (key policy).
\nFor details, see Controlling access to aliases in the\n Key Management Service Developer Guide.
\n\n Related operations:\n
\n\n CreateAlias\n
\n\n ListAliases\n
\n\n UpdateAlias\n
\nDeletes the specified alias.
\nAdding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see ABAC for KMS in the Key Management Service Developer Guide.
\nBecause an alias is not a property of a KMS key, you can delete and change the aliases of\n a KMS key without affecting the KMS key. Also, aliases do not appear in the response from the\n DescribeKey operation. To get the aliases of all KMS keys, use the ListAliases operation.
\nEach KMS key can have multiple aliases. To change the alias of a KMS key, use DeleteAlias to delete the current alias and CreateAlias to\n create a new alias. To associate an existing alias with a different KMS key, call UpdateAlias.
\n\n Cross-account use: No. You cannot perform this operation on an alias in a different Amazon Web Services account.
\n\n Required permissions\n
\n\n kms:DeleteAlias on\n the alias (IAM policy).
\n\n kms:DeleteAlias on\n the KMS key (key policy).
\nFor details, see Controlling access to aliases in the\n Key Management Service Developer Guide.
\n\n Related operations:\n
\n\n CreateAlias\n
\n\n ListAliases\n
\n\n UpdateAlias\n
\nDeletes a custom key store. This operation does not affect any backing elements of the\n custom key store. It does not delete the CloudHSM cluster that is associated with an CloudHSM key\n store, or affect any users or keys in the cluster. For an external key store, it does not\n affect the external key store proxy, external key manager, or any external keys.
\nThis operation is part of the custom key stores feature in KMS, which\ncombines the convenience and extensive integration of KMS with the isolation and control of a\nkey store that you own and manage.
\nThe custom key store that you delete cannot contain any KMS keys. Before deleting the key store,\n verify that you will never need to use any of the KMS keys in the key store for any\n cryptographic operations. Then, use ScheduleKeyDeletion to delete the KMS keys from the\n key store. After the required waiting period expires and all KMS keys are deleted from the\n custom key store, use DisconnectCustomKeyStore to disconnect the key store\n from KMS. Then, you can delete the custom key store.
\nFor keys in an CloudHSM key store, the ScheduleKeyDeletion operation makes a\n best effort to delete the key material from the associated cluster. However, you might need to\n manually delete the orphaned key\n material from the cluster and its backups. KMS never creates, manages, or deletes\n cryptographic keys in the external key manager associated with an external key store. You must\n manage them using your external key manager tools.
Instead of deleting the custom key store, consider using the DisconnectCustomKeyStore operation to disconnect the custom key store from its\n backing key store. While the key store is disconnected, you cannot create or use the KMS keys\n in the key store. But, you do not need to delete KMS keys and you can reconnect a disconnected\n custom key store at any time.
\nIf the operation succeeds, it returns a JSON object with no\nproperties.
\n\n Cross-account use: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.
\n\n Required permissions: kms:DeleteCustomKeyStore (IAM policy)
\n\n Related operations:\n
\n\n CreateCustomKeyStore\n
\n\n UpdateCustomKeyStore\n
\nDeletes a custom key store. This operation does not affect any backing elements of the\n custom key store. It does not delete the CloudHSM cluster that is associated with an CloudHSM key\n store, or affect any users or keys in the cluster. For an external key store, it does not\n affect the external key store proxy, external key manager, or any external keys.
\nThis operation is part of the custom key stores feature in KMS, which\ncombines the convenience and extensive integration of KMS with the isolation and control of a\nkey store that you own and manage.
\nThe custom key store that you delete cannot contain any KMS keys. Before deleting the key store,\n verify that you will never need to use any of the KMS keys in the key store for any\n cryptographic operations. Then, use ScheduleKeyDeletion to delete the KMS keys from the\n key store. After the required waiting period expires and all KMS keys are deleted from the\n custom key store, use DisconnectCustomKeyStore to disconnect the key store\n from KMS. Then, you can delete the custom key store.
\nFor keys in an CloudHSM key store, the ScheduleKeyDeletion operation makes a\n best effort to delete the key material from the associated cluster. However, you might need to\n manually delete the orphaned key\n material from the cluster and its backups. KMS never creates, manages, or deletes\n cryptographic keys in the external key manager associated with an external key store. You must\n manage them using your external key manager tools.
Instead of deleting the custom key store, consider using the DisconnectCustomKeyStore operation to disconnect the custom key store from its\n backing key store. While the key store is disconnected, you cannot create or use the KMS keys\n in the key store. But, you do not need to delete KMS keys and you can reconnect a disconnected\n custom key store at any time.
\nIf the operation succeeds, it returns a JSON object with no\nproperties.
\n\n Cross-account use: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.
\n\n Required permissions: kms:DeleteCustomKeyStore (IAM policy)
\n\n Related operations:\n
\n\n CreateCustomKeyStore\n
\n\n UpdateCustomKeyStore\n
\nDeletes key material that was previously imported. This operation makes the specified KMS\n key temporarily unusable. To restore the usability of the KMS key, reimport the same key\n material. For more information about importing key material into KMS, see Importing Key Material\n in the Key Management Service Developer Guide.
\nWhen the specified KMS key is in the PendingDeletion state, this operation\n does not change the KMS key's state. Otherwise, it changes the KMS key's state to\n PendingImport.
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:DeleteImportedKeyMaterial (key policy)
\n\n Related operations:\n
\n\n ImportKeyMaterial\n
\nDeletes key material that was previously imported. This operation makes the specified KMS\n key temporarily unusable. To restore the usability of the KMS key, reimport the same key\n material. For more information about importing key material into KMS, see Importing Key Material\n in the Key Management Service Developer Guide.
\nWhen the specified KMS key is in the PendingDeletion state, this operation\n does not change the KMS key's state. Otherwise, it changes the KMS key's state to\n PendingImport.
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:DeleteImportedKeyMaterial (key policy)
\n\n Related operations:\n
\n\n ImportKeyMaterial\n
\nGets information about custom key stores in the account and Region.
\nThis operation is part of the custom key stores feature in KMS, which\ncombines the convenience and extensive integration of KMS with the isolation and control of a\nkey store that you own and manage.
\nBy default, this operation returns information about all custom key stores in the account\n and Region. To get only information about a particular custom key store, use either the\n CustomKeyStoreName or CustomKeyStoreId parameter (but not\n both).
To determine whether the custom key store is connected to its CloudHSM cluster or external\n key store proxy, use the ConnectionState element in the response. If an attempt\n to connect the custom key store failed, the ConnectionState value is\n FAILED and the ConnectionErrorCode element in the response\n indicates the cause of the failure. For help interpreting the\n ConnectionErrorCode, see CustomKeyStoresListEntry.
Custom key stores have a DISCONNECTED connection state if the key store has\n never been connected or you used the DisconnectCustomKeyStore operation to\n disconnect it. Otherwise, the connection state is CONNECTED. If your custom key store\n connection state is CONNECTED but you are having trouble using it, verify that\n the backing store is active and available. For an CloudHSM key store, verify that the associated\n CloudHSM cluster is active and contains the minimum number of HSMs required for the operation, if\n any. For an external key store, verify that the external key store proxy and its associated\n external key manager are reachable and enabled.
For help repairing your CloudHSM key store, see the Troubleshooting CloudHSM key stores. For help\n repairing your external key store, see the Troubleshooting external key stores.\n Both topics are in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.
\n\n Required permissions: kms:DescribeCustomKeyStores (IAM policy)
\n\n Related operations:\n
\n\n CreateCustomKeyStore\n
\n\n DeleteCustomKeyStore\n
\n\n UpdateCustomKeyStore\n
\nSets the state of a KMS key to disabled. This change temporarily prevents use of the KMS\n key for cryptographic operations.
\nFor more information about how key state affects the use of a KMS key, see\n Key states of KMS keys in the \n Key Management Service Developer Guide\n .
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:DisableKey (key policy)
\n\n Related operations: EnableKey\n
" + "smithy.api#documentation": "Sets the state of a KMS key to disabled. This change temporarily prevents use of the KMS\n key for cryptographic operations.
\nFor more information about how key state affects the use of a KMS key, see\n Key states of KMS keys in the \n Key Management Service Developer Guide\n .
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:DisableKey (key policy)
\n\n Related operations: EnableKey\n
", + "smithy.api#examples": [ + { + "title": "To disable a KMS key", + "documentation": "The following example disables the specified KMS key.", + "input": { + "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab" + } + } + ] } }, "com.amazonaws.kms#DisableKeyRequest": { @@ -1842,7 +1968,16 @@ } ], "traits": { - "smithy.api#documentation": "Disables automatic\n rotation of the key material of the specified symmetric encryption KMS key.
\nAutomatic key rotation is supported only on symmetric encryption KMS keys.\n You cannot enable automatic rotation of asymmetric KMS keys, HMAC KMS keys, KMS keys with imported key material, or KMS keys in a custom key store. To enable or disable automatic rotation of a set of related multi-Region keys, set the property on the primary key.
\nYou can enable (EnableKeyRotation) and disable automatic rotation of the\n key material in customer managed KMS keys. Key material rotation of Amazon Web Services managed KMS keys is not\n configurable. KMS always rotates the key material for every year. Rotation of Amazon Web Services owned KMS\n keys varies.
\nIn May 2022, KMS changed the rotation schedule for Amazon Web Services managed keys from every three\n years to every year. For details, see EnableKeyRotation.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:DisableKeyRotation (key policy)
\n\n Related operations:\n
\n\n EnableKeyRotation\n
\n\n GetKeyRotationStatus\n
\nDisables automatic\n rotation of the key material of the specified symmetric encryption KMS key.
\nAutomatic key rotation is supported only on symmetric encryption KMS keys.\n You cannot enable automatic rotation of asymmetric KMS keys, HMAC KMS keys, KMS keys with imported key material, or KMS keys in a custom key store. To enable or disable automatic rotation of a set of related multi-Region keys, set the property on the primary key.
\nYou can enable (EnableKeyRotation) and disable automatic rotation of the\n key material in customer managed KMS keys. Key material rotation of Amazon Web Services managed KMS keys is not\n configurable. KMS always rotates the key material for every year. Rotation of Amazon Web Services owned KMS\n keys varies.
\nIn May 2022, KMS changed the rotation schedule for Amazon Web Services managed keys from every three\n years to every year. For details, see EnableKeyRotation.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:DisableKeyRotation (key policy)
\n\n Related operations:\n
\n\n EnableKeyRotation\n
\n\n GetKeyRotationStatus\n
\nDisconnects the custom key store from its backing key store. This operation disconnects an\n CloudHSM key store from its associated CloudHSM cluster or disconnects an external key store from\n the external key store proxy that communicates with your external key manager.
\nThis operation is part of the custom key stores feature in KMS, which\ncombines the convenience and extensive integration of KMS with the isolation and control of a\nkey store that you own and manage.
\nWhile a custom key store is disconnected, you can manage the custom key store and its KMS\n keys, but you cannot create or use its KMS keys. You can reconnect the custom key store at any\n time.
\nWhile a custom key store is disconnected, all attempts to create KMS keys in the custom key store or to use existing KMS keys in cryptographic operations will\n fail. This action can prevent users from storing and accessing sensitive data.
\nWhen you disconnect a custom key store, its ConnectionState changes to\n Disconnected. To find the connection state of a custom key store, use the DescribeCustomKeyStores operation. To reconnect a custom key store, use the\n ConnectCustomKeyStore operation.
If the operation succeeds, it returns a JSON object with no\nproperties.
\n\n Cross-account use: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.
\n\n Required permissions: kms:DisconnectCustomKeyStore (IAM policy)
\n\n Related operations:\n
\n\n CreateCustomKeyStore\n
\n\n DeleteCustomKeyStore\n
\n\n UpdateCustomKeyStore\n
\nDisconnects the custom key store from its backing key store. This operation disconnects an\n CloudHSM key store from its associated CloudHSM cluster or disconnects an external key store from\n the external key store proxy that communicates with your external key manager.
\nThis operation is part of the custom key stores feature in KMS, which\ncombines the convenience and extensive integration of KMS with the isolation and control of a\nkey store that you own and manage.
\nWhile a custom key store is disconnected, you can manage the custom key store and its KMS\n keys, but you cannot create or use its KMS keys. You can reconnect the custom key store at any\n time.
\nWhile a custom key store is disconnected, all attempts to create KMS keys in the custom key store or to use existing KMS keys in cryptographic operations will\n fail. This action can prevent users from storing and accessing sensitive data.
\nWhen you disconnect a custom key store, its ConnectionState changes to\n Disconnected. To find the connection state of a custom key store, use the DescribeCustomKeyStores operation. To reconnect a custom key store, use the\n ConnectCustomKeyStore operation.
If the operation succeeds, it returns a JSON object with no\nproperties.
\n\n Cross-account use: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.
\n\n Required permissions: kms:DisconnectCustomKeyStore (IAM policy)
\n\n Related operations:\n
\n\n CreateCustomKeyStore\n
\n\n DeleteCustomKeyStore\n
\n\n UpdateCustomKeyStore\n
\nDescribeCustomKeyStores operation.",
+ "input": {
+ "CustomKeyStoreId": "cks-1234567890abcdef0"
+ },
+ "output": {}
+ }
+ ]
}
},
"com.amazonaws.kms#DisconnectCustomKeyStoreRequest": {
@@ -1968,7 +2113,16 @@
}
],
"traits": {
- "smithy.api#documentation": "Sets the key state of a KMS key to enabled. This allows you to use the KMS key for\n cryptographic operations.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:EnableKey (key policy)
\n\n Related operations: DisableKey\n
" + "smithy.api#documentation": "Sets the key state of a KMS key to enabled. This allows you to use the KMS key for\n cryptographic operations.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:EnableKey (key policy)
\n\n Related operations: DisableKey\n
", + "smithy.api#examples": [ + { + "title": "To enable a KMS key", + "documentation": "The following example enables the specified KMS key.", + "input": { + "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab" + } + } + ] } }, "com.amazonaws.kms#EnableKeyRequest": { @@ -2018,7 +2172,16 @@ } ], "traits": { - "smithy.api#documentation": "Enables automatic rotation\n of the key material of the specified symmetric encryption KMS key.
\nWhen you enable automatic rotation of acustomer managed KMS key, KMS\n rotates the key material of the KMS key one year (approximately 365 days) from the enable date\n and every year thereafter. You can monitor rotation of the key material for your KMS keys in\n CloudTrail and Amazon CloudWatch. To disable rotation of the key material in a customer\n managed KMS key, use the DisableKeyRotation operation.
\nAutomatic key rotation is supported only on symmetric encryption KMS keys.\n You cannot enable automatic rotation of asymmetric KMS keys, HMAC KMS keys, KMS keys with imported key material, or KMS keys in a custom key store. To enable or disable automatic rotation of a set of related multi-Region keys, set the property on the primary key.
\nYou cannot enable or disable automatic rotation Amazon Web Services managed KMS keys. KMS\n always rotates the key material of Amazon Web Services managed keys every year. Rotation of Amazon Web Services owned KMS\n keys varies.
\nIn May 2022, KMS changed the rotation schedule for Amazon Web Services managed keys from every three\n years (approximately 1,095 days) to every year (approximately 365 days).
\nNew Amazon Web Services managed keys are automatically rotated one year after they are created, and\n approximately every year thereafter.
\nExisting Amazon Web Services managed keys are automatically rotated one year after their most recent\n rotation, and every year thereafter.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:EnableKeyRotation (key policy)
\n\n Related operations:\n
\n\n DisableKeyRotation\n
\n\n GetKeyRotationStatus\n
\nEnables automatic rotation\n of the key material of the specified symmetric encryption KMS key.
\nWhen you enable automatic rotation of acustomer managed KMS key, KMS\n rotates the key material of the KMS key one year (approximately 365 days) from the enable date\n and every year thereafter. You can monitor rotation of the key material for your KMS keys in\n CloudTrail and Amazon CloudWatch. To disable rotation of the key material in a customer\n managed KMS key, use the DisableKeyRotation operation.
\nAutomatic key rotation is supported only on symmetric encryption KMS keys.\n You cannot enable automatic rotation of asymmetric KMS keys, HMAC KMS keys, KMS keys with imported key material, or KMS keys in a custom key store. To enable or disable automatic rotation of a set of related multi-Region keys, set the property on the primary key.
\nYou cannot enable or disable automatic rotation Amazon Web Services managed KMS keys. KMS\n always rotates the key material of Amazon Web Services managed keys every year. Rotation of Amazon Web Services owned KMS\n keys varies.
\nIn May 2022, KMS changed the rotation schedule for Amazon Web Services managed keys from every three\n years (approximately 1,095 days) to every year (approximately 365 days).
\nNew Amazon Web Services managed keys are automatically rotated one year after they are created, and\n approximately every year thereafter.
\nExisting Amazon Web Services managed keys are automatically rotated one year after their most recent\n rotation, and every year thereafter.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:EnableKeyRotation (key policy)
\n\n Related operations:\n
\n\n DisableKeyRotation\n
\n\n GetKeyRotationStatus\n
\nEncrypts plaintext of up to 4,096 bytes using a KMS key. You can use a symmetric or\n asymmetric KMS key with a KeyUsage of ENCRYPT_DECRYPT.
You can use this operation to encrypt small amounts of arbitrary data, such as a personal\n identifier or database password, or other sensitive information. You don't need to use the\n Encrypt operation to encrypt a data key. The GenerateDataKey\n and GenerateDataKeyPair operations return a plaintext data key and an\n encrypted copy of that data key.
If you use a symmetric encryption KMS key, you can use an encryption context to add\n additional security to your encryption operation. If you specify an\n EncryptionContext when encrypting data, you must specify the same encryption\n context (a case-sensitive exact match) when decrypting the data. Otherwise, the request to\n decrypt fails with an InvalidCiphertextException. For more information, see\n Encryption\n Context in the Key Management Service Developer Guide.
If you specify an asymmetric KMS key, you must also specify the encryption algorithm. The\n algorithm must be compatible with the KMS key spec.
\nWhen you use an asymmetric KMS key to encrypt or reencrypt data, be sure to record the KMS key and encryption algorithm that you choose. You will be required to provide the same KMS key and encryption algorithm when you decrypt the data. If the KMS key and algorithm do not match the values used to encrypt the data, the decrypt operation fails.
\nYou are not required to supply the key ID and encryption algorithm when you decrypt with symmetric encryption KMS keys because KMS stores this information in the ciphertext blob. KMS cannot store metadata in ciphertext generated with asymmetric keys. The standard format for asymmetric key ciphertext does not include configurable fields.
\nThe maximum size of the data that you can encrypt varies with the type of KMS key and the\n encryption algorithm that you choose.
\nSymmetric encryption KMS keys
\n\n SYMMETRIC_DEFAULT: 4096 bytes
\n RSA_2048\n
\n RSAES_OAEP_SHA_1: 214 bytes
\n RSAES_OAEP_SHA_256: 190 bytes
\n RSA_3072\n
\n RSAES_OAEP_SHA_1: 342 bytes
\n RSAES_OAEP_SHA_256: 318 bytes
\n RSA_4096\n
\n RSAES_OAEP_SHA_1: 470 bytes
\n RSAES_OAEP_SHA_256: 446 bytes
\n SM2PKE: 1024 bytes (China Regions only)
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:Encrypt (key policy)
\n\n Related operations:\n
\n\n Decrypt\n
\n\n GenerateDataKey\n
\n\n GenerateDataKeyPair\n
\nEncrypts plaintext of up to 4,096 bytes using a KMS key. You can use a symmetric or\n asymmetric KMS key with a KeyUsage of ENCRYPT_DECRYPT.
You can use this operation to encrypt small amounts of arbitrary data, such as a personal\n identifier or database password, or other sensitive information. You don't need to use the\n Encrypt operation to encrypt a data key. The GenerateDataKey\n and GenerateDataKeyPair operations return a plaintext data key and an\n encrypted copy of that data key.
If you use a symmetric encryption KMS key, you can use an encryption context to add\n additional security to your encryption operation. If you specify an\n EncryptionContext when encrypting data, you must specify the same encryption\n context (a case-sensitive exact match) when decrypting the data. Otherwise, the request to\n decrypt fails with an InvalidCiphertextException. For more information, see\n Encryption\n Context in the Key Management Service Developer Guide.
If you specify an asymmetric KMS key, you must also specify the encryption algorithm. The\n algorithm must be compatible with the KMS key spec.
\nWhen you use an asymmetric KMS key to encrypt or reencrypt data, be sure to record the KMS key and encryption algorithm that you choose. You will be required to provide the same KMS key and encryption algorithm when you decrypt the data. If the KMS key and algorithm do not match the values used to encrypt the data, the decrypt operation fails.
\nYou are not required to supply the key ID and encryption algorithm when you decrypt with symmetric encryption KMS keys because KMS stores this information in the ciphertext blob. KMS cannot store metadata in ciphertext generated with asymmetric keys. The standard format for asymmetric key ciphertext does not include configurable fields.
\nThe maximum size of the data that you can encrypt varies with the type of KMS key and the\n encryption algorithm that you choose.
\nSymmetric encryption KMS keys
\n\n SYMMETRIC_DEFAULT: 4096 bytes
\n RSA_2048\n
\n RSAES_OAEP_SHA_1: 214 bytes
\n RSAES_OAEP_SHA_256: 190 bytes
\n RSA_3072\n
\n RSAES_OAEP_SHA_1: 342 bytes
\n RSAES_OAEP_SHA_256: 318 bytes
\n RSA_4096\n
\n RSAES_OAEP_SHA_1: 470 bytes
\n RSAES_OAEP_SHA_256: 446 bytes
\n SM2PKE: 1024 bytes (China Regions only)
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:Encrypt (key policy)
\n\n Related operations:\n
\n\n Decrypt\n
\n\n GenerateDataKey\n
\n\n GenerateDataKeyPair\n
\nReturns a unique symmetric data key for use outside of KMS. This operation returns a\n plaintext copy of the data key and a copy that is encrypted under a symmetric encryption KMS\n key that you specify. The bytes in the plaintext key are random; they are not related to the\n caller or the KMS key. You can use the plaintext key to encrypt your data outside of KMS and\n store the encrypted data key with the encrypted data.
\nTo generate a data key, specify the symmetric encryption KMS key that will be used to\n encrypt the data key. You cannot use an asymmetric KMS key to encrypt data keys. To get the\n type of your KMS key, use the DescribeKey operation.
\nYou must also specify the length of the data key. Use either the KeySpec or\n NumberOfBytes parameters (but not both). For 128-bit and 256-bit data keys, use\n the KeySpec parameter.
To generate a 128-bit SM4 data key (China Regions only), specify a KeySpec\n value of AES_128 or a NumberOfBytes value of 16. The\n symmetric encryption key used in China Regions to encrypt your data key is an SM4 encryption\n key.
To get only an encrypted copy of the data key, use GenerateDataKeyWithoutPlaintext. To generate an asymmetric data key pair, use\n the GenerateDataKeyPair or GenerateDataKeyPairWithoutPlaintext operation. To get a cryptographically secure\n random byte string, use GenerateRandom.
\nYou can use an optional encryption context to add additional security to the encryption\n operation. If you specify an EncryptionContext, you must specify the same\n encryption context (a case-sensitive exact match) when decrypting the encrypted data key.\n Otherwise, the request to decrypt fails with an InvalidCiphertextException. For more information, see Encryption Context in the\n Key Management Service Developer Guide.
\n GenerateDataKey also supports Amazon Web Services Nitro Enclaves, which provide an\n isolated compute environment in Amazon EC2. To call GenerateDataKey for an Amazon Web Services Nitro\n enclave, use the Amazon Web Services Nitro Enclaves SDK or any Amazon Web Services SDK. Use the Recipient parameter\n to provide the attestation document for the enclave. GenerateDataKey returns a\n copy of the data key encrypted under the specified KMS key, as usual. But instead of a\n plaintext copy of the data key, the response includes a copy of the data key encrypted under\n the public key from the attestation document (CiphertextForRecipient).\n For information about the interaction between KMS and Amazon Web Services Nitro Enclaves, see How Amazon Web Services Nitro Enclaves uses KMS in the Key Management Service Developer Guide..
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n How to use your data key\n
\nWe recommend that you use the following pattern to encrypt data locally in your\n application. You can write your own code or use a client-side encryption library, such as the\n Amazon Web Services Encryption SDK, the\n Amazon DynamoDB Encryption Client,\n or Amazon S3\n client-side encryption to do these tasks for you.
\nTo encrypt data outside of KMS:
\nUse the GenerateDataKey operation to get a data key.
Use the plaintext data key (in the Plaintext field of the response) to\n encrypt your data outside of KMS. Then erase the plaintext data key from memory.
Store the encrypted data key (in the CiphertextBlob field of the\n response) with the encrypted data.
To decrypt data outside of KMS:
\nUse the Decrypt operation to decrypt the encrypted data key. The\n operation returns a plaintext copy of the data key.
\nUse the plaintext data key to decrypt data outside of KMS, then erase the plaintext\n data key from memory.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:GenerateDataKey (key policy)
\n\n Related operations:\n
\n\n Decrypt\n
\n\n Encrypt\n
\n\n GenerateDataKeyPair\n
\nReturns a unique symmetric data key for use outside of KMS. This operation returns a\n plaintext copy of the data key and a copy that is encrypted under a symmetric encryption KMS\n key that you specify. The bytes in the plaintext key are random; they are not related to the\n caller or the KMS key. You can use the plaintext key to encrypt your data outside of KMS and\n store the encrypted data key with the encrypted data.
\nTo generate a data key, specify the symmetric encryption KMS key that will be used to\n encrypt the data key. You cannot use an asymmetric KMS key to encrypt data keys. To get the\n type of your KMS key, use the DescribeKey operation.
\nYou must also specify the length of the data key. Use either the KeySpec or\n NumberOfBytes parameters (but not both). For 128-bit and 256-bit data keys, use\n the KeySpec parameter.
To generate a 128-bit SM4 data key (China Regions only), specify a KeySpec\n value of AES_128 or a NumberOfBytes value of 16. The\n symmetric encryption key used in China Regions to encrypt your data key is an SM4 encryption\n key.
To get only an encrypted copy of the data key, use GenerateDataKeyWithoutPlaintext. To generate an asymmetric data key pair, use\n the GenerateDataKeyPair or GenerateDataKeyPairWithoutPlaintext operation. To get a cryptographically secure\n random byte string, use GenerateRandom.
\nYou can use an optional encryption context to add additional security to the encryption\n operation. If you specify an EncryptionContext, you must specify the same\n encryption context (a case-sensitive exact match) when decrypting the encrypted data key.\n Otherwise, the request to decrypt fails with an InvalidCiphertextException. For more information, see Encryption Context in the\n Key Management Service Developer Guide.
\n GenerateDataKey also supports Amazon Web Services Nitro Enclaves, which provide an\n isolated compute environment in Amazon EC2. To call GenerateDataKey for an Amazon Web Services Nitro\n enclave, use the Amazon Web Services Nitro Enclaves SDK or any Amazon Web Services SDK. Use the Recipient parameter\n to provide the attestation document for the enclave. GenerateDataKey returns a\n copy of the data key encrypted under the specified KMS key, as usual. But instead of a\n plaintext copy of the data key, the response includes a copy of the data key encrypted under\n the public key from the attestation document (CiphertextForRecipient).\n For information about the interaction between KMS and Amazon Web Services Nitro Enclaves, see How Amazon Web Services Nitro Enclaves uses KMS in the Key Management Service Developer Guide..
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n How to use your data key\n
\nWe recommend that you use the following pattern to encrypt data locally in your\n application. You can write your own code or use a client-side encryption library, such as the\n Amazon Web Services Encryption SDK, the\n Amazon DynamoDB Encryption Client,\n or Amazon S3\n client-side encryption to do these tasks for you.
\nTo encrypt data outside of KMS:
\nUse the GenerateDataKey operation to get a data key.
Use the plaintext data key (in the Plaintext field of the response) to\n encrypt your data outside of KMS. Then erase the plaintext data key from memory.
Store the encrypted data key (in the CiphertextBlob field of the\n response) with the encrypted data.
To decrypt data outside of KMS:
\nUse the Decrypt operation to decrypt the encrypted data key. The\n operation returns a plaintext copy of the data key.
\nUse the plaintext data key to decrypt data outside of KMS, then erase the plaintext\n data key from memory.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:GenerateDataKey (key policy)
\n\n Related operations:\n
\n\n Decrypt\n
\n\n Encrypt\n
\n\n GenerateDataKeyPair\n
\nReturns a unique asymmetric data key pair for use outside of KMS. This operation returns\n a plaintext public key, a plaintext private key, and a copy of the private key that is\n encrypted under the symmetric encryption KMS key you specify. You can use the data key pair to\n perform asymmetric cryptography and implement digital signatures outside of KMS. The bytes\n in the keys are random; they not related to the caller or to the KMS key that is used to\n encrypt the private key.
\nYou can use the public key that GenerateDataKeyPair returns to encrypt data\n or verify a signature outside of KMS. Then, store the encrypted private key with the data.\n When you are ready to decrypt data or sign a message, you can use the Decrypt operation to decrypt the encrypted private key.
To generate a data key pair, you must specify a symmetric encryption KMS key to encrypt\n the private key in a data key pair. You cannot use an asymmetric KMS key or a KMS key in a\n custom key store. To get the type and origin of your KMS key, use the DescribeKey operation.
\nUse the KeyPairSpec parameter to choose an RSA or Elliptic Curve (ECC) data\n key pair. In China Regions, you can also choose an SM2 data key pair. KMS recommends that\n you use ECC key pairs for signing, and use RSA and SM2 key pairs for either encryption or\n signing, but not both. However, KMS cannot enforce any restrictions on the use of data key\n pairs outside of KMS.
If you are using the data key pair to encrypt data, or for any operation where you don't\n immediately need a private key, consider using the GenerateDataKeyPairWithoutPlaintext operation.\n GenerateDataKeyPairWithoutPlaintext returns a plaintext public key and an\n encrypted private key, but omits the plaintext private key that you need only to decrypt\n ciphertext or sign a message. Later, when you need to decrypt the data or sign a message, use\n the Decrypt operation to decrypt the encrypted private key in the data key\n pair.
\n GenerateDataKeyPair returns a unique data key pair for each request. The\n bytes in the keys are random; they are not related to the caller or the KMS key that is used\n to encrypt the private key. The public key is a DER-encoded X.509 SubjectPublicKeyInfo, as\n specified in RFC 5280. The private\n key is a DER-encoded PKCS8 PrivateKeyInfo, as specified in RFC 5958.
\n GenerateDataKeyPair also supports Amazon Web Services Nitro Enclaves, which provide an\n isolated compute environment in Amazon EC2. To call GenerateDataKeyPair for an Amazon Web Services\n Nitro enclave, use the Amazon Web Services Nitro Enclaves SDK or any Amazon Web Services SDK. Use the Recipient\n parameter to provide the attestation document for the enclave.\n GenerateDataKeyPair returns the public data key and a copy of the private data\n key encrypted under the specified KMS key, as usual. But instead of a plaintext copy of the\n private data key (PrivateKeyPlaintext), the response includes a copy of the\n private data key encrypted under the public key from the attestation document\n (CiphertextForRecipient). For information about the interaction between KMS and Amazon Web Services Nitro Enclaves, see How Amazon Web Services Nitro Enclaves uses KMS in the Key Management Service Developer Guide..
You can use an optional encryption context to add additional security to the encryption\n operation. If you specify an EncryptionContext, you must specify the same\n encryption context (a case-sensitive exact match) when decrypting the encrypted data key.\n Otherwise, the request to decrypt fails with an InvalidCiphertextException. For more information, see Encryption Context in the\n Key Management Service Developer Guide.
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:GenerateDataKeyPair (key policy)
\n\n Related operations:\n
\n\n Decrypt\n
\n\n Encrypt\n
\n\n GenerateDataKey\n
\nReturns a unique asymmetric data key pair for use outside of KMS. This operation returns\n a plaintext public key, a plaintext private key, and a copy of the private key that is\n encrypted under the symmetric encryption KMS key you specify. You can use the data key pair to\n perform asymmetric cryptography and implement digital signatures outside of KMS. The bytes\n in the keys are random; they not related to the caller or to the KMS key that is used to\n encrypt the private key.
\nYou can use the public key that GenerateDataKeyPair returns to encrypt data\n or verify a signature outside of KMS. Then, store the encrypted private key with the data.\n When you are ready to decrypt data or sign a message, you can use the Decrypt operation to decrypt the encrypted private key.
To generate a data key pair, you must specify a symmetric encryption KMS key to encrypt\n the private key in a data key pair. You cannot use an asymmetric KMS key or a KMS key in a\n custom key store. To get the type and origin of your KMS key, use the DescribeKey operation.
\nUse the KeyPairSpec parameter to choose an RSA or Elliptic Curve (ECC) data\n key pair. In China Regions, you can also choose an SM2 data key pair. KMS recommends that\n you use ECC key pairs for signing, and use RSA and SM2 key pairs for either encryption or\n signing, but not both. However, KMS cannot enforce any restrictions on the use of data key\n pairs outside of KMS.
If you are using the data key pair to encrypt data, or for any operation where you don't\n immediately need a private key, consider using the GenerateDataKeyPairWithoutPlaintext operation.\n GenerateDataKeyPairWithoutPlaintext returns a plaintext public key and an\n encrypted private key, but omits the plaintext private key that you need only to decrypt\n ciphertext or sign a message. Later, when you need to decrypt the data or sign a message, use\n the Decrypt operation to decrypt the encrypted private key in the data key\n pair.
\n GenerateDataKeyPair returns a unique data key pair for each request. The\n bytes in the keys are random; they are not related to the caller or the KMS key that is used\n to encrypt the private key. The public key is a DER-encoded X.509 SubjectPublicKeyInfo, as\n specified in RFC 5280. The private\n key is a DER-encoded PKCS8 PrivateKeyInfo, as specified in RFC 5958.
\n GenerateDataKeyPair also supports Amazon Web Services Nitro Enclaves, which provide an\n isolated compute environment in Amazon EC2. To call GenerateDataKeyPair for an Amazon Web Services\n Nitro enclave, use the Amazon Web Services Nitro Enclaves SDK or any Amazon Web Services SDK. Use the Recipient\n parameter to provide the attestation document for the enclave.\n GenerateDataKeyPair returns the public data key and a copy of the private data\n key encrypted under the specified KMS key, as usual. But instead of a plaintext copy of the\n private data key (PrivateKeyPlaintext), the response includes a copy of the\n private data key encrypted under the public key from the attestation document\n (CiphertextForRecipient). For information about the interaction between KMS and Amazon Web Services Nitro Enclaves, see How Amazon Web Services Nitro Enclaves uses KMS in the Key Management Service Developer Guide..
You can use an optional encryption context to add additional security to the encryption\n operation. If you specify an EncryptionContext, you must specify the same\n encryption context (a case-sensitive exact match) when decrypting the encrypted data key.\n Otherwise, the request to decrypt fails with an InvalidCiphertextException. For more information, see Encryption Context in the\n Key Management Service Developer Guide.
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:GenerateDataKeyPair (key policy)
\n\n Related operations:\n
\n\n Decrypt\n
\n\n Encrypt\n
\n\n GenerateDataKey\n
\nReturns a unique asymmetric data key pair for use outside of KMS. This operation returns\n a plaintext public key and a copy of the private key that is encrypted under the symmetric\n encryption KMS key you specify. Unlike GenerateDataKeyPair, this operation\n does not return a plaintext private key. The bytes in the keys are random; they are not\n related to the caller or to the KMS key that is used to encrypt the private key.
\nYou can use the public key that GenerateDataKeyPairWithoutPlaintext returns\n to encrypt data or verify a signature outside of KMS. Then, store the encrypted private key\n with the data. When you are ready to decrypt data or sign a message, you can use the Decrypt operation to decrypt the encrypted private key.
To generate a data key pair, you must specify a symmetric encryption KMS key to encrypt\n the private key in a data key pair. You cannot use an asymmetric KMS key or a KMS key in a\n custom key store. To get the type and origin of your KMS key, use the DescribeKey operation.
\nUse the KeyPairSpec parameter to choose an RSA or Elliptic Curve (ECC) data\n key pair. In China Regions, you can also choose an SM2 data key pair. KMS recommends that\n you use ECC key pairs for signing, and use RSA and SM2 key pairs for either encryption or\n signing, but not both. However, KMS cannot enforce any restrictions on the use of data key\n pairs outside of KMS.
\n GenerateDataKeyPairWithoutPlaintext returns a unique data key pair for each\n request. The bytes in the key are not related to the caller or KMS key that is used to encrypt\n the private key. The public key is a DER-encoded X.509 SubjectPublicKeyInfo, as specified in\n RFC 5280.
You can use an optional encryption context to add additional security to the encryption\n operation. If you specify an EncryptionContext, you must specify the same\n encryption context (a case-sensitive exact match) when decrypting the encrypted data key.\n Otherwise, the request to decrypt fails with an InvalidCiphertextException. For more information, see Encryption Context in the\n Key Management Service Developer Guide.
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:GenerateDataKeyPairWithoutPlaintext (key\n policy)
\n\n Related operations:\n
\n\n Decrypt\n
\n\n Encrypt\n
\n\n GenerateDataKey\n
\n\n GenerateDataKeyPair\n
\nReturns a unique asymmetric data key pair for use outside of KMS. This operation returns\n a plaintext public key and a copy of the private key that is encrypted under the symmetric\n encryption KMS key you specify. Unlike GenerateDataKeyPair, this operation\n does not return a plaintext private key. The bytes in the keys are random; they are not\n related to the caller or to the KMS key that is used to encrypt the private key.
\nYou can use the public key that GenerateDataKeyPairWithoutPlaintext returns\n to encrypt data or verify a signature outside of KMS. Then, store the encrypted private key\n with the data. When you are ready to decrypt data or sign a message, you can use the Decrypt operation to decrypt the encrypted private key.
To generate a data key pair, you must specify a symmetric encryption KMS key to encrypt\n the private key in a data key pair. You cannot use an asymmetric KMS key or a KMS key in a\n custom key store. To get the type and origin of your KMS key, use the DescribeKey operation.
\nUse the KeyPairSpec parameter to choose an RSA or Elliptic Curve (ECC) data\n key pair. In China Regions, you can also choose an SM2 data key pair. KMS recommends that\n you use ECC key pairs for signing, and use RSA and SM2 key pairs for either encryption or\n signing, but not both. However, KMS cannot enforce any restrictions on the use of data key\n pairs outside of KMS.
\n GenerateDataKeyPairWithoutPlaintext returns a unique data key pair for each\n request. The bytes in the key are not related to the caller or KMS key that is used to encrypt\n the private key. The public key is a DER-encoded X.509 SubjectPublicKeyInfo, as specified in\n RFC 5280.
You can use an optional encryption context to add additional security to the encryption\n operation. If you specify an EncryptionContext, you must specify the same\n encryption context (a case-sensitive exact match) when decrypting the encrypted data key.\n Otherwise, the request to decrypt fails with an InvalidCiphertextException. For more information, see Encryption Context in the\n Key Management Service Developer Guide.
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:GenerateDataKeyPairWithoutPlaintext (key\n policy)
\n\n Related operations:\n
\n\n Decrypt\n
\n\n Encrypt\n
\n\n GenerateDataKey\n
\n\n GenerateDataKeyPair\n
\nReturns a unique symmetric data key for use outside of KMS. This operation returns a\n data key that is encrypted under a symmetric encryption KMS key that you specify. The bytes in\n the key are random; they are not related to the caller or to the KMS key.
\n\n GenerateDataKeyWithoutPlaintext is identical to the GenerateDataKey operation except that it does not return a plaintext copy of the\n data key.
This operation is useful for systems that need to encrypt data at some point, but not\n immediately. When you need to encrypt the data, you call the Decrypt\n operation on the encrypted copy of the key.
\nIt's also useful in distributed systems with different levels of trust. For example, you\n might store encrypted data in containers. One component of your system creates new containers\n and stores an encrypted data key with each container. Then, a different component puts the\n data into the containers. That component first decrypts the data key, uses the plaintext data\n key to encrypt data, puts the encrypted data into the container, and then destroys the\n plaintext data key. In this system, the component that creates the containers never sees the\n plaintext data key.
\nTo request an asymmetric data key pair, use the GenerateDataKeyPair or\n GenerateDataKeyPairWithoutPlaintext operations.
\nTo generate a data key, you must specify the symmetric encryption KMS key that is used to\n encrypt the data key. You cannot use an asymmetric KMS key or a key in a custom key store to\n generate a data key. To get the type of your KMS key, use the DescribeKey\n operation.
\nYou must also specify the length of the data key. Use either the KeySpec or\n NumberOfBytes parameters (but not both). For 128-bit and 256-bit data keys, use\n the KeySpec parameter.
To generate an SM4 data key (China Regions only), specify a KeySpec value of\n AES_128 or NumberOfBytes value of 16. The symmetric\n encryption key used in China Regions to encrypt your data key is an SM4 encryption key.
If the operation succeeds, you will find the encrypted copy of the data key in the\n CiphertextBlob field.
You can use an optional encryption context to add additional security to the encryption\n operation. If you specify an EncryptionContext, you must specify the same\n encryption context (a case-sensitive exact match) when decrypting the encrypted data key.\n Otherwise, the request to decrypt fails with an InvalidCiphertextException. For more information, see Encryption Context in the\n Key Management Service Developer Guide.
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:GenerateDataKeyWithoutPlaintext (key\n policy)
\n\n Related operations:\n
\n\n Decrypt\n
\n\n Encrypt\n
\n\n GenerateDataKey\n
\n\n GenerateDataKeyPair\n
\nReturns a unique symmetric data key for use outside of KMS. This operation returns a\n data key that is encrypted under a symmetric encryption KMS key that you specify. The bytes in\n the key are random; they are not related to the caller or to the KMS key.
\n\n GenerateDataKeyWithoutPlaintext is identical to the GenerateDataKey operation except that it does not return a plaintext copy of the\n data key.
This operation is useful for systems that need to encrypt data at some point, but not\n immediately. When you need to encrypt the data, you call the Decrypt\n operation on the encrypted copy of the key.
\nIt's also useful in distributed systems with different levels of trust. For example, you\n might store encrypted data in containers. One component of your system creates new containers\n and stores an encrypted data key with each container. Then, a different component puts the\n data into the containers. That component first decrypts the data key, uses the plaintext data\n key to encrypt data, puts the encrypted data into the container, and then destroys the\n plaintext data key. In this system, the component that creates the containers never sees the\n plaintext data key.
\nTo request an asymmetric data key pair, use the GenerateDataKeyPair or\n GenerateDataKeyPairWithoutPlaintext operations.
\nTo generate a data key, you must specify the symmetric encryption KMS key that is used to\n encrypt the data key. You cannot use an asymmetric KMS key or a key in a custom key store to\n generate a data key. To get the type of your KMS key, use the DescribeKey\n operation.
\nYou must also specify the length of the data key. Use either the KeySpec or\n NumberOfBytes parameters (but not both). For 128-bit and 256-bit data keys, use\n the KeySpec parameter.
To generate an SM4 data key (China Regions only), specify a KeySpec value of\n AES_128 or NumberOfBytes value of 16. The symmetric\n encryption key used in China Regions to encrypt your data key is an SM4 encryption key.
If the operation succeeds, you will find the encrypted copy of the data key in the\n CiphertextBlob field.
You can use an optional encryption context to add additional security to the encryption\n operation. If you specify an EncryptionContext, you must specify the same\n encryption context (a case-sensitive exact match) when decrypting the encrypted data key.\n Otherwise, the request to decrypt fails with an InvalidCiphertextException. For more information, see Encryption Context in the\n Key Management Service Developer Guide.
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:GenerateDataKeyWithoutPlaintext (key\n policy)
\n\n Related operations:\n
\n\n Decrypt\n
\n\n Encrypt\n
\n\n GenerateDataKey\n
\n\n GenerateDataKeyPair\n
\nGenerates a hash-based message authentication code (HMAC) for a message using an HMAC KMS\n key and a MAC algorithm that the key supports. HMAC KMS keys and the HMAC algorithms that\n KMS uses conform to industry standards defined in RFC 2104.
\nYou can use value that GenerateMac returns in the VerifyMac operation to\n demonstrate that the original message has not changed. Also, because a secret key is used to\n create the hash, you can verify that the party that generated the hash has the required secret\n key. You can also use the raw result to implement HMAC-based algorithms such as key derivation\n functions. This operation is part of KMS support for HMAC KMS keys. For\n details, see HMAC keys in\n KMS in the \n Key Management Service Developer Guide\n .
\nBest practices recommend that you limit the time during which any signing mechanism,\n including an HMAC, is effective. This deters an attack where the actor uses a signed message\n to establish validity repeatedly or long after the message is superseded. HMAC tags do not\n include a timestamp, but you can include a timestamp in the token or message to help you\n detect when its time to refresh the HMAC.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:GenerateMac (key policy)
\n\n Related operations: VerifyMac\n
" + "smithy.api#documentation": "Generates a hash-based message authentication code (HMAC) for a message using an HMAC KMS\n key and a MAC algorithm that the key supports. HMAC KMS keys and the HMAC algorithms that\n KMS uses conform to industry standards defined in RFC 2104.
\nYou can use value that GenerateMac returns in the VerifyMac operation to\n demonstrate that the original message has not changed. Also, because a secret key is used to\n create the hash, you can verify that the party that generated the hash has the required secret\n key. You can also use the raw result to implement HMAC-based algorithms such as key derivation\n functions. This operation is part of KMS support for HMAC KMS keys. For\n details, see HMAC keys in\n KMS in the \n Key Management Service Developer Guide\n .
\nBest practices recommend that you limit the time during which any signing mechanism,\n including an HMAC, is effective. This deters an attack where the actor uses a signed message\n to establish validity repeatedly or long after the message is superseded. HMAC tags do not\n include a timestamp, but you can include a timestamp in the token or message to help you\n detect when its time to refresh the HMAC.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:GenerateMac (key policy)
\n\n Related operations: VerifyMac\n
", + "smithy.api#examples": [ + { + "title": "To generate an HMAC for a message", + "documentation": "This example generates an HMAC for a message, an HMAC KMS key, and a MAC algorithm. The algorithm must be supported by the specified HMAC KMS key.", + "input": { + "Message": "Hello World", + "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", + "MacAlgorithm": "HMAC_SHA_384" + }, + "output": { + "Mac": "Returns a random byte string that is cryptographically secure.
\nYou must use the NumberOfBytes parameter to specify the length of the random\n byte string. There is no default value for string length.
By default, the random byte string is generated in KMS. To generate the byte string in\n the CloudHSM cluster associated with an CloudHSM key store, use the CustomKeyStoreId\n parameter.
\n GenerateRandom also supports Amazon Web Services Nitro Enclaves, which provide an\n isolated compute environment in Amazon EC2. To call GenerateRandom for a Nitro\n enclave, use the Amazon Web Services Nitro Enclaves SDK or any Amazon Web Services SDK. Use the Recipient parameter\n to provide the attestation document for the enclave. Instead of plaintext bytes, the response\n includes the plaintext bytes encrypted under the public key from the attestation document\n (CiphertextForRecipient).For information about the interaction between KMS and Amazon Web Services Nitro Enclaves, see How Amazon Web Services Nitro Enclaves uses KMS in the Key Management Service Developer Guide.
For more information about entropy and random number generation, see\n Key Management Service Cryptographic Details.
\n\n Cross-account use: Not applicable.\n GenerateRandom does not use any account-specific resources, such as KMS\n keys.
\n Required permissions: kms:GenerateRandom (IAM policy)
" + "smithy.api#documentation": "Returns a random byte string that is cryptographically secure.
\nYou must use the NumberOfBytes parameter to specify the length of the random\n byte string. There is no default value for string length.
By default, the random byte string is generated in KMS. To generate the byte string in\n the CloudHSM cluster associated with an CloudHSM key store, use the CustomKeyStoreId\n parameter.
\n GenerateRandom also supports Amazon Web Services Nitro Enclaves, which provide an\n isolated compute environment in Amazon EC2. To call GenerateRandom for a Nitro\n enclave, use the Amazon Web Services Nitro Enclaves SDK or any Amazon Web Services SDK. Use the Recipient parameter\n to provide the attestation document for the enclave. Instead of plaintext bytes, the response\n includes the plaintext bytes encrypted under the public key from the attestation document\n (CiphertextForRecipient).For information about the interaction between KMS and Amazon Web Services Nitro Enclaves, see How Amazon Web Services Nitro Enclaves uses KMS in the Key Management Service Developer Guide.
For more information about entropy and random number generation, see\n Key Management Service Cryptographic Details.
\n\n Cross-account use: Not applicable.\n GenerateRandom does not use any account-specific resources, such as KMS\n keys.
\n Required permissions: kms:GenerateRandom (IAM policy)
", + "smithy.api#examples": [ + { + "title": "To generate random data", + "documentation": "The following example generates 32 bytes of random data.", + "input": { + "NumberOfBytes": 32 + }, + "output": { + "Plaintext": "Gets a key policy attached to the specified KMS key.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:GetKeyPolicy (key policy)
\n\n Related operations: PutKeyPolicy\n
" + "smithy.api#documentation": "Gets a key policy attached to the specified KMS key.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:GetKeyPolicy (key policy)
\n\n Related operations: PutKeyPolicy\n
", + "smithy.api#examples": [ + { + "title": "To retrieve a key policy", + "documentation": "The following example retrieves the key policy for the specified KMS key.", + "input": { + "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", + "PolicyName": "default" + }, + "output": { + "Policy": "{\n \"Version\" : \"2012-10-17\",\n \"Id\" : \"key-default-1\",\n \"Statement\" : [ {\n \"Sid\" : \"Enable IAM User Permissions\",\n \"Effect\" : \"Allow\",\n \"Principal\" : {\n \"AWS\" : \"arn:aws:iam::111122223333:root\"\n },\n \"Action\" : \"kms:*\",\n \"Resource\" : \"*\"\n } ]\n}" + } + } + ] } }, "com.amazonaws.kms#GetKeyPolicyRequest": { @@ -2990,7 +3271,19 @@ } ], "traits": { - "smithy.api#documentation": "Gets a Boolean value that indicates whether automatic rotation of the key material is\n enabled for the specified KMS key.
\nWhen you enable automatic rotation for customer managed KMS keys, KMS\n rotates the key material of the KMS key one year (approximately 365 days) from the enable date\n and every year thereafter. You can monitor rotation of the key material for your KMS keys in\n CloudTrail and Amazon CloudWatch.
\nAutomatic key rotation is supported only on symmetric encryption KMS keys.\n You cannot enable automatic rotation of asymmetric KMS keys, HMAC KMS keys, KMS keys with imported key material, or KMS keys in a custom key store. To enable or disable automatic rotation of a set of related multi-Region keys, set the property on the primary key..
\nYou can enable (EnableKeyRotation) and disable automatic rotation (DisableKeyRotation) of the key material in customer managed KMS keys. Key\n material rotation of Amazon Web Services managed KMS keys is not\n configurable. KMS always rotates the key material in Amazon Web Services managed KMS keys every year. The\n key rotation status for Amazon Web Services managed KMS keys is always true.
In May 2022, KMS changed the rotation schedule for Amazon Web Services managed keys from every three\n years to every year. For details, see EnableKeyRotation.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\nDisabled: The key rotation status does not change when you disable a KMS key. However,\n while the KMS key is disabled, KMS does not rotate the key material. When you re-enable\n the KMS key, rotation resumes. If the key material in the re-enabled KMS key hasn't been\n rotated in one year, KMS rotates it immediately, and every year thereafter. If it's been\n less than a year since the key material in the re-enabled KMS key was rotated, the KMS key\n resumes its prior rotation schedule.
\nPending deletion: While a KMS key is pending deletion, its key rotation status is\n false and KMS does not rotate the key material. If you cancel the\n deletion, the original key rotation status returns to true.
\n Cross-account use: Yes. To perform this operation on a KMS key in a different Amazon Web Services account, specify the key\n ARN in the value of the KeyId parameter.
\n Required permissions: kms:GetKeyRotationStatus (key policy)
\n\n Related operations:\n
\n\n DisableKeyRotation\n
\n\n EnableKeyRotation\n
\nGets a Boolean value that indicates whether automatic rotation of the key material is\n enabled for the specified KMS key.
\nWhen you enable automatic rotation for customer managed KMS keys, KMS\n rotates the key material of the KMS key one year (approximately 365 days) from the enable date\n and every year thereafter. You can monitor rotation of the key material for your KMS keys in\n CloudTrail and Amazon CloudWatch.
\nAutomatic key rotation is supported only on symmetric encryption KMS keys.\n You cannot enable automatic rotation of asymmetric KMS keys, HMAC KMS keys, KMS keys with imported key material, or KMS keys in a custom key store. To enable or disable automatic rotation of a set of related multi-Region keys, set the property on the primary key..
\nYou can enable (EnableKeyRotation) and disable automatic rotation (DisableKeyRotation) of the key material in customer managed KMS keys. Key\n material rotation of Amazon Web Services managed KMS keys is not\n configurable. KMS always rotates the key material in Amazon Web Services managed KMS keys every year. The\n key rotation status for Amazon Web Services managed KMS keys is always true.
In May 2022, KMS changed the rotation schedule for Amazon Web Services managed keys from every three\n years to every year. For details, see EnableKeyRotation.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\nDisabled: The key rotation status does not change when you disable a KMS key. However,\n while the KMS key is disabled, KMS does not rotate the key material. When you re-enable\n the KMS key, rotation resumes. If the key material in the re-enabled KMS key hasn't been\n rotated in one year, KMS rotates it immediately, and every year thereafter. If it's been\n less than a year since the key material in the re-enabled KMS key was rotated, the KMS key\n resumes its prior rotation schedule.
\nPending deletion: While a KMS key is pending deletion, its key rotation status is\n false and KMS does not rotate the key material. If you cancel the\n deletion, the original key rotation status returns to true.
\n Cross-account use: Yes. To perform this operation on a KMS key in a different Amazon Web Services account, specify the key\n ARN in the value of the KeyId parameter.
\n Required permissions: kms:GetKeyRotationStatus (key policy)
\n\n Related operations:\n
\n\n DisableKeyRotation\n
\n\n EnableKeyRotation\n
\nReturns the public key of an asymmetric KMS key. Unlike the private key of a asymmetric\n KMS key, which never leaves KMS unencrypted, callers with kms:GetPublicKey\n permission can download the public key of an asymmetric KMS key. You can share the public key\n to allow others to encrypt messages and verify signatures outside of KMS.\n For information about asymmetric KMS keys, see Asymmetric KMS keys in the Key Management Service Developer Guide.
You do not need to download the public key. Instead, you can use the public key within\n KMS by calling the Encrypt, ReEncrypt, or Verify operations with the identifier of an asymmetric KMS key. When you use the\n public key within KMS, you benefit from the authentication, authorization, and logging that\n are part of every KMS operation. You also reduce of risk of encrypting data that cannot be\n decrypted. These features are not effective outside of KMS.
\nTo help you use the public key safely outside of KMS, GetPublicKey returns\n important information about the public key in the response, including:
\n KeySpec: The type of key material in the public key, such as\n RSA_4096 or ECC_NIST_P521.
\n KeyUsage: Whether the key is used for encryption or signing.
\n\n EncryptionAlgorithms or SigningAlgorithms: A list of the encryption algorithms or the signing\n algorithms for the key.
\nAlthough KMS cannot enforce these restrictions on external operations, it is crucial\n that you use this information to prevent the public key from being used improperly. For\n example, you can prevent a public signing key from being used encrypt data, or prevent a\n public key from being used with an encryption algorithm that is not supported by KMS. You\n can also avoid errors, such as using the wrong signing algorithm in a verification\n operation.
\nTo verify a signature outside of KMS with an SM2 public key (China Regions only), you\n must specify the distinguishing ID. By default, KMS uses 1234567812345678 as\n the distinguishing ID. For more information, see Offline\n verification with SM2 key pairs.
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:GetPublicKey (key policy)
\n\n Related operations: CreateKey\n
" + "smithy.api#documentation": "Returns the public key of an asymmetric KMS key. Unlike the private key of a asymmetric\n KMS key, which never leaves KMS unencrypted, callers with kms:GetPublicKey\n permission can download the public key of an asymmetric KMS key. You can share the public key\n to allow others to encrypt messages and verify signatures outside of KMS.\n For information about asymmetric KMS keys, see Asymmetric KMS keys in the Key Management Service Developer Guide.
You do not need to download the public key. Instead, you can use the public key within\n KMS by calling the Encrypt, ReEncrypt, or Verify operations with the identifier of an asymmetric KMS key. When you use the\n public key within KMS, you benefit from the authentication, authorization, and logging that\n are part of every KMS operation. You also reduce of risk of encrypting data that cannot be\n decrypted. These features are not effective outside of KMS.
\nTo help you use the public key safely outside of KMS, GetPublicKey returns\n important information about the public key in the response, including:
\n KeySpec: The type of key material in the public key, such as\n RSA_4096 or ECC_NIST_P521.
\n KeyUsage: Whether the key is used for encryption or signing.
\n\n EncryptionAlgorithms or SigningAlgorithms: A list of the encryption algorithms or the signing\n algorithms for the key.
\nAlthough KMS cannot enforce these restrictions on external operations, it is crucial\n that you use this information to prevent the public key from being used improperly. For\n example, you can prevent a public signing key from being used encrypt data, or prevent a\n public key from being used with an encryption algorithm that is not supported by KMS. You\n can also avoid errors, such as using the wrong signing algorithm in a verification\n operation.
\nTo verify a signature outside of KMS with an SM2 public key (China Regions only), you\n must specify the distinguishing ID. By default, KMS uses 1234567812345678 as\n the distinguishing ID. For more information, see Offline\n verification with SM2 key pairs.
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:GetPublicKey (key policy)
\n\n Related operations: CreateKey\n
", + "smithy.api#examples": [ + { + "title": "To download the public key of an asymmetric KMS key", + "documentation": "This example gets the public key of an asymmetric RSA KMS key used for encryption and decryption. The operation returns the key spec, key usage, and encryption or signing algorithms to help you use the public key correctly outside of AWS KMS.", + "input": { + "KeyId": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321" + }, + "output": { + "KeyId": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321", + "PublicKey": "Imports or reimports key material into an existing KMS key that was created without key\n material. ImportKeyMaterial also sets the expiration model and expiration date of\n the imported key material.
By default, KMS keys are created with key material that KMS generates. This operation\n supports Importing key\n material, an advanced feature that lets you generate and import the cryptographic\n key material for a KMS key. For more information about importing key material into KMS, see\n Importing key\n material in the Key Management Service Developer Guide.
\nAfter you successfully import key material into a KMS key, you can reimport\n the same key material into that KMS key, but you cannot import different key\n material. You might reimport key material to replace key material that expired or key material\n that you deleted. You might also reimport key material to change the expiration model or\n expiration date of the key material. Before reimporting key material, if necessary, call DeleteImportedKeyMaterial to delete the current imported key material.
\nEach time you import key material into KMS, you can determine whether\n (ExpirationModel) and when (ValidTo) the key material expires. To\n change the expiration of your key material, you must import it again, either by calling\n ImportKeyMaterial or using the import features of the KMS console.
Before calling ImportKeyMaterial:
Create or identify a KMS key with no key material. The KMS key must have an\n Origin value of EXTERNAL, which indicates that the KMS key is\n designed for imported key material.
To create an new KMS key for imported key material, call the CreateKey operation with an Origin value of EXTERNAL. You can create a\n symmetric encryption KMS key, HMAC KMS key, asymmetric encryption KMS key, or asymmetric\n signing KMS key. You can also import key material into a multi-Region key of any\n supported type. However, you can't import key material into a KMS key in a custom key store.
Use the DescribeKey operation to verify that the\n KeyState of the KMS key is PendingImport, which indicates that\n the KMS key has no key material.
If you are reimporting the same key material into an existing KMS key, you might need\n to call the DeleteImportedKeyMaterial to delete its existing key\n material.
\nCall the GetParametersForImport operation to get a public key and\n import token set for importing key material.
\nUse the public key in the GetParametersForImport response to encrypt\n your key material.
\n Then, in an ImportKeyMaterial request, you submit your encrypted key\n material and import token. When calling this operation, you must specify the following\n values:
The key ID or key ARN of the KMS key to associate with the imported key material. Its\n Origin must be EXTERNAL and its KeyState must be\n PendingImport. You cannot perform this operation on a KMS key in a custom key store, or on a KMS\n key in a different Amazon Web Services account. To get the Origin and KeyState\n of a KMS key, call DescribeKey.
The encrypted key material.
\nThe import token that GetParametersForImport returned. You must use\n a public key and token from the same GetParametersForImport response.
Whether the key material expires (ExpirationModel) and, if so, when\n (ValidTo). For help with this choice, see Setting an expiration time in the Key Management Service Developer Guide.
If you set an expiration date, KMS deletes the key material from the KMS key on the\n specified date, making the KMS key unusable. To use the KMS key in cryptographic\n operations again, you must reimport the same key material. However, you can delete and\n reimport the key material at any time, including before the key material expires. Each\n time you reimport, you can eliminate or reset the expiration time.
\nWhen this operation is successful, the key state of the KMS key changes from\n PendingImport to Enabled, and you can use the KMS key in\n cryptographic operations.
If this operation fails, use the exception to help determine the problem. If the error is\n related to the key material, the import token, or wrapping key, use GetParametersForImport to get a new public key and import token for the KMS key\n and repeat the import procedure. For help, see How To Import Key\n Material in the Key Management Service Developer Guide.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:ImportKeyMaterial (key policy)
\n\n Related operations:\n
\nImports or reimports key material into an existing KMS key that was created without key\n material. ImportKeyMaterial also sets the expiration model and expiration date of\n the imported key material.
By default, KMS keys are created with key material that KMS generates. This operation\n supports Importing key\n material, an advanced feature that lets you generate and import the cryptographic\n key material for a KMS key. For more information about importing key material into KMS, see\n Importing key\n material in the Key Management Service Developer Guide.
\nAfter you successfully import key material into a KMS key, you can reimport\n the same key material into that KMS key, but you cannot import different key\n material. You might reimport key material to replace key material that expired or key material\n that you deleted. You might also reimport key material to change the expiration model or\n expiration date of the key material. Before reimporting key material, if necessary, call DeleteImportedKeyMaterial to delete the current imported key material.
\nEach time you import key material into KMS, you can determine whether\n (ExpirationModel) and when (ValidTo) the key material expires. To\n change the expiration of your key material, you must import it again, either by calling\n ImportKeyMaterial or using the import features of the KMS console.
Before calling ImportKeyMaterial:
Create or identify a KMS key with no key material. The KMS key must have an\n Origin value of EXTERNAL, which indicates that the KMS key is\n designed for imported key material.
To create an new KMS key for imported key material, call the CreateKey operation with an Origin value of EXTERNAL. You can create a\n symmetric encryption KMS key, HMAC KMS key, asymmetric encryption KMS key, or asymmetric\n signing KMS key. You can also import key material into a multi-Region key of any\n supported type. However, you can't import key material into a KMS key in a custom key store.
Use the DescribeKey operation to verify that the\n KeyState of the KMS key is PendingImport, which indicates that\n the KMS key has no key material.
If you are reimporting the same key material into an existing KMS key, you might need\n to call the DeleteImportedKeyMaterial to delete its existing key\n material.
\nCall the GetParametersForImport operation to get a public key and\n import token set for importing key material.
\nUse the public key in the GetParametersForImport response to encrypt\n your key material.
\n Then, in an ImportKeyMaterial request, you submit your encrypted key\n material and import token. When calling this operation, you must specify the following\n values:
The key ID or key ARN of the KMS key to associate with the imported key material. Its\n Origin must be EXTERNAL and its KeyState must be\n PendingImport. You cannot perform this operation on a KMS key in a custom key store, or on a KMS\n key in a different Amazon Web Services account. To get the Origin and KeyState\n of a KMS key, call DescribeKey.
The encrypted key material.
\nThe import token that GetParametersForImport returned. You must use\n a public key and token from the same GetParametersForImport response.
Whether the key material expires (ExpirationModel) and, if so, when\n (ValidTo). For help with this choice, see Setting an expiration time in the Key Management Service Developer Guide.
If you set an expiration date, KMS deletes the key material from the KMS key on the\n specified date, making the KMS key unusable. To use the KMS key in cryptographic\n operations again, you must reimport the same key material. However, you can delete and\n reimport the key material at any time, including before the key material expires. Each\n time you reimport, you can eliminate or reset the expiration time.
\nWhen this operation is successful, the key state of the KMS key changes from\n PendingImport to Enabled, and you can use the KMS key in\n cryptographic operations.
If this operation fails, use the exception to help determine the problem. If the error is\n related to the key material, the import token, or wrapping key, use GetParametersForImport to get a new public key and import token for the KMS key\n and repeat the import procedure. For help, see How To Import Key\n Material in the Key Management Service Developer Guide.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:ImportKeyMaterial (key policy)
\n\n Related operations:\n
\nGets a list of aliases in the caller's Amazon Web Services account and region. For more information\n about aliases, see CreateAlias.
\nBy default, the ListAliases operation returns all aliases in the account and\n region. To get only the aliases associated with a particular KMS key, use the\n KeyId parameter.
The ListAliases response can include aliases that you created and associated\n with your customer managed keys, and aliases that Amazon Web Services created and associated with Amazon Web Services\n managed keys in your account. You can recognize Amazon Web Services aliases because their names have the\n format aws/, such as aws/dynamodb.
The response might also include aliases that have no TargetKeyId field. These\n are predefined aliases that Amazon Web Services has created but has not yet associated with a KMS key.\n Aliases that Amazon Web Services creates in your account, including predefined aliases, do not count against\n your KMS aliases\n quota.
\n Cross-account use: No. ListAliases does not\n return aliases in other Amazon Web Services accounts.
\n Required permissions: kms:ListAliases (IAM policy)
\nFor details, see Controlling access to aliases in the\n Key Management Service Developer Guide.
\n\n Related operations:\n
\n\n CreateAlias\n
\n\n DeleteAlias\n
\n\n UpdateAlias\n
\nGets the names of the key policies that are attached to a KMS key. This operation is\n designed to get policy names that you can use in a GetKeyPolicy operation.\n However, the only valid policy name is default.
\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:ListKeyPolicies (key policy)
\n\n Related operations:\n
\n\n GetKeyPolicy\n
\n\n PutKeyPolicy\n
\nGets a list of all KMS keys in the caller's Amazon Web Services account and Region.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:ListKeys (IAM policy)
\n\n Related operations:\n
\n\n CreateKey\n
\n\n DescribeKey\n
\n\n ListAliases\n
\n\n ListResourceTags\n
\nReturns all tags on the specified KMS key.
\nFor general information about tags, including the format and syntax, see Tagging Amazon Web Services resources in\n the Amazon Web Services General Reference. For information about using\n tags in KMS, see Tagging\n keys.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:ListResourceTags (key policy)
\n\n Related operations:\n
\n\n CreateKey\n
\n\n ReplicateKey\n
\n\n TagResource\n
\n\n UntagResource\n
\nAttaches a key policy to the specified KMS key.
\nFor more information about key policies, see Key Policies in the Key Management Service Developer Guide.\n For help writing and formatting a JSON policy document, see the IAM JSON Policy Reference in the \n Identity and Access Management User Guide\n . For examples of adding a key policy in multiple programming languages,\n see Setting a key policy in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:PutKeyPolicy (key policy)
\n\n Related operations: GetKeyPolicy\n
" + "smithy.api#documentation": "Attaches a key policy to the specified KMS key.
\nFor more information about key policies, see Key Policies in the Key Management Service Developer Guide.\n For help writing and formatting a JSON policy document, see the IAM JSON Policy Reference in the \n Identity and Access Management User Guide\n . For examples of adding a key policy in multiple programming languages,\n see Setting a key policy in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:PutKeyPolicy (key policy)
\n\n Related operations: GetKeyPolicy\n
", + "smithy.api#examples": [ + { + "title": "To attach a key policy to a KMS key", + "documentation": "The following example attaches a key policy to the specified KMS key.", + "input": { + "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", + "PolicyName": "default", + "Policy": "{\n \"Version\": \"2012-10-17\",\n \"Id\": \"custom-policy-2016-12-07\",\n \"Statement\": [\n {\n \"Sid\": \"Enable IAM User Permissions\",\n \"Effect\": \"Allow\",\n \"Principal\": {\n \"AWS\": \"arn:aws:iam::111122223333:root\"\n },\n \"Action\": \"kms:*\",\n \"Resource\": \"*\"\n },\n {\n \"Sid\": \"Allow access for Key Administrators\",\n \"Effect\": \"Allow\",\n \"Principal\": {\n \"AWS\": [\n \"arn:aws:iam::111122223333:user/ExampleAdminUser\",\n \"arn:aws:iam::111122223333:role/ExampleAdminRole\"\n ]\n },\n \"Action\": [\n \"kms:Create*\",\n \"kms:Describe*\",\n \"kms:Enable*\",\n \"kms:List*\",\n \"kms:Put*\",\n \"kms:Update*\",\n \"kms:Revoke*\",\n \"kms:Disable*\",\n \"kms:Get*\",\n \"kms:Delete*\",\n \"kms:ScheduleKeyDeletion\",\n \"kms:CancelKeyDeletion\"\n ],\n \"Resource\": \"*\"\n },\n {\n \"Sid\": \"Allow use of the key\",\n \"Effect\": \"Allow\",\n \"Principal\": {\n \"AWS\": \"arn:aws:iam::111122223333:role/ExamplePowerUserRole\"\n },\n \"Action\": [\n \"kms:Encrypt\",\n \"kms:Decrypt\",\n \"kms:ReEncrypt*\",\n \"kms:GenerateDataKey*\",\n \"kms:DescribeKey\"\n ],\n \"Resource\": \"*\"\n },\n {\n \"Sid\": \"Allow attachment of persistent resources\",\n \"Effect\": \"Allow\",\n \"Principal\": {\n \"AWS\": \"arn:aws:iam::111122223333:role/ExamplePowerUserRole\"\n },\n \"Action\": [\n \"kms:CreateGrant\",\n \"kms:ListGrants\",\n \"kms:RevokeGrant\"\n ],\n \"Resource\": \"*\",\n \"Condition\": {\n \"Bool\": {\n \"kms:GrantIsForAWSResource\": \"true\"\n }\n }\n }\n ]\n}\n" + } + } + ] } }, "com.amazonaws.kms#PutKeyPolicyRequest": { @@ -5141,7 +5607,22 @@ } ], "traits": { - "smithy.api#documentation": "Decrypts ciphertext and then reencrypts it entirely within KMS. You can use this\n operation to change the KMS key under which data is encrypted, such as when you manually\n rotate a KMS key or change the KMS key that protects a ciphertext. You can also use\n it to reencrypt ciphertext under the same KMS key, such as to change the encryption\n context of a ciphertext.
\nThe ReEncrypt operation can decrypt ciphertext that was encrypted by using a\n KMS key in an KMS operation, such as Encrypt or GenerateDataKey. It can also decrypt ciphertext that was encrypted by using the\n public key of an asymmetric KMS key\n outside of KMS. However, it cannot decrypt ciphertext produced by other libraries, such as\n the Amazon Web Services Encryption SDK or\n Amazon S3\n client-side encryption. These libraries return a ciphertext format that is\n incompatible with KMS.
When you use the ReEncrypt operation, you need to provide information for the\n decrypt operation and the subsequent encrypt operation.
If your ciphertext was encrypted under an asymmetric KMS key, you must use the\n SourceKeyId parameter to identify the KMS key that encrypted the\n ciphertext. You must also supply the encryption algorithm that was used. This information\n is required to decrypt the data.
If your ciphertext was encrypted under a symmetric encryption KMS key, the\n SourceKeyId parameter is optional. KMS can get this information from\n metadata that it adds to the symmetric ciphertext blob. This feature adds durability to\n your implementation by ensuring that authorized users can decrypt ciphertext decades after\n it was encrypted, even if they've lost track of the key ID. However, specifying the source\n KMS key is always recommended as a best practice. When you use the\n SourceKeyId parameter to specify a KMS key, KMS uses only the KMS key you\n specify. If the ciphertext was encrypted under a different KMS key, the\n ReEncrypt operation fails. This practice ensures that you use the KMS key\n that you intend.
To reencrypt the data, you must use the DestinationKeyId parameter to\n specify the KMS key that re-encrypts the data after it is decrypted. If the destination\n KMS key is an asymmetric KMS key, you must also provide the encryption algorithm. The\n algorithm that you choose must be compatible with the KMS key.
When you use an asymmetric KMS key to encrypt or reencrypt data, be sure to record the KMS key and encryption algorithm that you choose. You will be required to provide the same KMS key and encryption algorithm when you decrypt the data. If the KMS key and algorithm do not match the values used to encrypt the data, the decrypt operation fails.
\nYou are not required to supply the key ID and encryption algorithm when you decrypt with symmetric encryption KMS keys because KMS stores this information in the ciphertext blob. KMS cannot store metadata in ciphertext generated with asymmetric keys. The standard format for asymmetric key ciphertext does not include configurable fields.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. The source KMS key and\n destination KMS key can be in different Amazon Web Services accounts. Either or both KMS keys can be in a\n different account than the caller. To specify a KMS key in a different account, you must use\n its key ARN or alias ARN.
\n\n Required permissions:
\n\n kms:ReEncryptFrom\n permission on the source KMS key (key policy)
\n\n kms:ReEncryptTo\n permission on the destination KMS key (key policy)
\nTo permit reencryption from or to a KMS key, include the \"kms:ReEncrypt*\"\n permission in your key policy. This permission is\n automatically included in the key policy when you use the console to create a KMS key. But you\n must include it manually when you create a KMS key programmatically or when you use the PutKeyPolicy operation to set a key policy.
\n Related operations:\n
\n\n Decrypt\n
\n\n Encrypt\n
\n\n GenerateDataKey\n
\n\n GenerateDataKeyPair\n
\nDecrypts ciphertext and then reencrypts it entirely within KMS. You can use this\n operation to change the KMS key under which data is encrypted, such as when you manually\n rotate a KMS key or change the KMS key that protects a ciphertext. You can also use\n it to reencrypt ciphertext under the same KMS key, such as to change the encryption\n context of a ciphertext.
\nThe ReEncrypt operation can decrypt ciphertext that was encrypted by using a\n KMS key in an KMS operation, such as Encrypt or GenerateDataKey. It can also decrypt ciphertext that was encrypted by using the\n public key of an asymmetric KMS key\n outside of KMS. However, it cannot decrypt ciphertext produced by other libraries, such as\n the Amazon Web Services Encryption SDK or\n Amazon S3\n client-side encryption. These libraries return a ciphertext format that is\n incompatible with KMS.
When you use the ReEncrypt operation, you need to provide information for the\n decrypt operation and the subsequent encrypt operation.
If your ciphertext was encrypted under an asymmetric KMS key, you must use the\n SourceKeyId parameter to identify the KMS key that encrypted the\n ciphertext. You must also supply the encryption algorithm that was used. This information\n is required to decrypt the data.
If your ciphertext was encrypted under a symmetric encryption KMS key, the\n SourceKeyId parameter is optional. KMS can get this information from\n metadata that it adds to the symmetric ciphertext blob. This feature adds durability to\n your implementation by ensuring that authorized users can decrypt ciphertext decades after\n it was encrypted, even if they've lost track of the key ID. However, specifying the source\n KMS key is always recommended as a best practice. When you use the\n SourceKeyId parameter to specify a KMS key, KMS uses only the KMS key you\n specify. If the ciphertext was encrypted under a different KMS key, the\n ReEncrypt operation fails. This practice ensures that you use the KMS key\n that you intend.
To reencrypt the data, you must use the DestinationKeyId parameter to\n specify the KMS key that re-encrypts the data after it is decrypted. If the destination\n KMS key is an asymmetric KMS key, you must also provide the encryption algorithm. The\n algorithm that you choose must be compatible with the KMS key.
When you use an asymmetric KMS key to encrypt or reencrypt data, be sure to record the KMS key and encryption algorithm that you choose. You will be required to provide the same KMS key and encryption algorithm when you decrypt the data. If the KMS key and algorithm do not match the values used to encrypt the data, the decrypt operation fails.
\nYou are not required to supply the key ID and encryption algorithm when you decrypt with symmetric encryption KMS keys because KMS stores this information in the ciphertext blob. KMS cannot store metadata in ciphertext generated with asymmetric keys. The standard format for asymmetric key ciphertext does not include configurable fields.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. The source KMS key and\n destination KMS key can be in different Amazon Web Services accounts. Either or both KMS keys can be in a\n different account than the caller. To specify a KMS key in a different account, you must use\n its key ARN or alias ARN.
\n\n Required permissions:
\n\n kms:ReEncryptFrom\n permission on the source KMS key (key policy)
\n\n kms:ReEncryptTo\n permission on the destination KMS key (key policy)
\nTo permit reencryption from or to a KMS key, include the \"kms:ReEncrypt*\"\n permission in your key policy. This permission is\n automatically included in the key policy when you use the console to create a KMS key. But you\n must include it manually when you create a KMS key programmatically or when you use the PutKeyPolicy operation to set a key policy.
\n Related operations:\n
\n\n Decrypt\n
\n\n Encrypt\n
\n\n GenerateDataKey\n
\n\n GenerateDataKeyPair\n
\nReplicates a multi-Region key into the specified Region. This operation creates a\n multi-Region replica key based on a multi-Region primary key in a different Region of the same\n Amazon Web Services partition. You can create multiple replicas of a primary key, but each must be in a\n different Region. To create a multi-Region primary key, use the CreateKey\n operation.
\nThis operation supports multi-Region keys, an KMS feature that lets you create multiple\n interoperable KMS keys in different Amazon Web Services Regions. Because these KMS keys have the same key ID, key\n material, and other metadata, you can use them interchangeably to encrypt data in one Amazon Web Services Region and decrypt\n it in a different Amazon Web Services Region without re-encrypting the data or making a cross-Region call. For more information about multi-Region keys, see Multi-Region keys in KMS in the Key Management Service Developer Guide.
\nA replica key is a fully-functional KMS key that can be used\n independently of its primary and peer replica keys. A primary key and its replica keys share\n properties that make them interoperable. They have the same key ID and key material. They also\n have the same key\n spec, key\n usage, key\n material origin, and automatic key rotation status. KMS automatically synchronizes these shared\n properties among related multi-Region keys. All other properties of a replica key can differ,\n including its key\n policy, tags, aliases, and Key states of KMS keys. KMS pricing and quotas for KMS keys apply to each\n primary key and replica key.
\nWhen this operation completes, the new replica key has a transient key state of\n Creating. This key state changes to Enabled (or\n PendingImport) after a few seconds when the process of creating the new replica\n key is complete. While the key state is Creating, you can manage key, but you\n cannot yet use it in cryptographic operations. If you are creating and using the replica key\n programmatically, retry on KMSInvalidStateException or call\n DescribeKey to check its KeyState value before using it. For\n details about the Creating key state, see Key states of KMS keys in the\n Key Management Service Developer Guide.
You cannot create more than one replica of a primary key in any Region. If the Region\n already includes a replica of the key you're trying to replicate, ReplicateKey\n returns an AlreadyExistsException error. If the key state of the existing replica\n is PendingDeletion, you can cancel the scheduled key deletion (CancelKeyDeletion) or wait for the key to be deleted. The new replica key you\n create will have the same shared\n properties as the original replica key.
The CloudTrail log of a ReplicateKey operation records a\n ReplicateKey operation in the primary key's Region and a CreateKey operation in the replica key's Region.
If you replicate a multi-Region primary key with imported key material, the replica key is\n created with no key material. You must import the same key material that you imported into the\n primary key. For details, see Importing key material into multi-Region keys in the Key Management Service Developer Guide.
\nTo convert a replica key to a primary key, use the UpdatePrimaryRegion\n operation.
\n\n ReplicateKey uses different default values for the KeyPolicy\n and Tags parameters than those used in the KMS console. For details, see the\n parameter descriptions.
\n Cross-account use: No. You cannot use this operation to\n create a replica key in a different Amazon Web Services account.
\n\n Required permissions:
\n\n kms:ReplicateKey on the primary key (in the primary key's Region).\n Include this permission in the primary key's key policy.
\n kms:CreateKey in an IAM policy in the replica Region.
To use the Tags parameter, kms:TagResource in an IAM policy\n in the replica Region.
\n Related operations\n
\n\n CreateKey\n
\n\n UpdatePrimaryRegion\n
\nReplicates a multi-Region key into the specified Region. This operation creates a\n multi-Region replica key based on a multi-Region primary key in a different Region of the same\n Amazon Web Services partition. You can create multiple replicas of a primary key, but each must be in a\n different Region. To create a multi-Region primary key, use the CreateKey\n operation.
\nThis operation supports multi-Region keys, an KMS feature that lets you create multiple\n interoperable KMS keys in different Amazon Web Services Regions. Because these KMS keys have the same key ID, key\n material, and other metadata, you can use them interchangeably to encrypt data in one Amazon Web Services Region and decrypt\n it in a different Amazon Web Services Region without re-encrypting the data or making a cross-Region call. For more information about multi-Region keys, see Multi-Region keys in KMS in the Key Management Service Developer Guide.
\nA replica key is a fully-functional KMS key that can be used\n independently of its primary and peer replica keys. A primary key and its replica keys share\n properties that make them interoperable. They have the same key ID and key material. They also\n have the same key\n spec, key\n usage, key\n material origin, and automatic key rotation status. KMS automatically synchronizes these shared\n properties among related multi-Region keys. All other properties of a replica key can differ,\n including its key\n policy, tags, aliases, and Key states of KMS keys. KMS pricing and quotas for KMS keys apply to each\n primary key and replica key.
\nWhen this operation completes, the new replica key has a transient key state of\n Creating. This key state changes to Enabled (or\n PendingImport) after a few seconds when the process of creating the new replica\n key is complete. While the key state is Creating, you can manage key, but you\n cannot yet use it in cryptographic operations. If you are creating and using the replica key\n programmatically, retry on KMSInvalidStateException or call\n DescribeKey to check its KeyState value before using it. For\n details about the Creating key state, see Key states of KMS keys in the\n Key Management Service Developer Guide.
You cannot create more than one replica of a primary key in any Region. If the Region\n already includes a replica of the key you're trying to replicate, ReplicateKey\n returns an AlreadyExistsException error. If the key state of the existing replica\n is PendingDeletion, you can cancel the scheduled key deletion (CancelKeyDeletion) or wait for the key to be deleted. The new replica key you\n create will have the same shared\n properties as the original replica key.
The CloudTrail log of a ReplicateKey operation records a\n ReplicateKey operation in the primary key's Region and a CreateKey operation in the replica key's Region.
If you replicate a multi-Region primary key with imported key material, the replica key is\n created with no key material. You must import the same key material that you imported into the\n primary key. For details, see Importing key material into multi-Region keys in the Key Management Service Developer Guide.
\nTo convert a replica key to a primary key, use the UpdatePrimaryRegion\n operation.
\n\n ReplicateKey uses different default values for the KeyPolicy\n and Tags parameters than those used in the KMS console. For details, see the\n parameter descriptions.
\n Cross-account use: No. You cannot use this operation to\n create a replica key in a different Amazon Web Services account.
\n\n Required permissions:
\n\n kms:ReplicateKey on the primary key (in the primary key's Region).\n Include this permission in the primary key's key policy.
\n kms:CreateKey in an IAM policy in the replica Region.
To use the Tags parameter, kms:TagResource in an IAM policy\n in the replica Region.
\n Related operations\n
\n\n CreateKey\n
\n\n UpdatePrimaryRegion\n
\nDeletes a grant. Typically, you retire a grant when you no longer need its permissions. To\n identify the grant to retire, use a grant token, or both the grant ID and a\n key identifier (key ID or key ARN) of the KMS key. The CreateGrant operation\n returns both values.
\nThis operation can be called by the retiring principal for a grant,\n by the grantee principal if the grant allows the RetireGrant\n operation, and by the Amazon Web Services account in which the grant is created. It can also be called by\n principals to whom permission for retiring a grant is delegated. For details, see Retiring and revoking\n grants in the Key Management Service Developer Guide.
For detailed information about grants, including grant terminology, see Grants in KMS in the\n \n Key Management Service Developer Guide\n . For examples of working with grants in several\n programming languages, see Programming grants.
\n\n Cross-account use: Yes. You can retire a grant on a KMS\n key in a different Amazon Web Services account.
\n\n Required permissions::Permission to retire a grant is\n determined primarily by the grant. For details, see Retiring and revoking grants in\n the Key Management Service Developer Guide.
\n\n Related operations:\n
\n\n CreateGrant\n
\n\n ListGrants\n
\n\n ListRetirableGrants\n
\n\n RevokeGrant\n
\nDeletes a grant. Typically, you retire a grant when you no longer need its permissions. To\n identify the grant to retire, use a grant token, or both the grant ID and a\n key identifier (key ID or key ARN) of the KMS key. The CreateGrant operation\n returns both values.
\nThis operation can be called by the retiring principal for a grant,\n by the grantee principal if the grant allows the RetireGrant\n operation, and by the Amazon Web Services account in which the grant is created. It can also be called by\n principals to whom permission for retiring a grant is delegated. For details, see Retiring and revoking\n grants in the Key Management Service Developer Guide.
For detailed information about grants, including grant terminology, see Grants in KMS in the\n \n Key Management Service Developer Guide\n . For examples of working with grants in several\n programming languages, see Programming grants.
\n\n Cross-account use: Yes. You can retire a grant on a KMS\n key in a different Amazon Web Services account.
\n\n Required permissions::Permission to retire a grant is\n determined primarily by the grant. For details, see Retiring and revoking grants in\n the Key Management Service Developer Guide.
\n\n Related operations:\n
\n\n CreateGrant\n
\n\n ListGrants\n
\n\n ListRetirableGrants\n
\n\n RevokeGrant\n
\nDeletes the specified grant. You revoke a grant to terminate the permissions that the\n grant allows. For more information, see Retiring and revoking grants in\n the \n Key Management Service Developer Guide\n .
\nWhen you create, retire, or revoke a grant, there might be a brief delay, usually less than five minutes, until the grant is available throughout KMS. This state is known as eventual consistency. For details, see Eventual consistency in\n the \n Key Management Service Developer Guide\n .
\nFor detailed information about grants, including grant terminology, see Grants in KMS in the\n \n Key Management Service Developer Guide\n . For examples of working with grants in several\n programming languages, see Programming grants.
\n\n Cross-account use: Yes. To perform this operation on a KMS key in a different Amazon Web Services account, specify the key\n ARN in the value of the KeyId parameter.
\n Required permissions: kms:RevokeGrant (key policy).
\n\n Related operations:\n
\n\n CreateGrant\n
\n\n ListGrants\n
\n\n ListRetirableGrants\n
\n\n RetireGrant\n
\nDeletes the specified grant. You revoke a grant to terminate the permissions that the\n grant allows. For more information, see Retiring and revoking grants in\n the \n Key Management Service Developer Guide\n .
\nWhen you create, retire, or revoke a grant, there might be a brief delay, usually less than five minutes, until the grant is available throughout KMS. This state is known as eventual consistency. For details, see Eventual consistency in\n the \n Key Management Service Developer Guide\n .
\nFor detailed information about grants, including grant terminology, see Grants in KMS in the\n \n Key Management Service Developer Guide\n . For examples of working with grants in several\n programming languages, see Programming grants.
\n\n Cross-account use: Yes. To perform this operation on a KMS key in a different Amazon Web Services account, specify the key\n ARN in the value of the KeyId parameter.
\n Required permissions: kms:RevokeGrant (key policy).
\n\n Related operations:\n
\n\n CreateGrant\n
\n\n ListGrants\n
\n\n ListRetirableGrants\n
\n\n RetireGrant\n
\nCreates a digital\n signature for a message or message digest by using the private key in an asymmetric\n signing KMS key. To verify the signature, use the Verify operation, or use\n the public key in the same asymmetric KMS key outside of KMS. For information about asymmetric KMS keys, see Asymmetric KMS keys in the Key Management Service Developer Guide.
\nDigital signatures are generated and verified by using asymmetric key pair, such as an RSA\n or ECC pair that is represented by an asymmetric KMS key. The key owner (or an authorized\n user) uses their private key to sign a message. Anyone with the public key can verify that the\n message was signed with that particular private key and that the message hasn't changed since\n it was signed.
\nTo use the Sign operation, provide the following information:
Use the KeyId parameter to identify an asymmetric KMS key with a\n KeyUsage value of SIGN_VERIFY. To get the\n KeyUsage value of a KMS key, use the DescribeKey\n operation. The caller must have kms:Sign permission on the KMS key.
Use the Message parameter to specify the message or message digest to\n sign. You can submit messages of up to 4096 bytes. To sign a larger message, generate a\n hash digest of the message, and then provide the hash digest in the Message\n parameter. To indicate whether the message is a full message or a digest, use the\n MessageType parameter.
Choose a signing algorithm that is compatible with the KMS key.
\nWhen signing a message, be sure to record the KMS key and the signing algorithm. This\n information is required to verify the signature.
\nBest practices recommend that you limit the time during which any signature is\n effective. This deters an attack where the actor uses a signed message to establish validity\n repeatedly or long after the message is superseded. Signatures do not include a timestamp,\n but you can include a timestamp in the signed message to help you detect when its time to\n refresh the signature.
\nTo verify the signature that this operation generates, use the Verify\n operation. Or use the GetPublicKey operation to download the public key and\n then use the public key to verify the signature outside of KMS.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:Sign (key policy)
\n\n Related operations: Verify\n
" + "smithy.api#documentation": "Creates a digital\n signature for a message or message digest by using the private key in an asymmetric\n signing KMS key. To verify the signature, use the Verify operation, or use\n the public key in the same asymmetric KMS key outside of KMS. For information about asymmetric KMS keys, see Asymmetric KMS keys in the Key Management Service Developer Guide.
\nDigital signatures are generated and verified by using asymmetric key pair, such as an RSA\n or ECC pair that is represented by an asymmetric KMS key. The key owner (or an authorized\n user) uses their private key to sign a message. Anyone with the public key can verify that the\n message was signed with that particular private key and that the message hasn't changed since\n it was signed.
\nTo use the Sign operation, provide the following information:
Use the KeyId parameter to identify an asymmetric KMS key with a\n KeyUsage value of SIGN_VERIFY. To get the\n KeyUsage value of a KMS key, use the DescribeKey\n operation. The caller must have kms:Sign permission on the KMS key.
Use the Message parameter to specify the message or message digest to\n sign. You can submit messages of up to 4096 bytes. To sign a larger message, generate a\n hash digest of the message, and then provide the hash digest in the Message\n parameter. To indicate whether the message is a full message or a digest, use the\n MessageType parameter.
Choose a signing algorithm that is compatible with the KMS key.
\nWhen signing a message, be sure to record the KMS key and the signing algorithm. This\n information is required to verify the signature.
\nBest practices recommend that you limit the time during which any signature is\n effective. This deters an attack where the actor uses a signed message to establish validity\n repeatedly or long after the message is superseded. Signatures do not include a timestamp,\n but you can include a timestamp in the signed message to help you detect when its time to\n refresh the signature.
\nTo verify the signature that this operation generates, use the Verify\n operation. Or use the GetPublicKey operation to download the public key and\n then use the public key to verify the signature outside of KMS.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:Sign (key policy)
\n\n Related operations: Verify\n
", + "smithy.api#examples": [ + { + "title": "To digitally sign a message with an asymmetric KMS key.", + "documentation": "This operation uses the private key in an asymmetric elliptic curve (ECC) KMS key to generate a digital signature for a given message.", + "input": { + "KeyId": "alias/ECC_signing_key", + "Message": "Adds or edits tags on a customer managed key.
\nTagging or untagging a KMS key can allow or deny permission to the KMS key. For details, see ABAC for KMS in the Key Management Service Developer Guide.
\nEach tag consists of a tag key and a tag value, both of which are case-sensitive strings.\n The tag value can be an empty (null) string. To add a tag, specify a new tag key and a tag\n value. To edit a tag, specify an existing tag key and a new tag value.
\nYou can use this operation to tag a customer managed key, but you cannot\n tag an Amazon Web Services\n managed key, an Amazon Web Services owned key, a custom key\n store, or an alias.
\nYou can also add tags to a KMS key while creating it (CreateKey) or\n replicating it (ReplicateKey).
\nFor information about using tags in KMS, see Tagging keys. For general information about\n tags, including the format and syntax, see Tagging Amazon Web Services resources in the Amazon\n Web Services General Reference.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:TagResource (key policy)
\n\n Related operations\n
\n\n CreateKey\n
\n\n ListResourceTags\n
\n\n ReplicateKey\n
\n\n UntagResource\n
\nAdds or edits tags on a customer managed key.
\nTagging or untagging a KMS key can allow or deny permission to the KMS key. For details, see ABAC for KMS in the Key Management Service Developer Guide.
\nEach tag consists of a tag key and a tag value, both of which are case-sensitive strings.\n The tag value can be an empty (null) string. To add a tag, specify a new tag key and a tag\n value. To edit a tag, specify an existing tag key and a new tag value.
\nYou can use this operation to tag a customer managed key, but you cannot\n tag an Amazon Web Services\n managed key, an Amazon Web Services owned key, a custom key\n store, or an alias.
\nYou can also add tags to a KMS key while creating it (CreateKey) or\n replicating it (ReplicateKey).
\nFor information about using tags in KMS, see Tagging keys. For general information about\n tags, including the format and syntax, see Tagging Amazon Web Services resources in the Amazon\n Web Services General Reference.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:TagResource (key policy)
\n\n Related operations\n
\n\n CreateKey\n
\n\n ListResourceTags\n
\n\n ReplicateKey\n
\n\n UntagResource\n
\nDeletes tags from a customer managed key. To delete a tag,\n specify the tag key and the KMS key.
\nTagging or untagging a KMS key can allow or deny permission to the KMS key. For details, see ABAC for KMS in the Key Management Service Developer Guide.
\nWhen it succeeds, the UntagResource operation doesn't return any output.\n Also, if the specified tag key isn't found on the KMS key, it doesn't throw an exception or\n return a response. To confirm that the operation worked, use the ListResourceTags operation.
For information about using tags in KMS, see Tagging keys. For general information about\n tags, including the format and syntax, see Tagging Amazon Web Services resources in the Amazon\n Web Services General Reference.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:UntagResource (key policy)
\n\n Related operations\n
\n\n CreateKey\n
\n\n ListResourceTags\n
\n\n ReplicateKey\n
\n\n TagResource\n
\nDeletes tags from a customer managed key. To delete a tag,\n specify the tag key and the KMS key.
\nTagging or untagging a KMS key can allow or deny permission to the KMS key. For details, see ABAC for KMS in the Key Management Service Developer Guide.
\nWhen it succeeds, the UntagResource operation doesn't return any output.\n Also, if the specified tag key isn't found on the KMS key, it doesn't throw an exception or\n return a response. To confirm that the operation worked, use the ListResourceTags operation.
For information about using tags in KMS, see Tagging keys. For general information about\n tags, including the format and syntax, see Tagging Amazon Web Services resources in the Amazon\n Web Services General Reference.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:UntagResource (key policy)
\n\n Related operations\n
\n\n CreateKey\n
\n\n ListResourceTags\n
\n\n ReplicateKey\n
\n\n TagResource\n
\nAssociates an existing KMS alias with a different KMS key. Each alias is associated with\n only one KMS key at a time, although a KMS key can have multiple aliases. The alias and the\n KMS key must be in the same Amazon Web Services account and Region.
\nAdding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see ABAC for KMS in the Key Management Service Developer Guide.
\nThe current and new KMS key must be the same type (both symmetric or both asymmetric or\n both HMAC), and they must have the same key usage. This restriction prevents errors in code\n that uses aliases. If you must assign an alias to a different type of KMS key, use DeleteAlias to delete the old alias and CreateAlias to create\n a new alias.
\nYou cannot use UpdateAlias to change an alias name. To change an alias name,\n use DeleteAlias to delete the old alias and CreateAlias to\n create a new alias.
Because an alias is not a property of a KMS key, you can create, update, and delete the\n aliases of a KMS key without affecting the KMS key. Also, aliases do not appear in the\n response from the DescribeKey operation. To get the aliases of all KMS keys\n in the account, use the ListAliases operation.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions\n
\n\n kms:UpdateAlias on\n the alias (IAM policy).
\n\n kms:UpdateAlias on\n the current KMS key (key policy).
\n\n kms:UpdateAlias on\n the new KMS key (key policy).
\nFor details, see Controlling access to aliases in the\n Key Management Service Developer Guide.
\n\n Related operations:\n
\n\n CreateAlias\n
\n\n DeleteAlias\n
\n\n ListAliases\n
\nAssociates an existing KMS alias with a different KMS key. Each alias is associated with\n only one KMS key at a time, although a KMS key can have multiple aliases. The alias and the\n KMS key must be in the same Amazon Web Services account and Region.
\nAdding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see ABAC for KMS in the Key Management Service Developer Guide.
\nThe current and new KMS key must be the same type (both symmetric or both asymmetric or\n both HMAC), and they must have the same key usage. This restriction prevents errors in code\n that uses aliases. If you must assign an alias to a different type of KMS key, use DeleteAlias to delete the old alias and CreateAlias to create\n a new alias.
\nYou cannot use UpdateAlias to change an alias name. To change an alias name,\n use DeleteAlias to delete the old alias and CreateAlias to\n create a new alias.
Because an alias is not a property of a KMS key, you can create, update, and delete the\n aliases of a KMS key without affecting the KMS key. Also, aliases do not appear in the\n response from the DescribeKey operation. To get the aliases of all KMS keys\n in the account, use the ListAliases operation.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions\n
\n\n kms:UpdateAlias on\n the alias (IAM policy).
\n\n kms:UpdateAlias on\n the current KMS key (key policy).
\n\n kms:UpdateAlias on\n the new KMS key (key policy).
\nFor details, see Controlling access to aliases in the\n Key Management Service Developer Guide.
\n\n Related operations:\n
\n\n CreateAlias\n
\n\n DeleteAlias\n
\n\n ListAliases\n
\nChanges the properties of a custom key store. You can use this operation to change the\n properties of an CloudHSM key store or an external key store.
\nUse the required CustomKeyStoreId parameter to identify the custom key store.\n Use the remaining optional parameters to change its properties. This operation does not return\n any property values. To verify the updated property values, use the DescribeCustomKeyStores operation.
This operation is part of the custom key stores feature in KMS, which\ncombines the convenience and extensive integration of KMS with the isolation and control of a\nkey store that you own and manage.
\nWhen updating the properties of an external key store, verify that the updated settings\n connect your key store, via the external key store proxy, to the same external key manager\n as the previous settings, or to a backup or snapshot of the external key manager with the\n same cryptographic keys. If the updated connection settings fail, you can fix them and\n retry, although an extended delay might disrupt Amazon Web Services services. However, if KMS\n permanently loses its access to cryptographic keys, ciphertext encrypted under those keys is\n unrecoverable.
\nFor external key stores:
\nSome external key managers provide a simpler method for updating an external key store.\n For details, see your external key manager documentation.
\nWhen updating an external key store in the KMS console, you can upload a JSON-based\n proxy configuration file with the desired values. You cannot upload the proxy configuration\n file to the UpdateCustomKeyStore operation. However, you can use the file to\n help you determine the correct values for the UpdateCustomKeyStore\n parameters.
For an CloudHSM key store, you can use this operation to change the custom key store friendly\n name (NewCustomKeyStoreName), to tell KMS about a change to the\n kmsuser crypto user password (KeyStorePassword), or to associate\n the custom key store with a different, but related, CloudHSM cluster\n (CloudHsmClusterId). To update any property of an CloudHSM key store, the\n ConnectionState of the CloudHSM key store must be DISCONNECTED.
For an external key store, you can use this operation to change the custom key store\n friendly name (NewCustomKeyStoreName), or to tell KMS about a change to the\n external key store proxy authentication credentials\n (XksProxyAuthenticationCredential), connection method\n (XksProxyConnectivity), external proxy endpoint\n (XksProxyUriEndpoint) and path (XksProxyUriPath). For external key\n stores with an XksProxyConnectivity of VPC_ENDPOINT_SERVICE, you can\n also update the Amazon VPC endpoint service name (XksProxyVpcEndpointServiceName). To\n update most properties of an external key store, the ConnectionState of the\n external key store must be DISCONNECTED. However, you can update the\n CustomKeyStoreName, XksProxyAuthenticationCredential, and\n XksProxyUriPath of an external key store when it is in the CONNECTED or\n DISCONNECTED state.
If your update requires a DISCONNECTED state, before using\n UpdateCustomKeyStore, use the DisconnectCustomKeyStore\n operation to disconnect the custom key store. After the UpdateCustomKeyStore\n operation completes, use the ConnectCustomKeyStore to reconnect the custom\n key store. To find the ConnectionState of the custom key store, use the DescribeCustomKeyStores operation.
\n
\nBefore updating the custom key store, verify that the new values allow KMS to connect\n the custom key store to its backing key store. For example, before you change the\n XksProxyUriPath value, verify that the external key store proxy is reachable at\n the new path.
If the operation succeeds, it returns a JSON object with no\nproperties.
\n\n Cross-account use: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.
\n\n Required permissions: kms:UpdateCustomKeyStore (IAM policy)
\n\n Related operations:\n
\n\n CreateCustomKeyStore\n
\n\n DeleteCustomKeyStore\n
\nChanges the properties of a custom key store. You can use this operation to change the\n properties of an CloudHSM key store or an external key store.
\nUse the required CustomKeyStoreId parameter to identify the custom key store.\n Use the remaining optional parameters to change its properties. This operation does not return\n any property values. To verify the updated property values, use the DescribeCustomKeyStores operation.
This operation is part of the custom key stores feature in KMS, which\ncombines the convenience and extensive integration of KMS with the isolation and control of a\nkey store that you own and manage.
\nWhen updating the properties of an external key store, verify that the updated settings\n connect your key store, via the external key store proxy, to the same external key manager\n as the previous settings, or to a backup or snapshot of the external key manager with the\n same cryptographic keys. If the updated connection settings fail, you can fix them and\n retry, although an extended delay might disrupt Amazon Web Services services. However, if KMS\n permanently loses its access to cryptographic keys, ciphertext encrypted under those keys is\n unrecoverable.
\nFor external key stores:
\nSome external key managers provide a simpler method for updating an external key store.\n For details, see your external key manager documentation.
\nWhen updating an external key store in the KMS console, you can upload a JSON-based\n proxy configuration file with the desired values. You cannot upload the proxy configuration\n file to the UpdateCustomKeyStore operation. However, you can use the file to\n help you determine the correct values for the UpdateCustomKeyStore\n parameters.
For an CloudHSM key store, you can use this operation to change the custom key store friendly\n name (NewCustomKeyStoreName), to tell KMS about a change to the\n kmsuser crypto user password (KeyStorePassword), or to associate\n the custom key store with a different, but related, CloudHSM cluster\n (CloudHsmClusterId). To update any property of an CloudHSM key store, the\n ConnectionState of the CloudHSM key store must be DISCONNECTED.
For an external key store, you can use this operation to change the custom key store\n friendly name (NewCustomKeyStoreName), or to tell KMS about a change to the\n external key store proxy authentication credentials\n (XksProxyAuthenticationCredential), connection method\n (XksProxyConnectivity), external proxy endpoint\n (XksProxyUriEndpoint) and path (XksProxyUriPath). For external key\n stores with an XksProxyConnectivity of VPC_ENDPOINT_SERVICE, you can\n also update the Amazon VPC endpoint service name (XksProxyVpcEndpointServiceName). To\n update most properties of an external key store, the ConnectionState of the\n external key store must be DISCONNECTED. However, you can update the\n CustomKeyStoreName, XksProxyAuthenticationCredential, and\n XksProxyUriPath of an external key store when it is in the CONNECTED or\n DISCONNECTED state.
If your update requires a DISCONNECTED state, before using\n UpdateCustomKeyStore, use the DisconnectCustomKeyStore\n operation to disconnect the custom key store. After the UpdateCustomKeyStore\n operation completes, use the ConnectCustomKeyStore to reconnect the custom\n key store. To find the ConnectionState of the custom key store, use the DescribeCustomKeyStores operation.
\n
\nBefore updating the custom key store, verify that the new values allow KMS to connect\n the custom key store to its backing key store. For example, before you change the\n XksProxyUriPath value, verify that the external key store proxy is reachable at\n the new path.
If the operation succeeds, it returns a JSON object with no\nproperties.
\n\n Cross-account use: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.
\n\n Required permissions: kms:UpdateCustomKeyStore (IAM policy)
\n\n Related operations:\n
\n\n CreateCustomKeyStore\n
\n\n DeleteCustomKeyStore\n
\nUpdates the description of a KMS key. To see the description of a KMS key, use DescribeKey.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:UpdateKeyDescription (key policy)
\n\n Related operations\n
\n\n CreateKey\n
\n\n DescribeKey\n
\nUpdates the description of a KMS key. To see the description of a KMS key, use DescribeKey.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
\n\n Required permissions: kms:UpdateKeyDescription (key policy)
\n\n Related operations\n
\n\n CreateKey\n
\n\n DescribeKey\n
\nChanges the primary key of a multi-Region key.
\nThis operation changes the replica key in the specified Region to a primary key and\n changes the former primary key to a replica key. For example, suppose you have a primary key\n in us-east-1 and a replica key in eu-west-2. If you run\n UpdatePrimaryRegion with a PrimaryRegion value of\n eu-west-2, the primary key is now the key in eu-west-2, and the\n key in us-east-1 becomes a replica key. For details, see Updating the primary Region in the Key Management Service Developer Guide.
This operation supports multi-Region keys, an KMS feature that lets you create multiple\n interoperable KMS keys in different Amazon Web Services Regions. Because these KMS keys have the same key ID, key\n material, and other metadata, you can use them interchangeably to encrypt data in one Amazon Web Services Region and decrypt\n it in a different Amazon Web Services Region without re-encrypting the data or making a cross-Region call. For more information about multi-Region keys, see Multi-Region keys in KMS in the Key Management Service Developer Guide.
\nThe primary key of a multi-Region key is the source for properties\n that are always shared by primary and replica keys, including the key material, key ID, key spec, key usage, key material\n origin, and automatic\n key rotation. It's the only key that can be replicated. You cannot delete the primary\n key until all replica keys are deleted.
\nThe key ID and primary Region that you specify uniquely identify the replica key that will\n become the primary key. The primary Region must already have a replica key. This operation\n does not create a KMS key in the specified Region. To find the replica keys, use the DescribeKey operation on the primary key or any replica key. To create a replica\n key, use the ReplicateKey operation.
\nYou can run this operation while using the affected multi-Region keys in cryptographic\n operations. This operation should not delay, interrupt, or cause failures in cryptographic\n operations.
\nEven after this operation completes, the process of updating the primary Region might\n still be in progress for a few more seconds. Operations such as DescribeKey might\n display both the old and new primary keys as replicas. The old and new primary keys have a\n transient key state of Updating. The original key state is restored when the\n update is complete. While the key state is Updating, you can use the keys in\n cryptographic operations, but you cannot replicate the new primary key or perform certain\n management operations, such as enabling or disabling these keys. For details about the\n Updating key state, see Key states of KMS keys in the Key Management Service Developer Guide.
This operation does not return any output. To verify that primary key is changed, use the\n DescribeKey operation.
\n\n Cross-account use: No. You cannot use this operation in a\n different Amazon Web Services account.
\n\n Required permissions:
\n\n kms:UpdatePrimaryRegion on the current primary key (in the primary key's\n Region). Include this permission primary key's key policy.
\n kms:UpdatePrimaryRegion on the current replica key (in the replica key's\n Region). Include this permission in the replica key's key policy.
\n Related operations\n
\n\n CreateKey\n
\n\n ReplicateKey\n
\nChanges the primary key of a multi-Region key.
\nThis operation changes the replica key in the specified Region to a primary key and\n changes the former primary key to a replica key. For example, suppose you have a primary key\n in us-east-1 and a replica key in eu-west-2. If you run\n UpdatePrimaryRegion with a PrimaryRegion value of\n eu-west-2, the primary key is now the key in eu-west-2, and the\n key in us-east-1 becomes a replica key. For details, see Updating the primary Region in the Key Management Service Developer Guide.
This operation supports multi-Region keys, an KMS feature that lets you create multiple\n interoperable KMS keys in different Amazon Web Services Regions. Because these KMS keys have the same key ID, key\n material, and other metadata, you can use them interchangeably to encrypt data in one Amazon Web Services Region and decrypt\n it in a different Amazon Web Services Region without re-encrypting the data or making a cross-Region call. For more information about multi-Region keys, see Multi-Region keys in KMS in the Key Management Service Developer Guide.
\nThe primary key of a multi-Region key is the source for properties\n that are always shared by primary and replica keys, including the key material, key ID, key spec, key usage, key material\n origin, and automatic\n key rotation. It's the only key that can be replicated. You cannot delete the primary\n key until all replica keys are deleted.
\nThe key ID and primary Region that you specify uniquely identify the replica key that will\n become the primary key. The primary Region must already have a replica key. This operation\n does not create a KMS key in the specified Region. To find the replica keys, use the DescribeKey operation on the primary key or any replica key. To create a replica\n key, use the ReplicateKey operation.
\nYou can run this operation while using the affected multi-Region keys in cryptographic\n operations. This operation should not delay, interrupt, or cause failures in cryptographic\n operations.
\nEven after this operation completes, the process of updating the primary Region might\n still be in progress for a few more seconds. Operations such as DescribeKey might\n display both the old and new primary keys as replicas. The old and new primary keys have a\n transient key state of Updating. The original key state is restored when the\n update is complete. While the key state is Updating, you can use the keys in\n cryptographic operations, but you cannot replicate the new primary key or perform certain\n management operations, such as enabling or disabling these keys. For details about the\n Updating key state, see Key states of KMS keys in the Key Management Service Developer Guide.
This operation does not return any output. To verify that primary key is changed, use the\n DescribeKey operation.
\n\n Cross-account use: No. You cannot use this operation in a\n different Amazon Web Services account.
\n\n Required permissions:
\n\n kms:UpdatePrimaryRegion on the current primary key (in the primary key's\n Region). Include this permission primary key's key policy.
\n kms:UpdatePrimaryRegion on the current replica key (in the replica key's\n Region). Include this permission in the replica key's key policy.
\n Related operations\n
\n\n CreateKey\n
\n\n ReplicateKey\n
\nVerifies a digital signature that was generated by the Sign operation.
\n \nVerification confirms that an authorized user signed the message with the specified KMS\n key and signing algorithm, and the message hasn't changed since it was signed. If the\n signature is verified, the value of the SignatureValid field in the response is\n True. If the signature verification fails, the Verify operation\n fails with an KMSInvalidSignatureException exception.
A digital signature is generated by using the private key in an asymmetric KMS key. The\n signature is verified by using the public key in the same asymmetric KMS key.\n For information about asymmetric KMS keys, see Asymmetric KMS keys in the Key Management Service Developer Guide.
\nTo use the Verify operation, specify the same asymmetric KMS key, message,\n and signing algorithm that were used to produce the signature. The message type does not need\n to be the same as the one used for signing, but it must indicate whether the value of the\n Message parameter should be hashed as part of the verification process.
You can also verify the digital signature by using the public key of the KMS key outside\n of KMS. Use the GetPublicKey operation to download the public key in the\n asymmetric KMS key and then use the public key to verify the signature outside of KMS. The\n advantage of using the Verify operation is that it is performed within KMS. As\n a result, it's easy to call, the operation is performed within the FIPS boundary, it is logged\n in CloudTrail, and you can use key policy and IAM policy to determine who is authorized to use\n the KMS key to verify signatures.
To verify a signature outside of KMS with an SM2 public key (China Regions only), you\n must specify the distinguishing ID. By default, KMS uses 1234567812345678 as\n the distinguishing ID. For more information, see Offline\n verification with SM2 key pairs.
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:Verify (key policy)
\n\n Related operations: Sign\n
" + "smithy.api#documentation": "Verifies a digital signature that was generated by the Sign operation.
\n \nVerification confirms that an authorized user signed the message with the specified KMS\n key and signing algorithm, and the message hasn't changed since it was signed. If the\n signature is verified, the value of the SignatureValid field in the response is\n True. If the signature verification fails, the Verify operation\n fails with an KMSInvalidSignatureException exception.
A digital signature is generated by using the private key in an asymmetric KMS key. The\n signature is verified by using the public key in the same asymmetric KMS key.\n For information about asymmetric KMS keys, see Asymmetric KMS keys in the Key Management Service Developer Guide.
\nTo use the Verify operation, specify the same asymmetric KMS key, message,\n and signing algorithm that were used to produce the signature. The message type does not need\n to be the same as the one used for signing, but it must indicate whether the value of the\n Message parameter should be hashed as part of the verification process.
You can also verify the digital signature by using the public key of the KMS key outside\n of KMS. Use the GetPublicKey operation to download the public key in the\n asymmetric KMS key and then use the public key to verify the signature outside of KMS. The\n advantage of using the Verify operation is that it is performed within KMS. As\n a result, it's easy to call, the operation is performed within the FIPS boundary, it is logged\n in CloudTrail, and you can use key policy and IAM policy to determine who is authorized to use\n the KMS key to verify signatures.
To verify a signature outside of KMS with an SM2 public key (China Regions only), you\n must specify the distinguishing ID. By default, KMS uses 1234567812345678 as\n the distinguishing ID. For more information, see Offline\n verification with SM2 key pairs.
The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:Verify (key policy)
\n\n Related operations: Sign\n
", + "smithy.api#examples": [ + { + "title": "To use an asymmetric KMS key to verify a digital signature", + "documentation": "This operation uses the public key in an elliptic curve (ECC) asymmetric key to verify a digital signature within AWS KMS.", + "input": { + "KeyId": "alias/ECC_signing_key", + "Message": "Verifies the hash-based message authentication code (HMAC) for a specified message, HMAC\n KMS key, and MAC algorithm. To verify the HMAC, VerifyMac computes an HMAC using\n the message, HMAC KMS key, and MAC algorithm that you specify, and compares the computed HMAC\n to the HMAC that you specify. If the HMACs are identical, the verification succeeds;\n otherwise, it fails. Verification indicates that the message hasn't changed since the HMAC was\n calculated, and the specified key was used to generate and verify the HMAC.
HMAC KMS keys and the HMAC algorithms that KMS uses conform to industry standards\n defined in RFC 2104.
\nThis operation is part of KMS support for HMAC KMS keys. For details, see\n HMAC keys in KMS in the\n Key Management Service Developer Guide.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:VerifyMac (key policy)
\n\n Related operations: GenerateMac\n
" + "smithy.api#documentation": "Verifies the hash-based message authentication code (HMAC) for a specified message, HMAC\n KMS key, and MAC algorithm. To verify the HMAC, VerifyMac computes an HMAC using\n the message, HMAC KMS key, and MAC algorithm that you specify, and compares the computed HMAC\n to the HMAC that you specify. If the HMACs are identical, the verification succeeds;\n otherwise, it fails. Verification indicates that the message hasn't changed since the HMAC was\n calculated, and the specified key was used to generate and verify the HMAC.
HMAC KMS keys and the HMAC algorithms that KMS uses conform to industry standards\n defined in RFC 2104.
\nThis operation is part of KMS support for HMAC KMS keys. For details, see\n HMAC keys in KMS in the\n Key Management Service Developer Guide.
\nThe KMS key that you use for this operation must be in a compatible key state. For\ndetails, see Key states of KMS keys in the Key Management Service Developer Guide.
\n\n Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify\n the key ARN or alias ARN in the value of the KeyId parameter.
\n Required permissions: kms:VerifyMac (key policy)
\n\n Related operations: GenerateMac\n
", + "smithy.api#examples": [ + { + "title": "To verify an HMAC", + "documentation": "This example verifies an HMAC for a particular message, HMAC KMS keys, and MAC algorithm. A value of 'true' in the MacValid value in the response indicates that the HMAC is valid.", + "input": { + "Message": "Hello World", + "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", + "MacAlgorithm": "HMAC_SHA_384", + "Mac": "Deletes the specified pronunciation lexicon stored in an Amazon Web Services Region. A lexicon which has been deleted is not available for\n speech synthesis, nor is it possible to retrieve it using either the\n GetLexicon or ListLexicon APIs.
For more information, see Managing Lexicons.
", + "smithy.api#examples": [ + { + "title": "To delete a lexicon", + "documentation": "Deletes a specified pronunciation lexicon stored in an AWS Region.", + "input": { + "Name": "example" + }, + "output": {} + } + ], "smithy.api#http": { "method": "DELETE", "uri": "/v1/lexicons/{Name}", @@ -110,6 +120,40 @@ ], "traits": { "smithy.api#documentation": "Returns the list of voices that are available for use when\n requesting speech synthesis. Each voice speaks a specified language, is\n either male or female, and is identified by an ID, which is the ASCII\n version of the voice name.
\nWhen synthesizing speech ( SynthesizeSpeech ), you\n provide the voice ID for the voice you want from the list of voices\n returned by DescribeVoices.
For example, you want your news reader application to read news in\n a specific language, but giving a user the option to choose the voice.\n Using the DescribeVoices operation you can provide the user\n with a list of available voices to select from.
You can optionally specify a language code to filter the available\n voices. For example, if you specify en-US, the operation\n returns a list of all available US English voices.
This operation requires permissions to perform the\n polly:DescribeVoices action.
Returns a list of pronunciation lexicons stored in an Amazon Web Services Region. For more information, see Managing Lexicons.
", + "smithy.api#examples": [ + { + "title": "To list all lexicons in a region", + "documentation": "Returns a list of pronunciation lexicons stored in an AWS Region.", + "output": { + "Lexicons": [ + { + "Attributes": { + "LanguageCode": "en-US", + "LastModified": 1.478542980117E9, + "Alphabet": "ipa", + "LexemesCount": 1, + "LexiconArn": "arn:aws:polly:us-east-1:123456789012:lexicon/example", + "Size": 503 + }, + "Name": "example" + } + ] + } + } + ], "smithy.api#http": { "method": "GET", "uri": "/v1/lexicons", @@ -1223,52 +1288,56 @@ "type": "error" }, { - "conditions": [], - "type": "tree", - "rules": [ + "conditions": [ { - "conditions": [ + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - true - ] - } - ], - "error": "Invalid Configuration: Dualstack and custom endpoint are not supported", - "type": "error" - }, - { - "conditions": [], - "endpoint": { - "url": { - "ref": "Endpoint" + "ref": "UseDualStack" }, - "properties": {}, - "headers": {} - }, - "type": "endpoint" + true + ] } - ] + ], + "error": "Invalid Configuration: Dualstack and custom endpoint are not supported", + "type": "error" + }, + { + "conditions": [], + "endpoint": { + "url": { + "ref": "Endpoint" + }, + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] }, { - "conditions": [], + "conditions": [ + { + "fn": "isSet", + "argv": [ + { + "ref": "Region" + } + ] + } + ], "type": "tree", "rules": [ { "conditions": [ { - "fn": "isSet", + "fn": "aws.partition", "argv": [ { "ref": "Region" } - ] + ], + "assign": "PartitionResult" } ], "type": "tree", @@ -1276,13 +1345,22 @@ { "conditions": [ { - "fn": "aws.partition", + "fn": "booleanEquals", "argv": [ { - "ref": "Region" - } - ], - "assign": "PartitionResult" + "ref": "UseFIPS" + }, + true + ] + }, + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseDualStack" + }, + true + ] } ], "type": "tree", @@ -1292,224 +1370,175 @@ { "fn": "booleanEquals", "argv": [ + true, { - "ref": "UseFIPS" - }, - true + "fn": "getAttr", + "argv": [ + { + "ref": "PartitionResult" + }, + "supportsFIPS" + ] + } ] }, { "fn": "booleanEquals", "argv": [ + true, { - "ref": "UseDualStack" - }, - true - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [ - { - "fn": "booleanEquals", - "argv": [ - true, - { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsFIPS" - ] - } - ] - }, - { - "fn": "booleanEquals", + "fn": "getAttr", "argv": [ - true, { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsDualStack" - ] - } - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [], - "type": "tree", - "rules": [ - { - "conditions": [], - "endpoint": { - "url": "https://polly-fips.{Region}.{PartitionResult#dualStackDnsSuffix}", - "properties": {}, - "headers": {} - }, - "type": "endpoint" - } + "ref": "PartitionResult" + }, + "supportsDualStack" ] } ] - }, + } + ], + "type": "tree", + "rules": [ { "conditions": [], - "error": "FIPS and DualStack are enabled, but this partition does not support one or both", - "type": "error" + "endpoint": { + "url": "https://polly-fips.{Region}.{PartitionResult#dualStackDnsSuffix}", + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] }, + { + "conditions": [], + "error": "FIPS and DualStack are enabled, but this partition does not support one or both", + "type": "error" + } + ] + }, + { + "conditions": [ + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseFIPS" + }, + true + ] + } + ], + "type": "tree", + "rules": [ { "conditions": [ { "fn": "booleanEquals", "argv": [ + true, { - "ref": "UseFIPS" - }, - true - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [ - { - "fn": "booleanEquals", + "fn": "getAttr", "argv": [ - true, { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsFIPS" - ] - } - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [], - "type": "tree", - "rules": [ - { - "conditions": [], - "endpoint": { - "url": "https://polly-fips.{Region}.{PartitionResult#dnsSuffix}", - "properties": {}, - "headers": {} - }, - "type": "endpoint" - } + "ref": "PartitionResult" + }, + "supportsFIPS" ] } ] - }, + } + ], + "type": "tree", + "rules": [ { "conditions": [], - "error": "FIPS is enabled but this partition does not support FIPS", - "type": "error" + "endpoint": { + "url": "https://polly-fips.{Region}.{PartitionResult#dnsSuffix}", + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] }, + { + "conditions": [], + "error": "FIPS is enabled but this partition does not support FIPS", + "type": "error" + } + ] + }, + { + "conditions": [ + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseDualStack" + }, + true + ] + } + ], + "type": "tree", + "rules": [ { "conditions": [ { "fn": "booleanEquals", "argv": [ + true, { - "ref": "UseDualStack" - }, - true - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [ - { - "fn": "booleanEquals", + "fn": "getAttr", "argv": [ - true, { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsDualStack" - ] - } - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [], - "type": "tree", - "rules": [ - { - "conditions": [], - "endpoint": { - "url": "https://polly.{Region}.{PartitionResult#dualStackDnsSuffix}", - "properties": {}, - "headers": {} - }, - "type": "endpoint" - } + "ref": "PartitionResult" + }, + "supportsDualStack" ] } ] - }, - { - "conditions": [], - "error": "DualStack is enabled but this partition does not support DualStack", - "type": "error" } - ] - }, - { - "conditions": [], + ], "type": "tree", "rules": [ { "conditions": [], "endpoint": { - "url": "https://polly.{Region}.{PartitionResult#dnsSuffix}", + "url": "https://polly.{Region}.{PartitionResult#dualStackDnsSuffix}", "properties": {}, "headers": {} }, "type": "endpoint" } ] + }, + { + "conditions": [], + "error": "DualStack is enabled but this partition does not support DualStack", + "type": "error" } ] + }, + { + "conditions": [], + "endpoint": { + "url": "https://polly.{Region}.{PartitionResult#dnsSuffix}", + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] - }, - { - "conditions": [], - "error": "Invalid Configuration: Missing Region", - "type": "error" } ] + }, + { + "conditions": [], + "error": "Invalid Configuration: Missing Region", + "type": "error" } ] }, @@ -2174,6 +2203,17 @@ ], "traits": { "smithy.api#documentation": "Stores a pronunciation lexicon in an Amazon Web Services Region. If\n a lexicon with the same name already exists in the region, it is\n overwritten by the new lexicon. Lexicon operations have eventual\n consistency, therefore, it might take some time before the lexicon is\n available to the SynthesizeSpeech operation.
\nFor more information, see Managing Lexicons.
", + "smithy.api#examples": [ + { + "title": "To save a lexicon", + "documentation": "Stores a pronunciation lexicon in an AWS Region.", + "input": { + "Name": "W3C", + "Content": "file://example.pls" + }, + "output": {} + } + ], "smithy.api#http": { "method": "PUT", "uri": "/v1/lexicons/{Name}", @@ -2609,6 +2649,27 @@ ], "traits": { "smithy.api#documentation": "Synthesizes UTF-8 input, plain text or SSML, to a stream of bytes.\n SSML input must be valid, well-formed SSML. Some alphabets might not be\n available with all the voices (for example, Cyrillic might not be read at\n all by English voices) unless phoneme mapping is used. For more\n information, see How it Works.
", + "smithy.api#examples": [ + { + "title": "To synthesize speech", + "documentation": "Synthesizes plain text or SSML into a file of human-like speech.", + "input": { + "LexiconNames": [ + "example" + ], + "OutputFormat": "mp3", + "SampleRate": "8000", + "Text": "All Gaul is divided into three parts", + "TextType": "text", + "VoiceId": "Joanna" + }, + "output": { + "AudioStream": "TEXT", + "ContentType": "audio/mpeg", + "RequestCharacters": 37 + } + } + ], "smithy.api#http": { "method": "POST", "uri": "/v1/speech", @@ -3413,6 +3474,12 @@ "traits": { "smithy.api#enumValue": "Isabelle" } + }, + "Zayd": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "Zayd" + } } } }, diff --git a/aws/sdk/aws-models/qldb-session.json b/aws/sdk/aws-models/qldb-session.json index b12ca953200f104ee14b640efdfb59d947b1be9a..df4974f8c5d895919ddf984afec12df9f093a500 100644 --- a/aws/sdk/aws-models/qldb-session.json +++ b/aws/sdk/aws-models/qldb-session.json @@ -326,7 +326,7 @@ "min": 1, "max": 32 }, - "smithy.api#pattern": "(?!^.*--)(?!^[0-9]+$)(?!^-)(?!.*-$)^[A-Za-z0-9-]+$" + "smithy.api#pattern": "^(?!^.*--)(?!^[0-9]+$)(?!^-)(?!.*-$)^[A-Za-z0-9-]+$" } }, "com.amazonaws.qldbsession#LimitExceededException": { @@ -471,52 +471,56 @@ "type": "error" }, { - "conditions": [], - "type": "tree", - "rules": [ + "conditions": [ { - "conditions": [ + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - true - ] - } - ], - "error": "Invalid Configuration: Dualstack and custom endpoint are not supported", - "type": "error" - }, - { - "conditions": [], - "endpoint": { - "url": { - "ref": "Endpoint" + "ref": "UseDualStack" }, - "properties": {}, - "headers": {} - }, - "type": "endpoint" + true + ] } - ] + ], + "error": "Invalid Configuration: Dualstack and custom endpoint are not supported", + "type": "error" + }, + { + "conditions": [], + "endpoint": { + "url": { + "ref": "Endpoint" + }, + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] }, { - "conditions": [], + "conditions": [ + { + "fn": "isSet", + "argv": [ + { + "ref": "Region" + } + ] + } + ], "type": "tree", "rules": [ { "conditions": [ { - "fn": "isSet", + "fn": "aws.partition", "argv": [ { "ref": "Region" } - ] + ], + "assign": "PartitionResult" } ], "type": "tree", @@ -524,13 +528,22 @@ { "conditions": [ { - "fn": "aws.partition", + "fn": "booleanEquals", "argv": [ { - "ref": "Region" - } - ], - "assign": "PartitionResult" + "ref": "UseFIPS" + }, + true + ] + }, + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseDualStack" + }, + true + ] } ], "type": "tree", @@ -540,224 +553,175 @@ { "fn": "booleanEquals", "argv": [ + true, { - "ref": "UseFIPS" - }, - true + "fn": "getAttr", + "argv": [ + { + "ref": "PartitionResult" + }, + "supportsFIPS" + ] + } ] }, { "fn": "booleanEquals", "argv": [ + true, { - "ref": "UseDualStack" - }, - true - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [ - { - "fn": "booleanEquals", + "fn": "getAttr", "argv": [ - true, { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsFIPS" - ] - } - ] - }, - { - "fn": "booleanEquals", - "argv": [ - true, - { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsDualStack" - ] - } - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [], - "type": "tree", - "rules": [ - { - "conditions": [], - "endpoint": { - "url": "https://session.qldb-fips.{Region}.{PartitionResult#dualStackDnsSuffix}", - "properties": {}, - "headers": {} - }, - "type": "endpoint" - } + "ref": "PartitionResult" + }, + "supportsDualStack" ] } ] - }, + } + ], + "type": "tree", + "rules": [ { "conditions": [], - "error": "FIPS and DualStack are enabled, but this partition does not support one or both", - "type": "error" + "endpoint": { + "url": "https://session.qldb-fips.{Region}.{PartitionResult#dualStackDnsSuffix}", + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] }, + { + "conditions": [], + "error": "FIPS and DualStack are enabled, but this partition does not support one or both", + "type": "error" + } + ] + }, + { + "conditions": [ + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseFIPS" + }, + true + ] + } + ], + "type": "tree", + "rules": [ { "conditions": [ { "fn": "booleanEquals", "argv": [ + true, { - "ref": "UseFIPS" - }, - true - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [ - { - "fn": "booleanEquals", + "fn": "getAttr", "argv": [ - true, - { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsFIPS" - ] - } - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [], - "type": "tree", - "rules": [ { - "conditions": [], - "endpoint": { - "url": "https://session.qldb-fips.{Region}.{PartitionResult#dnsSuffix}", - "properties": {}, - "headers": {} - }, - "type": "endpoint" - } + "ref": "PartitionResult" + }, + "supportsFIPS" ] } ] - }, + } + ], + "type": "tree", + "rules": [ { "conditions": [], - "error": "FIPS is enabled but this partition does not support FIPS", - "type": "error" + "endpoint": { + "url": "https://session.qldb-fips.{Region}.{PartitionResult#dnsSuffix}", + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] }, + { + "conditions": [], + "error": "FIPS is enabled but this partition does not support FIPS", + "type": "error" + } + ] + }, + { + "conditions": [ + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseDualStack" + }, + true + ] + } + ], + "type": "tree", + "rules": [ { "conditions": [ { "fn": "booleanEquals", "argv": [ + true, { - "ref": "UseDualStack" - }, - true - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [ - { - "fn": "booleanEquals", + "fn": "getAttr", "argv": [ - true, - { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsDualStack" - ] - } - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [], - "type": "tree", - "rules": [ { - "conditions": [], - "endpoint": { - "url": "https://session.qldb.{Region}.{PartitionResult#dualStackDnsSuffix}", - "properties": {}, - "headers": {} - }, - "type": "endpoint" - } + "ref": "PartitionResult" + }, + "supportsDualStack" ] } ] - }, - { - "conditions": [], - "error": "DualStack is enabled but this partition does not support DualStack", - "type": "error" } - ] - }, - { - "conditions": [], + ], "type": "tree", "rules": [ { "conditions": [], "endpoint": { - "url": "https://session.qldb.{Region}.{PartitionResult#dnsSuffix}", + "url": "https://session.qldb.{Region}.{PartitionResult#dualStackDnsSuffix}", "properties": {}, "headers": {} }, "type": "endpoint" } ] + }, + { + "conditions": [], + "error": "DualStack is enabled but this partition does not support DualStack", + "type": "error" } ] + }, + { + "conditions": [], + "endpoint": { + "url": "https://session.qldb.{Region}.{PartitionResult#dnsSuffix}", + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] - }, - { - "conditions": [], - "error": "Invalid Configuration: Missing Region", - "type": "error" } ] + }, + { + "conditions": [], + "error": "Invalid Configuration: Missing Region", + "type": "error" } ] }, @@ -1334,6 +1298,9 @@ "smithy.api#documentation": "Command to fetch a page.
" } } + }, + "traits": { + "smithy.api#input": {} } }, "com.amazonaws.qldbsession#SendCommandResult": { @@ -1381,6 +1348,9 @@ "smithy.api#documentation": "Contains the details of the fetched page.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.qldbsession#SessionToken": { diff --git a/aws/sdk/aws-models/route53.json b/aws/sdk/aws-models/route53.json index 388346dd5b737d5195b004be91e986159e04dd79..a987bda7ef84b3af65652b3884d58fa33bbc4a18 100644 --- a/aws/sdk/aws-models/route53.json +++ b/aws/sdk/aws-models/route53.json @@ -334,52 +334,56 @@ "type": "error" }, { - "conditions": [], - "type": "tree", - "rules": [ + "conditions": [ { - "conditions": [ + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - true - ] - } - ], - "error": "Invalid Configuration: Dualstack and custom endpoint are not supported", - "type": "error" - }, - { - "conditions": [], - "endpoint": { - "url": { - "ref": "Endpoint" + "ref": "UseDualStack" }, - "properties": {}, - "headers": {} - }, - "type": "endpoint" + true + ] } - ] + ], + "error": "Invalid Configuration: Dualstack and custom endpoint are not supported", + "type": "error" + }, + { + "conditions": [], + "endpoint": { + "url": { + "ref": "Endpoint" + }, + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] }, { - "conditions": [], + "conditions": [ + { + "fn": "isSet", + "argv": [ + { + "ref": "Region" + } + ] + } + ], "type": "tree", "rules": [ { "conditions": [ { - "fn": "isSet", + "fn": "aws.partition", "argv": [ { "ref": "Region" } - ] + ], + "assign": "PartitionResult" } ], "type": "tree", @@ -387,597 +391,557 @@ { "conditions": [ { - "fn": "aws.partition", + "fn": "stringEquals", "argv": [ { - "ref": "Region" - } - ], - "assign": "PartitionResult" - } - ], - "type": "tree", - "rules": [ - { - "conditions": [ - { - "fn": "stringEquals", + "fn": "getAttr", "argv": [ { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "name" - ] + "ref": "PartitionResult" }, - "aws" + "name" ] }, + "aws" + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseFIPS" - }, - false - ] + "ref": "UseFIPS" }, + false + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - false - ] - } - ], - "endpoint": { - "url": "https://route53.amazonaws.com", - "properties": { - "authSchemes": [ - { - "name": "sigv4", - "signingName": "route53", - "signingRegion": "us-east-1" - } - ] + "ref": "UseDualStack" }, - "headers": {} - }, - "type": "endpoint" + false + ] + } + ], + "endpoint": { + "url": "https://route53.amazonaws.com", + "properties": { + "authSchemes": [ + { + "name": "sigv4", + "signingName": "route53", + "signingRegion": "us-east-1" + } + ] }, + "headers": {} + }, + "type": "endpoint" + }, + { + "conditions": [ { - "conditions": [ + "fn": "stringEquals", + "argv": [ { - "fn": "stringEquals", + "fn": "getAttr", "argv": [ { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "name" - ] + "ref": "PartitionResult" }, - "aws" + "name" ] }, + "aws" + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseFIPS" - }, - true - ] + "ref": "UseFIPS" + }, + true + ] + }, + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseDualStack" }, + false + ] + } + ], + "endpoint": { + "url": "https://route53-fips.amazonaws.com", + "properties": { + "authSchemes": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - false - ] + "name": "sigv4", + "signingName": "route53", + "signingRegion": "us-east-1" } - ], - "endpoint": { - "url": "https://route53-fips.amazonaws.com", - "properties": { - "authSchemes": [ - { - "name": "sigv4", - "signingName": "route53", - "signingRegion": "us-east-1" - } - ] - }, - "headers": {} - }, - "type": "endpoint" + ] }, + "headers": {} + }, + "type": "endpoint" + }, + { + "conditions": [ { - "conditions": [ + "fn": "stringEquals", + "argv": [ { - "fn": "stringEquals", + "fn": "getAttr", "argv": [ { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "name" - ] + "ref": "PartitionResult" }, - "aws-cn" + "name" ] }, + "aws-cn" + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseFIPS" - }, - false - ] + "ref": "UseFIPS" }, + false + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - false - ] - } - ], - "endpoint": { - "url": "https://route53.amazonaws.com.cn", - "properties": { - "authSchemes": [ - { - "name": "sigv4", - "signingName": "route53", - "signingRegion": "cn-northwest-1" - } - ] + "ref": "UseDualStack" }, - "headers": {} - }, - "type": "endpoint" + false + ] + } + ], + "endpoint": { + "url": "https://route53.amazonaws.com.cn", + "properties": { + "authSchemes": [ + { + "name": "sigv4", + "signingName": "route53", + "signingRegion": "cn-northwest-1" + } + ] }, + "headers": {} + }, + "type": "endpoint" + }, + { + "conditions": [ { - "conditions": [ + "fn": "stringEquals", + "argv": [ { - "fn": "stringEquals", + "fn": "getAttr", "argv": [ { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "name" - ] + "ref": "PartitionResult" }, - "aws-us-gov" + "name" ] }, + "aws-us-gov" + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseFIPS" - }, - false - ] + "ref": "UseFIPS" }, + false + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - false - ] - } - ], - "endpoint": { - "url": "https://route53.us-gov.amazonaws.com", - "properties": { - "authSchemes": [ - { - "name": "sigv4", - "signingName": "route53", - "signingRegion": "us-gov-west-1" - } - ] + "ref": "UseDualStack" }, - "headers": {} - }, - "type": "endpoint" + false + ] + } + ], + "endpoint": { + "url": "https://route53.us-gov.amazonaws.com", + "properties": { + "authSchemes": [ + { + "name": "sigv4", + "signingName": "route53", + "signingRegion": "us-gov-west-1" + } + ] }, + "headers": {} + }, + "type": "endpoint" + }, + { + "conditions": [ { - "conditions": [ + "fn": "stringEquals", + "argv": [ { - "fn": "stringEquals", + "fn": "getAttr", "argv": [ { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "name" - ] + "ref": "PartitionResult" }, - "aws-us-gov" + "name" ] }, + "aws-us-gov" + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseFIPS" - }, - true - ] + "ref": "UseFIPS" }, + true + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", + "ref": "UseDualStack" + }, + false + ] + } + ], + "endpoint": { + "url": "https://route53.us-gov.amazonaws.com", + "properties": { + "authSchemes": [ + { + "name": "sigv4", + "signingName": "route53", + "signingRegion": "us-gov-west-1" + } + ] + }, + "headers": {} + }, + "type": "endpoint" + }, + { + "conditions": [ + { + "fn": "stringEquals", + "argv": [ + { + "fn": "getAttr", "argv": [ { - "ref": "UseDualStack" + "ref": "PartitionResult" }, - false - ] - } - ], - "endpoint": { - "url": "https://route53.us-gov.amazonaws.com", - "properties": { - "authSchemes": [ - { - "name": "sigv4", - "signingName": "route53", - "signingRegion": "us-gov-west-1" - } + "name" ] }, - "headers": {} - }, - "type": "endpoint" + "aws-iso" + ] }, { - "conditions": [ + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseFIPS" + }, + false + ] + }, + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseDualStack" + }, + false + ] + } + ], + "endpoint": { + "url": "https://route53.c2s.ic.gov", + "properties": { + "authSchemes": [ + { + "name": "sigv4", + "signingName": "route53", + "signingRegion": "us-iso-east-1" + } + ] + }, + "headers": {} + }, + "type": "endpoint" + }, + { + "conditions": [ + { + "fn": "stringEquals", + "argv": [ { - "fn": "stringEquals", + "fn": "getAttr", "argv": [ { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "name" - ] + "ref": "PartitionResult" }, - "aws-iso" + "name" ] }, + "aws-iso-b" + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseFIPS" - }, - false - ] + "ref": "UseFIPS" }, + false + ] + }, + { + "fn": "booleanEquals", + "argv": [ { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - false - ] + "ref": "UseDualStack" + }, + false + ] + } + ], + "endpoint": { + "url": "https://route53.sc2s.sgov.gov", + "properties": { + "authSchemes": [ + { + "name": "sigv4", + "signingName": "route53", + "signingRegion": "us-isob-east-1" } - ], - "endpoint": { - "url": "https://route53.c2s.ic.gov", - "properties": { - "authSchemes": [ - { - "name": "sigv4", - "signingName": "route53", - "signingRegion": "us-iso-east-1" - } - ] + ] + }, + "headers": {} + }, + "type": "endpoint" + }, + { + "conditions": [ + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseFIPS" }, - "headers": {} - }, - "type": "endpoint" + true + ] }, + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseDualStack" + }, + true + ] + } + ], + "type": "tree", + "rules": [ { "conditions": [ { - "fn": "stringEquals", + "fn": "booleanEquals", "argv": [ + true, { "fn": "getAttr", "argv": [ { "ref": "PartitionResult" }, - "name" + "supportsFIPS" ] - }, - "aws-iso-b" - ] - }, - { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseFIPS" - }, - false - ] - }, - { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseDualStack" - }, - false - ] - } - ], - "endpoint": { - "url": "https://route53.sc2s.sgov.gov", - "properties": { - "authSchemes": [ - { - "name": "sigv4", - "signingName": "route53", - "signingRegion": "us-isob-east-1" } ] }, - "headers": {} - }, - "type": "endpoint" - }, - { - "conditions": [ - { - "fn": "booleanEquals", - "argv": [ - { - "ref": "UseFIPS" - }, - true - ] - }, { "fn": "booleanEquals", "argv": [ + true, { - "ref": "UseDualStack" - }, - true - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [ - { - "fn": "booleanEquals", - "argv": [ - true, - { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsFIPS" - ] - } - ] - }, - { - "fn": "booleanEquals", + "fn": "getAttr", "argv": [ - true, - { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsDualStack" - ] - } - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [], - "type": "tree", - "rules": [ { - "conditions": [], - "endpoint": { - "url": "https://route53-fips.{Region}.{PartitionResult#dualStackDnsSuffix}", - "properties": {}, - "headers": {} - }, - "type": "endpoint" - } + "ref": "PartitionResult" + }, + "supportsDualStack" ] } ] - }, + } + ], + "type": "tree", + "rules": [ { "conditions": [], - "error": "FIPS and DualStack are enabled, but this partition does not support one or both", - "type": "error" + "endpoint": { + "url": "https://route53-fips.{Region}.{PartitionResult#dualStackDnsSuffix}", + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] }, + { + "conditions": [], + "error": "FIPS and DualStack are enabled, but this partition does not support one or both", + "type": "error" + } + ] + }, + { + "conditions": [ + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseFIPS" + }, + true + ] + } + ], + "type": "tree", + "rules": [ { "conditions": [ { "fn": "booleanEquals", "argv": [ + true, { - "ref": "UseFIPS" - }, - true - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [ - { - "fn": "booleanEquals", + "fn": "getAttr", "argv": [ - true, - { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsFIPS" - ] - } - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [], - "type": "tree", - "rules": [ { - "conditions": [], - "endpoint": { - "url": "https://route53-fips.{Region}.{PartitionResult#dnsSuffix}", - "properties": {}, - "headers": {} - }, - "type": "endpoint" - } + "ref": "PartitionResult" + }, + "supportsFIPS" ] } ] - }, + } + ], + "type": "tree", + "rules": [ { "conditions": [], - "error": "FIPS is enabled but this partition does not support FIPS", - "type": "error" + "endpoint": { + "url": "https://route53-fips.{Region}.{PartitionResult#dnsSuffix}", + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] }, + { + "conditions": [], + "error": "FIPS is enabled but this partition does not support FIPS", + "type": "error" + } + ] + }, + { + "conditions": [ + { + "fn": "booleanEquals", + "argv": [ + { + "ref": "UseDualStack" + }, + true + ] + } + ], + "type": "tree", + "rules": [ { "conditions": [ { "fn": "booleanEquals", "argv": [ + true, { - "ref": "UseDualStack" - }, - true - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [ - { - "fn": "booleanEquals", + "fn": "getAttr", "argv": [ - true, - { - "fn": "getAttr", - "argv": [ - { - "ref": "PartitionResult" - }, - "supportsDualStack" - ] - } - ] - } - ], - "type": "tree", - "rules": [ - { - "conditions": [], - "type": "tree", - "rules": [ { - "conditions": [], - "endpoint": { - "url": "https://route53.{Region}.{PartitionResult#dualStackDnsSuffix}", - "properties": {}, - "headers": {} - }, - "type": "endpoint" - } + "ref": "PartitionResult" + }, + "supportsDualStack" ] } ] - }, - { - "conditions": [], - "error": "DualStack is enabled but this partition does not support DualStack", - "type": "error" } - ] - }, - { - "conditions": [], + ], "type": "tree", "rules": [ { "conditions": [], "endpoint": { - "url": "https://route53.{Region}.{PartitionResult#dnsSuffix}", + "url": "https://route53.{Region}.{PartitionResult#dualStackDnsSuffix}", "properties": {}, "headers": {} }, "type": "endpoint" } ] + }, + { + "conditions": [], + "error": "DualStack is enabled but this partition does not support DualStack", + "type": "error" } ] + }, + { + "conditions": [], + "endpoint": { + "url": "https://route53.{Region}.{PartitionResult#dnsSuffix}", + "properties": {}, + "headers": {} + }, + "type": "endpoint" } ] - }, - { - "conditions": [], - "error": "Invalid Configuration: Missing Region", - "type": "error" } ] + }, + { + "conditions": [], + "error": "Invalid Configuration: Missing Region", + "type": "error" } ] }, @@ -1753,6 +1717,28 @@ ], "traits": { "smithy.api#documentation": "Associates an Amazon VPC with a private hosted zone.
\nTo perform the association, the VPC and the private hosted zone must already\n\t\t\t\texist. You can't convert a public hosted zone into a private hosted zone.
\nIf you want to associate a VPC that was created by using one Amazon Web Services account with a private hosted zone that was created by using a\n\t\t\t\tdifferent account, the Amazon Web Services account that created the private hosted\n\t\t\t\tzone must first submit a CreateVPCAssociationAuthorization request.\n\t\t\t\tThen the account that created the VPC must submit an\n\t\t\t\t\tAssociateVPCWithHostedZone request.
When granting access, the hosted zone and the Amazon VPC must belong to\n\t\t\t\tthe same partition. A partition is a group of Amazon Web Services Regions. Each\n\t\t\t\t\tAmazon Web Services account is scoped to one partition.
\nThe following are the supported partitions:
\n\n aws - Amazon Web Services Regions
\n aws-cn - China Regions
\n aws-us-gov - Amazon Web Services GovCloud (US) Region
For more information, see Access Management\n\t\t\t\tin the Amazon Web Services General Reference.
\nCreates, changes, or deletes a resource record set, which contains authoritative DNS\n\t\t\tinformation for a specified domain name or subdomain name. For example, you can use\n\t\t\t\tChangeResourceRecordSets to create a resource record set that routes\n\t\t\ttraffic for test.example.com to a web server that has an IP address of\n\t\t\t192.0.2.44.
\n Deleting Resource Record Sets\n
\nTo delete a resource record set, you must specify all the same values that you\n\t\t\tspecified when you created it.
\n\n Change Batches and Transactional Changes\n
\nThe request body must include a document with a\n\t\t\t\tChangeResourceRecordSetsRequest element. The request body contains a\n\t\t\tlist of change items, known as a change batch. Change batches are considered\n\t\t\ttransactional changes. Route 53 validates the changes in the request and then either\n\t\t\tmakes all or none of the changes in the change batch request. This ensures that DNS\n\t\t\trouting isn't adversely affected by partial changes to the resource record sets in a\n\t\t\thosted zone.
For example, suppose a change batch request contains two changes: it deletes the\n\t\t\t\tCNAME resource record set for www.example.com and creates an alias\n\t\t\tresource record set for www.example.com. If validation for both records succeeds, Route\n\t\t\t53 deletes the first resource record set and creates the second resource record set in a\n\t\t\tsingle operation. If validation for either the DELETE or the\n\t\t\t\tCREATE action fails, then the request is canceled, and the original\n\t\t\t\tCNAME record continues to exist.
If you try to delete the same resource record set more than once in a single\n\t\t\t\tchange batch, Route 53 returns an InvalidChangeBatch error.
\n Traffic Flow\n
\nTo create resource record sets for complex routing configurations, use either the\n\t\t\ttraffic flow visual editor in the Route 53 console or the API actions for traffic\n\t\t\tpolicies and traffic policy instances. Save the configuration as a traffic policy, then\n\t\t\tassociate the traffic policy with one or more domain names (such as example.com) or\n\t\t\tsubdomain names (such as www.example.com), in the same hosted zone or in multiple hosted\n\t\t\tzones. You can roll back the updates if the new configuration isn't performing as\n\t\t\texpected. For more information, see Using Traffic Flow to Route\n\t\t\t\tDNS Traffic in the Amazon Route 53 Developer\n\t\t\tGuide.
\n\n Create, Delete, and Upsert\n
\nUse ChangeResourceRecordsSetsRequest to perform the following\n\t\t\tactions:
\n CREATE: Creates a resource record set that has the specified\n\t\t\t\t\tvalues.
\n DELETE: Deletes an existing resource record set that has the\n\t\t\t\t\tspecified values.
\n UPSERT: If a resource set exists Route 53 updates it with the\n\t\t\t\t\tvalues in the request.
\n Syntaxes for Creating, Updating, and Deleting Resource Record\n\t\t\t\tSets\n
\nThe syntax for a request depends on the type of resource record set that you want to\n\t\t\tcreate, delete, or update, such as weighted, alias, or failover. The XML elements in\n\t\t\tyour request must appear in the order listed in the syntax.
\nFor an example for each type of resource record set, see \"Examples.\"
\nDon't refer to the syntax in the \"Parameter Syntax\" section, which includes\n\t\t\tall of the elements for every kind of resource record set that you can create, delete,\n\t\t\tor update by using ChangeResourceRecordSets.
\n Change Propagation to Route 53 DNS Servers\n
\nWhen you submit a ChangeResourceRecordSets request, Route 53 propagates your\n\t\t\tchanges to all of the Route 53 authoritative DNS servers managing the hosted zone. While\n\t\t\tyour changes are propagating, GetChange returns a status of\n\t\t\t\tPENDING. When propagation is complete, GetChange returns a\n\t\t\tstatus of INSYNC. Changes generally propagate to all Route 53 name servers\n\t\t\tmanaging the hosted zone within 60 seconds. For more information, see GetChange.
\n Limits on ChangeResourceRecordSets Requests\n
\nFor information about the limits on a ChangeResourceRecordSets request,\n\t\t\tsee Limits in the Amazon Route 53 Developer Guide.
Adds, edits, or deletes tags for a health check or a hosted zone.
\nFor information about using tags for cost allocation, see Using Cost Allocation\n\t\t\t\tTags in the Billing and Cost Management User Guide.
", + "smithy.api#examples": [ + { + "title": "To add or remove tags from a hosted zone or health check", + "documentation": "The following example adds two tags and removes one tag from the hosted zone with ID Z3M3LMPEXAMPLE.", + "input": { + "ResourceType": "hostedzone", + "ResourceId": "Z3M3LMPEXAMPLE", + "AddTags": [ + { + "Key": "apex", + "Value": "3874" + }, + { + "Key": "acme", + "Value": "4938" + } + ], + "RemoveTagKeys": [ + "Nadir" + ] + }, + "output": {} + } + ], "smithy.api#http": { "method": "POST", "uri": "/2013-04-01/tags/{ResourceType}/{ResourceId}", @@ -5578,6 +5623,34 @@ ], "traits": { "smithy.api#documentation": "Gets information about a specified hosted zone including the four name servers\n\t\t\tassigned to the hosted zone.
", + "smithy.api#examples": [ + { + "title": "To get information about a hosted zone", + "documentation": "The following example gets information about the Z3M3LMPEXAMPLE hosted zone.", + "input": { + "Id": "Z3M3LMPEXAMPLE" + }, + "output": { + "HostedZone": { + "ResourceRecordSetCount": 8, + "CallerReference": "C741617D-04E4-F8DE-B9D7-0D150FC61C2E", + "Config": { + "PrivateZone": false + }, + "Id": "/hostedzone/Z3M3LMPEXAMPLE", + "Name": "myawsbucket.com." + }, + "DelegationSet": { + "NameServers": [ + "ns-2048.awsdns-64.com", + "ns-2049.awsdns-65.net", + "ns-2050.awsdns-66.org", + "ns-2051.awsdns-67.co.uk" + ] + } + } + } + ], "smithy.api#http": { "method": "GET", "uri": "/2013-04-01/hostedzone/{Id}", diff --git a/aws/sdk/aws-models/s3.json b/aws/sdk/aws-models/s3.json index 92a0e925980e642d08fb4241dc5a0de817a9de35..174eb169d200a686b17e4bd541d669dde0842484 100644 --- a/aws/sdk/aws-models/s3.json +++ b/aws/sdk/aws-models/s3.json @@ -62,6 +62,18 @@ ], "traits": { "smithy.api#documentation": "This action aborts a multipart upload. After a multipart upload is aborted, no\n additional parts can be uploaded using that upload ID. The storage consumed by any\n previously uploaded parts will be freed. However, if any part uploads are currently in\n progress, those part uploads might or might not succeed. As a result, it might be necessary\n to abort a given multipart upload multiple times in order to completely free all storage\n consumed by all parts.
\nTo verify that all parts have been removed, so you don't get charged for the part\n storage, you should call the ListParts action and ensure that\n the parts list is empty.
\nFor information about permissions required to use the multipart upload, see Multipart Upload\n and Permissions.
\nThe following operations are related to AbortMultipartUpload:
\n UploadPart\n
\n\n ListParts\n
\n\n ListMultipartUploads\n
\nCreates a copy of an object that is already stored in Amazon S3.
\nYou can store individual objects of up to 5 TB in Amazon S3. You create a copy of your\n object up to 5 GB in size in a single atomic action using this API. However, to copy an\n object greater than 5 GB, you must use the multipart upload Upload Part - Copy\n (UploadPartCopy) API. For more information, see Copy Object Using the\n REST Multipart Upload API.
\nAll copy requests must be authenticated. Additionally, you must have\n read access to the source object and write\n access to the destination bucket. For more information, see REST Authentication. Both the\n Region that you want to copy the object from and the Region that you want to copy the\n object to must be enabled for your account.
\nA copy request might return an error when Amazon S3 receives the copy request or while Amazon S3\n is copying the files. If the error occurs before the copy action starts, you receive a\n standard Amazon S3 error. If the error occurs during the copy operation, the error response is\n embedded in the 200 OK response. This means that a 200 OK\n response can contain either a success or an error. If you call the S3 API directly, make\n sure to design your application to parse the contents of the response and handle it\n appropriately. If you use Amazon Web Services SDKs, SDKs handle this condition. The SDKs detect the\n embedded error and apply error handling per your configuration settings (including\n automatically retrying the request as appropriate). If the condition persists, the SDKs\n throws an exception (or, for the SDKs that don't use exceptions, they return the\n error).
If the copy is successful, you receive a response with information about the copied\n object.
\nIf the request is an HTTP 1.1 request, the response is chunk encoded. If it were not,\n it would not contain the content-length, and you would need to read the entire\n body.
\nThe copy request charge is based on the storage class and Region that you specify for\n the destination object. The request can also result in a data retrieval charge for the\n source if the source storage class bills for data retrieval. For pricing information, see\n Amazon S3 pricing.
\nAmazon S3 transfer acceleration does not support cross-Region copies. If you request a\n cross-Region copy using a transfer acceleration endpoint, you get a 400 Bad\n Request error. For more information, see Transfer\n Acceleration.
When copying an object, you can preserve all metadata (the default) or specify new metadata.\n However, the access control list (ACL) is not preserved and is set to private for the user making the request. To\n override the default ACL setting, specify a new ACL when generating a copy request. For\n more information, see Using ACLs.
\nTo specify whether you want the object metadata copied from the source object or\n replaced with metadata provided in the request, you can optionally add the\n x-amz-metadata-directive header. When you grant permissions, you can use\n the s3:x-amz-metadata-directive condition key to enforce certain metadata\n behavior when objects are uploaded. For more information, see Specifying Conditions in a\n Policy in the Amazon S3 User Guide. For a complete list of\n Amazon S3-specific condition keys, see Actions, Resources, and Condition Keys for\n Amazon S3.
\n x-amz-website-redirect-location is unique to each object and must be\n specified in the request headers to copy the value.
To only copy an object under certain conditions, such as whether the Etag\n matches or whether the object was modified before or after a specified date, use the\n following request parameters:
\n x-amz-copy-source-if-match\n
\n x-amz-copy-source-if-none-match\n
\n x-amz-copy-source-if-unmodified-since\n
\n x-amz-copy-source-if-modified-since\n
If both the x-amz-copy-source-if-match and\n x-amz-copy-source-if-unmodified-since headers are present in the request\n and evaluate as follows, Amazon S3 returns 200 OK and copies the data:
\n x-amz-copy-source-if-match condition evaluates to true
\n x-amz-copy-source-if-unmodified-since condition evaluates to\n false
If both the x-amz-copy-source-if-none-match and\n x-amz-copy-source-if-modified-since headers are present in the request and\n evaluate as follows, Amazon S3 returns the 412 Precondition Failed response\n code:
\n x-amz-copy-source-if-none-match condition evaluates to false
\n x-amz-copy-source-if-modified-since condition evaluates to\n true
All headers with the x-amz- prefix, including\n x-amz-copy-source, must be signed.
Amazon S3 automatically encrypts all new objects that are copied to an S3 bucket. When\n copying an object, if you don't specify encryption information in your copy\n request, the encryption setting of the target object is set to the default\n encryption configuration of the destination bucket. By default, all buckets have a\n base level of encryption configuration that uses server-side encryption with Amazon S3\n managed keys (SSE-S3). If the destination bucket has a default encryption\n configuration that uses server-side encryption with Key Management Service (KMS) keys\n (SSE-KMS), dual-layer server-side encryption with Amazon Web Services KMS keys (DSSE-KMS), or\n server-side encryption with customer-provided encryption keys (SSE-C), Amazon S3 uses\n the corresponding KMS key, or a customer-provided key to encrypt the target\n object copy.
\nWhen you perform a CopyObject operation, if you want to use a different type\n of encryption setting for the target object, you can use other appropriate\n encryption-related headers to encrypt the target object with a KMS key, an Amazon S3 managed\n key, or a customer-provided key. With server-side encryption, Amazon S3 encrypts your data as it\n writes your data to disks in its data centers and decrypts the data when you access it. If the\n encryption setting in your request is different from the default encryption configuration\n of the destination bucket, the encryption setting in your request takes precedence. If the\n source object for the copy is stored in Amazon S3 using SSE-C, you must provide the necessary\n encryption information in your request so that Amazon S3 can decrypt the object for copying. For\n more information about server-side encryption, see Using Server-Side\n Encryption.
If a target object uses SSE-KMS, you can enable an S3 Bucket Key for the\n object. For more information, see Amazon S3 Bucket Keys in the\n Amazon S3 User Guide.
\nWhen copying an object, you can optionally use headers to grant ACL-based permissions.\n By default, all objects are private. Only the owner has full access control. When adding a\n new object, you can grant permissions to individual Amazon Web Services accounts or to predefined groups\n that are defined by Amazon S3. These permissions are then added to the ACL on the object. For more\n information, see Access Control List (ACL) Overview and Managing ACLs Using the REST\n API.
\nIf the bucket that you're copying objects to uses the bucket owner enforced setting for\n S3 Object Ownership, ACLs are disabled and no longer affect permissions. Buckets that use\n this setting only accept PUT requests that don't specify an ACL or PUT requests that\n specify bucket owner full control ACLs, such as the bucket-owner-full-control\n canned ACL or an equivalent form of this ACL expressed in the XML format.
For more information, see Controlling ownership of\n objects and disabling ACLs in the Amazon S3 User Guide.
\nIf your bucket uses the bucket owner enforced setting for Object Ownership, all\n objects written to the bucket by any account will be owned by the bucket owner.
\nWhen copying an object, if it has a checksum, that checksum will be copied to the new\n object by default. When you copy the object over, you can optionally specify a different\n checksum algorithm to use with the x-amz-checksum-algorithm header.
You can use the CopyObject action to change the storage class of an object\n that is already stored in Amazon S3 by using the StorageClass parameter. For more\n information, see Storage Classes in the\n Amazon S3 User Guide.
If the source object's storage class is GLACIER, you must restore a copy of\n this object before you can use it as a source object for the copy operation. For\n more information, see RestoreObject. For\n more information, see Copying\n Objects.
\nBy default, x-amz-copy-source header identifies the current version of an object\n to copy. If the current version is a delete marker, Amazon S3 behaves as if the object was\n deleted. To copy a different version, use the versionId subresource.
If you enable versioning on the target bucket, Amazon S3 generates a unique version ID for\n the object being copied. This version ID is different from the version ID of the source\n object. Amazon S3 returns the version ID of the copied object in the\n x-amz-version-id response header in the response.
If you do not enable versioning or suspend it on the target bucket, the version ID that\n Amazon S3 generates is always null.
\nThe following operations are related to CopyObject:
Creates a new S3 bucket. To create a bucket, you must register with Amazon S3 and have a\n valid Amazon Web Services Access Key ID to authenticate requests. Anonymous requests are never allowed to\n create buckets. By creating the bucket, you become the bucket owner.
\nNot every string is an acceptable bucket name. For information about bucket naming\n restrictions, see Bucket naming\n rules.
\nIf you want to create an Amazon S3 on Outposts bucket, see Create Bucket.
\nBy default, the bucket is created in the US East (N. Virginia) Region. You can\n optionally specify a Region in the request body. You might choose a Region to optimize\n latency, minimize costs, or address regulatory requirements. For example, if you reside in\n Europe, you will probably find it advantageous to create buckets in the Europe (Ireland)\n Region. For more information, see Accessing a\n bucket.
\nIf you send your create bucket request to the s3.amazonaws.com endpoint,\n the request goes to the us-east-1 Region. Accordingly, the signature calculations in\n Signature Version 4 must use us-east-1 as the Region, even if the location constraint in\n the request specifies another Region where the bucket is to be created. If you create a\n bucket in a Region other than US East (N. Virginia), your application must be able to\n handle 307 redirect. For more information, see Virtual hosting of\n buckets.
In addition to s3:CreateBucket, the following permissions are required when\n your CreateBucket request includes specific headers:
\n Access control lists (ACLs) - If your CreateBucket request\n specifies access control list (ACL) permissions and the ACL is public-read, public-read-write,\n authenticated-read, or if you specify access permissions explicitly through any other\n ACL, both s3:CreateBucket and s3:PutBucketAcl permissions\n are needed. If the ACL for the CreateBucket request is private or if the request doesn't\n specify any ACLs, only s3:CreateBucket permission is needed.
\n Object Lock - If ObjectLockEnabledForBucket is set to true in your\n CreateBucket request,\n s3:PutBucketObjectLockConfiguration and\n s3:PutBucketVersioning permissions are required.
\n S3 Object Ownership - If your CreateBucket request includes the x-amz-object-ownership header, then the\n s3:PutBucketOwnershipControls permission is required. By default, ObjectOwnership is set to BucketOWnerEnforced and ACLs are disabled. We recommend keeping\n ACLs disabled, except in uncommon use cases where you must control access for each object individually. If you want to change the ObjectOwnership setting, you can use the \n x-amz-object-ownership header in your CreateBucket request to set the ObjectOwnership setting of your choice.\n For more information about S3 Object Ownership, see Controlling object\n ownership in the Amazon S3 User Guide.
\n S3 Block Public Access - If your specific use case requires granting public access to your S3 resources, you can disable Block Public Access. You can create a new bucket with Block Public Access enabled, then separately call the \n DeletePublicAccessBlock\n API. To use this operation, you must have the\n s3:PutBucketPublicAccessBlock permission. By default, all Block\n Public Access settings are enabled for new buckets. To avoid inadvertent exposure of\n your resources, we recommend keeping the S3 Block Public Access settings enabled. For more information about S3 Block Public Access, see Blocking public\n access to your Amazon S3 storage in the Amazon S3 User Guide.
If your CreateBucket request sets BucketOwnerEnforced for Amazon S3 Object Ownership\n and specifies a bucket ACL that provides access to an external Amazon Web Services account, your request fails with a 400 error and returns the InvalidBucketAcLWithObjectOwnership error code. For more information,\n see Setting Object\n Ownership on an existing bucket in the Amazon S3 User Guide.
The following operations are related to CreateBucket:
\n PutObject\n
\n\n DeleteBucket\n
\nThis action initiates a multipart upload and returns an upload ID. This upload ID is\n used to associate all of the parts in the specific multipart upload. You specify this\n upload ID in each of your subsequent upload part requests (see UploadPart). You also include this\n upload ID in the final request to either complete or abort the multipart upload\n request.
\nFor more information about multipart uploads, see Multipart Upload Overview.
\nIf you have configured a lifecycle rule to abort incomplete multipart uploads, the\n upload must complete within the number of days specified in the bucket lifecycle\n configuration. Otherwise, the incomplete multipart upload becomes eligible for an abort\n action and Amazon S3 aborts the multipart upload. For more information, see Aborting Incomplete Multipart Uploads Using a Bucket Lifecycle Configuration.
\nFor information about the permissions required to use the multipart upload API, see\n Multipart\n Upload and Permissions.
\nFor request signing, multipart upload is just a series of regular requests. You initiate\n a multipart upload, send one or more requests to upload parts, and then complete the\n multipart upload process. You sign each request individually. There is nothing special\n about signing multipart upload requests. For more information about signing, see Authenticating Requests (Amazon Web Services Signature Version 4).
\nAfter you initiate a multipart upload and upload one or more parts, to stop being\n charged for storing the uploaded parts, you must either complete or abort the multipart\n upload. Amazon S3 frees up the space used to store the parts and stop charging you for\n storing them only after you either complete or abort a multipart upload.
\nServer-side encryption is for data encryption at rest. Amazon S3 encrypts your data as it\n writes it to disks in its data centers and decrypts it when you access it. Amazon S3\n automatically encrypts all new objects that are uploaded to an S3 bucket. When doing a\n multipart upload, if you don't specify encryption information in your request, the\n encryption setting of the uploaded parts is set to the default encryption configuration of\n the destination bucket. By default, all buckets have a base level of encryption\n configuration that uses server-side encryption with Amazon S3 managed keys (SSE-S3). If the\n destination bucket has a default encryption configuration that uses server-side encryption\n with an Key Management Service (KMS) key (SSE-KMS), or a customer-provided encryption key (SSE-C),\n Amazon S3 uses the corresponding KMS key, or a customer-provided key to encrypt the uploaded\n parts. When you perform a CreateMultipartUpload operation, if you want to use a different\n type of encryption setting for the uploaded parts, you can request that Amazon S3 encrypts the\n object with a KMS key, an Amazon S3 managed key, or a customer-provided key. If the encryption\n setting in your request is different from the default encryption configuration of the\n destination bucket, the encryption setting in your request takes precedence. If you choose\n to provide your own encryption key, the request headers you provide in UploadPart\n and UploadPartCopy requests must match the headers you used in the request to\n initiate the upload by using CreateMultipartUpload. You can request that Amazon S3\n save the uploaded parts encrypted with server-side encryption with an Amazon S3 managed key\n (SSE-S3), an Key Management Service (KMS) key (SSE-KMS), or a customer-provided encryption key\n (SSE-C).
To perform a multipart upload with encryption by using an Amazon Web Services KMS key, the requester\n must have permission to the kms:Decrypt and kms:GenerateDataKey*\n actions on the key. These permissions are required because Amazon S3 must decrypt and read data\n from the encrypted file parts before it completes the multipart upload. For more\n information, see Multipart upload API\n and permissions and Protecting data using\n server-side encryption with Amazon Web Services KMS in the\n Amazon S3 User Guide.
If your Identity and Access Management (IAM) user or role is in the same Amazon Web Services account as the KMS key,\n then you must have these permissions on the key policy. If your IAM user or role belongs\n to a different account than the key, then you must have the permissions on both the key\n policy and your IAM user or role.
\nFor more information, see Protecting Data Using Server-Side\n Encryption.
\nWhen copying an object, you can optionally specify the accounts or groups that\n should be granted specific permissions on the new object. There are two ways to\n grant the permissions using the request headers:
\nSpecify a canned ACL with the x-amz-acl request header. For\n more information, see Canned\n ACL.
Specify access permissions explicitly with the\n x-amz-grant-read, x-amz-grant-read-acp,\n x-amz-grant-write-acp, and\n x-amz-grant-full-control headers. These parameters map to\n the set of permissions that Amazon S3 supports in an ACL. For more information,\n see Access Control List (ACL) Overview.
You can use either a canned ACL or specify access permissions explicitly. You\n cannot do both.
\nAmazon S3 encrypts data\n by using server-side encryption with an Amazon S3 managed key (SSE-S3) by default. Server-side encryption is for data encryption at rest. Amazon S3 encrypts\n your data as it writes it to disks in its data centers and decrypts it when you\n access it. You can request that Amazon S3 encrypts\n data at rest by using server-side encryption with other key options. The option you use depends on\n whether you want to use KMS keys (SSE-KMS) or provide your own encryption keys\n (SSE-C).
\nUse KMS keys (SSE-KMS) that include the Amazon Web Services managed key\n (aws/s3) and KMS customer managed keys stored in Key Management Service (KMS) – If you\n want Amazon Web Services to manage the keys used to encrypt data, specify the following\n headers in the request.
\n x-amz-server-side-encryption\n
\n x-amz-server-side-encryption-aws-kms-key-id\n
\n x-amz-server-side-encryption-context\n
If you specify x-amz-server-side-encryption:aws:kms, but\n don't provide x-amz-server-side-encryption-aws-kms-key-id,\n Amazon S3 uses the Amazon Web Services managed key (aws/s3 key) in KMS to\n protect the data.
All GET and PUT requests for an object protected\n by KMS fail if you don't make them by using Secure Sockets Layer (SSL),\n Transport Layer Security (TLS), or Signature Version 4.
For more information about server-side encryption with KMS keys\n (SSE-KMS), see Protecting Data\n Using Server-Side Encryption with KMS keys.
\nUse customer-provided encryption keys (SSE-C) – If you want to manage\n your own encryption keys, provide all the following headers in the\n request.
\n\n x-amz-server-side-encryption-customer-algorithm\n
\n x-amz-server-side-encryption-customer-key\n
\n x-amz-server-side-encryption-customer-key-MD5\n
For more information about server-side encryption with customer-provided\n encryption keys (SSE-C), see \n Protecting data using server-side encryption with customer-provided\n encryption keys (SSE-C).
\nYou also can use the following access control–related headers with this\n operation. By default, all objects are private. Only the owner has full access\n control. When adding a new object, you can grant permissions to individual\n Amazon Web Services accounts or to predefined groups defined by Amazon S3. These permissions are then\n added to the access control list (ACL) on the object. For more information, see\n Using ACLs. With this operation, you can grant access permissions\n using one of the following two methods:
\nSpecify a canned ACL (x-amz-acl) — Amazon S3 supports a set of\n predefined ACLs, known as canned ACLs. Each canned ACL\n has a predefined set of grantees and permissions. For more information, see\n Canned\n ACL.
Specify access permissions explicitly — To explicitly grant access\n permissions to specific Amazon Web Services accounts or groups, use the following headers.\n Each header maps to specific permissions that Amazon S3 supports in an ACL. For\n more information, see Access Control List (ACL)\n Overview. In the header, you specify a list of grantees who get\n the specific permission. To grant permissions explicitly, use:
\n\n x-amz-grant-read\n
\n x-amz-grant-write\n
\n x-amz-grant-read-acp\n
\n x-amz-grant-write-acp\n
\n x-amz-grant-full-control\n
You specify each grantee as a type=value pair, where the type is one of\n the following:
\n\n id – if the value specified is the canonical user ID\n of an Amazon Web Services account
\n uri – if you are granting permissions to a predefined\n group
\n emailAddress – if the value specified is the email\n address of an Amazon Web Services account
Using email addresses to specify a grantee is only supported in the following Amazon Web Services Regions:
\nUS East (N. Virginia)
\nUS West (N. California)
\nUS West (Oregon)
\nAsia Pacific (Singapore)
\nAsia Pacific (Sydney)
\nAsia Pacific (Tokyo)
\nEurope (Ireland)
\nSouth America (São Paulo)
\nFor a list of all the Amazon S3 supported Regions and endpoints, see Regions and Endpoints in the Amazon Web Services General Reference.
\nFor example, the following x-amz-grant-read header grants the Amazon Web Services accounts identified by account IDs permissions to read object data and its metadata:
\n x-amz-grant-read: id=\"11112222333\", id=\"444455556666\" \n
The following operations are related to CreateMultipartUpload:
\n UploadPart\n
\n\n AbortMultipartUpload\n
\n\n ListParts\n
\n\n ListMultipartUploads\n
\nDeletes the S3 bucket. All objects (including all object versions and delete markers) in\n the bucket must be deleted before the bucket itself can be deleted.
\nThe following operations are related to DeleteBucket:
\n CreateBucket\n
\n\n DeleteObject\n
\nDeletes the cors configuration information set for the bucket.
To use this operation, you must have permission to perform the\n s3:PutBucketCORS action. The bucket owner has this permission by default\n and can grant this permission to others.
For information about cors, see Enabling Cross-Origin Resource Sharing in\n the Amazon S3 User Guide.
\n Related Resources\n
\n\n PutBucketCors\n
\n\n RESTOPTIONSobject\n
\nDeletes the lifecycle configuration from the specified bucket. Amazon S3 removes all the\n lifecycle configuration rules in the lifecycle subresource associated with the bucket. Your\n objects never expire, and Amazon S3 no longer automatically deletes any objects on the basis of\n rules contained in the deleted lifecycle configuration.
\nTo use this operation, you must have permission to perform the\n s3:PutLifecycleConfiguration action. By default, the bucket owner has this\n permission and the bucket owner can grant this permission to others.
There is usually some time lag before lifecycle configuration deletion is fully\n propagated to all the Amazon S3 systems.
\nFor more information about the object expiration, see Elements to Describe Lifecycle Actions.
\nRelated actions include:
\nThis implementation of the DELETE action uses the policy subresource to delete the\n policy of a specified bucket. If you are using an identity other than the root user of the\n Amazon Web Services account that owns the bucket, the calling identity must have the\n DeleteBucketPolicy permissions on the specified bucket and belong to the\n bucket owner's account to use this operation.
If you don't have DeleteBucketPolicy permissions, Amazon S3 returns a 403\n Access Denied error. If you have the correct permissions, but you're not using an\n identity that belongs to the bucket owner's account, Amazon S3 returns a 405 Method Not\n Allowed error.
To ensure that bucket owners don't inadvertently lock themselves out of their own\n buckets, the root principal in a bucket owner's Amazon Web Services account can perform the\n GetBucketPolicy, PutBucketPolicy, and\n DeleteBucketPolicy API actions, even if their bucket policy explicitly\n denies the root principal's access. Bucket owner root principals can only be blocked from performing \n these API actions by VPC endpoint policies and Amazon Web Services Organizations policies.
For more information about bucket policies, see Using Bucket Policies and\n UserPolicies.
\nThe following operations are related to DeleteBucketPolicy\n
\n CreateBucket\n
\n\n DeleteObject\n
\nDeletes the replication configuration from the bucket.
\nTo use this operation, you must have permissions to perform the\n s3:PutReplicationConfiguration action. The bucket owner has these\n permissions by default and can grant it to others. For more information about permissions,\n see Permissions Related to Bucket Subresource Operations and Managing\n Access Permissions to Your Amazon S3 Resources.
It can take a while for the deletion of a replication configuration to fully\n propagate.
\nFor information about replication configuration, see Replication in the\n Amazon S3 User Guide.
\nThe following operations are related to DeleteBucketReplication:
\n PutBucketReplication\n
\n\n GetBucketReplication\n
\nDeletes the tags from the bucket.
\nTo use this operation, you must have permission to perform the\n s3:PutBucketTagging action. By default, the bucket owner has this\n permission and can grant this permission to others.
The following operations are related to DeleteBucketTagging:
\n GetBucketTagging\n
\n\n PutBucketTagging\n
\nThis action removes the website configuration for a bucket. Amazon S3 returns a 200\n OK response upon successfully deleting a website configuration on the specified\n bucket. You will get a 200 OK response if the website configuration you are\n trying to delete does not exist on the bucket. Amazon S3 returns a 404 response if\n the bucket specified in the request does not exist.
This DELETE action requires the S3:DeleteBucketWebsite permission. By\n default, only the bucket owner can delete the website configuration attached to a bucket.\n However, bucket owners can grant other users permission to delete the website configuration\n by writing a bucket policy granting them the S3:DeleteBucketWebsite\n permission.
For more information about hosting websites, see Hosting Websites on Amazon S3.
\nThe following operations are related to DeleteBucketWebsite:
\n GetBucketWebsite\n
\n\n PutBucketWebsite\n
\nRemoves the null version (if there is one) of an object and inserts a delete marker,\n which becomes the latest version of the object. If there isn't a null version, Amazon S3 does\n not remove any objects but will still respond that the command was successful.
\nTo remove a specific version, you must use the version Id subresource. Using this\n subresource permanently deletes the version. If the object deleted is a delete marker, Amazon S3\n sets the response header, x-amz-delete-marker, to true.
If the object you want to delete is in a bucket where the bucket versioning\n configuration is MFA Delete enabled, you must include the x-amz-mfa request\n header in the DELETE versionId request. Requests that include\n x-amz-mfa must use HTTPS.
For more information about MFA Delete, see Using MFA Delete. To see sample\n requests that use versioning, see Sample\n Request.
\nYou can delete objects by explicitly calling DELETE Object or configure its lifecycle\n (PutBucketLifecycle) to enable Amazon S3 to remove them for you. If you want to block\n users or accounts from removing or deleting objects from your bucket, you must deny them\n the s3:DeleteObject, s3:DeleteObjectVersion, and\n s3:PutLifeCycleConfiguration actions.
The following action is related to DeleteObject:
\n PutObject\n
\nRemoves the entire tag set from the specified object. For more information about\n managing object tags, see Object Tagging.
\nTo use this operation, you must have permission to perform the\n s3:DeleteObjectTagging action.
To delete tags of a specific object version, add the versionId query\n parameter in the request. You will need permission for the\n s3:DeleteObjectVersionTagging action.
The following operations are related to DeleteObjectTagging:
\n PutObjectTagging\n
\n\n GetObjectTagging\n
\nReturns the Cross-Origin Resource Sharing (CORS) configuration information set for the\n bucket.
\n To use this operation, you must have permission to perform the\n s3:GetBucketCORS action. By default, the bucket owner has this permission\n and can grant it to others.
To use this API operation against an access point, provide the alias of the access point in place of the bucket name.
\nTo use this API operation against an Object Lambda access point, provide the alias of the Object Lambda access point in place of the bucket name. \nIf the Object Lambda access point alias in a request is not valid, the error code InvalidAccessPointAliasError is returned. \nFor more information about InvalidAccessPointAliasError, see List of\n Error Codes.
For more information about CORS, see Enabling Cross-Origin Resource\n Sharing.
\nThe following operations are related to GetBucketCors:
\n PutBucketCors\n
\n\n DeleteBucketCors\n
\nBucket lifecycle configuration now supports specifying a lifecycle rule using an\n object key name prefix, one or more object tags, or a combination of both. Accordingly,\n this section describes the latest API. The response describes the new filter element\n that you can use to specify a filter to select a subset of objects to which the rule\n applies. If you are using a previous version of the lifecycle configuration, it still\n works. For the earlier action, see GetBucketLifecycle.
\nReturns the lifecycle configuration information set on the bucket. For information about\n lifecycle configuration, see Object Lifecycle\n Management.
\nTo use this operation, you must have permission to perform the\n s3:GetLifecycleConfiguration action. The bucket owner has this permission,\n by default. The bucket owner can grant this permission to others. For more information\n about permissions, see Permissions Related to Bucket Subresource Operations and Managing\n Access Permissions to Your Amazon S3 Resources.
\n GetBucketLifecycleConfiguration has the following special error:
Error code: NoSuchLifecycleConfiguration\n
Description: The lifecycle configuration does not exist.
\nHTTP Status Code: 404 Not Found
\nSOAP Fault Code Prefix: Client
\nThe following operations are related to\n GetBucketLifecycleConfiguration:
\n GetBucketLifecycle\n
\n\n PutBucketLifecycle\n
\nReturns the Region the bucket resides in. You set the bucket's Region using the\n LocationConstraint request parameter in a CreateBucket\n request. For more information, see CreateBucket.
To use this API operation against an access point, provide the alias of the access point in place of the bucket name.
\nTo use this API operation against an Object Lambda access point, provide the alias of the Object Lambda access point in place of the bucket name. \nIf the Object Lambda access point alias in a request is not valid, the error code InvalidAccessPointAliasError is returned. \nFor more information about InvalidAccessPointAliasError, see List of\n Error Codes.
We recommend that you use HeadBucket to return the Region\n that a bucket resides in. For backward compatibility, Amazon S3 continues to support\n GetBucketLocation.
\nThe following operations are related to GetBucketLocation:
\n GetObject\n
\n\n CreateBucket\n
\nReturns the policy of a specified bucket. If you are using an identity other than the\n root user of the Amazon Web Services account that owns the bucket, the calling identity must have the\n GetBucketPolicy permissions on the specified bucket and belong to the\n bucket owner's account in order to use this operation.
If you don't have GetBucketPolicy permissions, Amazon S3 returns a 403\n Access Denied error. If you have the correct permissions, but you're not using an\n identity that belongs to the bucket owner's account, Amazon S3 returns a 405 Method Not\n Allowed error.
To ensure that bucket owners don't inadvertently lock themselves out of their own\n buckets, the root principal in a bucket owner's Amazon Web Services account can perform the\n GetBucketPolicy, PutBucketPolicy, and\n DeleteBucketPolicy API actions, even if their bucket policy explicitly\n denies the root principal's access. Bucket owner root principals can only be blocked from performing \n these API actions by VPC endpoint policies and Amazon Web Services Organizations policies.
To use this API operation against an access point, provide the alias of the access point in place of the bucket name.
\nTo use this API operation against an Object Lambda access point, provide the alias of the Object Lambda access point in place of the bucket name. \nIf the Object Lambda access point alias in a request is not valid, the error code InvalidAccessPointAliasError is returned. \nFor more information about InvalidAccessPointAliasError, see List of\n Error Codes.
For more information about bucket policies, see Using Bucket Policies and User\n Policies.
\nThe following action is related to GetBucketPolicy:
\n GetObject\n
\nReturns the replication configuration of a bucket.
\nIt can take a while to propagate the put or delete a replication configuration to\n all Amazon S3 systems. Therefore, a get request soon after put or delete can return a wrong\n result.
\nFor information about replication configuration, see Replication in the\n Amazon S3 User Guide.
\nThis action requires permissions for the s3:GetReplicationConfiguration\n action. For more information about permissions, see Using Bucket Policies and User\n Policies.
If you include the Filter element in a replication configuration, you must\n also include the DeleteMarkerReplication and Priority elements.\n The response also returns those elements.
For information about GetBucketReplication errors, see List of\n replication-related error codes\n
The following operations are related to GetBucketReplication:
\n PutBucketReplication\n
\nReturns the request payment configuration of a bucket. To use this version of the\n operation, you must be the bucket owner. For more information, see Requester Pays\n Buckets.
\nThe following operations are related to GetBucketRequestPayment:
\n ListObjects\n
\nReturns the tag set associated with the bucket.
\nTo use this operation, you must have permission to perform the\n s3:GetBucketTagging action. By default, the bucket owner has this\n permission and can grant this permission to others.
\n GetBucketTagging has the following special error:
Error code: NoSuchTagSet\n
Description: There is no tag set associated with the bucket.
\nThe following operations are related to GetBucketTagging:
\n PutBucketTagging\n
\n\n DeleteBucketTagging\n
\nReturns the versioning state of a bucket.
\nTo retrieve the versioning state of a bucket, you must be the bucket owner.
\nThis implementation also returns the MFA Delete status of the versioning state. If the\n MFA Delete status is enabled, the bucket owner must use an authentication\n device to change the versioning state of the bucket.
The following operations are related to GetBucketVersioning:
\n GetObject\n
\n\n PutObject\n
\n\n DeleteObject\n
\nReturns the website configuration for a bucket. To host website on Amazon S3, you can\n configure a bucket as website by adding a website configuration. For more information about\n hosting websites, see Hosting Websites on Amazon S3.
\nThis GET action requires the S3:GetBucketWebsite permission. By default,\n only the bucket owner can read the bucket website configuration. However, bucket owners can\n allow other users to read the website configuration by writing a bucket policy granting\n them the S3:GetBucketWebsite permission.
The following operations are related to GetBucketWebsite:
\n DeleteBucketWebsite\n
\n\n PutBucketWebsite\n
\nReturns the access control list (ACL) of an object. To use this operation, you must have\n s3:GetObjectAcl permissions or READ_ACP access to the object.\n For more information, see Mapping of ACL permissions and access policy permissions in the Amazon S3\n User Guide\n
This action is not supported by Amazon S3 on Outposts.
\nBy default, GET returns ACL information about the current version of an object. To\n return ACL information about a different version, use the versionId subresource.
\nIf your bucket uses the bucket owner enforced setting for S3 Object Ownership,\n requests to read ACLs are still supported and return the\n bucket-owner-full-control ACL with the owner being the account that\n created the bucket. For more information, see Controlling object\n ownership and disabling ACLs in the\n Amazon S3 User Guide.
The following operations are related to GetObjectAcl:
\n GetObject\n
\n\n GetObjectAttributes\n
\n\n DeleteObject\n
\n\n PutObject\n
\nReturns the tag-set of an object. You send the GET request against the tagging\n subresource associated with the object.
\nTo use this operation, you must have permission to perform the\n s3:GetObjectTagging action. By default, the GET action returns information\n about current version of an object. For a versioned bucket, you can have multiple versions\n of an object in your bucket. To retrieve tags of any other version, use the versionId query\n parameter. You also need permission for the s3:GetObjectVersionTagging\n action.
By default, the bucket owner has this permission and can grant this permission to\n others.
\nFor information about the Amazon S3 object tagging feature, see Object Tagging.
\nThe following actions are related to GetObjectTagging:
\n DeleteObjectTagging\n
\n\n GetObjectAttributes\n
\n\n PutObjectTagging\n
\nReturns torrent files from a bucket. BitTorrent can save you bandwidth when you're\n distributing large files.
\nYou can get torrent only for objects that are less than 5 GB in size, and that are\n not encrypted using server-side encryption with a customer-provided encryption\n key.
\nTo use GET, you must have READ access to the object.
\nThis action is not supported by Amazon S3 on Outposts.
\nThe following action is related to GetObjectTorrent:
\n GetObject\n
\nThis action is useful to determine if a bucket exists and you have permission to access\n it. The action returns a 200 OK if the bucket exists and you have permission\n to access it.
If the bucket does not exist or you do not have permission to access it, the\n HEAD request returns a generic 400 Bad Request, 403\n Forbidden or 404 Not Found code. A message body is not included, so\n you cannot determine the exception beyond these error codes.
To use this operation, you must have permissions to perform the\n s3:ListBucket action. The bucket owner has this permission by default and\n can grant this permission to others. For more information about permissions, see Permissions Related to Bucket Subresource Operations and Managing\n Access Permissions to Your Amazon S3 Resources.
To use this API operation against an access point, you must provide the alias of the access point in place of the\n bucket name or specify the access point ARN. When using the access point ARN, you must direct requests to\n the access point hostname. The access point hostname takes the form\n AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com.\n When using the Amazon Web Services SDKs, you provide the ARN in place of the bucket name. For more\n information, see Using access points.
\nTo use this API operation against an Object Lambda access point, provide the alias of the Object Lambda access point in place of the bucket name. \nIf the Object Lambda access point alias in a request is not valid, the error code InvalidAccessPointAliasError is returned. \nFor more information about InvalidAccessPointAliasError, see List of\n Error Codes.
Returns a list of all buckets owned by the authenticated sender of the request. To use\n this operation, you must have the s3:ListAllMyBuckets permission.
For information about Amazon S3 buckets, see Creating, configuring, and\n working with Amazon S3 buckets.
", + "smithy.api#examples": [ + { + "title": "To list all buckets", + "documentation": "The following example returns all the buckets owned by the sender of this request.", + "output": { + "Owner": { + "DisplayName": "own-display-name", + "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31" + }, + "Buckets": [ + { + "CreationDate": "2012-02-15T21:03:02.000Z", + "Name": "examplebucket" + }, + { + "CreationDate": "2011-07-24T19:33:50.000Z", + "Name": "examplebucket2" + }, + { + "CreationDate": "2010-12-17T00:56:49.000Z", + "Name": "examplebucket3" + } + ] + } + } + ], "smithy.api#http": { "method": "GET", "uri": "/", @@ -23969,6 +24292,46 @@ }, "traits": { "smithy.api#documentation": "Returns metadata about all versions of the objects in a bucket. You can also use request\n parameters as selection criteria to return metadata about a subset of all the object\n versions.
\n To use this operation, you must have permission to perform the\n s3:ListBucketVersions action. Be aware of the name difference.
A 200 OK response can contain valid or invalid XML. Make sure to design\n your application to parse the contents of the response and handle it\n appropriately.
To use this operation, you must have READ access to the bucket.
\nThis action is not supported by Amazon S3 on Outposts.
\nThe following operations are related to ListObjectVersions:
\n ListObjectsV2\n
\n\n GetObject\n
\n\n PutObject\n
\n\n DeleteObject\n
\nSets the permissions on an existing bucket using access control lists (ACL). For more\n information, see Using ACLs. To set the ACL of a\n bucket, you must have WRITE_ACP permission.
You can use one of the following two ways to set a bucket's permissions:
\nSpecify the ACL in the request body
\nSpecify permissions using request headers
\nYou cannot specify access permission using both the body and the request\n headers.
\nDepending on your application needs, you may choose to set the ACL on a bucket using\n either the request body or the headers. For example, if you have an existing application\n that updates a bucket ACL using the request body, then you can continue to use that\n approach.
\nIf your bucket uses the bucket owner enforced setting for S3 Object Ownership, ACLs\n are disabled and no longer affect permissions. You must use policies to grant access to\n your bucket and the objects in it. Requests to set ACLs or update ACLs fail and return\n the AccessControlListNotSupported error code. Requests to read ACLs are\n still supported. For more information, see Controlling object\n ownership in the Amazon S3 User Guide.
You can set access permissions by using one of the following methods:
\nSpecify a canned ACL with the x-amz-acl request header. Amazon S3 supports\n a set of predefined ACLs, known as canned ACLs. Each canned ACL\n has a predefined set of grantees and permissions. Specify the canned ACL name as the\n value of x-amz-acl. If you use this header, you cannot use other access\n control-specific headers in your request. For more information, see Canned\n ACL.
Specify access permissions explicitly with the x-amz-grant-read,\n x-amz-grant-read-acp, x-amz-grant-write-acp, and\n x-amz-grant-full-control headers. When using these headers, you\n specify explicit access permissions and grantees (Amazon Web Services accounts or Amazon S3 groups) who\n will receive the permission. If you use these ACL-specific headers, you cannot use\n the x-amz-acl header to set a canned ACL. These parameters map to the\n set of permissions that Amazon S3 supports in an ACL. For more information, see Access Control\n List (ACL) Overview.
You specify each grantee as a type=value pair, where the type is one of the\n following:
\n\n id – if the value specified is the canonical user ID of an\n Amazon Web Services account
\n uri – if you are granting permissions to a predefined\n group
\n emailAddress – if the value specified is the email address of\n an Amazon Web Services account
Using email addresses to specify a grantee is only supported in the following Amazon Web Services Regions:
\nUS East (N. Virginia)
\nUS West (N. California)
\nUS West (Oregon)
\nAsia Pacific (Singapore)
\nAsia Pacific (Sydney)
\nAsia Pacific (Tokyo)
\nEurope (Ireland)
\nSouth America (São Paulo)
\nFor a list of all the Amazon S3 supported Regions and endpoints, see Regions and Endpoints in the Amazon Web Services General Reference.
\nFor example, the following x-amz-grant-write header grants create,\n overwrite, and delete objects permission to LogDelivery group predefined by Amazon S3 and\n two Amazon Web Services accounts identified by their email addresses.
\n x-amz-grant-write: uri=\"http://acs.amazonaws.com/groups/s3/LogDelivery\",\n id=\"111122223333\", id=\"555566667777\" \n
You can use either a canned ACL or specify access permissions explicitly. You cannot do\n both.
\nYou can specify the person (grantee) to whom you're assigning access rights (using\n request elements) in the following ways:
\nBy the person's ID:
\n\n
DisplayName is optional and ignored in the request
\nBy URI:
\n\n
By Email address:
\n\n
The grantee is resolved to the CanonicalUser and, in a response to a GET Object\n acl request, appears as the CanonicalUser.
\nUsing email addresses to specify a grantee is only supported in the following Amazon Web Services Regions:
\nUS East (N. Virginia)
\nUS West (N. California)
\nUS West (Oregon)
\nAsia Pacific (Singapore)
\nAsia Pacific (Sydney)
\nAsia Pacific (Tokyo)
\nEurope (Ireland)
\nSouth America (São Paulo)
\nFor a list of all the Amazon S3 supported Regions and endpoints, see Regions and Endpoints in the Amazon Web Services General Reference.
\nThe following operations are related to PutBucketAcl:
\n CreateBucket\n
\n\n DeleteBucket\n
\n\n GetObjectAcl\n
\nSets the cors configuration for your bucket. If the configuration exists,\n Amazon S3 replaces it.
To use this operation, you must be allowed to perform the s3:PutBucketCORS\n action. By default, the bucket owner has this permission and can grant it to others.
You set this configuration on a bucket so that the bucket can service cross-origin\n requests. For example, you might want to enable a request whose origin is\n http://www.example.com to access your Amazon S3 bucket at\n my.example.bucket.com by using the browser's XMLHttpRequest\n capability.
To enable cross-origin resource sharing (CORS) on a bucket, you add the\n cors subresource to the bucket. The cors subresource is an XML\n document in which you configure rules that identify origins and the HTTP methods that can\n be executed on your bucket. The document is limited to 64 KB in size.
When Amazon S3 receives a cross-origin request (or a pre-flight OPTIONS request) against a\n bucket, it evaluates the cors configuration on the bucket and uses the first\n CORSRule rule that matches the incoming browser request to enable a\n cross-origin request. For a rule to match, the following conditions must be met:
The request's Origin header must match AllowedOrigin\n elements.
The request method (for example, GET, PUT, HEAD, and so on) or the\n Access-Control-Request-Method header in case of a pre-flight\n OPTIONS request must be one of the AllowedMethod\n elements.
Every header specified in the Access-Control-Request-Headers request\n header of a pre-flight request must match an AllowedHeader element.\n
For more information about CORS, go to Enabling Cross-Origin Resource Sharing in\n the Amazon S3 User Guide.
\nThe following operations are related to PutBucketCors:
\n GetBucketCors\n
\n\n DeleteBucketCors\n
\n\n RESTOPTIONSobject\n
\nCreates a new lifecycle configuration for the bucket or replaces an existing lifecycle\n configuration. Keep in mind that this will overwrite an existing lifecycle configuration,\n so if you want to retain any configuration details, they must be included in the new\n lifecycle configuration. For information about lifecycle configuration, see Managing\n your storage lifecycle.
\nBucket lifecycle configuration now supports specifying a lifecycle rule using an\n object key name prefix, one or more object tags, or a combination of both. Accordingly,\n this section describes the latest API. The previous version of the API supported\n filtering based only on an object key name prefix, which is supported for backward\n compatibility. For the related API description, see PutBucketLifecycle.
\nYou specify the lifecycle configuration in your request body. The lifecycle\n configuration is specified as XML consisting of one or more rules. An Amazon S3 Lifecycle\n configuration can have up to 1,000 rules. This limit is not adjustable. Each rule consists\n of the following:
\nA filter identifying a subset of objects to which the rule applies. The filter can\n be based on a key name prefix, object tags, or a combination of both.
\nA status indicating whether the rule is in effect.
\nOne or more lifecycle transition and expiration actions that you want Amazon S3 to\n perform on the objects identified by the filter. If the state of your bucket is\n versioning-enabled or versioning-suspended, you can have many versions of the same\n object (one current version and zero or more noncurrent versions). Amazon S3 provides\n predefined actions that you can specify for current and noncurrent object\n versions.
\nFor more information, see Object Lifecycle Management\n and Lifecycle Configuration Elements.
\nBy default, all Amazon S3 resources are private, including buckets, objects, and related\n subresources (for example, lifecycle configuration and website configuration). Only the\n resource owner (that is, the Amazon Web Services account that created it) can access the resource. The\n resource owner can optionally grant access permissions to others by writing an access\n policy. For this operation, a user must get the s3:PutLifecycleConfiguration\n permission.
You can also explicitly deny permissions. An explicit deny also supersedes any other\n permissions. If you want to block users or accounts from removing or deleting objects from\n your bucket, you must deny them permissions for the following actions:
\n\n s3:DeleteObject\n
\n s3:DeleteObjectVersion\n
\n s3:PutLifecycleConfiguration\n
For more information about permissions, see Managing Access Permissions to\n Your Amazon S3 Resources.
\nThe following operations are related to PutBucketLifecycleConfiguration:
Set the logging parameters for a bucket and to specify permissions for who can view and\n modify the logging parameters. All logs are saved to buckets in the same Amazon Web Services Region as\n the source bucket. To set the logging status of a bucket, you must be the bucket\n owner.
\nThe bucket owner is automatically granted FULL_CONTROL to all logs. You use the\n Grantee request element to grant access to other people. The\n Permissions request element specifies the kind of access the grantee has to\n the logs.
If the target bucket for log delivery uses the bucket owner enforced setting for S3\n Object Ownership, you can't use the Grantee request element to grant access\n to others. Permissions can only be granted using policies. For more information, see\n Permissions for server access log delivery in the\n Amazon S3 User Guide.
You can specify the person (grantee) to whom you're assigning access rights (by using\n request elements) in the following ways:
\nBy the person's ID:
\n\n
\n DisplayName is optional and ignored in the request.
By Email address:
\n\n \n
The grantee is resolved to the CanonicalUser and, in a response to a GETObjectAcl\n request, appears as the CanonicalUser.
By URI:
\n\n
To enable logging, you use LoggingEnabled and its children request elements. To disable\n logging, you use an empty BucketLoggingStatus request element:
\n
For more information about server access logging, see Server Access Logging in the\n Amazon S3 User Guide.
\nFor more information about creating a bucket, see CreateBucket. For more\n information about returning the logging status of a bucket, see GetBucketLogging.
\nThe following operations are related to PutBucketLogging:
\n PutObject\n
\n\n DeleteBucket\n
\n\n CreateBucket\n
\n\n GetBucketLogging\n
\nEnables notifications of specified events for a bucket. For more information about event\n notifications, see Configuring Event\n Notifications.
\nUsing this API, you can replace an existing notification configuration. The\n configuration is an XML file that defines the event types that you want Amazon S3 to publish and\n the destination where you want Amazon S3 to publish an event notification when it detects an\n event of the specified type.
\nBy default, your bucket has no event notifications configured. That is, the notification\n configuration will be an empty NotificationConfiguration.
\n
\n \n
This action replaces the existing notification configuration with the configuration you\n include in the request body.
\nAfter Amazon S3 receives this request, it first verifies that any Amazon Simple Notification\n Service (Amazon SNS) or Amazon Simple Queue Service (Amazon SQS) destination exists, and\n that the bucket owner has permission to publish to it by sending a test notification. In\n the case of Lambda destinations, Amazon S3 verifies that the Lambda function permissions\n grant Amazon S3 permission to invoke the function from the Amazon S3 bucket. For more information,\n see Configuring Notifications for Amazon S3 Events.
\nYou can disable notifications by adding the empty NotificationConfiguration\n element.
\nFor more information about the number of event notification configurations that you can\n create per bucket, see Amazon S3 service quotas in Amazon Web Services\n General Reference.
\nBy default, only the bucket owner can configure notifications on a bucket. However,\n bucket owners can use a bucket policy to grant permission to other users to set this\n configuration with the required s3:PutBucketNotification permission.
The PUT notification is an atomic operation. For example, suppose your notification\n configuration includes SNS topic, SQS queue, and Lambda function configurations. When\n you send a PUT request with this configuration, Amazon S3 sends test messages to your SNS\n topic. If the message fails, the entire PUT action will fail, and Amazon S3 will not add the\n configuration to your bucket.
\nIf the configuration in the request body includes only one\n TopicConfiguration specifying only the\n s3:ReducedRedundancyLostObject event type, the response will also include\n the x-amz-sns-test-message-id header containing the message ID of the test\n notification sent to the topic.
The following action is related to\n PutBucketNotificationConfiguration:
Applies an Amazon S3 bucket policy to an Amazon S3 bucket. If you are using an identity other than\n the root user of the Amazon Web Services account that owns the bucket, the calling identity must have the\n PutBucketPolicy permissions on the specified bucket and belong to the\n bucket owner's account in order to use this operation.
If you don't have PutBucketPolicy permissions, Amazon S3 returns a 403\n Access Denied error. If you have the correct permissions, but you're not using an\n identity that belongs to the bucket owner's account, Amazon S3 returns a 405 Method Not\n Allowed error.
To ensure that bucket owners don't inadvertently lock themselves out of their own\n buckets, the root principal in a bucket owner's Amazon Web Services account can perform the\n GetBucketPolicy, PutBucketPolicy, and\n DeleteBucketPolicy API actions, even if their bucket policy explicitly\n denies the root principal's access. Bucket owner root principals can only be blocked from performing \n these API actions by VPC endpoint policies and Amazon Web Services Organizations policies.
For more information, see Bucket policy\n examples.
\nThe following operations are related to PutBucketPolicy:
\n CreateBucket\n
\n\n DeleteBucket\n
\nCreates a replication configuration or replaces an existing one. For more information,\n see Replication in the Amazon S3 User Guide.
\nSpecify the replication configuration in the request body. In the replication\n configuration, you provide the name of the destination bucket or buckets where you want\n Amazon S3 to replicate objects, the IAM role that Amazon S3 can assume to replicate objects on your\n behalf, and other relevant information.
\nA replication configuration must include at least one rule, and can contain a maximum of\n 1,000. Each rule identifies a subset of objects to replicate by filtering the objects in\n the source bucket. To choose additional subsets of objects to replicate, add a rule for\n each subset.
\nTo specify a subset of the objects in the source bucket to apply a replication rule to,\n add the Filter element as a child of the Rule element. You can filter objects based on an\n object key prefix, one or more object tags, or both. When you add the Filter element in the\n configuration, you must also add the following elements:\n DeleteMarkerReplication, Status, and\n Priority.
If you are using an earlier version of the replication configuration, Amazon S3 handles\n replication of delete markers differently. For more information, see Backward Compatibility.
\nFor information about enabling versioning on a bucket, see Using Versioning.
\nBy default, Amazon S3 doesn't replicate objects that are stored at rest using server-side\n encryption with KMS keys. To replicate Amazon Web Services KMS-encrypted objects, add the following:\n SourceSelectionCriteria, SseKmsEncryptedObjects,\n Status, EncryptionConfiguration, and\n ReplicaKmsKeyID. For information about replication configuration, see\n Replicating Objects\n Created with SSE Using KMS keys.
For information on PutBucketReplication errors, see List of\n replication-related error codes\n
To create a PutBucketReplication request, you must have\n s3:PutReplicationConfiguration permissions for the bucket.\n \n
By default, a resource owner, in this case the Amazon Web Services account that created the bucket,\n can perform this operation. The resource owner can also grant others permissions to perform\n the operation. For more information about permissions, see Specifying Permissions in a\n Policy and Managing Access Permissions to\n Your Amazon S3 Resources.
\nTo perform this operation, the user or role performing the action must have the\n iam:PassRole permission.
\nThe following operations are related to PutBucketReplication:
\n GetBucketReplication\n
\nSets the request payment configuration for a bucket. By default, the bucket owner pays\n for downloads from the bucket. This configuration parameter enables the bucket owner (only)\n to specify that the person requesting the download will be charged for the download. For\n more information, see Requester Pays\n Buckets.
\nThe following operations are related to PutBucketRequestPayment:
\n CreateBucket\n
\nSets the tags for a bucket.
\nUse tags to organize your Amazon Web Services bill to reflect your own cost structure. To do this,\n sign up to get your Amazon Web Services account bill with tag key values included. Then, to see the cost\n of combined resources, organize your billing information according to resources with the\n same tag key values. For example, you can tag several resources with a specific application\n name, and then organize your billing information to see the total cost of that application\n across several services. For more information, see Cost Allocation and\n Tagging and Using Cost Allocation in Amazon S3 Bucket\n Tags.
\nWhen this operation sets the tags for a bucket, it will overwrite any current tags\n the bucket already has. You cannot use this operation to add tags to an existing list of\n tags.
\nTo use this operation, you must have permissions to perform the\n s3:PutBucketTagging action. The bucket owner has this permission by default\n and can grant this permission to others. For more information about permissions, see Permissions Related to Bucket Subresource Operations and Managing\n Access Permissions to Your Amazon S3 Resources.
\n PutBucketTagging has the following special errors:
Error code: InvalidTagError\n
Description: The tag provided was not a valid tag. This error can occur if\n the tag did not pass input validation. For information about tag restrictions,\n see User-Defined Tag Restrictions and Amazon Web Services-Generated Cost Allocation Tag Restrictions.
\nError code: MalformedXMLError\n
Description: The XML provided does not match the schema.
\nError code: OperationAbortedError \n
Description: A conflicting conditional action is currently in progress\n against this resource. Please try again.
\nError code: InternalError\n
Description: The service was unable to apply the provided tag to the\n bucket.
\nThe following operations are related to PutBucketTagging:
\n GetBucketTagging\n
\n\n DeleteBucketTagging\n
\nSets the versioning state of an existing bucket.
\nYou can set the versioning state with one of the following values:
\n\n Enabled—Enables versioning for the objects in the\n bucket. All objects added to the bucket receive a unique version ID.
\n\n Suspended—Disables versioning for the objects in the\n bucket. All objects added to the bucket receive the version ID null.
\nIf the versioning state has never been set on a bucket, it has no versioning state; a\n GetBucketVersioning request does not return a versioning state value.
\nIn order to enable MFA Delete, you must be the bucket owner. If you are the bucket owner\n and want to enable MFA Delete in the bucket versioning configuration, you must include the\n x-amz-mfa request header and the Status and the\n MfaDelete request elements in a request to set the versioning state of the\n bucket.
If you have an object expiration lifecycle configuration in your non-versioned bucket and\n you want to maintain the same permanent delete behavior when you enable versioning, you\n must add a noncurrent expiration policy. The noncurrent expiration lifecycle configuration will\n manage the deletes of the noncurrent object versions in the version-enabled bucket. (A\n version-enabled bucket maintains one current and zero or more noncurrent object\n versions.) For more information, see Lifecycle and Versioning.
\nThe following operations are related to PutBucketVersioning:
\n CreateBucket\n
\n\n DeleteBucket\n
\n\n GetBucketVersioning\n
\nSets the configuration of the website that is specified in the website\n subresource. To configure a bucket as a website, you can add this subresource on the bucket\n with website configuration information such as the file name of the index document and any\n redirect rules. For more information, see Hosting Websites on Amazon S3.
This PUT action requires the S3:PutBucketWebsite permission. By default,\n only the bucket owner can configure the website attached to a bucket; however, bucket\n owners can allow other users to set the website configuration by writing a bucket policy\n that grants them the S3:PutBucketWebsite permission.
To redirect all website requests sent to the bucket's website endpoint, you add a\n website configuration with the following elements. Because all requests are sent to another\n website, you don't need to provide index document name for the bucket.
\n\n WebsiteConfiguration\n
\n RedirectAllRequestsTo\n
\n HostName\n
\n Protocol\n
If you want granular control over redirects, you can use the following elements to add\n routing rules that describe conditions for redirecting requests and information about the\n redirect destination. In this case, the website configuration must provide an index\n document for the bucket, because some requests might not be redirected.
\n\n WebsiteConfiguration\n
\n IndexDocument\n
\n Suffix\n
\n ErrorDocument\n
\n Key\n
\n RoutingRules\n
\n RoutingRule\n
\n Condition\n
\n HttpErrorCodeReturnedEquals\n
\n KeyPrefixEquals\n
\n Redirect\n
\n Protocol\n
\n HostName\n
\n ReplaceKeyPrefixWith\n
\n ReplaceKeyWith\n
\n HttpRedirectCode\n
Amazon S3 has a limitation of 50 routing rules per website configuration. If you require more\n than 50 routing rules, you can use object redirect. For more information, see Configuring an\n Object Redirect in the Amazon S3 User Guide.
", + "smithy.api#examples": [ + { + "title": "Set website configuration on a bucket", + "documentation": "The following example adds website configuration to a bucket.", + "input": { + "Bucket": "examplebucket", + "ContentMD5": "", + "WebsiteConfiguration": { + "IndexDocument": { + "Suffix": "index.html" + }, + "ErrorDocument": { + "Key": "error.html" + } + } + } + } + ], "smithy.api#http": { "method": "PUT", "uri": "/{Bucket}?website", @@ -27508,6 +28093,24 @@ "requestAlgorithmMember": "ChecksumAlgorithm" }, "smithy.api#documentation": "Adds an object to a bucket. You must have WRITE permissions on a bucket to add an object\n to it.
\nAmazon S3 never adds partial objects; if you receive a success response, Amazon S3 added the\n entire object to the bucket. You cannot use PutObject to only update a\n single piece of metadata for an existing object. You must put the entire object with\n updated metadata if you want to update some values.
Amazon S3 is a distributed system. If it receives multiple write requests for the same object\n simultaneously, it overwrites all but the last object written. To prevent objects from\n being deleted or overwritten, you can use Amazon S3 Object\n Lock.
\nTo ensure that data is not corrupted traversing the network, use the\n Content-MD5 header. When you use this header, Amazon S3 checks the object\n against the provided MD5 value and, if they do not match, returns an error. Additionally,\n you can calculate the MD5 while putting an object to Amazon S3 and compare the returned ETag to\n the calculated MD5 value.
To successfully complete the PutObject request, you must have the\n s3:PutObject in your IAM permissions.
To successfully change the objects acl of your PutObject request,\n you must have the s3:PutObjectAcl in your IAM permissions.
To successfully set the tag-set with your PutObject request, you\n must have the s3:PutObjectTagging in your IAM permissions.
The Content-MD5 header is required for any request to upload an\n object with a retention period configured using Amazon S3 Object Lock. For more\n information about Amazon S3 Object Lock, see Amazon S3 Object Lock\n Overview in the Amazon S3 User Guide.
You have four mutually exclusive options to protect data using server-side encryption in\n Amazon S3, depending on how you choose to manage the encryption keys. Specifically, the\n encryption key options are Amazon S3 managed keys (SSE-S3), Amazon Web Services KMS keys (SSE-KMS or\n DSSE-KMS), and customer-provided keys (SSE-C). Amazon S3 encrypts data with server-side\n encryption by using Amazon S3 managed keys (SSE-S3) by default. You can optionally tell Amazon S3 to\n encrypt data at rest by using server-side encryption with other key options. For more\n information, see Using Server-Side\n Encryption.
\nWhen adding a new object, you can use headers to grant ACL-based permissions to\n individual Amazon Web Services accounts or to predefined groups defined by Amazon S3. These permissions are\n then added to the ACL on the object. By default, all objects are private. Only the owner\n has full access control. For more information, see Access Control List (ACL) Overview\n and Managing\n ACLs Using the REST API.
\nIf the bucket that you're uploading objects to uses the bucket owner enforced setting\n for S3 Object Ownership, ACLs are disabled and no longer affect permissions. Buckets that\n use this setting only accept PUT requests that don't specify an ACL or PUT requests that\n specify bucket owner full control ACLs, such as the bucket-owner-full-control\n canned ACL or an equivalent form of this ACL expressed in the XML format. PUT requests that\n contain other ACLs (for example, custom grants to certain Amazon Web Services accounts) fail and return a\n 400 error with the error code AccessControlListNotSupported.\n For more information, see Controlling ownership of\n objects and disabling ACLs in the Amazon S3 User Guide.
If your bucket uses the bucket owner enforced setting for Object Ownership, all\n objects written to the bucket by any account will be owned by the bucket owner.
\nBy default, Amazon S3 uses the STANDARD Storage Class to store newly created objects. The\n STANDARD storage class provides high durability and high availability. Depending on\n performance needs, you can specify a different Storage Class. Amazon S3 on Outposts only uses\n the OUTPOSTS Storage Class. For more information, see Storage Classes in the\n Amazon S3 User Guide.
\nIf you enable versioning for a bucket, Amazon S3 automatically generates a unique version ID\n for the object being stored. Amazon S3 returns this ID in the response. When you enable\n versioning for a bucket, if Amazon S3 receives multiple write requests for the same object\n simultaneously, it stores all of the objects. For more information about versioning, see\n Adding Objects to\n Versioning-Enabled Buckets. For information about returning the versioning state\n of a bucket, see GetBucketVersioning.
\nFor more information about related Amazon S3 APIs, see the following:
\n\n CopyObject\n
\n\n DeleteObject\n
\nUses the acl subresource to set the access control list (ACL) permissions\n for a new or existing object in an S3 bucket. You must have WRITE_ACP\n permission to set the ACL of an object. For more information, see What\n permissions can I grant? in the Amazon S3 User Guide.
This action is not supported by Amazon S3 on Outposts.
\nDepending on your application needs, you can choose to set the ACL on an object using\n either the request body or the headers. For example, if you have an existing application\n that updates a bucket ACL using the request body, you can continue to use that approach.\n For more information, see Access Control List (ACL) Overview\n in the Amazon S3 User Guide.
\nIf your bucket uses the bucket owner enforced setting for S3 Object Ownership, ACLs\n are disabled and no longer affect permissions. You must use policies to grant access to\n your bucket and the objects in it. Requests to set ACLs or update ACLs fail and return\n the AccessControlListNotSupported error code. Requests to read ACLs are\n still supported. For more information, see Controlling object\n ownership in the Amazon S3 User Guide.
You can set access permissions using one of the following methods:
\nSpecify a canned ACL with the x-amz-acl request header. Amazon S3 supports\n a set of predefined ACLs, known as canned ACLs. Each canned ACL has a predefined set\n of grantees and permissions. Specify the canned ACL name as the value of\n x-amz-acl. If you use this header, you cannot use other access\n control-specific headers in your request. For more information, see Canned\n ACL.
Specify access permissions explicitly with the x-amz-grant-read,\n x-amz-grant-read-acp, x-amz-grant-write-acp, and\n x-amz-grant-full-control headers. When using these headers, you\n specify explicit access permissions and grantees (Amazon Web Services accounts or Amazon S3 groups) who\n will receive the permission. If you use these ACL-specific headers, you cannot use\n x-amz-acl header to set a canned ACL. These parameters map to the set\n of permissions that Amazon S3 supports in an ACL. For more information, see Access Control\n List (ACL) Overview.
You specify each grantee as a type=value pair, where the type is one of the\n following:
\n\n id – if the value specified is the canonical user ID of an\n Amazon Web Services account
\n uri – if you are granting permissions to a predefined\n group
\n emailAddress – if the value specified is the email address of\n an Amazon Web Services account
Using email addresses to specify a grantee is only supported in the following Amazon Web Services Regions:
\nUS East (N. Virginia)
\nUS West (N. California)
\nUS West (Oregon)
\nAsia Pacific (Singapore)
\nAsia Pacific (Sydney)
\nAsia Pacific (Tokyo)
\nEurope (Ireland)
\nSouth America (São Paulo)
\nFor a list of all the Amazon S3 supported Regions and endpoints, see Regions and Endpoints in the Amazon Web Services General Reference.
\nFor example, the following x-amz-grant-read header grants list\n objects permission to the two Amazon Web Services accounts identified by their email\n addresses.
\n x-amz-grant-read: emailAddress=\"xyz@amazon.com\",\n emailAddress=\"abc@amazon.com\" \n
You can use either a canned ACL or specify access permissions explicitly. You cannot do\n both.
\nYou can specify the person (grantee) to whom you're assigning access rights (using\n request elements) in the following ways:
\nBy the person's ID:
\n\n
DisplayName is optional and ignored in the request.
\nBy URI:
\n\n
By Email address:
\n\n
The grantee is resolved to the CanonicalUser and, in a response to a GET Object\n acl request, appears as the CanonicalUser.
\nUsing email addresses to specify a grantee is only supported in the following Amazon Web Services Regions:
\nUS East (N. Virginia)
\nUS West (N. California)
\nUS West (Oregon)
\nAsia Pacific (Singapore)
\nAsia Pacific (Sydney)
\nAsia Pacific (Tokyo)
\nEurope (Ireland)
\nSouth America (São Paulo)
\nFor a list of all the Amazon S3 supported Regions and endpoints, see Regions and Endpoints in the Amazon Web Services General Reference.
\nThe ACL of an object is set at the object version level. By default, PUT sets the ACL of\n the current version of an object. To set the ACL of a different version, use the\n versionId subresource.
The following operations are related to PutObjectAcl:
\n CopyObject\n
\n\n GetObject\n
\nSets the supplied tag-set to an object that already exists in a bucket.
\nA tag is a key-value pair. You can associate tags with an object by sending a PUT\n request against the tagging subresource that is associated with the object. You can\n retrieve tags by sending a GET request. For more information, see GetObjectTagging.
\nFor tagging-related restrictions related to characters and encodings, see Tag\n Restrictions. Note that Amazon S3 limits the maximum number of tags to 10 tags per\n object.
\nTo use this operation, you must have permission to perform the\n s3:PutObjectTagging action. By default, the bucket owner has this\n permission and can grant this permission to others.
To put tags of any other version, use the versionId query parameter. You\n also need permission for the s3:PutObjectVersionTagging action.
For information about the Amazon S3 object tagging feature, see Object Tagging.
\n\n PutObjectTagging has the following special errors:
\n Code: InvalidTagError \n
\n\n Cause: The tag provided was not a valid tag. This error can occur\n if the tag did not pass input validation. For more information, see Object\n Tagging.\n
\n\n Code: MalformedXMLError \n
\n\n Cause: The XML provided does not match the schema.\n
\n\n Code: OperationAbortedError \n
\n\n Cause: A conflicting conditional action is currently in progress\n against this resource. Please try again.\n
\n\n Code: InternalError\n
\n\n Cause: The service was unable to apply the provided tag to the\n object.\n
\nThe following operations are related to PutObjectTagging:
\n GetObjectTagging\n
\n\n DeleteObjectTagging\n
\nRestores an archived copy of an object back into Amazon S3
\nThis action is not supported by Amazon S3 on Outposts.
\nThis action performs the following types of requests:
\n\n select - Perform a select query on an archived object
\n restore an archive - Restore an archived object
For more information about the S3 structure in the request body, see the\n following:
\n PutObject\n
\n\n Managing Access with ACLs in the\n Amazon S3 User Guide\n
\n\n Protecting Data Using\n Server-Side Encryption in the\n Amazon S3 User Guide\n
\nDefine the SQL expression for the SELECT type of restoration for your\n query in the request body's SelectParameters structure. You can use\n expressions like the following examples.
The following expression returns all records from the specified\n object.
\n\n SELECT * FROM Object\n
Assuming that you are not using any headers for data stored in the object,\n you can specify columns with positional headers.
\n\n SELECT s._1, s._2 FROM Object s WHERE s._3 > 100\n
If you have headers and you set the fileHeaderInfo in the\n CSV structure in the request body to USE, you can\n specify headers in the query. (If you set the fileHeaderInfo field\n to IGNORE, the first row is skipped for the query.) You cannot mix\n ordinal positions with header column names.
\n SELECT s.Id, s.FirstName, s.SSN FROM S3Object s\n
When making a select request, you can also do the following:
\nTo expedite your queries, specify the Expedited tier. For more\n information about tiers, see \"Restoring Archives,\" later in this topic.
Specify details about the data serialization format of both the input object that\n is being queried and the serialization of the CSV-encoded query results.
\nThe following are additional important facts about the select feature:
\nThe output results are new Amazon S3 objects. Unlike archive retrievals, they are\n stored until explicitly deleted-manually or through a lifecycle configuration.
\nYou can issue more than one select request on the same Amazon S3 object. Amazon S3 doesn't\n duplicate requests, so avoid issuing duplicate requests.
\n Amazon S3 accepts a select request even if the object has already been restored. A\n select request doesn’t return error response 409.
To use this operation, you must have permissions to perform the\n s3:RestoreObject action. The bucket owner has this permission by default\n and can grant this permission to others. For more information about permissions, see Permissions Related to Bucket Subresource Operations and Managing\n Access Permissions to Your Amazon S3 Resources in the\n Amazon S3 User Guide.
Objects that you archive to the S3 Glacier Flexible Retrieval Flexible Retrieval or\n S3 Glacier Deep Archive storage class, and S3 Intelligent-Tiering Archive or\n S3 Intelligent-Tiering Deep Archive tiers, are not accessible in real time. For objects in the\n S3 Glacier Flexible Retrieval Flexible Retrieval or S3 Glacier Deep Archive storage\n classes, you must first initiate a restore request, and then wait until a temporary copy of\n the object is available. If you want a permanent copy of the object, create a copy of it in\n the Amazon S3 Standard storage class in your S3 bucket. To access an archived object, you must\n restore the object for the duration (number of days) that you specify. For objects in the\n Archive Access or Deep Archive Access tiers of S3 Intelligent-Tiering, you must first\n initiate a restore request, and then wait until the object is moved into the Frequent\n Access tier.
\nTo restore a specific object version, you can provide a version ID. If you don't provide\n a version ID, Amazon S3 restores the current version.
\nWhen restoring an archived object, you can specify one of the following data access tier\n options in the Tier element of the request body:
\n Expedited - Expedited retrievals allow you to quickly access your\n data stored in the S3 Glacier Flexible Retrieval Flexible Retrieval storage class or\n S3 Intelligent-Tiering Archive tier when occasional urgent requests for restoring archives\n are required. For all but the largest archived objects (250 MB+), data accessed using\n Expedited retrievals is typically made available within 1–5 minutes. Provisioned\n capacity ensures that retrieval capacity for Expedited retrievals is available when\n you need it. Expedited retrievals and provisioned capacity are not available for\n objects stored in the S3 Glacier Deep Archive storage class or\n S3 Intelligent-Tiering Deep Archive tier.
\n Standard - Standard retrievals allow you to access any of your\n archived objects within several hours. This is the default option for retrieval\n requests that do not specify the retrieval option. Standard retrievals typically\n finish within 3–5 hours for objects stored in the S3 Glacier Flexible Retrieval Flexible\n Retrieval storage class or S3 Intelligent-Tiering Archive tier. They typically finish within\n 12 hours for objects stored in the S3 Glacier Deep Archive storage class or\n S3 Intelligent-Tiering Deep Archive tier. Standard retrievals are free for objects stored in\n S3 Intelligent-Tiering.
\n Bulk - Bulk retrievals free for objects stored in the S3 Glacier\n Flexible Retrieval and S3 Intelligent-Tiering storage classes, enabling you to\n retrieve large amounts, even petabytes, of data at no cost. Bulk retrievals typically\n finish within 5–12 hours for objects stored in the S3 Glacier Flexible Retrieval\n Flexible Retrieval storage class or S3 Intelligent-Tiering Archive tier. Bulk retrievals are\n also the lowest-cost retrieval option when restoring objects from\n S3 Glacier Deep Archive. They typically finish within 48 hours for objects\n stored in the S3 Glacier Deep Archive storage class or S3 Intelligent-Tiering Deep Archive\n tier.
For more information about archive retrieval options and provisioned capacity for\n Expedited data access, see Restoring Archived Objects in\n the Amazon S3 User Guide.
You can use Amazon S3 restore speed upgrade to change the restore speed to a faster speed\n while it is in progress. For more information, see Upgrading the speed of an in-progress restore in the\n Amazon S3 User Guide.
\nTo get the status of object restoration, you can send a HEAD request.\n Operations return the x-amz-restore header, which provides information about\n the restoration status, in the response. You can use Amazon S3 event notifications to notify you\n when a restore is initiated or completed. For more information, see Configuring Amazon S3\n Event Notifications in the Amazon S3 User Guide.
After restoring an archived object, you can update the restoration period by reissuing\n the request with a new period. Amazon S3 updates the restoration period relative to the current\n time and charges only for the request-there are no data transfer charges. You cannot\n update the restoration period when Amazon S3 is actively processing your current restore request\n for the object.
\nIf your bucket has a lifecycle configuration with a rule that includes an expiration\n action, the object expiration overrides the life span that you specify in a restore\n request. For example, if you restore an object copy for 10 days, but the object is\n scheduled to expire in 3 days, Amazon S3 deletes the object in 3 days. For more information\n about lifecycle configuration, see PutBucketLifecycleConfiguration and Object Lifecycle Management\n in Amazon S3 User Guide.
\nA successful action returns either the 200 OK or 202 Accepted\n status code.
If the object is not previously restored, then Amazon S3 returns 202\n Accepted in the response.
If the object is previously restored, Amazon S3 returns 200 OK in the\n response.
Special errors:
\n\n Code: RestoreAlreadyInProgress\n
\n\n Cause: Object restore is already in progress. (This error does not\n apply to SELECT type requests.)\n
\n\n HTTP Status Code: 409 Conflict\n
\n\n SOAP Fault Code Prefix: Client\n
\n\n Code: GlacierExpeditedRetrievalNotAvailable\n
\n\n Cause: expedited retrievals are currently not available. Try again\n later. (Returned if there is insufficient capacity to process the Expedited\n request. This error applies only to Expedited retrievals and not to\n S3 Standard or Bulk retrievals.)\n
\n\n HTTP Status Code: 503\n
\n\n SOAP Fault Code Prefix: N/A\n
\nThe following operations are related to RestoreObject:
The alias of the Object Lambda Access Point.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#CreateAccessPointRequest": { @@ -7131,6 +6791,9 @@ "smithy.api#documentation": "The name or alias of the access point.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#CreateBucket": { @@ -7276,6 +6939,9 @@ "smithy.api#documentation": "The Amazon Resource Name (ARN) of the bucket.
\nFor using this parameter with Amazon S3 on Outposts with the REST API, you must specify the name and the x-amz-outpost-id as well.
\nFor using this parameter with S3 on Outposts with the Amazon Web Services SDK and CLI, you must specify the ARN of the bucket accessed in the format arn:aws:s3-outposts:. For example, to access the bucket reports through Outpost my-outpost owned by account 123456789012 in Region us-west-2, use the URL encoding of arn:aws:s3-outposts:us-west-2:123456789012:outpost/my-outpost/bucket/reports. The value must be URL encoded.
The ID for this job. Amazon S3 generates this ID automatically and returns it after a\n successful Create Job request.
The request token associated with the request. You can use this token with DescribeMultiRegionAccessPointOperation to determine the status of asynchronous\n requests.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#CreationDate": { @@ -8098,7 +7770,10 @@ }, "com.amazonaws.s3control#DeleteJobTaggingResult": { "type": "structure", - "members": {} + "members": {}, + "traits": { + "smithy.api#output": {} + } }, "com.amazonaws.s3control#DeleteMarkerReplication": { "type": "structure", @@ -8217,6 +7892,9 @@ "smithy.api#documentation": "The request token associated with the request. You can use this token with DescribeMultiRegionAccessPointOperation to determine the status of asynchronous\n requests.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#DeletePublicAccessBlock": { @@ -8372,7 +8050,10 @@ }, "com.amazonaws.s3control#DeleteStorageLensConfigurationTaggingResult": { "type": "structure", - "members": {} + "members": {}, + "traits": { + "smithy.api#output": {} + } }, "com.amazonaws.s3control#DescribeJob": { "type": "operation", @@ -8450,6 +8131,9 @@ "smithy.api#documentation": "Contains the configuration parameters and status for the job specified in the\n Describe Job request.
A container element containing the details of the asynchronous operation.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#Destination": { @@ -8851,6 +8538,9 @@ "smithy.api#documentation": "Object Lambda Access Point configuration document.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetAccessPointForObjectLambda": { @@ -8933,6 +8623,9 @@ "smithy.api#documentation": "The alias of the Object Lambda Access Point.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetAccessPointPolicy": { @@ -9022,6 +8715,9 @@ "smithy.api#documentation": "Object Lambda Access Point resource policy document.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetAccessPointPolicyRequest": { @@ -9064,6 +8760,9 @@ "smithy.api#documentation": "The access point policy associated with the specified access point.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetAccessPointPolicyStatus": { @@ -9150,6 +8849,9 @@ "PolicyStatus": { "target": "com.amazonaws.s3control#PolicyStatus" } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetAccessPointPolicyStatusRequest": { @@ -9192,6 +8894,9 @@ "smithy.api#documentation": "Indicates the current policy status of the specified access point.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetAccessPointRequest": { @@ -9285,6 +8990,9 @@ "smithy.api#documentation": "The Amazon Web Services account ID associated with the S3 bucket associated with this access point.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetBucket": { @@ -9377,6 +9085,9 @@ "smithy.api#documentation": "Container for the lifecycle rule of the Outposts bucket.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetBucketPolicy": { @@ -9444,6 +9155,9 @@ "smithy.api#documentation": "The policy of the Outposts bucket.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetBucketReplication": { @@ -9511,6 +9225,9 @@ "smithy.api#documentation": "A container for one or more replication rules. A replication configuration must have at least one rule and you can add up to 100 rules. The maximum size of a\n replication configuration is 128 KB.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetBucketRequest": { @@ -9566,6 +9283,9 @@ "smithy.api#documentation": "The creation date of the Outposts bucket.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetBucketTagging": { @@ -9634,6 +9354,9 @@ "smithy.api#required": {} } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetBucketVersioning": { @@ -9708,6 +9431,9 @@ "smithy.api#xmlName": "MfaDelete" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetJobTagging": { @@ -9783,6 +9509,9 @@ "smithy.api#documentation": "The set of tags associated with the S3 Batch Operations job.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetMultiRegionAccessPoint": { @@ -9874,6 +9603,9 @@ "smithy.api#documentation": "The policy associated with the specified Multi-Region Access Point.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetMultiRegionAccessPointPolicyStatus": { @@ -9936,6 +9668,9 @@ "Established": { "target": "com.amazonaws.s3control#PolicyStatus" } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetMultiRegionAccessPointRequest": { @@ -9975,6 +9710,9 @@ "smithy.api#documentation": "A container element containing the details of the requested Multi-Region Access Point.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GetMultiRegionAccessPointRoutes": { @@ -10046,6 +9784,9 @@ "smithy.api#documentation": "The different routes that make up the route configuration. Active routes return a value\n of 100, and passive routes return a value of 0.
The tags of S3 Storage Lens configuration requested.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#GrantFullControl": { @@ -11420,6 +11167,9 @@ "smithy.api#documentation": "If the list has more access points than can be returned in one call to this API, this field\n contains a continuation token that you can provide in subsequent calls to this API to\n retrieve additional access points.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#ListAccessPointsRequest": { @@ -11482,6 +11232,9 @@ "smithy.api#documentation": "If the specified bucket has more access points than can be returned in one call to this API,\n this field contains a continuation token that you can provide in subsequent calls to this\n API to retrieve additional access points.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#ListJobs": { @@ -11582,6 +11335,9 @@ "smithy.api#documentation": "The list of current jobs and jobs that have ended within the last 30 days.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#ListMultiRegionAccessPoints": { @@ -11665,6 +11421,9 @@ "smithy.api#documentation": "If the specified bucket has more Multi-Region Access Points than can be returned in one call to this\n action, this field contains a continuation token. You can use this token tin subsequent\n calls to this action to retrieve additional Multi-Region Access Points.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#ListRegionalBuckets": { @@ -11757,6 +11516,9 @@ "smithy.api#documentation": "\n NextToken is sent when isTruncated is true, which means there\n are more buckets that can be listed. The next list requests to Amazon S3 can be continued with\n this NextToken. NextToken is obfuscated and is not a real\n key.
The request token associated with the request. You can use this token with DescribeMultiRegionAccessPointOperation to determine the status of asynchronous\n requests.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#PutPublicAccessBlock": { @@ -13731,7 +13502,10 @@ }, "com.amazonaws.s3control#PutStorageLensConfigurationTaggingResult": { "type": "structure", - "members": {} + "members": {}, + "traits": { + "smithy.api#output": {} + } }, "com.amazonaws.s3control#Region": { "type": "structure", @@ -15639,7 +15413,10 @@ }, "com.amazonaws.s3control#SubmitMultiRegionAccessPointRoutesResult": { "type": "structure", - "members": {} + "members": {}, + "traits": { + "smithy.api#output": {} + } }, "com.amazonaws.s3control#SuspendedCause": { "type": "string", @@ -15889,6 +15666,9 @@ "smithy.api#required": {} } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#UpdateJobStatus": { @@ -15997,6 +15777,9 @@ "smithy.api#documentation": "The reason that the specified job's status was updated.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.s3control#VersioningConfiguration": { diff --git a/aws/sdk/aws-models/sso.json b/aws/sdk/aws-models/sso.json index 4f48553e765a20ce5ae79e96ae2866677d84d0dd..9804c2167318f2ca56a55185356f331eb580447a 100644 --- a/aws/sdk/aws-models/sso.json +++ b/aws/sdk/aws-models/sso.json @@ -154,6 +154,9 @@ "smithy.api#required": {} } } + }, + "traits": { + "smithy.api#input": {} } }, "com.amazonaws.sso#GetRoleCredentialsResponse": { @@ -165,6 +168,9 @@ "smithy.api#documentation": "The credentials for the role that is assigned to the user.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.sso#InvalidRequestException": { @@ -252,6 +258,9 @@ "smithy.api#required": {} } } + }, + "traits": { + "smithy.api#input": {} } }, "com.amazonaws.sso#ListAccountRolesResponse": { @@ -269,6 +278,9 @@ "smithy.api#documentation": "A paginated response with the list of roles and the next token if more results are\n available.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.sso#ListAccounts": { @@ -335,6 +347,9 @@ "smithy.api#required": {} } } + }, + "traits": { + "smithy.api#input": {} } }, "com.amazonaws.sso#ListAccountsResponse": { @@ -352,6 +367,9 @@ "smithy.api#documentation": "A paginated response with the list of account information and the next token if more\n results are available.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.sso#Logout": { @@ -375,7 +393,7 @@ ], "traits": { "smithy.api#auth": [], - "smithy.api#documentation": "Removes the locally stored SSO tokens from the client-side cache and sends an API call to\n the IAM Identity Center service to invalidate the corresponding server-side IAM Identity Center sign in\n session.
\n\nIf a user uses IAM Identity Center to access the AWS CLI, the user’s IAM Identity Center sign in session is\n used to obtain an IAM session, as specified in the corresponding IAM Identity Center permission set.\n More specifically, IAM Identity Center assumes an IAM role in the target account on behalf of the user,\n and the corresponding temporary AWS credentials are returned to the client.
\n\nAfter user logout, any existing IAM role sessions that were created by using IAM Identity Center\n permission sets continue based on the duration configured in the permission set.\n For more information, see User\n authentications in the IAM Identity Center User\n Guide.
\nRemoves the locally stored SSO tokens from the client-side cache and sends an API call to\n the IAM Identity Center service to invalidate the corresponding server-side IAM Identity Center sign in\n session.
\nIf a user uses IAM Identity Center to access the AWS CLI, the user’s IAM Identity Center sign in session is\n used to obtain an IAM session, as specified in the corresponding IAM Identity Center permission set.\n More specifically, IAM Identity Center assumes an IAM role in the target account on behalf of the user,\n and the corresponding temporary AWS credentials are returned to the client.
\nAfter user logout, any existing IAM role sessions that were created by using IAM Identity Center\n permission sets continue based on the duration configured in the permission set.\n For more information, see User\n authentications in the IAM Identity Center User\n Guide.
\nAWS IAM Identity Center (successor to AWS Single Sign-On) Portal is a web service that makes it easy for you to assign user access to\n IAM Identity Center resources such as the AWS access portal. Users can get AWS account applications and roles\n assigned to them and get federated into the application.
\n\nAlthough AWS Single Sign-On was renamed, the sso and\n identitystore API namespaces will continue to retain their original name for\n backward compatibility purposes. For more information, see IAM Identity Center rename.
This reference guide describes the IAM Identity Center Portal operations that you can call\n programatically and includes detailed information on data types and errors.
\n\nAWS provides SDKs that consist of libraries and sample code for various programming\n languages and platforms, such as Java, Ruby, .Net, iOS, or Android. The SDKs provide a\n convenient way to create programmatic access to IAM Identity Center and other AWS services. For more\n information about the AWS SDKs, including how to download and install them, see Tools for Amazon Web Services.
\nAWS IAM Identity Center (successor to AWS Single Sign-On) Portal is a web service that makes it easy for you to assign user access to\n IAM Identity Center resources such as the AWS access portal. Users can get AWS account applications and roles\n assigned to them and get federated into the application.
\nAlthough AWS Single Sign-On was renamed, the sso and\n identitystore API namespaces will continue to retain their original name for\n backward compatibility purposes. For more information, see IAM Identity Center rename.
This reference guide describes the IAM Identity Center Portal operations that you can call\n programatically and includes detailed information on data types and errors.
\nAWS provides SDKs that consist of libraries and sample code for various programming\n languages and platforms, such as Java, Ruby, .Net, iOS, or Android. The SDKs provide a\n convenient way to create programmatic access to IAM Identity Center and other AWS services. For more\n information about the AWS SDKs, including how to download and install them, see Tools for Amazon Web Services.
\nReturns a set of temporary security credentials that you can use to access Amazon Web Services\n resources. These temporary credentials consist of an access key ID, a secret access key,\n and a security token. Typically, you use AssumeRole within your account or for\n cross-account access. For a comparison of AssumeRole with other API operations\n that produce temporary credentials, see Requesting Temporary Security\n Credentials and Comparing the\n Amazon Web Services STS API operations in the IAM User Guide.
\n Permissions\n
\nThe temporary security credentials created by AssumeRole can be used to\n make API calls to any Amazon Web Services service with the following exception: You cannot call the\n Amazon Web Services STS GetFederationToken or GetSessionToken API\n operations.
(Optional) You can pass inline or managed session policies to\n this operation. You can pass a single JSON policy document to use as an inline session\n policy. You can also specify up to 10 managed policy Amazon Resource Names (ARNs) to use as\n managed session policies. The plaintext that you use for both inline and managed session\n policies can't exceed 2,048 characters. Passing policies to this operation returns new \n temporary credentials. The resulting session's permissions are the intersection of the \n role's identity-based policy and the session policies. You can use the role's temporary \n credentials in subsequent Amazon Web Services API calls to access resources in the account that owns \n the role. You cannot use session policies to grant more permissions than those allowed \n by the identity-based policy of the role that is being assumed. For more information, see\n Session\n Policies in the IAM User Guide.
\nWhen you create a role, you create two policies: a role trust policy that specifies\n who can assume the role, and a permissions policy that specifies\n what can be done with the role. You specify the trusted principal\n that is allowed to assume the role in the role trust policy.
\nTo assume a role from a different account, your Amazon Web Services account must be trusted by the\n role. The trust relationship is defined in the role's trust policy when the role is\n created. That trust policy states which accounts are allowed to delegate that access to\n users in the account.
\nA user who wants to access a role in a different account must also have permissions that\n are delegated from the account administrator. The administrator must attach a policy that\n allows the user to call AssumeRole for the ARN of the role in the other\n account.
To allow a user to assume a role in the same account, you can do either of the\n following:
\nAttach a policy to the user that allows the user to call AssumeRole\n (as long as the role's trust policy trusts the account).
Add the user as a principal directly in the role's trust policy.
\nYou can do either because the role’s trust policy acts as an IAM resource-based\n policy. When a resource-based policy grants access to a principal in the same account, no\n additional identity-based policy is required. For more information about trust policies and\n resource-based policies, see IAM Policies in the\n IAM User Guide.
\n\n Tags\n
\n(Optional) You can pass tag key-value pairs to your session. These tags are called\n session tags. For more information about session tags, see Passing Session Tags in STS in the\n IAM User Guide.
\nAn administrator must grant you the permissions necessary to pass session tags. The\n administrator can also create granular permissions to allow you to pass only specific\n session tags. For more information, see Tutorial: Using Tags\n for Attribute-Based Access Control in the\n IAM User Guide.
\nYou can set the session tags as transitive. Transitive tags persist during role\n chaining. For more information, see Chaining Roles\n with Session Tags in the IAM User Guide.
\n\n Using MFA with AssumeRole\n
\n(Optional) You can include multi-factor authentication (MFA) information when you call\n AssumeRole. This is useful for cross-account scenarios to ensure that the\n user that assumes the role has been authenticated with an Amazon Web Services MFA device. In that\n scenario, the trust policy of the role being assumed includes a condition that tests for\n MFA authentication. If the caller does not include valid MFA information, the request to\n assume the role is denied. The condition in a trust policy that tests for MFA\n authentication might look like the following example.
\n \"Condition\": {\"Bool\": {\"aws:MultiFactorAuthPresent\": true}}\n
For more information, see Configuring MFA-Protected API Access\n in the IAM User Guide guide.
\nTo use MFA with AssumeRole, you pass values for the\n SerialNumber and TokenCode parameters. The\n SerialNumber value identifies the user's hardware or virtual MFA device.\n The TokenCode is the time-based one-time password (TOTP) that the MFA device\n produces.
Returns a set of temporary security credentials that you can use to access Amazon Web Services\n resources. These temporary credentials consist of an access key ID, a secret access key,\n and a security token. Typically, you use AssumeRole within your account or for\n cross-account access. For a comparison of AssumeRole with other API operations\n that produce temporary credentials, see Requesting Temporary Security\n Credentials and Comparing the\n Amazon Web Services STS API operations in the IAM User Guide.
\n Permissions\n
\nThe temporary security credentials created by AssumeRole can be used to\n make API calls to any Amazon Web Services service with the following exception: You cannot call the\n Amazon Web Services STS GetFederationToken or GetSessionToken API\n operations.
(Optional) You can pass inline or managed session policies to\n this operation. You can pass a single JSON policy document to use as an inline session\n policy. You can also specify up to 10 managed policy Amazon Resource Names (ARNs) to use as\n managed session policies. The plaintext that you use for both inline and managed session\n policies can't exceed 2,048 characters. Passing policies to this operation returns new \n temporary credentials. The resulting session's permissions are the intersection of the \n role's identity-based policy and the session policies. You can use the role's temporary \n credentials in subsequent Amazon Web Services API calls to access resources in the account that owns \n the role. You cannot use session policies to grant more permissions than those allowed \n by the identity-based policy of the role that is being assumed. For more information, see\n Session\n Policies in the IAM User Guide.
\nWhen you create a role, you create two policies: a role trust policy that specifies\n who can assume the role, and a permissions policy that specifies\n what can be done with the role. You specify the trusted principal\n that is allowed to assume the role in the role trust policy.
\nTo assume a role from a different account, your Amazon Web Services account must be trusted by the\n role. The trust relationship is defined in the role's trust policy when the role is\n created. That trust policy states which accounts are allowed to delegate that access to\n users in the account.
\nA user who wants to access a role in a different account must also have permissions that\n are delegated from the account administrator. The administrator must attach a policy that\n allows the user to call AssumeRole for the ARN of the role in the other\n account.
To allow a user to assume a role in the same account, you can do either of the\n following:
\nAttach a policy to the user that allows the user to call AssumeRole\n (as long as the role's trust policy trusts the account).
Add the user as a principal directly in the role's trust policy.
\nYou can do either because the role’s trust policy acts as an IAM resource-based\n policy. When a resource-based policy grants access to a principal in the same account, no\n additional identity-based policy is required. For more information about trust policies and\n resource-based policies, see IAM Policies in the\n IAM User Guide.
\n\n Tags\n
\n(Optional) You can pass tag key-value pairs to your session. These tags are called\n session tags. For more information about session tags, see Passing Session Tags in STS in the\n IAM User Guide.
\nAn administrator must grant you the permissions necessary to pass session tags. The\n administrator can also create granular permissions to allow you to pass only specific\n session tags. For more information, see Tutorial: Using Tags\n for Attribute-Based Access Control in the\n IAM User Guide.
\nYou can set the session tags as transitive. Transitive tags persist during role\n chaining. For more information, see Chaining Roles\n with Session Tags in the IAM User Guide.
\n\n Using MFA with AssumeRole\n
\n(Optional) You can include multi-factor authentication (MFA) information when you call\n AssumeRole. This is useful for cross-account scenarios to ensure that the\n user that assumes the role has been authenticated with an Amazon Web Services MFA device. In that\n scenario, the trust policy of the role being assumed includes a condition that tests for\n MFA authentication. If the caller does not include valid MFA information, the request to\n assume the role is denied. The condition in a trust policy that tests for MFA\n authentication might look like the following example.
\n \"Condition\": {\"Bool\": {\"aws:MultiFactorAuthPresent\": true}}\n
For more information, see Configuring MFA-Protected API Access\n in the IAM User Guide guide.
\nTo use MFA with AssumeRole, you pass values for the\n SerialNumber and TokenCode parameters. The\n SerialNumber value identifies the user's hardware or virtual MFA device.\n The TokenCode is the time-based one-time password (TOTP) that the MFA device\n produces.
Returns a set of temporary security credentials for users who have been authenticated\n via a SAML authentication response. This operation provides a mechanism for tying an\n enterprise identity store or directory to role-based Amazon Web Services access without user-specific\n credentials or configuration. For a comparison of AssumeRoleWithSAML with the\n other API operations that produce temporary credentials, see Requesting Temporary Security\n Credentials and Comparing the\n Amazon Web Services STS API operations in the IAM User Guide.
The temporary security credentials returned by this operation consist of an access key\n ID, a secret access key, and a security token. Applications can use these temporary\n security credentials to sign calls to Amazon Web Services services.
\n\n Session Duration\n
\nBy default, the temporary security credentials created by\n AssumeRoleWithSAML last for one hour. However, you can use the optional\n DurationSeconds parameter to specify the duration of your session. Your\n role session lasts for the duration that you specify, or until the time specified in the\n SAML authentication response's SessionNotOnOrAfter value, whichever is\n shorter. You can provide a DurationSeconds value from 900 seconds (15 minutes)\n up to the maximum session duration setting for the role. This setting can have a value from\n 1 hour to 12 hours. To learn how to view the maximum value for your role, see View the\n Maximum Session Duration Setting for a Role in the\n IAM User Guide. The maximum session duration limit applies when\n you use the AssumeRole* API operations or the assume-role* CLI\n commands. However the limit does not apply when you use those operations to create a\n console URL. For more information, see Using IAM Roles in the\n IAM User Guide.
\n Role chaining limits your CLI or Amazon Web Services API role\n session to a maximum of one hour. When you use the AssumeRole API operation\n to assume a role, you can specify the duration of your role session with the\n DurationSeconds parameter. You can specify a parameter value of up to\n 43200 seconds (12 hours), depending on the maximum session duration setting for your\n role. However, if you assume a role using role chaining and provide a\n DurationSeconds parameter value greater than one hour, the operation\n fails.
\n Permissions\n
\nThe temporary security credentials created by AssumeRoleWithSAML can be\n used to make API calls to any Amazon Web Services service with the following exception: you cannot call\n the STS GetFederationToken or GetSessionToken API\n operations.
(Optional) You can pass inline or managed session policies to\n this operation. You can pass a single JSON policy document to use as an inline session\n policy. You can also specify up to 10 managed policy Amazon Resource Names (ARNs) to use as\n managed session policies. The plaintext that you use for both inline and managed session\n policies can't exceed 2,048 characters. Passing policies to this operation returns new \n temporary credentials. The resulting session's permissions are the intersection of the \n role's identity-based policy and the session policies. You can use the role's temporary \n credentials in subsequent Amazon Web Services API calls to access resources in the account that owns \n the role. You cannot use session policies to grant more permissions than those allowed \n by the identity-based policy of the role that is being assumed. For more information, see\n Session\n Policies in the IAM User Guide.
\nCalling AssumeRoleWithSAML does not require the use of Amazon Web Services security\n credentials. The identity of the caller is validated by using keys in the metadata document\n that is uploaded for the SAML provider entity for your identity provider.
Calling AssumeRoleWithSAML can result in an entry in your CloudTrail logs.\n The entry includes the value in the NameID element of the SAML assertion.\n We recommend that you use a NameIDType that is not associated with any\n personally identifiable information (PII). For example, you could instead use the\n persistent identifier\n (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent).
\n Tags\n
\n(Optional) You can configure your IdP to pass attributes into your SAML assertion as\n session tags. Each session tag consists of a key name and an associated value. For more\n information about session tags, see Passing Session Tags in STS in the\n IAM User Guide.
\nYou can pass up to 50 session tags. The plaintext session tag keys can’t exceed 128\n characters and the values can’t exceed 256 characters. For these and additional limits, see\n IAM\n and STS Character Limits in the IAM User Guide.
\nAn Amazon Web Services conversion compresses the passed inline session policy, managed policy ARNs,\n and session tags into a packed binary format that has a separate limit. Your request can\n fail for this limit even if your plaintext meets the other requirements. The\n PackedPolicySize response element indicates by percentage how close the\n policies and tags for your request are to the upper size limit.
You can pass a session tag with the same key as a tag that is attached to the role. When\n you do, session tags override the role's tags with the same key.
\nAn administrator must grant you the permissions necessary to pass session tags. The\n administrator can also create granular permissions to allow you to pass only specific\n session tags. For more information, see Tutorial: Using Tags\n for Attribute-Based Access Control in the\n IAM User Guide.
\nYou can set the session tags as transitive. Transitive tags persist during role\n chaining. For more information, see Chaining Roles\n with Session Tags in the IAM User Guide.
\n\n SAML Configuration\n
\nBefore your application can call AssumeRoleWithSAML, you must configure\n your SAML identity provider (IdP) to issue the claims required by Amazon Web Services. Additionally, you\n must use Identity and Access Management (IAM) to create a SAML provider entity in your Amazon Web Services account that\n represents your identity provider. You must also create an IAM role that specifies this\n SAML provider in its trust policy.
For more information, see the following resources:
\n\n About\n SAML 2.0-based Federation in the IAM User Guide.\n
\n\n Creating SAML Identity Providers in the\n IAM User Guide.
\n\n Configuring\n a Relying Party and Claims in the IAM User Guide.\n
\n\n Creating a Role for SAML 2.0 Federation in the\n IAM User Guide.
\nReturns a set of temporary security credentials for users who have been authenticated\n via a SAML authentication response. This operation provides a mechanism for tying an\n enterprise identity store or directory to role-based Amazon Web Services access without user-specific\n credentials or configuration. For a comparison of AssumeRoleWithSAML with the\n other API operations that produce temporary credentials, see Requesting Temporary Security\n Credentials and Comparing the\n Amazon Web Services STS API operations in the IAM User Guide.
The temporary security credentials returned by this operation consist of an access key\n ID, a secret access key, and a security token. Applications can use these temporary\n security credentials to sign calls to Amazon Web Services services.
\n\n Session Duration\n
\nBy default, the temporary security credentials created by\n AssumeRoleWithSAML last for one hour. However, you can use the optional\n DurationSeconds parameter to specify the duration of your session. Your\n role session lasts for the duration that you specify, or until the time specified in the\n SAML authentication response's SessionNotOnOrAfter value, whichever is\n shorter. You can provide a DurationSeconds value from 900 seconds (15 minutes)\n up to the maximum session duration setting for the role. This setting can have a value from\n 1 hour to 12 hours. To learn how to view the maximum value for your role, see View the\n Maximum Session Duration Setting for a Role in the\n IAM User Guide. The maximum session duration limit applies when\n you use the AssumeRole* API operations or the assume-role* CLI\n commands. However the limit does not apply when you use those operations to create a\n console URL. For more information, see Using IAM Roles in the\n IAM User Guide.
\n Role chaining limits your CLI or Amazon Web Services API role\n session to a maximum of one hour. When you use the AssumeRole API operation\n to assume a role, you can specify the duration of your role session with the\n DurationSeconds parameter. You can specify a parameter value of up to\n 43200 seconds (12 hours), depending on the maximum session duration setting for your\n role. However, if you assume a role using role chaining and provide a\n DurationSeconds parameter value greater than one hour, the operation\n fails.
\n Permissions\n
\nThe temporary security credentials created by AssumeRoleWithSAML can be\n used to make API calls to any Amazon Web Services service with the following exception: you cannot call\n the STS GetFederationToken or GetSessionToken API\n operations.
(Optional) You can pass inline or managed session policies to\n this operation. You can pass a single JSON policy document to use as an inline session\n policy. You can also specify up to 10 managed policy Amazon Resource Names (ARNs) to use as\n managed session policies. The plaintext that you use for both inline and managed session\n policies can't exceed 2,048 characters. Passing policies to this operation returns new \n temporary credentials. The resulting session's permissions are the intersection of the \n role's identity-based policy and the session policies. You can use the role's temporary \n credentials in subsequent Amazon Web Services API calls to access resources in the account that owns \n the role. You cannot use session policies to grant more permissions than those allowed \n by the identity-based policy of the role that is being assumed. For more information, see\n Session\n Policies in the IAM User Guide.
\nCalling AssumeRoleWithSAML does not require the use of Amazon Web Services security\n credentials. The identity of the caller is validated by using keys in the metadata document\n that is uploaded for the SAML provider entity for your identity provider.
Calling AssumeRoleWithSAML can result in an entry in your CloudTrail logs.\n The entry includes the value in the NameID element of the SAML assertion.\n We recommend that you use a NameIDType that is not associated with any\n personally identifiable information (PII). For example, you could instead use the\n persistent identifier\n (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent).
\n Tags\n
\n(Optional) You can configure your IdP to pass attributes into your SAML assertion as\n session tags. Each session tag consists of a key name and an associated value. For more\n information about session tags, see Passing Session Tags in STS in the\n IAM User Guide.
\nYou can pass up to 50 session tags. The plaintext session tag keys can’t exceed 128\n characters and the values can’t exceed 256 characters. For these and additional limits, see\n IAM\n and STS Character Limits in the IAM User Guide.
\nAn Amazon Web Services conversion compresses the passed inline session policy, managed policy ARNs,\n and session tags into a packed binary format that has a separate limit. Your request can\n fail for this limit even if your plaintext meets the other requirements. The\n PackedPolicySize response element indicates by percentage how close the\n policies and tags for your request are to the upper size limit.
You can pass a session tag with the same key as a tag that is attached to the role. When\n you do, session tags override the role's tags with the same key.
\nAn administrator must grant you the permissions necessary to pass session tags. The\n administrator can also create granular permissions to allow you to pass only specific\n session tags. For more information, see Tutorial: Using Tags\n for Attribute-Based Access Control in the\n IAM User Guide.
\nYou can set the session tags as transitive. Transitive tags persist during role\n chaining. For more information, see Chaining Roles\n with Session Tags in the IAM User Guide.
\n\n SAML Configuration\n
\nBefore your application can call AssumeRoleWithSAML, you must configure\n your SAML identity provider (IdP) to issue the claims required by Amazon Web Services. Additionally, you\n must use Identity and Access Management (IAM) to create a SAML provider entity in your Amazon Web Services account that\n represents your identity provider. You must also create an IAM role that specifies this\n SAML provider in its trust policy.
For more information, see the following resources:
\n\n About\n SAML 2.0-based Federation in the IAM User Guide.\n
\n\n Creating SAML Identity Providers in the\n IAM User Guide.
\n\n Configuring\n a Relying Party and Claims in the IAM User Guide.\n
\n\n Creating a Role for SAML 2.0 Federation in the\n IAM User Guide.
\nReturns a set of temporary security credentials for users who have been authenticated in\n a mobile or web application with a web identity provider. Example providers include the\n OAuth 2.0 providers Login with Amazon and Facebook, or any OpenID Connect-compatible\n identity provider such as Google or Amazon Cognito federated identities.
\nFor mobile applications, we recommend that you use Amazon Cognito. You can use Amazon Cognito with the\n Amazon Web Services SDK for iOS Developer Guide and the Amazon Web Services SDK for Android Developer Guide to uniquely\n identify a user. You can also supply the user with a consistent identity throughout the\n lifetime of an application.
\nTo learn more about Amazon Cognito, see Amazon Cognito identity\n pools in Amazon Cognito Developer Guide.
\nCalling AssumeRoleWithWebIdentity does not require the use of Amazon Web Services\n security credentials. Therefore, you can distribute an application (for example, on mobile\n devices) that requests temporary security credentials without including long-term Amazon Web Services\n credentials in the application. You also don't need to deploy server-based proxy services\n that use long-term Amazon Web Services credentials. Instead, the identity of the caller is validated by\n using a token from the web identity provider. For a comparison of\n AssumeRoleWithWebIdentity with the other API operations that produce\n temporary credentials, see Requesting Temporary Security\n Credentials and Comparing the\n Amazon Web Services STS API operations in the IAM User Guide.
The temporary security credentials returned by this API consist of an access key ID, a\n secret access key, and a security token. Applications can use these temporary security\n credentials to sign calls to Amazon Web Services service API operations.
\n\n Session Duration\n
\nBy default, the temporary security credentials created by\n AssumeRoleWithWebIdentity last for one hour. However, you can use the\n optional DurationSeconds parameter to specify the duration of your session.\n You can provide a value from 900 seconds (15 minutes) up to the maximum session duration\n setting for the role. This setting can have a value from 1 hour to 12 hours. To learn how\n to view the maximum value for your role, see View the\n Maximum Session Duration Setting for a Role in the\n IAM User Guide. The maximum session duration limit applies when\n you use the AssumeRole* API operations or the assume-role* CLI\n commands. However the limit does not apply when you use those operations to create a\n console URL. For more information, see Using IAM Roles in the\n IAM User Guide.
\n Permissions\n
\nThe temporary security credentials created by AssumeRoleWithWebIdentity can\n be used to make API calls to any Amazon Web Services service with the following exception: you cannot\n call the STS GetFederationToken or GetSessionToken API\n operations.
(Optional) You can pass inline or managed session policies to\n this operation. You can pass a single JSON policy document to use as an inline session\n policy. You can also specify up to 10 managed policy Amazon Resource Names (ARNs) to use as\n managed session policies. The plaintext that you use for both inline and managed session\n policies can't exceed 2,048 characters. Passing policies to this operation returns new \n temporary credentials. The resulting session's permissions are the intersection of the \n role's identity-based policy and the session policies. You can use the role's temporary \n credentials in subsequent Amazon Web Services API calls to access resources in the account that owns \n the role. You cannot use session policies to grant more permissions than those allowed \n by the identity-based policy of the role that is being assumed. For more information, see\n Session\n Policies in the IAM User Guide.
\n\n Tags\n
\n(Optional) You can configure your IdP to pass attributes into your web identity token as\n session tags. Each session tag consists of a key name and an associated value. For more\n information about session tags, see Passing Session Tags in STS in the\n IAM User Guide.
\nYou can pass up to 50 session tags. The plaintext session tag keys can’t exceed 128\n characters and the values can’t exceed 256 characters. For these and additional limits, see\n IAM\n and STS Character Limits in the IAM User Guide.
\nAn Amazon Web Services conversion compresses the passed inline session policy, managed policy ARNs,\n and session tags into a packed binary format that has a separate limit. Your request can\n fail for this limit even if your plaintext meets the other requirements. The\n PackedPolicySize response element indicates by percentage how close the\n policies and tags for your request are to the upper size limit.
You can pass a session tag with the same key as a tag that is attached to the role. When\n you do, the session tag overrides the role tag with the same key.
\nAn administrator must grant you the permissions necessary to pass session tags. The\n administrator can also create granular permissions to allow you to pass only specific\n session tags. For more information, see Tutorial: Using Tags\n for Attribute-Based Access Control in the\n IAM User Guide.
\nYou can set the session tags as transitive. Transitive tags persist during role\n chaining. For more information, see Chaining Roles\n with Session Tags in the IAM User Guide.
\n\n Identities\n
\nBefore your application can call AssumeRoleWithWebIdentity, you must have\n an identity token from a supported identity provider and create a role that the application\n can assume. The role that your application assumes must trust the identity provider that is\n associated with the identity token. In other words, the identity provider must be specified\n in the role's trust policy.
Calling AssumeRoleWithWebIdentity can result in an entry in your\n CloudTrail logs. The entry includes the Subject of\n the provided web identity token. We recommend that you avoid using any personally\n identifiable information (PII) in this field. For example, you could instead use a GUID\n or a pairwise identifier, as suggested\n in the OIDC specification.
For more information about how to use web identity federation and the\n AssumeRoleWithWebIdentity API, see the following resources:
\n Using Web Identity Federation API Operations for Mobile Apps and Federation Through a Web-based Identity Provider.
\n\n Web Identity Federation Playground. Walk through the process of\n authenticating through Login with Amazon, Facebook, or Google, getting temporary\n security credentials, and then using those credentials to make a request to Amazon Web Services.\n
\n\n Amazon Web Services SDK for iOS Developer Guide and Amazon Web Services SDK for Android Developer Guide. These toolkits\n contain sample apps that show how to invoke the identity providers. The toolkits then\n show how to use the information from these providers to get and use temporary\n security credentials.
\n\n Web Identity\n Federation with Mobile Applications. This article discusses web identity\n federation and shows an example of how to use web identity federation to get access\n to content in Amazon S3.
\nReturns a set of temporary security credentials for users who have been authenticated in\n a mobile or web application with a web identity provider. Example providers include the\n OAuth 2.0 providers Login with Amazon and Facebook, or any OpenID Connect-compatible\n identity provider such as Google or Amazon Cognito federated identities.
\nFor mobile applications, we recommend that you use Amazon Cognito. You can use Amazon Cognito with the\n Amazon Web Services SDK for iOS Developer Guide and the Amazon Web Services SDK for Android Developer Guide to uniquely\n identify a user. You can also supply the user with a consistent identity throughout the\n lifetime of an application.
\nTo learn more about Amazon Cognito, see Amazon Cognito identity\n pools in Amazon Cognito Developer Guide.
\nCalling AssumeRoleWithWebIdentity does not require the use of Amazon Web Services\n security credentials. Therefore, you can distribute an application (for example, on mobile\n devices) that requests temporary security credentials without including long-term Amazon Web Services\n credentials in the application. You also don't need to deploy server-based proxy services\n that use long-term Amazon Web Services credentials. Instead, the identity of the caller is validated by\n using a token from the web identity provider. For a comparison of\n AssumeRoleWithWebIdentity with the other API operations that produce\n temporary credentials, see Requesting Temporary Security\n Credentials and Comparing the\n Amazon Web Services STS API operations in the IAM User Guide.
The temporary security credentials returned by this API consist of an access key ID, a\n secret access key, and a security token. Applications can use these temporary security\n credentials to sign calls to Amazon Web Services service API operations.
\n\n Session Duration\n
\nBy default, the temporary security credentials created by\n AssumeRoleWithWebIdentity last for one hour. However, you can use the\n optional DurationSeconds parameter to specify the duration of your session.\n You can provide a value from 900 seconds (15 minutes) up to the maximum session duration\n setting for the role. This setting can have a value from 1 hour to 12 hours. To learn how\n to view the maximum value for your role, see View the\n Maximum Session Duration Setting for a Role in the\n IAM User Guide. The maximum session duration limit applies when\n you use the AssumeRole* API operations or the assume-role* CLI\n commands. However the limit does not apply when you use those operations to create a\n console URL. For more information, see Using IAM Roles in the\n IAM User Guide.
\n Permissions\n
\nThe temporary security credentials created by AssumeRoleWithWebIdentity can\n be used to make API calls to any Amazon Web Services service with the following exception: you cannot\n call the STS GetFederationToken or GetSessionToken API\n operations.
(Optional) You can pass inline or managed session policies to\n this operation. You can pass a single JSON policy document to use as an inline session\n policy. You can also specify up to 10 managed policy Amazon Resource Names (ARNs) to use as\n managed session policies. The plaintext that you use for both inline and managed session\n policies can't exceed 2,048 characters. Passing policies to this operation returns new \n temporary credentials. The resulting session's permissions are the intersection of the \n role's identity-based policy and the session policies. You can use the role's temporary \n credentials in subsequent Amazon Web Services API calls to access resources in the account that owns \n the role. You cannot use session policies to grant more permissions than those allowed \n by the identity-based policy of the role that is being assumed. For more information, see\n Session\n Policies in the IAM User Guide.
\n\n Tags\n
\n(Optional) You can configure your IdP to pass attributes into your web identity token as\n session tags. Each session tag consists of a key name and an associated value. For more\n information about session tags, see Passing Session Tags in STS in the\n IAM User Guide.
\nYou can pass up to 50 session tags. The plaintext session tag keys can’t exceed 128\n characters and the values can’t exceed 256 characters. For these and additional limits, see\n IAM\n and STS Character Limits in the IAM User Guide.
\nAn Amazon Web Services conversion compresses the passed inline session policy, managed policy ARNs,\n and session tags into a packed binary format that has a separate limit. Your request can\n fail for this limit even if your plaintext meets the other requirements. The\n PackedPolicySize response element indicates by percentage how close the\n policies and tags for your request are to the upper size limit.
You can pass a session tag with the same key as a tag that is attached to the role. When\n you do, the session tag overrides the role tag with the same key.
\nAn administrator must grant you the permissions necessary to pass session tags. The\n administrator can also create granular permissions to allow you to pass only specific\n session tags. For more information, see Tutorial: Using Tags\n for Attribute-Based Access Control in the\n IAM User Guide.
\nYou can set the session tags as transitive. Transitive tags persist during role\n chaining. For more information, see Chaining Roles\n with Session Tags in the IAM User Guide.
\n\n Identities\n
\nBefore your application can call AssumeRoleWithWebIdentity, you must have\n an identity token from a supported identity provider and create a role that the application\n can assume. The role that your application assumes must trust the identity provider that is\n associated with the identity token. In other words, the identity provider must be specified\n in the role's trust policy.
Calling AssumeRoleWithWebIdentity can result in an entry in your\n CloudTrail logs. The entry includes the Subject of\n the provided web identity token. We recommend that you avoid using any personally\n identifiable information (PII) in this field. For example, you could instead use a GUID\n or a pairwise identifier, as suggested\n in the OIDC specification.
For more information about how to use web identity federation and the\n AssumeRoleWithWebIdentity API, see the following resources:
\n Using Web Identity Federation API Operations for Mobile Apps and Federation Through a Web-based Identity Provider.
\n\n Web Identity Federation Playground. Walk through the process of\n authenticating through Login with Amazon, Facebook, or Google, getting temporary\n security credentials, and then using those credentials to make a request to Amazon Web Services.\n
\n\n Amazon Web Services SDK for iOS Developer Guide and Amazon Web Services SDK for Android Developer Guide. These toolkits\n contain sample apps that show how to invoke the identity providers. The toolkits then\n show how to use the information from these providers to get and use temporary\n security credentials.
\n\n Web Identity\n Federation with Mobile Applications. This article discusses web identity\n federation and shows an example of how to use web identity federation to get access\n to content in Amazon S3.
\nDecodes additional information about the authorization status of a request from an\n encoded message returned in response to an Amazon Web Services request.
\nFor example, if a user is not authorized to perform an operation that he or she has\n requested, the request returns a Client.UnauthorizedOperation response (an\n HTTP 403 response). Some Amazon Web Services operations additionally return an encoded message that can\n provide details about this authorization failure.
Only certain Amazon Web Services operations return an encoded authorization message. The\n documentation for an individual operation indicates whether that operation returns an\n encoded message in addition to returning an HTTP code.
\nThe message is encoded because the details of the authorization status can contain\n privileged information that the user who requested the operation should not see. To decode\n an authorization status message, a user must be granted permissions through an IAM policy to\n request the DecodeAuthorizationMessage\n (sts:DecodeAuthorizationMessage) action.
The decoded message includes the following type of information:
\nWhether the request was denied due to an explicit deny or due to the absence of an\n explicit allow. For more information, see Determining Whether a Request is Allowed or Denied in the\n IAM User Guide.
\nThe principal who made the request.
\nThe requested action.
\nThe requested resource.
\nThe values of condition keys in the context of the user's request.
\nDecodes additional information about the authorization status of a request from an\n encoded message returned in response to an Amazon Web Services request.
\nFor example, if a user is not authorized to perform an operation that he or she has\n requested, the request returns a Client.UnauthorizedOperation response (an\n HTTP 403 response). Some Amazon Web Services operations additionally return an encoded message that can\n provide details about this authorization failure.
Only certain Amazon Web Services operations return an encoded authorization message. The\n documentation for an individual operation indicates whether that operation returns an\n encoded message in addition to returning an HTTP code.
\nThe message is encoded because the details of the authorization status can contain\n privileged information that the user who requested the operation should not see. To decode\n an authorization status message, a user must be granted permissions through an IAM policy to\n request the DecodeAuthorizationMessage\n (sts:DecodeAuthorizationMessage) action.
The decoded message includes the following type of information:
\nWhether the request was denied due to an explicit deny or due to the absence of an\n explicit allow. For more information, see Determining Whether a Request is Allowed or Denied in the\n IAM User Guide.
\nThe principal who made the request.
\nThe requested action.
\nThe requested resource.
\nThe values of condition keys in the context of the user's request.
\nReturns details about the IAM user or role whose credentials are used to\n call the operation.
\nNo permissions are required to perform this operation. If an administrator attaches a\n policy to your identity that explicitly denies access to the\n sts:GetCallerIdentity action, you can still perform this operation.\n Permissions are not required because the same information is returned when access is\n denied. To view an example response, see I Am Not Authorized to Perform: iam:DeleteVirtualMFADevice in the\n IAM User Guide.
Returns details about the IAM user or role whose credentials are used to\n call the operation.
\nNo permissions are required to perform this operation. If an administrator attaches a\n policy to your identity that explicitly denies access to the\n sts:GetCallerIdentity action, you can still perform this operation.\n Permissions are not required because the same information is returned when access is\n denied. To view an example response, see I Am Not Authorized to Perform: iam:DeleteVirtualMFADevice in the\n IAM User Guide.
Returns a set of temporary security credentials (consisting of an access key ID, a\n secret access key, and a security token) for a user. A typical use is in a proxy\n application that gets temporary security credentials on behalf of distributed applications\n inside a corporate network.
\nYou must call the GetFederationToken operation using the long-term security\n credentials of an IAM user. As a result, this call is appropriate in\n contexts where those credentials can be safeguarded, usually in a server-based application.\n For a comparison of GetFederationToken with the other API operations that\n produce temporary credentials, see Requesting Temporary Security\n Credentials and Comparing the\n Amazon Web Services STS API operations in the IAM User Guide.
Although it is possible to call GetFederationToken using the security\n credentials of an Amazon Web Services account root user rather than an IAM user that you\n create for the purpose of a proxy application, we do not recommend it. For more\n information, see Safeguard your root user credentials and don't use them for everyday tasks in the\n IAM User Guide.
You can create a mobile-based or browser-based app that can authenticate users using\n a web identity provider like Login with Amazon, Facebook, Google, or an OpenID\n Connect-compatible identity provider. In this case, we recommend that you use Amazon Cognito or\n AssumeRoleWithWebIdentity. For more information, see Federation Through a Web-based Identity Provider in the\n IAM User Guide.
\n Session duration\n
\nThe temporary credentials are valid for the specified duration, from 900 seconds (15\n minutes) up to a maximum of 129,600 seconds (36 hours). The default session duration is\n 43,200 seconds (12 hours). Temporary credentials obtained by using the root user\n credentials have a maximum duration of 3,600 seconds (1 hour).
\n\n Permissions\n
\nYou can use the temporary credentials created by GetFederationToken in any\n Amazon Web Services service with the following exceptions:
You cannot call any IAM operations using the CLI or the Amazon Web Services API. This\n limitation does not apply to console sessions.
\nYou cannot call any STS operations except GetCallerIdentity.
You can use temporary credentials for single sign-on (SSO) to the console.
\nYou must pass an inline or managed session policy to\n this operation. You can pass a single JSON policy document to use as an inline session\n policy. You can also specify up to 10 managed policy Amazon Resource Names (ARNs) to use as\n managed session policies. The plaintext that you use for both inline and managed session\n policies can't exceed 2,048 characters.
\nThough the session policy parameters are optional, if you do not pass a policy, then the\n resulting federated user session has no permissions. When you pass session policies, the\n session permissions are the intersection of the IAM user policies and the\n session policies that you pass. This gives you a way to further restrict the permissions\n for a federated user. You cannot use session policies to grant more permissions than those\n that are defined in the permissions policy of the IAM user. For more\n information, see Session Policies in\n the IAM User Guide. For information about using\n GetFederationToken to create temporary security credentials, see GetFederationToken—Federation Through a Custom Identity Broker.
You can use the credentials to access a resource that has a resource-based policy. If\n that policy specifically references the federated user session in the\n Principal element of the policy, the session has the permissions allowed by\n the policy. These permissions are granted in addition to the permissions granted by the\n session policies.
\n Tags\n
\n(Optional) You can pass tag key-value pairs to your session. These are called session\n tags. For more information about session tags, see Passing Session Tags in STS in the\n IAM User Guide.
\nYou can create a mobile-based or browser-based app that can authenticate users using\n a web identity provider like Login with Amazon, Facebook, Google, or an OpenID\n Connect-compatible identity provider. In this case, we recommend that you use Amazon Cognito or\n AssumeRoleWithWebIdentity. For more information, see Federation Through a Web-based Identity Provider in the\n IAM User Guide.
An administrator must grant you the permissions necessary to pass session tags. The\n administrator can also create granular permissions to allow you to pass only specific\n session tags. For more information, see Tutorial: Using Tags\n for Attribute-Based Access Control in the\n IAM User Guide.
\nTag key–value pairs are not case sensitive, but case is preserved. This means that you\n cannot have separate Department and department tag keys. Assume\n that the user that you are federating has the\n Department=Marketing tag and you pass the\n department=engineering session tag. Department\n and department are not saved as separate tags, and the session tag passed in\n the request takes precedence over the user tag.
Returns a set of temporary security credentials (consisting of an access key ID, a\n secret access key, and a security token) for a user. A typical use is in a proxy\n application that gets temporary security credentials on behalf of distributed applications\n inside a corporate network.
\nYou must call the GetFederationToken operation using the long-term security\n credentials of an IAM user. As a result, this call is appropriate in\n contexts where those credentials can be safeguarded, usually in a server-based application.\n For a comparison of GetFederationToken with the other API operations that\n produce temporary credentials, see Requesting Temporary Security\n Credentials and Comparing the\n Amazon Web Services STS API operations in the IAM User Guide.
Although it is possible to call GetFederationToken using the security\n credentials of an Amazon Web Services account root user rather than an IAM user that you\n create for the purpose of a proxy application, we do not recommend it. For more\n information, see Safeguard your root user credentials and don't use them for everyday tasks in the\n IAM User Guide.
You can create a mobile-based or browser-based app that can authenticate users using\n a web identity provider like Login with Amazon, Facebook, Google, or an OpenID\n Connect-compatible identity provider. In this case, we recommend that you use Amazon Cognito or\n AssumeRoleWithWebIdentity. For more information, see Federation Through a Web-based Identity Provider in the\n IAM User Guide.
\n Session duration\n
\nThe temporary credentials are valid for the specified duration, from 900 seconds (15\n minutes) up to a maximum of 129,600 seconds (36 hours). The default session duration is\n 43,200 seconds (12 hours). Temporary credentials obtained by using the root user\n credentials have a maximum duration of 3,600 seconds (1 hour).
\n\n Permissions\n
\nYou can use the temporary credentials created by GetFederationToken in any\n Amazon Web Services service with the following exceptions:
You cannot call any IAM operations using the CLI or the Amazon Web Services API. This\n limitation does not apply to console sessions.
\nYou cannot call any STS operations except GetCallerIdentity.
You can use temporary credentials for single sign-on (SSO) to the console.
\nYou must pass an inline or managed session policy to\n this operation. You can pass a single JSON policy document to use as an inline session\n policy. You can also specify up to 10 managed policy Amazon Resource Names (ARNs) to use as\n managed session policies. The plaintext that you use for both inline and managed session\n policies can't exceed 2,048 characters.
\nThough the session policy parameters are optional, if you do not pass a policy, then the\n resulting federated user session has no permissions. When you pass session policies, the\n session permissions are the intersection of the IAM user policies and the\n session policies that you pass. This gives you a way to further restrict the permissions\n for a federated user. You cannot use session policies to grant more permissions than those\n that are defined in the permissions policy of the IAM user. For more\n information, see Session Policies in\n the IAM User Guide. For information about using\n GetFederationToken to create temporary security credentials, see GetFederationToken—Federation Through a Custom Identity Broker.
You can use the credentials to access a resource that has a resource-based policy. If\n that policy specifically references the federated user session in the\n Principal element of the policy, the session has the permissions allowed by\n the policy. These permissions are granted in addition to the permissions granted by the\n session policies.
\n Tags\n
\n(Optional) You can pass tag key-value pairs to your session. These are called session\n tags. For more information about session tags, see Passing Session Tags in STS in the\n IAM User Guide.
\nYou can create a mobile-based or browser-based app that can authenticate users using\n a web identity provider like Login with Amazon, Facebook, Google, or an OpenID\n Connect-compatible identity provider. In this case, we recommend that you use Amazon Cognito or\n AssumeRoleWithWebIdentity. For more information, see Federation Through a Web-based Identity Provider in the\n IAM User Guide.
An administrator must grant you the permissions necessary to pass session tags. The\n administrator can also create granular permissions to allow you to pass only specific\n session tags. For more information, see Tutorial: Using Tags\n for Attribute-Based Access Control in the\n IAM User Guide.
\nTag key–value pairs are not case sensitive, but case is preserved. This means that you\n cannot have separate Department and department tag keys. Assume\n that the user that you are federating has the\n Department=Marketing tag and you pass the\n department=engineering session tag. Department\n and department are not saved as separate tags, and the session tag passed in\n the request takes precedence over the user tag.
Returns a set of temporary credentials for an Amazon Web Services account or IAM user.\n The credentials consist of an access key ID, a secret access key, and a security token.\n Typically, you use GetSessionToken if you want to use MFA to protect\n programmatic calls to specific Amazon Web Services API operations like Amazon EC2\n StopInstances.
MFA-enabled IAM users must call GetSessionToken and submit\n an MFA code that is associated with their MFA device. Using the temporary security\n credentials that the call returns, IAM users can then make programmatic\n calls to API operations that require MFA authentication. An incorrect MFA code causes the\n API to return an access denied error. For a comparison of GetSessionToken with\n the other API operations that produce temporary credentials, see Requesting\n Temporary Security Credentials and Comparing the\n Amazon Web Services STS API operations in the IAM User Guide.
No permissions are required for users to perform this operation. The purpose of the\n sts:GetSessionToken operation is to authenticate the user using MFA. You\n cannot use policies to control authentication operations. For more information, see\n Permissions for GetSessionToken in the\n IAM User Guide.
\n Session Duration\n
\nThe GetSessionToken operation must be called by using the long-term Amazon Web Services\n security credentials of an IAM user. Credentials that are created by IAM users are valid for the duration that you specify. This duration can range\n from 900 seconds (15 minutes) up to a maximum of 129,600 seconds (36 hours), with a default\n of 43,200 seconds (12 hours). Credentials based on account credentials can range from 900\n seconds (15 minutes) up to 3,600 seconds (1 hour), with a default of 1 hour.
\n Permissions\n
\nThe temporary security credentials created by GetSessionToken can be used\n to make API calls to any Amazon Web Services service with the following exceptions:
You cannot call any IAM API operations unless MFA authentication information is\n included in the request.
\nYou cannot call any STS API except\n AssumeRole or GetCallerIdentity.
The credentials that GetSessionToken returns are based on permissions\n associated with the IAM user whose credentials were used to call the\n operation. The temporary credentials have the same permissions as the IAM user.
Although it is possible to call GetSessionToken using the security\n credentials of an Amazon Web Services account root user rather than an IAM user, we do\n not recommend it. If GetSessionToken is called using root user\n credentials, the temporary credentials have root user permissions. For more\n information, see Safeguard your root user credentials and don't use them for everyday tasks in the\n IAM User Guide\n
For more information about using GetSessionToken to create temporary\n credentials, see Temporary\n Credentials for Users in Untrusted Environments in the\n IAM User Guide.
Returns a set of temporary credentials for an Amazon Web Services account or IAM user.\n The credentials consist of an access key ID, a secret access key, and a security token.\n Typically, you use GetSessionToken if you want to use MFA to protect\n programmatic calls to specific Amazon Web Services API operations like Amazon EC2\n StopInstances.
MFA-enabled IAM users must call GetSessionToken and submit\n an MFA code that is associated with their MFA device. Using the temporary security\n credentials that the call returns, IAM users can then make programmatic\n calls to API operations that require MFA authentication. An incorrect MFA code causes the\n API to return an access denied error. For a comparison of GetSessionToken with\n the other API operations that produce temporary credentials, see Requesting\n Temporary Security Credentials and Comparing the\n Amazon Web Services STS API operations in the IAM User Guide.
No permissions are required for users to perform this operation. The purpose of the\n sts:GetSessionToken operation is to authenticate the user using MFA. You\n cannot use policies to control authentication operations. For more information, see\n Permissions for GetSessionToken in the\n IAM User Guide.
\n Session Duration\n
\nThe GetSessionToken operation must be called by using the long-term Amazon Web Services\n security credentials of an IAM user. Credentials that are created by IAM users are valid for the duration that you specify. This duration can range\n from 900 seconds (15 minutes) up to a maximum of 129,600 seconds (36 hours), with a default\n of 43,200 seconds (12 hours). Credentials based on account credentials can range from 900\n seconds (15 minutes) up to 3,600 seconds (1 hour), with a default of 1 hour.
\n Permissions\n
\nThe temporary security credentials created by GetSessionToken can be used\n to make API calls to any Amazon Web Services service with the following exceptions:
You cannot call any IAM API operations unless MFA authentication information is\n included in the request.
\nYou cannot call any STS API except\n AssumeRole or GetCallerIdentity.
The credentials that GetSessionToken returns are based on permissions\n associated with the IAM user whose credentials were used to call the\n operation. The temporary credentials have the same permissions as the IAM user.
Although it is possible to call GetSessionToken using the security\n credentials of an Amazon Web Services account root user rather than an IAM user, we do\n not recommend it. If GetSessionToken is called using root user\n credentials, the temporary credentials have root user permissions. For more\n information, see Safeguard your root user credentials and don't use them for everyday tasks in the\n IAM User Guide\n
For more information about using GetSessionToken to create temporary\n credentials, see Temporary\n Credentials for Users in Untrusted Environments in the\n IAM User Guide.
A CancellationMessage is returned when a CancelQuery\n request for the query specified by QueryId has already been issued.
The query string to run. Parameter\n names can be specified in the query string @ character followed by an\n identifier. The named Parameter @scheduled_runtime is reserved and can be used in the query to get the time at which the query is scheduled to run.
The timestamp calculated according to the ScheduleConfiguration parameter, will be the value of @scheduled_runtime paramater for each query run. \n For example, consider an instance of a scheduled query executing on 2021-12-01 00:00:00. For this instance, the @scheduled_runtime parameter is \n initialized to the timestamp 2021-12-01 00:00:00 when invoking the query.
The query string to run. Parameter\n names can be specified in the query string @ character followed by an\n identifier. The named Parameter @scheduled_runtime is reserved and can be used in the query to get the time at which the query is scheduled to run.
The timestamp calculated according to the ScheduleConfiguration parameter, will be the value of @scheduled_runtime paramater for each query run. \n For example, consider an instance of a scheduled query executing on 2021-12-01 00:00:00. For this instance, the @scheduled_runtime parameter is \n initialized to the timestamp 2021-12-01 00:00:00 when invoking the query.
Using a ClientToken makes the call to CreateScheduledQuery idempotent, in other words, making the same request repeatedly will produce the same result. Making \n multiple identical CreateScheduledQuery requests has the same effect as making a single request.\n\n
\n If CreateScheduledQuery is called without a ClientToken, the\n Query SDK generates a ClientToken on your behalf.
After 8 hours, any request with the same ClientToken is treated\n as a new request.
Using a ClientToken makes the call to CreateScheduledQuery idempotent, in other words, making the same request repeatedly will produce the same result. Making \n multiple identical CreateScheduledQuery requests has the same effect as making a single request.\n\n
\n If CreateScheduledQuery is called without a ClientToken, the\n Query SDK generates a ClientToken on your behalf.
After 8 hours, any request with the same ClientToken is treated\n as a new request.
The Amazon KMS key used to encrypt the scheduled query resource, at-rest. If the Amazon KMS\n key is not specified, the scheduled query resource will be encrypted with a Timestream\n owned Amazon KMS key. To specify a KMS key, use the key ID, key ARN, alias name, or alias\n ARN. When using an alias name, prefix the name with alias/\n
\nIf ErrorReportConfiguration uses SSE_KMS as encryption type, the same KmsKeyId is used to encrypt the error report at rest.
The Amazon KMS key used to encrypt the scheduled query resource, at-rest. If the Amazon KMS\n key is not specified, the scheduled query resource will be encrypted with a Timestream\n owned Amazon KMS key. To specify a KMS key, use the key ID, key ARN, alias name, or alias\n ARN. When using an alias name, prefix the name with alias/\n
\nIf ErrorReportConfiguration uses SSE_KMS as encryption type, the same KmsKeyId is used to encrypt the error report at rest.
DescribeEndpoints returns a list of available endpoints to make Timestream\n API calls against. This API is available through both Write and Query.
\nBecause the Timestream SDKs are designed to transparently work with the\n service’s architecture, including the management and mapping of the service endpoints,\n it is not recommended that you use this API unless:
\nYou are using VPC endpoints (Amazon Web Services PrivateLink) with Timestream\n \n
\nYour application uses a programming language that does not yet have SDK\n support
\nYou require better control over the client-side implementation
\nFor detailed information on how and when to use and implement DescribeEndpoints, see\n The Endpoint Discovery Pattern.
" + "smithy.api#documentation": "DescribeEndpoints returns a list of available endpoints to make Timestream\n API calls against. This API is available through both Write and Query.
\nBecause the Timestream SDKs are designed to transparently work with the\n service’s architecture, including the management and mapping of the service endpoints,\n it is not recommended that you use this API unless:
\nYou are using VPC endpoints (Amazon Web Services PrivateLink) with Timestream\n \n
\nYour application uses a programming language that does not yet have SDK\n support
\nYou require better control over the client-side implementation
\nFor detailed information on how and when to use and implement DescribeEndpoints, see\n The Endpoint Discovery Pattern.
" } }, "com.amazonaws.timestreamquery#DescribeEndpointsRequest": { "type": "structure", - "members": {} + "members": {}, + "traits": { + "smithy.api#input": {} + } }, "com.amazonaws.timestreamquery#DescribeEndpointsResponse": { "type": "structure", @@ -423,6 +441,9 @@ "smithy.api#required": {} } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.timestreamquery#DescribeScheduledQuery": { @@ -470,6 +491,9 @@ "smithy.api#required": {} } } + }, + "traits": { + "smithy.api#input": {} } }, "com.amazonaws.timestreamquery#DescribeScheduledQueryResponse": { @@ -482,6 +506,9 @@ "smithy.api#required": {} } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.timestreamquery#DimensionMapping": { @@ -513,14 +540,14 @@ } }, "com.amazonaws.timestreamquery#DimensionValueType": { - "type": "string", - "traits": { - "smithy.api#enum": [ - { - "value": "VARCHAR", - "name": "VARCHAR" + "type": "enum", + "members": { + "VARCHAR": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "VARCHAR" } - ] + } } }, "com.amazonaws.timestreamquery#Double": { @@ -650,6 +677,9 @@ "smithy.api#idempotencyToken": {} } } + }, + "traits": { + "smithy.api#input": {} } }, "com.amazonaws.timestreamquery#ExecutionStats": { @@ -754,6 +784,7 @@ "smithy.api#paginated": { "inputToken": "NextToken", "outputToken": "NextToken", + "items": "ScheduledQueries", "pageSize": "MaxResults" } } @@ -773,6 +804,9 @@ "smithy.api#documentation": "A pagination token to resume pagination.
" } } + }, + "traits": { + "smithy.api#input": {} } }, "com.amazonaws.timestreamquery#ListScheduledQueriesResponse": { @@ -791,6 +825,9 @@ "smithy.api#documentation": "A token to specify where to start paginating. This is the NextToken from a previously\n truncated response.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.timestreamquery#ListTagsForResource": { @@ -823,6 +860,7 @@ "smithy.api#paginated": { "inputToken": "NextToken", "outputToken": "NextToken", + "items": "Tags", "pageSize": "MaxResults" } } @@ -849,6 +887,9 @@ "smithy.api#documentation": "A pagination token to resume pagination.
" } } + }, + "traits": { + "smithy.api#input": {} } }, "com.amazonaws.timestreamquery#ListTagsForResourceResponse": { @@ -867,6 +908,9 @@ "smithy.api#documentation": "A pagination token to resume pagination with a subsequent call to\n ListTagsForResourceResponse.
By setting this value to true, Timestream will only validate that the\n query string is a valid Timestream query, and not store the prepared query for later\n use.
\n Query is a synchronous operation that enables you to run a query against\n your Amazon Timestream data. Query will time out after 60 seconds.\n You must update the default timeout in the SDK to support a timeout of 60 seconds. See\n the code\n sample for details.
Your query request will fail in the following cases:
\n If you submit a Query request with the same client token outside\n of the 5-minute idempotency window.
If you submit a Query request with the same client token, but\n change other parameters, within the 5-minute idempotency window.
If the size of the row (including the query metadata) exceeds 1 MB, then the\n query will fail with the following error message:
\n\n Query aborted as max page response size has been exceeded by the output\n result row\n
If the IAM principal of the query initiator and the result reader are not the\n same and/or the query initiator and the result reader do not have the same query\n string in the query requests, the query will fail with an Invalid\n pagination token error.
\n Query is a synchronous operation that enables you to run a query against\n your Amazon Timestream data. Query will time out after 60 seconds.\n You must update the default timeout in the SDK to support a timeout of 60 seconds. See\n the code\n sample for details.
Your query request will fail in the following cases:
\n If you submit a Query request with the same client token outside\n of the 5-minute idempotency window.
If you submit a Query request with the same client token, but\n change other parameters, within the 5-minute idempotency window.
If the size of the row (including the query metadata) exceeds 1 MB, then the\n query will fail with the following error message:
\n\n Query aborted as max page response size has been exceeded by the output\n result row\n
If the IAM principal of the query initiator and the result reader are not the\n same and/or the query initiator and the result reader do not have the same query\n string in the query requests, the query will fail with an Invalid\n pagination token error.
Unique, case-sensitive string of up to 64 ASCII characters specified when a\n Query request is made. Providing a ClientToken makes the\n call to Query\n idempotent. This means that running the same query repeatedly will\n produce the same result. In other words, making multiple identical Query\n requests has the same effect as making a single request. When using\n ClientToken in a query, note the following:
If the Query API is instantiated without a ClientToken, the\n Query SDK generates a ClientToken on your behalf.
If the Query invocation only contains the\n ClientToken but does not include a NextToken, that\n invocation of Query is assumed to be a new query run.
If the invocation contains NextToken, that particular invocation\n is assumed to be a subsequent invocation of a prior call to the Query API, and a\n result set is returned.
After 4 hours, any request with the same ClientToken is treated\n as a new request.
Unique, case-sensitive string of up to 64 ASCII characters specified when a\n Query request is made. Providing a ClientToken makes the\n call to Query\n idempotent. This means that running the same query repeatedly will\n produce the same result. In other words, making multiple identical Query\n requests has the same effect as making a single request. When using\n ClientToken in a query, note the following:
If the Query API is instantiated without a ClientToken, the\n Query SDK generates a ClientToken on your behalf.
If the Query invocation only contains the\n ClientToken but does not include a NextToken, that\n invocation of Query is assumed to be a new query run.
If the invocation contains NextToken, that particular invocation\n is assumed to be a subsequent invocation of a prior call to the Query API, and a\n result set is returned.
After 4 hours, any request with the same ClientToken is treated\n as a new request.
A pagination token used to return a set of results. When the Query API\n is invoked using NextToken, that particular invocation is assumed to be a\n subsequent invocation of a prior call to Query, and a result set is\n returned. However, if the Query invocation only contains the\n ClientToken, that invocation of Query is assumed to be a\n new query run.
Note the following when using NextToken in a query:
\nA pagination token can be used for up to five Query invocations,\n OR for a duration of up to 1 hour – whichever comes first.
Using the same NextToken will return the same set of records. To\n keep paginating through the result set, you must to use the most recent\n nextToken.
Suppose a Query invocation returns two NextToken\n values, TokenA and TokenB. If TokenB is\n used in a subsequent Query invocation, then TokenA is\n invalidated and cannot be reused.
To request a previous result set from a query after pagination has begun, you\n must re-invoke the Query API.
\nThe latest NextToken should be used to paginate until\n null is returned, at which point a new NextToken\n should be used.
If the IAM principal of the query initiator and the result reader are not the\n same and/or the query initiator and the result reader do not have the same query\n string in the query requests, the query will fail with an Invalid\n pagination token error.
A pagination token used to return a set of results. When the Query API\n is invoked using NextToken, that particular invocation is assumed to be a\n subsequent invocation of a prior call to Query, and a result set is\n returned. However, if the Query invocation only contains the\n ClientToken, that invocation of Query is assumed to be a\n new query run.
Note the following when using NextToken in a query:
\nA pagination token can be used for up to five Query invocations,\n OR for a duration of up to 1 hour – whichever comes first.
Using the same NextToken will return the same set of records. To\n keep paginating through the result set, you must to use the most recent\n nextToken.
Suppose a Query invocation returns two NextToken\n values, TokenA and TokenB. If TokenB is\n used in a subsequent Query invocation, then TokenA is\n invalidated and cannot be reused.
To request a previous result set from a query after pagination has begun, you\n must re-invoke the Query API.
\nThe latest NextToken should be used to paginate until\n null is returned, at which point a new NextToken\n should be used.
If the IAM principal of the query initiator and the result reader are not the\n same and/or the query initiator and the result reader do not have the same query\n string in the query requests, the query will fail with an Invalid\n pagination token error.
The total number of rows to be returned in the Query output. The initial\n run of Query with a MaxRows value specified will return the\n result set of the query in two cases:
The size of the result is less than 1MB.
The number of rows in the result set is less than the value of\n maxRows.
Otherwise, the initial invocation of Query only returns a\n NextToken, which can then be used in subsequent calls to fetch the\n result set. To resume pagination, provide the NextToken value in the\n subsequent command.
If the row size is large (e.g. a row has many columns), Timestream may return\n fewer rows to keep the response size from exceeding the 1 MB limit. If\n MaxRows is not provided, Timestream will send the necessary\n number of rows to meet the 1 MB limit.
The total number of rows to be returned in the Query output. The initial\n run of Query with a MaxRows value specified will return the\n result set of the query in two cases:
The size of the result is less than 1MB.
The number of rows in the result set is less than the value of\n maxRows.
Otherwise, the initial invocation of Query only returns a\n NextToken, which can then be used in subsequent calls to fetch the\n result set. To resume pagination, provide the NextToken value in the\n subsequent command.
If the row size is large (e.g. a row has many columns), Timestream may return\n fewer rows to keep the response size from exceeding the 1 MB limit. If\n MaxRows is not provided, Timestream will send the necessary\n number of rows to meet the 1 MB limit.
Information about the status of the query, including progress and bytes\n scanned.
" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.timestreamquery#QueryStatus": { @@ -1433,18 +1497,20 @@ } }, "com.amazonaws.timestreamquery#S3EncryptionOption": { - "type": "string", - "traits": { - "smithy.api#enum": [ - { - "value": "SSE_S3", - "name": "SSE_S3" - }, - { - "value": "SSE_KMS", - "name": "SSE_KMS" + "type": "enum", + "members": { + "SSE_S3": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "SSE_S3" } - ] + }, + "SSE_KMS": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "SSE_KMS" + } + } } }, "com.amazonaws.timestreamquery#S3ObjectKey": { @@ -1481,81 +1547,109 @@ } }, "com.amazonaws.timestreamquery#ScalarMeasureValueType": { - "type": "string", - "traits": { - "smithy.api#enum": [ - { - "value": "BIGINT", - "name": "BIGINT" - }, - { - "value": "BOOLEAN", - "name": "BOOLEAN" - }, - { - "value": "DOUBLE", - "name": "DOUBLE" - }, - { - "value": "VARCHAR", - "name": "VARCHAR" - }, - { - "value": "TIMESTAMP", - "name": "TIMESTAMP" + "type": "enum", + "members": { + "BIGINT": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "BIGINT" } - ] + }, + "BOOLEAN": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "BOOLEAN" + } + }, + "DOUBLE": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "DOUBLE" + } + }, + "VARCHAR": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "VARCHAR" + } + }, + "TIMESTAMP": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "TIMESTAMP" + } + } } }, "com.amazonaws.timestreamquery#ScalarType": { - "type": "string", - "traits": { - "smithy.api#enum": [ - { - "value": "VARCHAR", - "name": "VARCHAR" - }, - { - "value": "BOOLEAN", - "name": "BOOLEAN" - }, - { - "value": "BIGINT", - "name": "BIGINT" - }, - { - "value": "DOUBLE", - "name": "DOUBLE" - }, - { - "value": "TIMESTAMP", - "name": "TIMESTAMP" - }, - { - "value": "DATE", - "name": "DATE" - }, - { - "value": "TIME", - "name": "TIME" - }, - { - "value": "INTERVAL_DAY_TO_SECOND", - "name": "INTERVAL_DAY_TO_SECOND" - }, - { - "value": "INTERVAL_YEAR_TO_MONTH", - "name": "INTERVAL_YEAR_TO_MONTH" - }, - { - "value": "UNKNOWN", - "name": "UNKNOWN" - }, - { - "value": "INTEGER", - "name": "INTEGER" + "type": "enum", + "members": { + "VARCHAR": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "VARCHAR" } - ] + }, + "BOOLEAN": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "BOOLEAN" + } + }, + "BIGINT": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "BIGINT" + } + }, + "DOUBLE": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "DOUBLE" + } + }, + "TIMESTAMP": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "TIMESTAMP" + } + }, + "DATE": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "DATE" + } + }, + "TIME": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "TIME" + } + }, + "INTERVAL_DAY_TO_SECOND": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "INTERVAL_DAY_TO_SECOND" + } + }, + "INTERVAL_YEAR_TO_MONTH": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "INTERVAL_YEAR_TO_MONTH" + } + }, + "UNKNOWN": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "UNKNOWN" + } + }, + "INTEGER": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "INTEGER" + } + } } }, "com.amazonaws.timestreamquery#ScalarValue": { @@ -1771,26 +1865,32 @@ } }, "com.amazonaws.timestreamquery#ScheduledQueryRunStatus": { - "type": "string", - "traits": { - "smithy.api#enum": [ - { - "value": "AUTO_TRIGGER_SUCCESS", - "name": "AUTO_TRIGGER_SUCCESS" - }, - { - "value": "AUTO_TRIGGER_FAILURE", - "name": "AUTO_TRIGGER_FAILURE" - }, - { - "value": "MANUAL_TRIGGER_SUCCESS", - "name": "MANUAL_TRIGGER_SUCCESS" - }, - { - "value": "MANUAL_TRIGGER_FAILURE", - "name": "MANUAL_TRIGGER_FAILURE" + "type": "enum", + "members": { + "AUTO_TRIGGER_SUCCESS": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "AUTO_TRIGGER_SUCCESS" + } + }, + "AUTO_TRIGGER_FAILURE": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "AUTO_TRIGGER_FAILURE" + } + }, + "MANUAL_TRIGGER_SUCCESS": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "MANUAL_TRIGGER_SUCCESS" } - ] + }, + "MANUAL_TRIGGER_FAILURE": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "MANUAL_TRIGGER_FAILURE" + } + } } }, "com.amazonaws.timestreamquery#ScheduledQueryRunSummary": { @@ -1844,18 +1944,20 @@ } }, "com.amazonaws.timestreamquery#ScheduledQueryState": { - "type": "string", - "traits": { - "smithy.api#enum": [ - { - "value": "ENABLED", - "name": "ENABLED" - }, - { - "value": "DISABLED", - "name": "DISABLED" + "type": "enum", + "members": { + "ENABLED": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "ENABLED" + } + }, + "DISABLED": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "DISABLED" } - ] + } } }, "com.amazonaws.timestreamquery#SchemaName": { @@ -2049,11 +2151,17 @@ "smithy.api#required": {} } } + }, + "traits": { + "smithy.api#input": {} } }, "com.amazonaws.timestreamquery#TagResourceResponse": { "type": "structure", - "members": {} + "members": {}, + "traits": { + "smithy.api#output": {} + } }, "com.amazonaws.timestreamquery#TagValue": { "type": "string", @@ -2274,7 +2382,7 @@ "name": "timestream" }, "aws.protocols#awsJson1_0": {}, - "smithy.api#documentation": "An encoded stream of audio blobs. Audio streams are encoded as either HTTP/2 or WebSocket \n data frames.
\nFor more information, see Transcribing streaming audio.
", + "smithy.api#documentation": "An encoded stream of audio blobs. Audio streams are encoded as either HTTP/2 or WebSocket \n data frames.
\nFor more information, see Transcribing streaming audio.
", "smithy.api#streaming": {} } }, @@ -915,7 +915,7 @@ "Confidence": { "target": "com.amazonaws.transcribestreaming#Confidence", "traits": { - "smithy.api#documentation": "The confidence score associated with the identified PHI entity in your audio.
\nConfidence scores are values between 0 and 1. A larger value indicates a higher\n probability that the identified entity correctly matches the entity spoken in your\n media.
" + "smithy.api#documentation": "The confidence score associated with the identified PHI entity in your audio.
\nConfidence scores are values between 0 and 1. A larger value indicates a higher\n probability that the identified entity correctly matches the entity spoken in your\n media.
" } } }, @@ -961,7 +961,7 @@ "Confidence": { "target": "com.amazonaws.transcribestreaming#Confidence", "traits": { - "smithy.api#documentation": "The confidence score associated with a word or phrase in your transcript.
\nConfidence scores are values between 0 and 1. A larger value indicates a higher\n probability that the identified item correctly matches the item spoken in your\n media.
" + "smithy.api#documentation": "The confidence score associated with a word or phrase in your transcript.
\nConfidence scores are values between 0 and 1. A larger value indicates a higher\n probability that the identified item correctly matches the item spoken in your\n media.
" } }, "Speaker": { @@ -1008,7 +1008,7 @@ "target": "com.amazonaws.transcribestreaming#Boolean", "traits": { "smithy.api#default": false, - "smithy.api#documentation": "Indicates if the segment is complete.
\nIf IsPartial is true, the segment is not complete. If\n IsPartial is false, the segment is complete.
Indicates if the segment is complete.
\nIf IsPartial is true, the segment is not complete. If\n IsPartial is false, the segment is complete.
The Result associated with a \n .
Contains a set of transcription results from one or more audio segments, along with\n additional information per your request parameters. This can include information relating to\n alternative transcriptions, channel identification, partial result stabilization, language \n identification, and other transcription-related data.
" + "smithy.api#documentation": "The Result associated with a \n .
Contains a set of transcription results from one or more audio segments, along with\n additional information per your request parameters. This can include information relating to\n alternative transcriptions, channel identification, partial result stabilization, language \n identification, and other transcription-related data.
" } }, "com.amazonaws.transcribestreaming#MedicalResultList": { @@ -1045,7 +1045,7 @@ } }, "traits": { - "smithy.api#documentation": "The MedicalTranscript associated with a \n .
\n MedicalTranscript contains Results, which contains a set of \n transcription results from one or more audio segments, along with additional information per your \n request parameters.
The MedicalTranscript associated with a \n .
\n MedicalTranscript contains Results, which contains a set of \n transcription results from one or more audio segments, along with additional information per your \n request parameters.
The MedicalTranscriptEvent associated with a \n MedicalTranscriptResultStream.
Contains a set of transcription results from one or more audio segments, along with additional \n information per your request parameters.
" + "smithy.api#documentation": "The MedicalTranscriptEvent associated with a \n MedicalTranscriptResultStream.
Contains a set of transcription results from one or more audio segments, along with additional \n information per your request parameters.
" } }, "com.amazonaws.transcribestreaming#MedicalTranscriptResultStream": { @@ -1068,7 +1068,7 @@ "TranscriptEvent": { "target": "com.amazonaws.transcribestreaming#MedicalTranscriptEvent", "traits": { - "smithy.api#documentation": "The MedicalTranscriptEvent associated with a \n MedicalTranscriptResultStream.
Contains a set of transcription results from one or more audio segments, along with \n additional information per your request parameters. This can include information relating to\n alternative transcriptions, channel identification, partial result stabilization, language \n identification, and other transcription-related data.
" + "smithy.api#documentation": "The MedicalTranscriptEvent associated with a \n MedicalTranscriptResultStream.
Contains a set of transcription results from one or more audio segments, along with \n additional information per your request parameters. This can include information relating to\n alternative transcriptions, channel identification, partial result stabilization, language \n identification, and other transcription-related data.
" } }, "BadRequestException": { @@ -1457,7 +1457,7 @@ "VocabularyFilterName": { "target": "com.amazonaws.transcribestreaming#VocabularyFilterName", "traits": { - "smithy.api#documentation": "Specify the name of the custom vocabulary filter that you want to use when processing your\n transcription. Note that vocabulary filter names are case sensitive.
\nIf the language of the specified custom vocabulary filter doesn't match the language identified in\n your media, the vocabulary filter is not applied to your transcription.
\nFor more information, see Using vocabulary filtering with unwanted \n words.
", + "smithy.api#documentation": "Specify the name of the custom vocabulary filter that you want to use when processing your\n transcription. Note that vocabulary filter names are case sensitive.
\nIf the language of the specified custom vocabulary filter doesn't match the language identified in\n your media, the vocabulary filter is not applied to your transcription.
\nFor more information, see Using vocabulary filtering with unwanted \n words.
", "smithy.api#httpHeader": "x-amzn-transcribe-vocabulary-filter-name" } }, @@ -1471,7 +1471,7 @@ "LanguageModelName": { "target": "com.amazonaws.transcribestreaming#ModelName", "traits": { - "smithy.api#documentation": "Specify the name of the custom language model that you want to use when processing your\n transcription. Note that language model names are case sensitive.
\nThe language of the specified language model must match the language code you specify\n in your transcription request. If the languages don't match, the custom language model isn't applied. \n There are no errors or warnings associated with a language mismatch.
\nFor more information, see Custom language models.
", + "smithy.api#documentation": "Specify the name of the custom language model that you want to use when processing your\n transcription. Note that language model names are case sensitive.
\nThe language of the specified language model must match the language code you specify\n in your transcription request. If the languages don't match, the custom language model isn't applied. \n There are no errors or warnings associated with a language mismatch.
\nFor more information, see Custom language models.
", "smithy.api#httpHeader": "x-amzn-transcribe-language-model-name" } }, @@ -1486,21 +1486,21 @@ "PartialResultsStability": { "target": "com.amazonaws.transcribestreaming#PartialResultsStability", "traits": { - "smithy.api#documentation": "Specify the level of stability to use when you enable partial results stabilization \n (EnablePartialResultsStabilization).
Low stability provides the highest accuracy. High stability transcribes faster, but with slightly\n lower accuracy.
\nFor more information, see Partial-result \n stabilization.
", + "smithy.api#documentation": "Specify the level of stability to use when you enable partial results stabilization \n (EnablePartialResultsStabilization).
Low stability provides the highest accuracy. High stability transcribes faster, but with slightly\n lower accuracy.
\nFor more information, see Partial-result \n stabilization.
", "smithy.api#httpHeader": "x-amzn-transcribe-partial-results-stability" } }, "ContentIdentificationType": { "target": "com.amazonaws.transcribestreaming#ContentIdentificationType", "traits": { - "smithy.api#documentation": "Labels all personally identifiable information (PII) identified in your transcript.
\nContent identification is performed at the segment level; PII specified in \n PiiEntityTypes is flagged upon complete transcription of an audio segment.
You can’t set ContentIdentificationType and ContentRedactionType\n in the same request. If you set both, your request returns a\n BadRequestException.
For more information, see Redacting or identifying personally identifiable\n information.
", + "smithy.api#documentation": "Labels all personally identifiable information (PII) identified in your transcript.
\nContent identification is performed at the segment level; PII specified in \n PiiEntityTypes is flagged upon complete transcription of an audio segment.
You can’t set ContentIdentificationType and ContentRedactionType\n in the same request. If you set both, your request returns a\n BadRequestException.
For more information, see Redacting or identifying personally identifiable\n information.
", "smithy.api#httpHeader": "x-amzn-transcribe-content-identification-type" } }, "ContentRedactionType": { "target": "com.amazonaws.transcribestreaming#ContentRedactionType", "traits": { - "smithy.api#documentation": "Redacts all personally identifiable information (PII) identified in your transcript.
\nContent redaction is performed at the segment level; PII specified in \n PiiEntityTypes is redacted upon complete transcription of an audio segment.
You can’t set ContentRedactionType and ContentIdentificationType\n in the same request. If you set both, your request returns a\n BadRequestException.
For more information, see Redacting or identifying personally identifiable\n information.
", + "smithy.api#documentation": "Redacts all personally identifiable information (PII) identified in your transcript.
\nContent redaction is performed at the segment level; PII specified in \n PiiEntityTypes is redacted upon complete transcription of an audio segment.
You can’t set ContentRedactionType and ContentIdentificationType\n in the same request. If you set both, your request returns a\n BadRequestException.
For more information, see Redacting or identifying personally identifiable\n information.
", "smithy.api#httpHeader": "x-amzn-transcribe-content-redaction-type" } }, @@ -1511,6 +1511,9 @@ "smithy.api#httpHeader": "x-amzn-transcribe-pii-entity-types" } } + }, + "traits": { + "smithy.api#input": {} } }, "com.amazonaws.transcribestreaming#StartCallAnalyticsStreamTranscriptionResponse": { @@ -1622,6 +1625,9 @@ "smithy.api#httpHeader": "x-amzn-transcribe-pii-entity-types" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.transcribestreaming#StartMedicalStreamTranscription": { @@ -1650,7 +1656,7 @@ } ], "traits": { - "smithy.api#documentation": "Starts a bidirectional HTTP/2 or WebSocket stream where audio is streamed to \n Amazon Transcribe Medical and the transcription results are streamed to your\n application.
\nThe following parameters are required:
\n\n language-code\n
\n media-encoding\n
\n sample-rate\n
For more information on streaming with Amazon Transcribe Medical, see \n Transcribing\n streaming audio.
", + "smithy.api#documentation": "Starts a bidirectional HTTP/2 or WebSocket stream where audio is streamed to \n Amazon Transcribe Medical and the transcription results are streamed to your\n application.
\nThe following parameters are required:
\n\n language-code\n
\n media-encoding\n
\n sample-rate\n
For more information on streaming with Amazon Transcribe Medical, see \n Transcribing\n streaming audio.
", "smithy.api#http": { "method": "POST", "uri": "/medical-stream-transcription", @@ -1664,7 +1670,7 @@ "LanguageCode": { "target": "com.amazonaws.transcribestreaming#LanguageCode", "traits": { - "smithy.api#documentation": "Specify the language code that represents the language spoken in your audio.
\nAmazon Transcribe Medical only supports US English (en-US).
Specify the language code that represents the language spoken in your audio.
\nAmazon Transcribe Medical only supports US English (en-US).
Specify the encoding used for the input audio. Supported formats are:
\nFLAC
\nOPUS-encoded audio in an Ogg container
\nPCM (only signed 16-bit little-endian audio formats, which does not include\n WAV)
\nFor more information, see Media formats.
", + "smithy.api#documentation": "Specify the encoding used for the input audio. Supported formats are:
\nFLAC
\nOPUS-encoded audio in an Ogg container
\nPCM (only signed 16-bit little-endian audio formats, which does not include\n WAV)
\nFor more information, see Media formats.
", "smithy.api#httpHeader": "x-amzn-transcribe-media-encoding", "smithy.api#required": {} } @@ -1712,14 +1718,14 @@ "target": "com.amazonaws.transcribestreaming#Boolean", "traits": { "smithy.api#default": false, - "smithy.api#documentation": "Enables speaker partitioning (diarization) in your transcription output. Speaker\n partitioning labels the speech from individual speakers in your media file.
\nFor more information, see Partitioning speakers (diarization).
", + "smithy.api#documentation": "Enables speaker partitioning (diarization) in your transcription output. Speaker\n partitioning labels the speech from individual speakers in your media file.
\nFor more information, see Partitioning speakers (diarization).
", "smithy.api#httpHeader": "x-amzn-transcribe-show-speaker-label" } }, "SessionId": { "target": "com.amazonaws.transcribestreaming#SessionId", "traits": { - "smithy.api#documentation": "Specify a name for your transcription session. If you don't include this parameter in \n your request, Amazon Transcribe Medical generates an ID and returns it in the\n response.
\nYou can use a session ID to retry a streaming session.
", + "smithy.api#documentation": "Specify a name for your transcription session. If you don't include this parameter in \n your request, Amazon Transcribe Medical generates an ID and returns it in the\n response.
\nYou can use a session ID to retry a streaming session.
", "smithy.api#httpHeader": "x-amzn-transcribe-session-id" } }, @@ -1734,7 +1740,7 @@ "target": "com.amazonaws.transcribestreaming#Boolean", "traits": { "smithy.api#default": false, - "smithy.api#documentation": "Enables channel identification in multi-channel audio.
\nChannel identification transcribes the audio on each channel independently, then appends\n the output for each channel into one transcript.
\nIf you have multi-channel audio and do not enable channel identification, your audio is \n transcribed in a continuous manner and your transcript is not separated by channel.
\nFor more information, see Transcribing multi-channel audio.
", + "smithy.api#documentation": "Enables channel identification in multi-channel audio.
\nChannel identification transcribes the audio on each channel independently, then appends\n the output for each channel into one transcript.
\nIf you have multi-channel audio and do not enable channel identification, your audio is \n transcribed in a continuous manner and your transcript is not separated by channel.
\nFor more information, see Transcribing multi-channel audio.
", "smithy.api#httpHeader": "x-amzn-transcribe-enable-channel-identification" } }, @@ -1748,10 +1754,13 @@ "ContentIdentificationType": { "target": "com.amazonaws.transcribestreaming#MedicalContentIdentificationType", "traits": { - "smithy.api#documentation": "Labels all personal health information (PHI) identified in your transcript.
\nContent identification is performed at the segment level; PHI is flagged upon complete\n transcription of an audio segment.
\nFor more information, see Identifying personal health information (PHI) in a\n transcription.
", + "smithy.api#documentation": "Labels all personal health information (PHI) identified in your transcript.
\nContent identification is performed at the segment level; PHI is flagged upon complete\n transcription of an audio segment.
\nFor more information, see Identifying personal health information (PHI) in a\n transcription.
", "smithy.api#httpHeader": "x-amzn-transcribe-content-identification-type" } } + }, + "traits": { + "smithy.api#input": {} } }, "com.amazonaws.transcribestreaming#StartMedicalStreamTranscriptionResponse": { @@ -1850,6 +1859,9 @@ "smithy.api#httpHeader": "x-amzn-transcribe-content-identification-type" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.transcribestreaming#StartStreamTranscription": { @@ -1929,7 +1941,7 @@ "AudioStream": { "target": "com.amazonaws.transcribestreaming#AudioStream", "traits": { - "smithy.api#documentation": "An encoded stream of audio blobs. Audio streams are encoded as either HTTP/2 or WebSocket \n data frames.
\nFor more information, see Transcribing streaming audio.
", + "smithy.api#documentation": "An encoded stream of audio blobs. Audio streams are encoded as either HTTP/2 or WebSocket \n data frames.
\nFor more information, see Transcribing streaming audio.
", "smithy.api#httpPayload": {}, "smithy.api#required": {} } @@ -1937,7 +1949,7 @@ "VocabularyFilterName": { "target": "com.amazonaws.transcribestreaming#VocabularyFilterName", "traits": { - "smithy.api#documentation": "Specify the name of the custom vocabulary filter that you want to use when processing your\n transcription. Note that vocabulary filter names are case sensitive.
\nIf the language of the specified custom vocabulary filter doesn't match the language identified in\n your media, the vocabulary filter is not applied to your transcription.
\nThis parameter is not intended for use with the\n IdentifyLanguage parameter. If you're including IdentifyLanguage\n in your request and want to use one or more vocabulary filters with your transcription, use\n the VocabularyFilterNames parameter instead.
For more information, see Using vocabulary filtering with unwanted \n words.
", + "smithy.api#documentation": "Specify the name of the custom vocabulary filter that you want to use when processing your\n transcription. Note that vocabulary filter names are case sensitive.
\nIf the language of the specified custom vocabulary filter doesn't match the language identified in\n your media, the vocabulary filter is not applied to your transcription.
\nThis parameter is not intended for use with the\n IdentifyLanguage parameter. If you're including IdentifyLanguage\n in your request and want to use one or more vocabulary filters with your transcription, use\n the VocabularyFilterNames parameter instead.
For more information, see Using vocabulary filtering with unwanted \n words.
", "smithy.api#httpHeader": "x-amzn-transcribe-vocabulary-filter-name" } }, @@ -1952,7 +1964,7 @@ "target": "com.amazonaws.transcribestreaming#Boolean", "traits": { "smithy.api#default": false, - "smithy.api#documentation": "Enables speaker partitioning (diarization) in your transcription output. Speaker partitioning \n labels the speech from individual speakers in your media file.
\nFor more information, see Partitioning speakers (diarization).
", + "smithy.api#documentation": "Enables speaker partitioning (diarization) in your transcription output. Speaker partitioning \n labels the speech from individual speakers in your media file.
\nFor more information, see Partitioning speakers (diarization).
", "smithy.api#httpHeader": "x-amzn-transcribe-show-speaker-label" } }, @@ -1960,7 +1972,7 @@ "target": "com.amazonaws.transcribestreaming#Boolean", "traits": { "smithy.api#default": false, - "smithy.api#documentation": "Enables channel identification in multi-channel audio.
\nChannel identification transcribes the audio on each channel independently, then appends the \n output for each channel into one transcript.
\nIf you have multi-channel audio and do not enable channel identification, your audio is \n transcribed in a continuous manner and your transcript is not separated by channel.
\nFor more information, see Transcribing multi-channel audio.
", + "smithy.api#documentation": "Enables channel identification in multi-channel audio.
\nChannel identification transcribes the audio on each channel independently, then appends the \n output for each channel into one transcript.
\nIf you have multi-channel audio and do not enable channel identification, your audio is \n transcribed in a continuous manner and your transcript is not separated by channel.
\nFor more information, see Transcribing multi-channel audio.
", "smithy.api#httpHeader": "x-amzn-transcribe-enable-channel-identification" } }, @@ -1982,21 +1994,21 @@ "PartialResultsStability": { "target": "com.amazonaws.transcribestreaming#PartialResultsStability", "traits": { - "smithy.api#documentation": "Specify the level of stability to use when you enable partial results stabilization \n (EnablePartialResultsStabilization).
Low stability provides the highest accuracy. High stability transcribes faster, but with slightly\n lower accuracy.
\nFor more information, see Partial-result \n stabilization.
", + "smithy.api#documentation": "Specify the level of stability to use when you enable partial results stabilization \n (EnablePartialResultsStabilization).
Low stability provides the highest accuracy. High stability transcribes faster, but with slightly\n lower accuracy.
\nFor more information, see Partial-result \n stabilization.
", "smithy.api#httpHeader": "x-amzn-transcribe-partial-results-stability" } }, "ContentIdentificationType": { "target": "com.amazonaws.transcribestreaming#ContentIdentificationType", "traits": { - "smithy.api#documentation": "Labels all personally identifiable information (PII) identified in your transcript.
\nContent identification is performed at the segment level; PII specified in \n PiiEntityTypes is flagged upon complete transcription of an audio segment.
You can’t set ContentIdentificationType and ContentRedactionType\n in the same request. If you set both, your request returns a\n BadRequestException.
For more information, see Redacting or identifying personally identifiable\n information.
", + "smithy.api#documentation": "Labels all personally identifiable information (PII) identified in your transcript.
\nContent identification is performed at the segment level; PII specified in \n PiiEntityTypes is flagged upon complete transcription of an audio segment.
You can’t set ContentIdentificationType and ContentRedactionType\n in the same request. If you set both, your request returns a\n BadRequestException.
For more information, see Redacting or identifying personally identifiable\n information.
", "smithy.api#httpHeader": "x-amzn-transcribe-content-identification-type" } }, "ContentRedactionType": { "target": "com.amazonaws.transcribestreaming#ContentRedactionType", "traits": { - "smithy.api#documentation": "Redacts all personally identifiable information (PII) identified in your transcript.
\nContent redaction is performed at the segment level; PII specified in \n PiiEntityTypes is redacted upon complete transcription of an audio segment.
You can’t set ContentRedactionType and ContentIdentificationType\n in the same request. If you set both, your request returns a\n BadRequestException.
For more information, see Redacting or identifying personally identifiable\n information.
", + "smithy.api#documentation": "Redacts all personally identifiable information (PII) identified in your transcript.
\nContent redaction is performed at the segment level; PII specified in \n PiiEntityTypes is redacted upon complete transcription of an audio segment.
You can’t set ContentRedactionType and ContentIdentificationType\n in the same request. If you set both, your request returns a\n BadRequestException.
For more information, see Redacting or identifying personally identifiable\n information.
", "smithy.api#httpHeader": "x-amzn-transcribe-content-redaction-type" } }, @@ -2010,7 +2022,7 @@ "LanguageModelName": { "target": "com.amazonaws.transcribestreaming#ModelName", "traits": { - "smithy.api#documentation": "Specify the name of the custom language model that you want to use when processing your\n transcription. Note that language model names are case sensitive.
\nThe language of the specified language model must match the language code you specify\n in your transcription request. If the languages don't match, the custom language model isn't applied. \n There are no errors or warnings associated with a language mismatch.
\nFor more information, see Custom language models.
", + "smithy.api#documentation": "Specify the name of the custom language model that you want to use when processing your\n transcription. Note that language model names are case sensitive.
\nThe language of the specified language model must match the language code you specify\n in your transcription request. If the languages don't match, the custom language model isn't applied. \n There are no errors or warnings associated with a language mismatch.
\nFor more information, see Custom language models.
", "smithy.api#httpHeader": "x-amzn-transcribe-language-model-name" } }, @@ -2018,7 +2030,7 @@ "target": "com.amazonaws.transcribestreaming#Boolean", "traits": { "smithy.api#default": false, - "smithy.api#documentation": "Enables automatic language identification for your transcription.
\nIf you include IdentifyLanguage, you can optionally include a list of \n language codes, using LanguageOptions, that you think may be present in \n your audio stream. Including language options can improve transcription accuracy.
You can also include a preferred language using PreferredLanguage. Adding a \n preferred language can help Amazon Transcribe identify the language faster than if you omit this \n parameter.
If you have multi-channel audio that contains different languages on each channel, and you've \n enabled channel identification, automatic language identification identifies the dominant language on \n each audio channel.
\nNote that you must include either LanguageCode or \n IdentifyLanguage in your request. If you include both parameters, your request\n fails.
Streaming language identification can't be combined with custom language models or \n redaction.
", + "smithy.api#documentation": "Enables automatic language identification for your transcription.
\nIf you include IdentifyLanguage, you can optionally include a list of \n language codes, using LanguageOptions, that you think may be present in \n your audio stream. Including language options can improve transcription accuracy.
You can also include a preferred language using PreferredLanguage. Adding a \n preferred language can help Amazon Transcribe identify the language faster than if you omit this \n parameter.
If you have multi-channel audio that contains different languages on each channel, and you've \n enabled channel identification, automatic language identification identifies the dominant language on \n each audio channel.
\nNote that you must include either LanguageCode or \n IdentifyLanguage in your request. If you include both parameters, your request\n fails.
Streaming language identification can't be combined with custom language models or \n redaction.
", "smithy.api#httpHeader": "x-amzn-transcribe-identify-language" } }, @@ -2039,17 +2051,20 @@ "VocabularyNames": { "target": "com.amazonaws.transcribestreaming#VocabularyNames", "traits": { - "smithy.api#documentation": "Specify the names of the custom vocabularies that you want to use when processing your\n transcription. Note that vocabulary names are case sensitive.
\nIf none of the languages of the specified custom vocabularies match the language identified in \n your media, your job fails.
\nThis parameter is only intended for use with the\n IdentifyLanguage parameter. If you're not\n including IdentifyLanguage in your request and want to use a custom vocabulary\n with your transcription, use the VocabularyName parameter instead.
For more information, see Custom vocabularies.
", + "smithy.api#documentation": "Specify the names of the custom vocabularies that you want to use when processing your\n transcription. Note that vocabulary names are case sensitive.
\nIf none of the languages of the specified custom vocabularies match the language identified in \n your media, your job fails.
\nThis parameter is only intended for use with the\n IdentifyLanguage parameter. If you're not\n including IdentifyLanguage in your request and want to use a custom vocabulary\n with your transcription, use the VocabularyName parameter instead.
For more information, see Custom vocabularies.
", "smithy.api#httpHeader": "x-amzn-transcribe-vocabulary-names" } }, "VocabularyFilterNames": { "target": "com.amazonaws.transcribestreaming#VocabularyFilterNames", "traits": { - "smithy.api#documentation": "Specify the names of the custom vocabulary filters that you want to use when processing\n your transcription. Note that vocabulary filter names are case sensitive.
\nIf none of the languages of the specified custom vocabulary filters match the language identified\n in your media, your job fails.
\nThis parameter is only intended for use with \n the IdentifyLanguage parameter. If you're not \n including IdentifyLanguage in your request and want to use a custom vocabulary filter \n with your transcription, use the VocabularyFilterName parameter instead.
For more information, see Using vocabulary filtering with unwanted \n words.
", + "smithy.api#documentation": "Specify the names of the custom vocabulary filters that you want to use when processing\n your transcription. Note that vocabulary filter names are case sensitive.
\nIf none of the languages of the specified custom vocabulary filters match the language identified\n in your media, your job fails.
\nThis parameter is only intended for use with \n the IdentifyLanguage parameter. If you're not \n including IdentifyLanguage in your request and want to use a custom vocabulary filter \n with your transcription, use the VocabularyFilterName parameter instead.
For more information, see Using vocabulary filtering with unwanted \n words.
", "smithy.api#httpHeader": "x-amzn-transcribe-vocabulary-filter-names" } } + }, + "traits": { + "smithy.api#input": {} } }, "com.amazonaws.transcribestreaming#StartStreamTranscriptionResponse": { @@ -2220,6 +2235,9 @@ "smithy.api#httpHeader": "x-amzn-transcribe-vocabulary-filter-names" } } + }, + "traits": { + "smithy.api#output": {} } }, "com.amazonaws.transcribestreaming#String": { @@ -2291,7 +2309,7 @@ "h2" ] }, - "smithy.api#documentation": "Amazon Transcribe streaming offers three main types of real-time transcription: \n Standard, Medical, and \n Call Analytics.
\n\n Standard transcriptions are the most common option. Refer\n to for details.
\n\n Medical transcriptions are tailored to medical professionals \n and incorporate medical terms. A common use case for this service is transcribing doctor-patient \n dialogue in real time, so doctors can focus on their patient instead of taking notes. Refer to\n for details.
\n\n Call Analytics transcriptions are designed for use with call\n center audio on two different channels; if you're looking for insight into customer service calls, use this \n option. Refer to for details.
\nAmazon Transcribe streaming offers three main types of real-time transcription: \n Standard, Medical, and \n Call Analytics.
\n\n Standard transcriptions are the most common option. Refer\n to for details.
\n\n Medical transcriptions are tailored to medical professionals \n and incorporate medical terms. A common use case for this service is transcribing doctor-patient \n dialogue in real time, so doctors can focus on their patient instead of taking notes. Refer to\n for details.
\n\n Call Analytics transcriptions are designed for use with call\n center audio on two different channels; if you're looking for insight into customer service calls, use this \n option. Refer to for details.
\n