lib/aws-sdk-secretsmanager/client.rb in aws-sdk-secretsmanager-1.39.0 vs lib/aws-sdk-secretsmanager/client.rb in aws-sdk-secretsmanager-1.40.0

- old
+ new

@@ -321,37 +321,37 @@ end # @!group API Operations # Disables automatic scheduled rotation and cancels the rotation of a - # secret if one is currently in progress. + # secret if currently in progress. # # To re-enable scheduled rotation, call RotateSecret with # `AutomaticallyRotateAfterDays` set to a value greater than 0. This - # will immediately rotate your secret and then enable the automatic + # immediately rotates your secret and then enables the automatic # schedule. # - # <note markdown="1"> If you cancel a rotation that is in progress, it can leave the - # `VersionStage` labels in an unexpected state. Depending on what step - # of the rotation was in progress, you might need to remove the staging - # label `AWSPENDING` from the partially created version, specified by - # the `VersionId` response value. You should also evaluate the partially + # <note markdown="1"> If you cancel a rotation while in progress, it can leave the + # `VersionStage` labels in an unexpected state. Depending on the step of + # the rotation in progress, you might need to remove the staging label + # `AWSPENDING` from the partially created version, specified by the + # `VersionId` response value. You should also evaluate the partially # rotated new version to see if it should be deleted, which you can do - # by removing all staging labels from the new version's `VersionStage` + # by removing all staging labels from the new version `VersionStage` # field. # # </note> # # To successfully start a rotation, the staging label `AWSPENDING` must # be in one of the following states: # - # * Not be attached to any version at all + # * Not attached to any version at all # # * Attached to the same version as the staging label `AWSCURRENT` # - # If the staging label `AWSPENDING` is attached to a different version - # than the version with `AWSCURRENT` then the attempt to rotate fails. + # If the staging label `AWSPENDING` attached to a different version than + # the version with `AWSCURRENT` then the attempt to rotate fails. # # **Minimum permissions** # # To run this command, you must have the following permissions: # @@ -371,13 +371,13 @@ # # * To list all of the versions currently associated with a secret, use # ListSecretVersionIds. # # @option params [required, String] :secret_id - # Specifies the secret for which you want to cancel a rotation request. - # You can specify either the Amazon Resource Name (ARN) or the friendly - # name of the secret. + # Specifies the secret to cancel a rotation request. You can specify + # either the Amazon Resource Name (ARN) or the friendly name of the + # secret. # # <note markdown="1"> If you specify an ARN, we generally recommend that you specify a # complete ARN. You can specify a partial ARN too—for example, if you # don’t include the final hyphen and six random characters that Secrets # Manager adds at the end of the ARN when you created the secret. A @@ -386,12 +386,18 @@ # followed by six characters (before Secrets Manager adds the hyphen and # six characters to the ARN) and you try to use that as a partial ARN, # then those characters cause Secrets Manager to assume that you’re # specifying a complete ARN. This confusion can cause unexpected # results. To avoid this situation, we recommend that you don’t create - # secret names that end with a hyphen followed by six characters. + # secret names ending with a hyphen followed by six characters. # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # # </note> # # @return [Types::CancelRotateSecretResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::CancelRotateSecretResponse#arn #arn} => String @@ -445,42 +451,42 @@ # contains a copy of the encrypted secret data. Each version is # associated with one or more "staging labels" that identify where the # version is in the rotation cycle. The `SecretVersionsToStages` field # of the secret contains the mapping of staging labels to the active # versions of the secret. Versions without a staging label are - # considered deprecated and are not included in the list. + # considered deprecated and not included in the list. # # You provide the secret data to be encrypted by putting text in either # the `SecretString` parameter or binary data in the `SecretBinary` # parameter, but not both. If you include `SecretString` or # `SecretBinary` then Secrets Manager also creates an initial secret # version and automatically attaches the staging label `AWSCURRENT` to # the new version. # - # <note markdown="1"> * If you call an operation that needs to encrypt or decrypt the - # `SecretString` or `SecretBinary` for a secret in the same account as - # the calling user and that secret doesn't specify a AWS KMS - # encryption key, Secrets Manager uses the account's default AWS - # managed customer master key (CMK) with the alias - # `aws/secretsmanager`. If this key doesn't already exist in your - # account then Secrets Manager creates it for you automatically. All - # users and roles in the same AWS account automatically have access to - # use the default CMK. Note that if an Secrets Manager API call - # results in AWS having to create the account's AWS-managed CMK, it - # can result in a one-time significant delay in returning the result. + # <note markdown="1"> * If you call an operation to encrypt or decrypt the `SecretString` or + # `SecretBinary` for a secret in the same account as the calling user + # and that secret doesn't specify a AWS KMS encryption key, Secrets + # Manager uses the account's default AWS managed customer master key + # (CMK) with the alias `aws/secretsmanager`. If this key doesn't + # already exist in your account then Secrets Manager creates it for + # you automatically. All users and roles in the same AWS account + # automatically have access to use the default CMK. Note that if an + # Secrets Manager API call results in AWS creating the account's + # AWS-managed CMK, it can result in a one-time significant delay in + # returning the result. # - # * If the secret is in a different AWS account from the credentials - # calling an API that requires encryption or decryption of the secret - # value then you must create and use a custom AWS KMS CMK because you - # can't access the default CMK for the account using credentials from - # a different AWS account. Store the ARN of the CMK in the secret when - # you create the secret or when you update it by including it in the - # `KMSKeyId`. If you call an API that must encrypt or decrypt - # `SecretString` or `SecretBinary` using credentials from a different - # account then the AWS KMS key policy must grant cross-account access - # to that other account's user or role for both the - # kms:GenerateDataKey and kms:Decrypt operations. + # * If the secret resides in a different AWS account from the + # credentials calling an API that requires encryption or decryption of + # the secret value then you must create and use a custom AWS KMS CMK + # because you can't access the default CMK for the account using + # credentials from a different AWS account. Store the ARN of the CMK + # in the secret when you create the secret or when you update it by + # including it in the `KMSKeyId`. If you call an API that must encrypt + # or decrypt `SecretString` or `SecretBinary` using credentials from a + # different account then the AWS KMS key policy must grant + # cross-account access to that other account's user or role for both + # the kms:GenerateDataKey and kms:Decrypt operations. # # </note> # # # @@ -490,15 +496,15 @@ # # * secretsmanager:CreateSecret # # * kms:GenerateDataKey - needed only if you use a customer-managed AWS # KMS key to encrypt the secret. You do not need this permission to - # use the account's default AWS managed CMK for Secrets Manager. + # use the account default AWS managed CMK for Secrets Manager. # # * kms:Decrypt - needed only if you use a customer-managed AWS KMS key # to encrypt the secret. You do not need this permission to use the - # account's default AWS managed CMK for Secrets Manager. + # account default AWS managed CMK for Secrets Manager. # # * secretsmanager:TagResource - needed only if you include the `Tags` # parameter. # # **Related operations** @@ -524,15 +530,14 @@ # Specifies the friendly name of the new secret. # # The secret name must be ASCII letters, digits, or the following # characters : /\_+=.@- # - # <note markdown="1"> Don't end your secret name with a hyphen followed by six characters. + # <note markdown="1"> Do not end your secret name with a hyphen followed by six characters. # If you do so, you risk confusion and unexpected results when searching - # for a secret by partial ARN. This is because Secrets Manager - # automatically adds a hyphen and six random characters at the end of - # the ARN. + # for a secret by partial ARN. Secrets Manager automatically adds a + # hyphen and six random characters at the end of the ARN. # # </note> # # @option params [String] :client_request_token # (Optional) If you include `SecretString` or `SecretBinary`, then an @@ -543,11 +548,11 @@ # then you can leave this parameter empty. The CLI or SDK generates a # random UUID for you and includes it as the value for this parameter in # the request. If you don't use the SDK and instead generate a raw HTTP # request to the Secrets Manager service endpoint, then you must # generate a `ClientRequestToken` yourself for the new version and - # include that value in the request. + # include the value in the request. # # </note> # # This value helps ensure idempotency. Secrets Manager uses this value # to prevent the accidental creation of duplicate versions if there are @@ -556,14 +561,13 @@ # the specified secret. # # * If the `ClientRequestToken` value isn't already associated with a # version of the secret then a new version of the secret is created. # - # * If a version with this value already exists and that version's + # * If a version with this value already exists and the version # `SecretString` and `SecretBinary` values are the same as those in - # the request, then the request is ignored (the operation is - # idempotent). + # the request, then the request is ignored. # # * If a version with this value already exists and that version's # `SecretString` and `SecretBinary` values are different from those in # the request then the request fails because you cannot modify an # existing version. Instead, use PutSecretValue to create a new @@ -595,13 +599,13 @@ # `aws/secretsmanager`). If a AWS KMS CMK with that name doesn't yet # exist, then Secrets Manager creates it for you automatically the first # time it needs to encrypt a version's `SecretString` or `SecretBinary` # fields. # - # You can use the account's default CMK to encrypt and decrypt only if - # you call this operation using credentials from the same account that - # owns the secret. If the secret is in a different account, then you + # You can use the account default CMK to encrypt and decrypt only if you + # call this operation using credentials from the same account that owns + # the secret. If the secret resides in a different account, then you # must create a custom CMK and specify the ARN in this field. # # @option params [String, IO] :secret_binary # (Optional) Specifies binary data that you want to encrypt and store in # the new version of the secret. To use this parameter in the @@ -632,11 +636,11 @@ # string argument and specify key/value pairs. For information on how to # format a JSON parameter for the various command line tool # environments, see [Using JSON for Parameters][1] in the *AWS CLI User # Guide*. For example: # - # `[\{"username":"bob"\},\{"password":"abc123xyz456"\}]` + # `\{"username":"bob","password":"abc123xyz456"\}` # # If your command-line tool or SDK requires quotation marks around the # parameter, you should use single quotes to avoid confusion with the # double quotes required in the JSON text. # @@ -678,20 +682,20 @@ # # * Maximum value length—255 Unicode characters in UTF-8 # # * Tag keys and values are case sensitive. # - # * Do not use the `aws:` prefix in your tag names or values because it - # is reserved for AWS use. You can't edit or delete tag names or + # * Do not use the `aws:` prefix in your tag names or values because AWS + # reserves it for AWS use. You can't edit or delete tag names or # values with this prefix. Tags with this prefix do not count against # your tags per secret limit. # - # * If your tagging schema will be used across multiple services and - # resources, remember that other services might have restrictions on - # allowed characters. Generally allowed characters are: letters, - # spaces, and numbers representable in UTF-8, plus the following - # special characters: + - = . \_ : / @. + # * If you use your tagging schema across multiple services and + # resources, remember other services might have restrictions on + # allowed characters. Generally allowed characters: letters, spaces, + # and numbers representable in UTF-8, plus the following special + # characters: + - = . \_ : / @. # # # # [1]: https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#cli-using-param-json # @@ -751,12 +755,11 @@ def create_secret(params = {}, options = {}) req = build_request(:create_secret, params) req.send_request(options) end - # Deletes the resource-based permission policy that's attached to the - # secret. + # Deletes the resource-based permission policy attached to the secret. # # **Minimum permissions** # # To run this command, you must have the following permissions: # @@ -787,12 +790,18 @@ # followed by six characters (before Secrets Manager adds the hyphen and # six characters to the ARN) and you try to use that as a partial ARN, # then those characters cause Secrets Manager to assume that you’re # specifying a complete ARN. This confusion can cause unexpected # results. To avoid this situation, we recommend that you don’t create - # secret names that end with a hyphen followed by six characters. + # secret names ending with a hyphen followed by six characters. # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # # </note> # # @return [Types::DeleteResourcePolicyResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::DeleteResourcePolicyResponse#arn #arn} => String @@ -890,12 +899,18 @@ # followed by six characters (before Secrets Manager adds the hyphen and # six characters to the ARN) and you try to use that as a partial ARN, # then those characters cause Secrets Manager to assume that you’re # specifying a complete ARN. This confusion can cause unexpected # results. To avoid this situation, we recommend that you don’t create - # secret names that end with a hyphen followed by six characters. + # secret names ending with a hyphen followed by six characters. # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # # </note> # # @option params [Integer] :recovery_window_in_days # (Optional) Specifies the number of days that Secrets Manager waits # before it can delete the secret. You can't use both this parameter @@ -968,12 +983,12 @@ req = build_request(:delete_secret, params) req.send_request(options) end # Retrieves the details of a secret. It does not include the encrypted - # fields. Only those fields that are populated with a value are returned - # in the response. + # fields. Secrets Manager only returns fields populated with a value in + # the response. # # **Minimum permissions** # # To run this command, you must have the following permissions: # @@ -1006,12 +1021,18 @@ # followed by six characters (before Secrets Manager adds the hyphen and # six characters to the ARN) and you try to use that as a partial ARN, # then those characters cause Secrets Manager to assume that you’re # specifying a complete ARN. This confusion can cause unexpected # results. To avoid this situation, we recommend that you don’t create - # secret names that end with a hyphen followed by six characters. + # secret names ending with a hyphen followed by six characters. # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # # </note> # # @return [Types::DescribeSecretResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::DescribeSecretResponse#arn #arn} => String @@ -1026,10 +1047,11 @@ # * {Types::DescribeSecretResponse#last_accessed_date #last_accessed_date} => Time # * {Types::DescribeSecretResponse#deleted_date #deleted_date} => Time # * {Types::DescribeSecretResponse#tags #tags} => Array&lt;Types::Tag&gt; # * {Types::DescribeSecretResponse#version_ids_to_stages #version_ids_to_stages} => Hash&lt;String,Array&lt;String&gt;&gt; # * {Types::DescribeSecretResponse#owning_service #owning_service} => String + # * {Types::DescribeSecretResponse#created_date #created_date} => Time # # # @example Example: To retrieve the details of a secret # # # The following example shows how to get the details about a secret. @@ -1096,10 +1118,11 @@ # resp.tags[0].value #=> String # resp.version_ids_to_stages #=> Hash # resp.version_ids_to_stages["SecretVersionIdType"] #=> Array # resp.version_ids_to_stages["SecretVersionIdType"][0] #=> String # resp.owning_service #=> String + # resp.created_date #=> Time # # @see http://docs.aws.amazon.com/goto/WebAPI/secretsmanager-2017-10-17/DescribeSecret AWS API Documentation # # @overload describe_secret(params = {}) # @param [Hash] params ({}) @@ -1214,15 +1237,14 @@ def get_random_password(params = {}, options = {}) req = build_request(:get_random_password, params) req.send_request(options) end - # Retrieves the JSON text of the resource-based policy document that's - # attached to the specified secret. The JSON request string input and - # response output are shown formatted with white space and line breaks - # for better readability. Submit your input as a single line JSON - # string. + # Retrieves the JSON text of the resource-based policy document attached + # to the specified secret. The JSON request string input and response + # output displays formatted code with white space and line breaks for + # better readability. Submit your input as a single line JSON string. # # **Minimum permissions** # # To run this command, you must have the following permissions: # @@ -1232,12 +1254,12 @@ # # **Related operations** # # * To attach a resource policy to a secret, use PutResourcePolicy. # - # * To delete the resource-based policy that's attached to a secret, - # use DeleteResourcePolicy. + # * To delete the resource-based policy attached to a secret, use + # DeleteResourcePolicy. # # * To list all of the currently available secrets, use ListSecrets. # # @option params [required, String] :secret_id # Specifies the secret that you want to retrieve the attached @@ -1253,12 +1275,18 @@ # followed by six characters (before Secrets Manager adds the hyphen and # six characters to the ARN) and you try to use that as a partial ARN, # then those characters cause Secrets Manager to assume that you’re # specifying a complete ARN. This confusion can cause unexpected # results. To avoid this situation, we recommend that you don’t create - # secret names that end with a hyphen followed by six characters. + # secret names ending with a hyphen followed by six characters. # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # # </note> # # @return [Types::GetResourcePolicyResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::GetResourcePolicyResponse#arn #arn} => String @@ -1338,12 +1366,18 @@ # followed by six characters (before Secrets Manager adds the hyphen and # six characters to the ARN) and you try to use that as a partial ARN, # then those characters cause Secrets Manager to assume that you’re # specifying a complete ARN. This confusion can cause unexpected # results. To avoid this situation, we recommend that you don’t create - # secret names that end with a hyphen followed by six characters. + # secret names ending with a hyphen followed by six characters. # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # # </note> # # @option params [String] :version_id # Specifies the unique identifier of the version of the secret that you # want to retrieve. If you specify this parameter then don't specify @@ -1435,12 +1469,12 @@ # default, the list includes only versions that have at least one # staging label in `VersionStage` attached. # # <note markdown="1"> Always check the `NextToken` response parameter when calling any of # the `List*` operations. These operations can occasionally return an - # empty or shorter than expected list of results even when there are - # more results available. When this happens, the `NextToken` response + # empty or shorter than expected list of results even when there more + # results become available. When this happens, the `NextToken` response # parameter contains a value to pass to the next call to the same API to # request the next part of the list. # # </note> # @@ -1472,32 +1506,38 @@ # followed by six characters (before Secrets Manager adds the hyphen and # six characters to the ARN) and you try to use that as a partial ARN, # then those characters cause Secrets Manager to assume that you’re # specifying a complete ARN. This confusion can cause unexpected # results. To avoid this situation, we recommend that you don’t create - # secret names that end with a hyphen followed by six characters. + # secret names ending with a hyphen followed by six characters. # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # # </note> # # @option params [Integer] :max_results - # (Optional) Limits the number of results that you want to include in - # the response. If you don't include this parameter, it defaults to a - # value that's specific to the operation. If additional items exist - # beyond the maximum you specify, the `NextToken` response element is - # present and has a value (isn't null). Include that value as the - # `NextToken` request parameter in the next call to the operation to get - # the next part of the results. Note that Secrets Manager might return - # fewer results than the maximum even when there are more results - # available. You should check `NextToken` after every operation to - # ensure that you receive all of the results. + # (Optional) Limits the number of results you want to include in the + # response. If you don't include this parameter, it defaults to a value + # that's specific to the operation. If additional items exist beyond + # the maximum you specify, the `NextToken` response element is present + # and has a value (isn't null). Include that value as the `NextToken` + # request parameter in the next call to the operation to get the next + # part of the results. Note that Secrets Manager might return fewer + # results than the maximum even when there are more results available. + # You should check `NextToken` after every operation to ensure that you + # receive all of the results. # # @option params [String] :next_token # (Optional) Use this parameter in a request if you receive a - # `NextToken` response in a previous request that indicates that - # there's more output available. In a subsequent call, set it to the - # value of the previous call's `NextToken` response to indicate where - # the output should continue from. + # `NextToken` response in a previous request indicating there's more + # output available. In a subsequent call, set it to the value of the + # previous call `NextToken` response to indicate where the output should + # continue from. # # @option params [Boolean] :include_deprecated # (Optional) Specifies that you want the results to include versions # that do not have any staging labels attached to them. Such versions # are considered deprecated and are subject to deletion by Secrets @@ -1585,12 +1625,12 @@ # `SecretBinary` are not included in the output. To get that # information, call the GetSecretValue operation. # # <note markdown="1"> Always check the `NextToken` response parameter when calling any of # the `List*` operations. These operations can occasionally return an - # empty or shorter than expected list of results even when there are - # more results available. When this happens, the `NextToken` response + # empty or shorter than expected list of results even when there more + # results become available. When this happens, the `NextToken` response # parameter contains a value to pass to the next call to the same API to # request the next part of the list. # # </note> # @@ -1607,28 +1647,34 @@ # * To list the versions attached to a secret, use ListSecretVersionIds. # # ^ # # @option params [Integer] :max_results - # (Optional) Limits the number of results that you want to include in - # the response. If you don't include this parameter, it defaults to a - # value that's specific to the operation. If additional items exist - # beyond the maximum you specify, the `NextToken` response element is - # present and has a value (isn't null). Include that value as the - # `NextToken` request parameter in the next call to the operation to get - # the next part of the results. Note that Secrets Manager might return - # fewer results than the maximum even when there are more results - # available. You should check `NextToken` after every operation to - # ensure that you receive all of the results. + # (Optional) Limits the number of results you want to include in the + # response. If you don't include this parameter, it defaults to a value + # that's specific to the operation. If additional items exist beyond + # the maximum you specify, the `NextToken` response element is present + # and has a value (isn't null). Include that value as the `NextToken` + # request parameter in the next call to the operation to get the next + # part of the results. Note that Secrets Manager might return fewer + # results than the maximum even when there are more results available. + # You should check `NextToken` after every operation to ensure that you + # receive all of the results. # # @option params [String] :next_token # (Optional) Use this parameter in a request if you receive a - # `NextToken` response in a previous request that indicates that - # there's more output available. In a subsequent call, set it to the - # value of the previous call's `NextToken` response to indicate where - # the output should continue from. + # `NextToken` response in a previous request indicating there's more + # output available. In a subsequent call, set it to the value of the + # previous call `NextToken` response to indicate where the output should + # continue from. # + # @option params [Array<Types::Filter>] :filters + # Lists the secret request filters. + # + # @option params [String] :sort_order + # Lists secrets in the requested order. + # # @return [Types::ListSecretsResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::ListSecretsResponse#secret_list #secret_list} => Array&lt;Types::SecretListEntry&gt; # * {Types::ListSecretsResponse#next_token #next_token} => String # @@ -1673,10 +1719,17 @@ # @example Request syntax with placeholder values # # resp = client.list_secrets({ # max_results: 1, # next_token: "NextTokenType", + # filters: [ + # { + # key: "description", # accepts description, name, tag-key, tag-value, all + # values: ["FilterValueStringType"], + # }, + # ], + # sort_order: "asc", # accepts asc, desc # }) # # @example Response structure # # resp.secret_list #=> Array @@ -1696,10 +1749,11 @@ # resp.secret_list[0].tags[0].value #=> String # resp.secret_list[0].secret_versions_to_stages #=> Hash # resp.secret_list[0].secret_versions_to_stages["SecretVersionIdType"] #=> Array # resp.secret_list[0].secret_versions_to_stages["SecretVersionIdType"][0] #=> String # resp.secret_list[0].owning_service #=> String + # resp.secret_list[0].created_date #=> Time # resp.next_token #=> String # # @see http://docs.aws.amazon.com/goto/WebAPI/secretsmanager-2017-10-17/ListSecrets AWS API Documentation # # @overload list_secrets(params = {}) @@ -1729,11 +1783,11 @@ # # ^ # # **Related operations** # - # * To retrieve the resource policy that's attached to a secret, use + # * To retrieve the resource policy attached to a secret, use # GetResourcePolicy. # # * To delete the resource-based policy that's attached to a secret, # use DeleteResourcePolicy. # @@ -1757,12 +1811,18 @@ # followed by six characters (before Secrets Manager adds the hyphen and # six characters to the ARN) and you try to use that as a partial ARN, # then those characters cause Secrets Manager to assume that you’re # specifying a complete ARN. This confusion can cause unexpected # results. To avoid this situation, we recommend that you don’t create - # secret names that end with a hyphen followed by six characters. + # secret names ending with a hyphen followed by six characters. # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # # </note> # # @option params [required, String] :resource_policy # A JSON-formatted string that's constructed according to the grammar # and syntax for an AWS resource-based policy. The policy in the string @@ -1773,10 +1833,14 @@ # # # # [1]: http://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#cli-using-param-json # + # @option params [Boolean] :block_public_policy + # Makes an optional API call to Zelkova to validate the Resource Policy + # to prevent broad access to your secret. + # # @return [Types::PutResourcePolicyResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::PutResourcePolicyResponse#arn #arn} => String # * {Types::PutResourcePolicyResponse#name #name} => String # @@ -1799,10 +1863,11 @@ # @example Request syntax with placeholder values # # resp = client.put_resource_policy({ # secret_id: "SecretIdType", # required # resource_policy: "NonEmptyResourcePolicyType", # required + # block_public_policy: false, # }) # # @example Response structure # # resp.arn #=> String @@ -1848,33 +1913,33 @@ # and you specify the same secret data, the operation succeeds but # does nothing. However, if the secret data is different, then the # operation fails because you cannot modify an existing version; you # can only create new ones. # - # <note markdown="1"> * If you call an operation that needs to encrypt or decrypt the - # `SecretString` or `SecretBinary` for a secret in the same account as - # the calling user and that secret doesn't specify a AWS KMS - # encryption key, Secrets Manager uses the account's default AWS - # managed customer master key (CMK) with the alias - # `aws/secretsmanager`. If this key doesn't already exist in your - # account then Secrets Manager creates it for you automatically. All - # users and roles in the same AWS account automatically have access to - # use the default CMK. Note that if an Secrets Manager API call - # results in AWS having to create the account's AWS-managed CMK, it - # can result in a one-time significant delay in returning the result. + # <note markdown="1"> * If you call an operation to encrypt or decrypt the `SecretString` or + # `SecretBinary` for a secret in the same account as the calling user + # and that secret doesn't specify a AWS KMS encryption key, Secrets + # Manager uses the account's default AWS managed customer master key + # (CMK) with the alias `aws/secretsmanager`. If this key doesn't + # already exist in your account then Secrets Manager creates it for + # you automatically. All users and roles in the same AWS account + # automatically have access to use the default CMK. Note that if an + # Secrets Manager API call results in AWS creating the account's + # AWS-managed CMK, it can result in a one-time significant delay in + # returning the result. # - # * If the secret is in a different AWS account from the credentials - # calling an API that requires encryption or decryption of the secret - # value then you must create and use a custom AWS KMS CMK because you - # can't access the default CMK for the account using credentials from - # a different AWS account. Store the ARN of the CMK in the secret when - # you create the secret or when you update it by including it in the - # `KMSKeyId`. If you call an API that must encrypt or decrypt - # `SecretString` or `SecretBinary` using credentials from a different - # account then the AWS KMS key policy must grant cross-account access - # to that other account's user or role for both the - # kms:GenerateDataKey and kms:Decrypt operations. + # * If the secret resides in a different AWS account from the + # credentials calling an API that requires encryption or decryption of + # the secret value then you must create and use a custom AWS KMS CMK + # because you can't access the default CMK for the account using + # credentials from a different AWS account. Store the ARN of the CMK + # in the secret when you create the secret or when you update it by + # including it in the `KMSKeyId`. If you call an API that must encrypt + # or decrypt `SecretString` or `SecretBinary` using credentials from a + # different account then the AWS KMS key policy must grant + # cross-account access to that other account's user or role for both + # the kms:GenerateDataKey and kms:Decrypt operations. # # </note> # # **Minimum permissions** # @@ -1911,12 +1976,18 @@ # followed by six characters (before Secrets Manager adds the hyphen and # six characters to the ARN) and you try to use that as a partial ARN, # then those characters cause Secrets Manager to assume that you’re # specifying a complete ARN. This confusion can cause unexpected # results. To avoid this situation, we recommend that you don’t create - # secret names that end with a hyphen followed by six characters. + # secret names ending with a hyphen followed by six characters. # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # # </note> # # @option params [String] :client_request_token # (Optional) Specifies a unique identifier for the new version of the # secret. @@ -1942,11 +2013,11 @@ # # * If a version with this value already exists and that version's # `SecretString` or `SecretBinary` values are the same as those in the # request then the request is ignored (the operation is idempotent). # - # * If a version with this value already exists and that version's + # * If a version with this value already exists and the version of the # `SecretString` and `SecretBinary` values are different from those in # the request then the request fails because you cannot modify an # existing secret version. You can only create new versions to store # new secret values. # @@ -2104,12 +2175,18 @@ # followed by six characters (before Secrets Manager adds the hyphen and # six characters to the ARN) and you try to use that as a partial ARN, # then those characters cause Secrets Manager to assume that you’re # specifying a complete ARN. This confusion can cause unexpected # results. To avoid this situation, we recommend that you don’t create - # secret names that end with a hyphen followed by six characters. + # secret names ending with a hyphen followed by six characters. # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # # </note> # # @return [Types::RestoreSecretResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::RestoreSecretResponse#arn #arn} => String @@ -2167,12 +2244,12 @@ # begin to use the new version. For more information about rotating # secrets and how to configure a Lambda function to rotate the secrets # for your protected service, see [Rotating Secrets in AWS Secrets # Manager][1] in the *AWS Secrets Manager User Guide*. # - # Secrets Manager schedules the next rotation when the previous one is - # complete. Secrets Manager schedules the date by adding the rotation + # Secrets Manager schedules the next rotation when the previous one + # completes. Secrets Manager schedules the date by adding the rotation # interval (number of days) to the actual date of the last rotation. The # service chooses the hour within that 24-hour date window randomly. The # minute is also chosen somewhat randomly, but weighted towards the top # of the hour and influenced by a variety of factors that help # distribute load. @@ -2184,13 +2261,13 @@ # same version of the secret, or # # * The `AWSPENDING` staging label is not attached to any version of the # secret. # - # If instead the `AWSPENDING` staging label is present but is not - # attached to the same version as `AWSCURRENT` then any later invocation - # of `RotateSecret` assumes that a previous rotation request is still in + # If the `AWSPENDING` staging label is present but not attached to the + # same version as `AWSCURRENT` then any later invocation of + # `RotateSecret` assumes that a previous rotation request is still in # progress and returns an error. # # **Minimum permissions** # # To run this command, you must have the following permissions: @@ -2228,12 +2305,18 @@ # followed by six characters (before Secrets Manager adds the hyphen and # six characters to the ARN) and you try to use that as a partial ARN, # then those characters cause Secrets Manager to assume that you’re # specifying a complete ARN. This confusion can cause unexpected # results. To avoid this situation, we recommend that you don’t create - # secret names that end with a hyphen followed by six characters. + # secret names ending with a hyphen followed by six characters. # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # # </note> # # @option params [String] :client_request_token # (Optional) Specifies a unique identifier for the new version of the # secret that helps ensure idempotency. @@ -2244,12 +2327,12 @@ # parameter. If you don't use the SDK and instead generate a raw HTTP # request to the Secrets Manager service endpoint, then you must # generate a `ClientRequestToken` yourself for new versions and include # that value in the request. # - # You only need to specify your own value if you are implementing your - # own retry logic and want to ensure that a given secret is not created + # You only need to specify your own value if you implement your own + # retry logic and want to ensure that a given secret is not created # twice. We recommend that you generate a [UUID-type][1] value to ensure # uniqueness within the specified secret. # # Secrets Manager uses this value to prevent the accidental creation of # duplicate versions if there are failures and retries during the @@ -2316,20 +2399,20 @@ # # * Maximum value length—255 Unicode characters in UTF-8 # # * Tag keys and values are case sensitive. # - # * Do not use the `aws:` prefix in your tag names or values because it - # is reserved for AWS use. You can't edit or delete tag names or + # * Do not use the `aws:` prefix in your tag names or values because AWS + # reserves it for AWS use. You can't edit or delete tag names or # values with this prefix. Tags with this prefix do not count against # your tags per secret limit. # - # * If your tagging schema will be used across multiple services and - # resources, remember that other services might have restrictions on - # allowed characters. Generally allowed characters are: letters, - # spaces, and numbers representable in UTF-8, plus the following - # special characters: + - = . \_ : / @. + # * If you use your tagging schema across multiple services and + # resources, remember other services might have restrictions on + # allowed characters. Generally allowed characters: letters, spaces, + # and numbers representable in UTF-8, plus the following special + # characters: + - = . \_ : / @. # # If you use tags as part of your security strategy, then adding or # removing a tag can change permissions. If successfully completing this # operation would result in you losing your permissions for this secret, # then the operation is blocked and returns an Access Denied error. @@ -2363,12 +2446,18 @@ # followed by six characters (before Secrets Manager adds the hyphen and # six characters to the ARN) and you try to use that as a partial ARN, # then those characters cause Secrets Manager to assume that you’re # specifying a complete ARN. This confusion can cause unexpected # results. To avoid this situation, we recommend that you don’t create - # secret names that end with a hyphen followed by six characters. + # secret names ending with a hyphen followed by six characters. # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # # </note> # # @option params [required, Array<Types::Tag>] :tags # The tags to attach to the secret. Each element in the list consists of # a `Key` and a `Value`. @@ -2465,12 +2554,18 @@ # followed by six characters (before Secrets Manager adds the hyphen and # six characters to the ARN) and you try to use that as a partial ARN, # then those characters cause Secrets Manager to assume that you’re # specifying a complete ARN. This confusion can cause unexpected # results. To avoid this situation, we recommend that you don’t create - # secret names that end with a hyphen followed by six characters. + # secret names ending with a hyphen followed by six characters. # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # # </note> # # @option params [required, Array<String>] :tag_keys # A list of tag key names to remove from the secret. You don't specify # the value. Both the key and its associated value are removed. @@ -2537,33 +2632,33 @@ # # * If you include `SecretString` or `SecretBinary` to create a new # secret version, Secrets Manager automatically attaches the staging # label `AWSCURRENT` to the new version. # - # <note markdown="1"> * If you call an operation that needs to encrypt or decrypt the - # `SecretString` or `SecretBinary` for a secret in the same account as - # the calling user and that secret doesn't specify a AWS KMS - # encryption key, Secrets Manager uses the account's default AWS - # managed customer master key (CMK) with the alias - # `aws/secretsmanager`. If this key doesn't already exist in your - # account then Secrets Manager creates it for you automatically. All - # users and roles in the same AWS account automatically have access to - # use the default CMK. Note that if an Secrets Manager API call - # results in AWS having to create the account's AWS-managed CMK, it - # can result in a one-time significant delay in returning the result. + # <note markdown="1"> * If you call an operation to encrypt or decrypt the `SecretString` or + # `SecretBinary` for a secret in the same account as the calling user + # and that secret doesn't specify a AWS KMS encryption key, Secrets + # Manager uses the account's default AWS managed customer master key + # (CMK) with the alias `aws/secretsmanager`. If this key doesn't + # already exist in your account then Secrets Manager creates it for + # you automatically. All users and roles in the same AWS account + # automatically have access to use the default CMK. Note that if an + # Secrets Manager API call results in AWS creating the account's + # AWS-managed CMK, it can result in a one-time significant delay in + # returning the result. # - # * If the secret is in a different AWS account from the credentials - # calling an API that requires encryption or decryption of the secret - # value then you must create and use a custom AWS KMS CMK because you - # can't access the default CMK for the account using credentials from - # a different AWS account. Store the ARN of the CMK in the secret when - # you create the secret or when you update it by including it in the - # `KMSKeyId`. If you call an API that must encrypt or decrypt - # `SecretString` or `SecretBinary` using credentials from a different - # account then the AWS KMS key policy must grant cross-account access - # to that other account's user or role for both the - # kms:GenerateDataKey and kms:Decrypt operations. + # * If the secret resides in a different AWS account from the + # credentials calling an API that requires encryption or decryption of + # the secret value then you must create and use a custom AWS KMS CMK + # because you can't access the default CMK for the account using + # credentials from a different AWS account. Store the ARN of the CMK + # in the secret when you create the secret or when you update it by + # including it in the `KMSKeyId`. If you call an API that must encrypt + # or decrypt `SecretString` or `SecretBinary` using credentials from a + # different account then the AWS KMS key policy must grant + # cross-account access to that other account's user or role for both + # the kms:GenerateDataKey and kms:Decrypt operations. # # </note> # # **Minimum permissions** # @@ -2604,12 +2699,18 @@ # followed by six characters (before Secrets Manager adds the hyphen and # six characters to the ARN) and you try to use that as a partial ARN, # then those characters cause Secrets Manager to assume that you’re # specifying a complete ARN. This confusion can cause unexpected # results. To avoid this situation, we recommend that you don’t create - # secret names that end with a hyphen followed by six characters. + # secret names ending with a hyphen followed by six characters. # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # # </note> # # @option params [String] :client_request_token # (Optional) If you want to add a new version to the secret, this # parameter specifies a unique identifier for the new version that helps @@ -2841,13 +2942,13 @@ # # # [1]: https://docs.aws.amazon.com/secretsmanager/latest/userguide/terms-concepts.html#term_staging-label # # @option params [required, String] :secret_id - # Specifies the secret with the version whose list of staging labels you - # want to modify. You can specify either the Amazon Resource Name (ARN) - # or the friendly name of the secret. + # Specifies the secret with the version with the list of staging labels + # you want to modify. You can specify either the Amazon Resource Name + # (ARN) or the friendly name of the secret. # # <note markdown="1"> If you specify an ARN, we generally recommend that you specify a # complete ARN. You can specify a partial ARN too—for example, if you # don’t include the final hyphen and six random characters that Secrets # Manager adds at the end of the ARN when you created the secret. A @@ -2856,12 +2957,18 @@ # followed by six characters (before Secrets Manager adds the hyphen and # six characters to the ARN) and you try to use that as a partial ARN, # then those characters cause Secrets Manager to assume that you’re # specifying a complete ARN. This confusion can cause unexpected # results. To avoid this situation, we recommend that you don’t create - # secret names that end with a hyphen followed by six characters. + # secret names ending with a hyphen followed by six characters. # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # # </note> # # @option params [required, String] :version_stage # The staging label to add to this version. # @@ -2874,11 +2981,11 @@ # specify this parameter, or the version ID does not match, then the # operation fails. # # @option params [String] :move_to_version_id # (Optional) The secret version ID that you want to add the staging - # label to. If you want to remove a label from a version, then do not + # label. If you want to remove a label from a version, then do not # specify this parameter. # # If the staging label is already attached to a different version of the # secret, then you must also specify the `RemoveFromVersionId` # parameter. @@ -2964,10 +3071,90 @@ def update_secret_version_stage(params = {}, options = {}) req = build_request(:update_secret_version_stage, params) req.send_request(options) end + # Validates the JSON text of the resource-based policy document attached + # to the specified secret. The JSON request string input and response + # output displays formatted code with white space and line breaks for + # better readability. Submit your input as a single line JSON string. A + # resource-based policy is optional. + # + # @option params [String] :secret_id + # The identifier for the secret that you want to validate a resource + # policy. You can specify either the Amazon Resource Name (ARN) or the + # friendly name of the secret. + # + # <note markdown="1"> If you specify an ARN, we generally recommend that you specify a + # complete ARN. You can specify a partial ARN too—for example, if you + # don’t include the final hyphen and six random characters that Secrets + # Manager adds at the end of the ARN when you created the secret. A + # partial ARN match can work as long as it uniquely matches only one + # secret. However, if your secret has a name that ends in a hyphen + # followed by six characters (before Secrets Manager adds the hyphen and + # six characters to the ARN) and you try to use that as a partial ARN, + # then those characters cause Secrets Manager to assume that you’re + # specifying a complete ARN. This confusion can cause unexpected + # results. To avoid this situation, we recommend that you don’t create + # secret names ending with a hyphen followed by six characters. + # + # If you specify an incomplete ARN without the random suffix, and + # instead provide the 'friendly name', you *must* not include the + # random suffix. If you do include the random suffix added by Secrets + # Manager, you receive either a *ResourceNotFoundException* or an + # *AccessDeniedException* error, depending on your permissions. + # + # </note> + # + # @option params [required, String] :resource_policy + # Identifies the Resource Policy attached to the secret. + # + # @return [Types::ValidateResourcePolicyResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: + # + # * {Types::ValidateResourcePolicyResponse#policy_validation_passed #policy_validation_passed} => Boolean + # * {Types::ValidateResourcePolicyResponse#validation_errors #validation_errors} => Array&lt;Types::ValidationErrorsEntry&gt; + # + # + # @example Example: To validate a resource-based policy to a secret + # + # # The following example shows how to validate a resource-based policy to a secret. + # + # resp = client.validate_resource_policy({ + # resource_policy: "{\n\"Version\":\"2012-10-17\",\n\"Statement\":[{\n\"Effect\":\"Allow\",\n\"Principal\":{\n\"AWS\":\"arn:aws:iam::123456789012:root\"\n},\n\"Action\":\"secretsmanager:GetSecretValue\",\n\"Resource\":\"*\"\n}]\n}", + # secret_id: "MyTestDatabaseSecret", + # }) + # + # resp.to_h outputs the following: + # { + # policy_validation_passed: true, + # validation_errors: [ + # ], + # } + # + # @example Request syntax with placeholder values + # + # resp = client.validate_resource_policy({ + # secret_id: "SecretIdType", + # resource_policy: "NonEmptyResourcePolicyType", # required + # }) + # + # @example Response structure + # + # resp.policy_validation_passed #=> Boolean + # resp.validation_errors #=> Array + # resp.validation_errors[0].check_name #=> String + # resp.validation_errors[0].error_message #=> String + # + # @see http://docs.aws.amazon.com/goto/WebAPI/secretsmanager-2017-10-17/ValidateResourcePolicy AWS API Documentation + # + # @overload validate_resource_policy(params = {}) + # @param [Hash] params ({}) + def validate_resource_policy(params = {}, options = {}) + req = build_request(:validate_resource_policy, params) + req.send_request(options) + end + # @!endgroup # @param params ({}) # @api private def build_request(operation_name, params = {}) @@ -2977,10 +3164,10 @@ operation: config.api.operation(operation_name), client: self, params: params, config: config) context[:gem_name] = 'aws-sdk-secretsmanager' - context[:gem_version] = '1.39.0' + context[:gem_version] = '1.40.0' Seahorse::Client::Request.new(handlers, context) end # @api private # @deprecated