Como o AWS Systems Manager Parameter Store usa o AWS KMS - AWS Key Management Service

Como o AWS Systems Manager Parameter Store usa o AWS KMS

Com o AWS Systems Manager Parameter Store, você pode criar parâmetros de string segura, que são parâmetros com um nome de parâmetro em texto simples e um valor de parâmetro criptografado. O Parameter Store usa o AWS KMS para criptografar e descriptografar os valores de parâmetros de parâmetros de string segura.

Com o Parameter Store, você pode criar, armazenar e gerenciar dados como parâmetros com valores. Você pode criar um parâmetro no Parameter Store e usá-lo em várias aplicações e serviços, de acordo com as políticas e as permissões que você define. Quando precisa alterar um valor de parâmetro, você altera uma instância, em vez de gerenciar uma alteração passível de erros em várias origens. O Parameter Store é compatível com uma estrutura hierárquica para nomes de parâmetros, de modo que você pode qualificar um parâmetro para usos específicos.

Para gerenciar dados confidenciais, crie parâmetros de string segura. O Parameter Store usa chaves do AWS KMS keys para criptografar os valores de parâmetros de string segura quando você os cria ou altera. Ele também usa chaves do KMS para descriptografar os valores do parâmetro quando você os acessa. Você pode usar a Chave gerenciada pela AWS criada pelo Parameter Store para sua conta ou especificar sua própria chave gerenciada pelo cliente.

Importante

O Parameter Store apenas é compatível com chaves do KMS simétricas. Não é possível usar uma chave do KMS assimétrica para criptografar os parâmetros. Para obter ajuda para determinar se uma chave do KMS é simétrica ou assimétrica, consulte Identificar chaves do KMS assimétricas.

O repositório de parâmetros oferece suporte a dois níveis de parâmetros de string segura: padrão e avançado. Parâmetros padrão, que não podem exceder 4.096 bytes, são criptografados e descriptografados diretamente na chave do KMS especificada. Para criptografar e descriptografar parâmetros de string segura avançados, o Parameter Store usa a criptografia de envelope com o AWS Encryption SDK. Você pode converter um parâmetro de string segura padrão em um parâmetro avançado, mas não pode converter um parâmetro avançado em um padrão. Para obter mais informações sobre a diferença entre parâmetros de string segura padrão e avançados, consulte Sobre parâmetros avançados do Systems Manager, no Manual do usuário do AWS Systems Manager.

Proteger parâmetros de string segura padrão

O Parameter Store não executa operações de criptografia. Em vez disso, ele se baseia no AWS KMS para criptografar e descriptografar valores de parâmetros de string segura. Quando você cria ou altera um valor de parâmetro de string segura padrão, o Parameter Store chama a operação do AWS KMS Encrypt. Essa operação usa uma chave do KMS de criptografia simétrica diretamente para criptografar o valor do parâmetro em vez de usar a chave do KMS para gerar uma chave de dados.

Você pode selecionar a chave do KMS que o Parameter Store usa para criptografar o valor de parâmetro. Se você não especificar uma chave do KMS, o Parameter Store usará a Chave gerenciada pela AWS que o Systems Manager cria automaticamente na sua conta. Essa chave do KMS tem o alias aws/ssm.

Para visualizar a chave do KMS padrão do aws/ssm da sua conta, use a operação DescribeKey na API do AWS KMS. O exemplo a seguir usa o comando describe-key na AWS Command Line Interface (AWS CLI) com o nome de alias aws/ssm.

aws kms describe-key --key-id alias/aws/ssm

Para criar um parâmetro de string segura padrão, use a operação PutParameter na API do Systems Manager. Omita o parâmetro de Tier ou especifique um valor de Standard, que é o padrão. Inclua um parâmetro Type com um valor de SecureString. Para especificar uma chave do KMS, use o parâmetro KeyId. O padrão é a Chave gerenciada pela AWS para sua conta, aws/ssm.

Depois, o Parameter Store chama a operação Encrypt do AWS KMS com a chave do KMS e o valor do parâmetro em texto simples. O AWS KMS retorna o valor do parâmetro criptografado, que o Parameter Store armazena com o nome do parâmetro.

O exemplo a seguir usa o comando put-parameter do Systems Manager e seu parâmetro --type na AWS CLI para criar um parâmetro de string segura. Como o comando omite os parâmetros --tier e --key-id opcionais, o Parameter Store cria um parâmetro de string segura padrão e o criptografa com a Chave gerenciada pela AWS

aws ssm put-parameter --name MyParameter --value "secret_value" --type SecureString

O exemplo semelhante a seguir usa o parâmetro --key-id para especificar uma chave gerenciada pelo cliente. O exemplo usa um ID de chave do KMS para identificar a chave do KMS, mas você pode usar qualquer identificador de chave do KMS válido. Como o comando omite o parâmetro Tier (--tier), o cria um parâmetro de string segura padrão, e não um avançado.

aws ssm put-parameter --name param1 --value "secret" --type SecureString --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Quando você obtém um parâmetro de string segura do Parameter Store, seu valor está criptografado. Para obter um parâmetro, use a operação GetParameter na API do Systems Manager.

O exemplo a seguir usa o comando get-parameter do Systems Manager na AWS CLI para obter o parâmetro MyParameter no Parameter Store sem descriptografar seu valor.

$ aws ssm get-parameter --name MyParameter { "Parameter": { "Type": "SecureString", "Name": "MyParameter", "Value": "AQECAHgnOkMROh5LaLXkA4j0+vYi6tmM17Lg/9E464VRo68cvwAAAG8wbQYJKoZIhvcNAQcGoGAwXgIBADBZBgkqhkiG9w0BBwEwHgYJYZZIAWUDBAEuMBEEDImYOw44gna0Jm00hAIBEIAsjgr7mum1EnnXzE3xM8bGle0oKYcfVCHtBkfjIeZGTgL6Hg0fSDnpMHdcSXY=" } }

Para descriptografar o valor de parâmetro antes de retorná-lo, defina o parâmetro WithDecryption de GetParameter como true. Quando você usa WithDecryption, o Parameter Store chama a operação do AWS KMS Decrypt em seu nome para descriptografar o valor de parâmetro. Como resultado, a solicitação de GetParameter retorna o parâmetro com um valor de parâmetro de texto simples, como mostrado no exemplo a seguir.

$ aws ssm get-parameter --name MyParameter --with-decryption { "Parameter": { "Type": "SecureString", "Name": "MyParameter", "Value": "secret_value" } }

O fluxo de trabalho a seguir mostra como o Parameter Store usa uma chave do KMS para criptografar e descriptografar um parâmetro de string segura padrão.

Criptografar um parâmetro padrão

  1. Quando você usa PutParameter para criar um parâmetro de string segura, o Parameter Store envia uma solicitação Encrypt ao AWS KMS. Essa solicitação inclui o valor do parâmetro em texto simples e a chave do KMS que você escolheu e o contexto de criptografia do Parameter Store. Durante a transmissão ao AWS KMS, o valor em texto não criptografado no parâmetro de string segura é protegido pelo Transport Layer Security (TLS).

  2. O AWS KMS criptografa o valor de parâmetro com a chave do KMS especificada e o contexto de criptografia. Ele retorna o texto cifrado ao Parameter Store, que armazena o nome de parâmetro e seu valor criptografado.

    
              Criptografar um valor de parâmetro de string segura padrão

Descriptografar parâmetros padrão

  1. Quando você inclui o parâmetro WithDecryption em uma solicitação GetParameter, o Parameter Store envia uma solicitação Decrypt ao AWS KMS com o valor do parâmetro de string segura e o contexto de criptografia do Parameter Store.

  2. O AWS KMS usa a mesma chave do KMS e o contexto de criptografia fornecido para descriptografar o valor criptografado. Ele retorna o valor do parâmetro em texto simples (descriptografado) ao Parameter Store. Durante a transmissão, os dados em texto simples são protegidos por TLS.

  3. O Parameter Store retorna o valor do parâmetro em texto simples na resposta de GetParameter.

Proteger parâmetros de string segura avançados

Quando você usa PutParameter para criar um parâmetro de string segura avançado, o Parameter Store usa criptografia de envelope com o AWS Encryption SDK e uma AWS KMS key de criptografia simétrica para proteger o valor do parâmetro. Cada valor de parâmetro avançado é criptografado com uma chave de dados exclusiva, e a chave de dados é criptografada em uma chave do KMS. É possível usar a Chave gerenciada pela AWS para a conta (aws/ssm) ou qualquer chave gerenciada pelo cliente.

O AWS Encryption SDK é uma biblioteca no lado do cliente de software livre que ajuda você a criptografar e descriptografar dados usando padrões do setor e práticas recomendadas. Ele é compatível com várias plataformas e várias linguagens de programação, incluindo uma interface de linha de comando. Você pode visualizar o código-fonte e contribuir para o desenvolvimento no GitHub.

Para cada valor de parâmetro de string segura, o Parameter Store chama o AWS Encryption SDK para criptografar o valor do parâmetro usando uma chave de dados exclusiva gerada pelo AWS KMS (GenerateDataKey). O AWS Encryption SDK retorna ao Parameter Store uma mensagem criptografada que inclui o valor de parâmetro criptografado e uma cópia criptografada da chave de dados exclusiva. O Parameter Store armazena toda a mensagem criptografada no valor do parâmetro de string segura. Quando você obtém um parâmetro de string segura avançado, o Parameter Store usa o AWS Encryption SDK para descriptografar o valor do parâmetro. Isso requer uma chamada para o AWS KMS descriptografar a chave de dados criptografada.

Para criar um parâmetro de string segura avançado, use a operação PutParameter na API do Systems Manager. Defina o valor do parâmetro Tier como Advanced. Inclua um parâmetro Type com um valor de SecureString. Para especificar uma chave do KMS, use o parâmetro KeyId. O padrão é a Chave gerenciada pela AWS para sua conta, aws/ssm.

aws ssm put-parameter --name MyParameter --value "secret_value" --type SecureString --tier Advanced

O exemplo semelhante a seguir usa o parâmetro --key-id para especificar uma chave gerenciada pelo cliente. O exemplo usa o Amazon Resource Name (ARN) da chave do KMS, mas você pode usar qualquer identificador válido de chave do KMS.

aws ssm put-parameter --name MyParameter --value "secret_value" --type SecureString --tier Advanced --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

Quando você obtém um parâmetro de string segura do Parameter Store, seu valor é a mensagem criptografada que é retornado pelo AWS Encryption SDK. Para obter um parâmetro, use a operação GetParameter na API do Systems Manager.

O exemplo a seguir usa a operação GetParameter do Systems Manager para obter o parâmetro MyParameter no Parameter Store sem descriptografar seu valor.

$ aws ssm get-parameter --name MyParameter { "Parameter": { "Type": "SecureString", "Name": "MyParameter", "Value": "AQECAHgnOkMROh5LaLXkA4j0+vYi6tmM17Lg/9E464VRo68cvwAAAG8wbQYJKoZIhvcNAQcGoGAwXgIBADBZBgkqhkiG9w0BBwEwHgYJYZZIAWUDBAEuMBEEDImYOw44gna0Jm00hAIBEIAsjgr7mum1EnnXzE3xM8bGle0oKYcfVCHtBkfjIeZGTgL6Hg0fSDnpMHdcSXY=" } }

Para descriptografar o valor de parâmetro antes de retorná-lo, defina o parâmetro WithDecryption de GetParameter como true. Quando você usa WithDecryption, o Parameter Store chama a operação do AWS KMS Decrypt em seu nome para descriptografar o valor de parâmetro. Como resultado, a solicitação de GetParameter retorna o parâmetro com um valor de parâmetro de texto simples, como mostrado no exemplo a seguir.

$ aws ssm get-parameter --name MyParameter --with-decryption { "Parameter": { "Type": "SecureString", "Name": "MyParameter", "Value": "secret_value" } }

Você não pode converter um parâmetro de string segura avançado em um padrão, mas pode converter uma string segura padrão em uma avançada. Para converter um parâmetro de string segura padrão em uma string segura avançada, use a operação PutParameter com o parâmetro Overwrite. O Type deve ser SecureString, e o valor Tier deve ser Advanced. O parâmetro KeyId, que identifica uma chave gerenciada pelo cliente, é opcional. Se você omiti-lo, o Parameter Store usará a Chave gerenciada pela AWS da conta. É possível especificar qualquer chave do KMS que a entidade principal tenha permissão para usar, mesmo se você tiver usado uma chave do KMS diferente para criptografar o parâmetro padrão.

Quando você usa o parâmetro Overwrite, o Parameter Store usa o AWS Encryption SDK para criptografar o valor do parâmetro. Ele armazena a mensagem recém-criptografada no Parameter Store.

$ aws ssm put-parameter --name myStdParameter --value "secret_value" --type SecureString --tier Advanced --key-id 1234abcd-12ab-34cd-56ef-1234567890ab --overwrite

O fluxo de trabalho a seguir mostra como o Parameter Store usa uma chave do KMS para criptografar e descriptografar um parâmetro de string segura avançado.

Criptografar um parâmetro avançado

  1. Quando você usa o PutParameter para criar um parâmetro de string segura avançado, o Parameter Store usa o AWS Encryption SDK e o AWS KMS para criptografar o valor do parâmetro. O Parameter Store chama o AWS Encryption SDK com o valor do parâmetro, a chave do KMS que você especificou e a contexto de criptografia do Parameter Store.

  2. O AWS Encryption SDK envia uma solicitação GenerateDataKey ao AWS KMS com o identificador da chave do KMS especificada e o contexto de criptografia do Parameter Store. O AWS KMS retorna duas cópias da chave de dados exclusiva: uma em texto simples e uma criptografada na chave do KMS. (O contexto de criptografia é usado ao criptografar a chave de dados.)

  3. O AWS Encryption SDK usa a chave de dados em texto simples para criptografar valor de parâmetro. Ele retorna uma mensagem criptografada que inclui o valor do parâmetro criptografado, a chave de dados criptografada e outros dados, incluindo o contexto criptografia do Parameter Store.

  4. O Parameter Store armazena a mensagem criptografada como o valor do parâmetro.

    
              Criptografar um valor de parâmetro de string segura

Descriptografar um parâmetro avançado

  1. Você pode incluir o parâmetro WithDecryption em uma solicitação GetParameter para obter um parâmetro de string segura avançado. Quando você fizer isso, o Parameter Store repassará a mensagem criptografada do valor de parâmetro para um método de descriptografia do AWS Encryption SDK.

  2. O AWS Encryption SDK chama a operação do AWS KMS Decrypt. Ele repassa a chave de dados criptografada e o contexto de criptografia do Parameter Store da mensagem criptografada.

  3. O AWS KMS usa a chave do KMS e o contexto de criptografia do Parameter Store para descriptografar a chave de dados criptografada. Ele retorna a chave de dados de texto simples (descriptografada) ao AWS Encryption SDK.

  4. O AWS Encryption SDK usa a chave de dados de texto simples para descriptografar o valor de parâmetro. Ele retorna o valor do parâmetro em texto simples ao Parameter Store.

  5. O Parameter Store verifica o contexto de criptografia e retorna a você o valor de parâmetro em texto simples na resposta GetParameter.

Definir permissões para criptografar e descriptografar valores de parâmetro

Para criptografar um valor de parâmetro de string segura padrão, o usuário precisa da permissão kms:Encrypt. Para criptografar um valor de parâmetro de string segura avançado, o usuário precisa da permissão kms:GenerateDataKey. Para descriptografar qualquer tipo de valor de parâmetro de string segura, o usuário precisa da permissão kms:Decrypt.

Você pode usar políticas do IAM para permitir ou negar permissão para um usuário chamar as operações PutParameter e GetParameter do Systems Manager.

Além disso, se estiver usando chaves gerenciadas pelo cliente para criptografar seus valores de parâmetro de string segura, você poderá usar políticas do IAM e políticas de chaves para criptografar e descriptografar permissões. No entanto, você não pode estabelecer políticas de controle de acesso para a chave do KMS aws/ssm padrão. Para obter informações detalhadas sobre o como controlar o acesso a chaves gerenciadas pelo cliente, consulte Autenticação e controle de acesso para o AWS KMS.

O exemplo a seguir mostra uma política do IAM criada para parâmetros de string padrão. Ela permite que o usuário chame a operação PutParameter do Systems Manager em todos os parâmetros no caminho FinancialParameters. A política também permite que o usuário chame a operação do AWS KMS Encrypt em um exemplo de chave gerenciada pelo cliente.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:PutParameter" ], "Resource": "arn:aws:ssm:us-west-2:111122223333:parameter/FinancialParameters/*" }, { "Effect": "Allow", "Action": [ "kms:Encrypt" ], "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" } ] }

O exemplo a seguir mostra uma política do IAM criada para parâmetros de string segura avançados. Ela permite que o usuário chame a operação PutParameter do Systems Manager em todos os parâmetros no caminho ReservedParameters. A política também permite que o usuário chame a operação do AWS KMS GenerateDataKey em um exemplo de chave gerenciada pelo cliente.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:PutParameter" ], "Resource": "arn:aws:ssm:us-west-2:111122223333:parameter/ReservedParameters/*" }, { "Effect": "Allow", "Action": [ "kms:GenerateDataKey" ], "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" } ] }

O último exemplo também mostra uma política do IAM que pode ser usada para parâmetros de string segura padrão ou avançados. Ela permite que o usuário chame as operações GetParameter do Systems Manager (e operações relacionadas) em todos os parâmetros no caminho de ITParameters. A política também permite que o usuário chame a operação do AWS KMS Decrypt em um exemplo de chave gerenciada pelo cliente.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:GetParameter*" ], "Resource": "arn:aws:ssm:us-west-2:111122223333:parameter/ITParameters/*" }, { "Effect": "Allow", "Action": [ "kms:Decrypt" ], "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" } ] }

Contexto de criptografia do Parameter Store

Um contexto de criptografia é um conjunto de pares de chave-valor que contêm dados arbitrários não secretos. Quando você inclui um contexto de criptografia em uma solicitação para criptografar dados, o AWS KMS vincula de forma criptográfica o contexto de criptografia aos dados criptografados. Para descriptografar os dados, você deve passar o mesmo contexto de criptografia.

Você também pode usar o contexto de criptografia para identificar uma operação de criptografia em registros de auditoria e logs. O contexto de criptografia aparece em texto simples em logs, como logs do AWS CloudTrail.

O AWS Encryption SDK também obtém um contexto de criptografia, embora lide com ele de maneira diferente. O Parameter Store fornece o contexto de criptografia para o método de criptografia. O AWS Encryption SDK vincula forma criptográfica o contexto de criptografia aos dados criptografados. Isso inclui o contexto de criptografia em texto simples no cabeçalho da mensagem criptografada retornada por ele. No entanto, ao contrário do AWS KMS, os métodos de descriptografia do AWS Encryption SDK não têm um contexto de criptografia como entrada. Em vez disso, quando ele descriptografa dados, o AWS Encryption SDKobtém o contexto de criptografia na mensagem criptografada. O Parameter Store verifica se o contexto de criptografia inclui o valor que ele espera antes de retornar o valor do parâmetro em texto simples para você.

O Parameter Store usa o seguinte contexto de criptografia em suas operações de criptografia:

  • Chave: PARAMETER_ARN

  • Valor: O Amazon Resource Name (ARN) do parâmetro que está sendo criptografado.

O formato do contexto de criptografia é o seguinte:

"PARAMETER_ARN":"arn:aws:ssm:<REGION_NAME>:<ACCOUNT_ID>:parameter/<parameter-name>"

Por exemplo, o Parameter Store inclui esse contexto de criptografia em chamadas para criptografar e descriptografar o parâmetro MyParameter em um exemplo de Conta da AWS e região.

"PARAMETER_ARN":"arn:aws:ssm:us-west-2:111122223333:parameter/MyParameter"

Se o parâmetro estiver em um caminho hierárquico do Parameter Store, o caminho e o nome são incluídos no contexto de criptografia. Por exemplo, esse contexto de criptografia é usado ao criptografar ou descriptografar o parâmetro MyParameter no caminho /ReadableParameters em um exemplo de Conta da AWS e região.

"PARAMETER_ARN":"arn:aws:ssm:us-west-2:111122223333:parameter/ReadableParameters/MyParameter"

Você pode descriptografar um valor de parâmetro de string segura criptografado chamando a operação Decrypt do AWS KMS com o contexto de criptografia correto e o valor do parâmetro criptografado que a operação GetParameter do Systems Manager retorna. No entanto, recomendamos que você descriptografe valores de parâmetros do Parameter Store usando a operação GetParameter com o parâmetro WithDecryption.

Você também pode incluir o contexto de criptografia em uma política do IAM. Por exemplo, você pode permitir que um usuário descriptografe apenas determinado valor de parâmetro ou conjunto de valores de parâmetro.

O exemplo a seguir de declaração de política do IAM permite que o usuário obtenha o valor do parâmetro MyParameter e descriptografe o valor usando a chave do KMS especificada. No entanto, as permissões são aplicáveis somente quando o contexto de criptografia corresponde à string especificada. Essas permissões não são aplicáveis a nenhum outro parâmetro ou chave do KMS, e ocorrerá falha na chamada para GetParameter se o contexto de criptografia não corresponder à string.

Antes de usar uma declaração de política como essa, substitua os ARNs de exemplo por valores válidos.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:GetParameter*" ], "Resource": "arn:aws:ssm:us-west-2:111122223333:parameter/MyParameter" }, { "Effect": "Allow", "Action": [ "kms:Decrypt" ], "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "Condition": { "StringEquals": { "kms:EncryptionContext:PARAMETER_ARN":"arn:aws:ssm:us-west-2:111122223333:parameter/MyParameter" } } } ] }

Solução de problemas com chaves do KMS no Parameter Store

Para executar qualquer operação em um parâmetro de string segura, o Parameter Store deve ser capaz de usar a chave do KMS do AWS KMS que você especifica para a operação desejada. A maioria das falhas do Parameter Store relacionadas a chaves do KMS é causada pelos seguintes problemas:

  • As credenciais que uma aplicação está usando não têm permissão para executar a ação especificada na chave do KMS.

    Para corrigir este erro, execute a aplicação com credenciais diferentes ou revise a política da IAM ou de chaves que está impedindo a operação. Para obter ajuda com políticas do IAM e chaves do AWS KMS, consulte Autenticação e controle de acesso para o AWS KMS.

  • A chave do KMS não foi encontrada.

    Isso geralmente acontece quando você usa um identificador incorreto para a chave do KMS. Encontre os identificadores corretos para a chave do KMS e tente o comando novamente.

  • A chave do KMS não está habilitada. Quando isso ocorre, o Parameter Store retorna uma exceção InvalidKeyId com uma mensagem de erro detalhada do AWS KMS. Se o estado da chave do KMS for Disabled, habilite-a. Se for Pending Import, conclua o procedimento de importação. Se o estado da chave for Pending Deletion, cancele a exclusão da chave ou use uma chave do KMS diferente.

    Para encontrar o estado de chave de uma chave do KMS no console do AWS KMS, na página Customer managed keys (Chaves gerenciadas pelo cliente) ou Chaves gerenciadas pela AWS, consulte a coluna Status. Para usar uma API do AWS KMS para localizar o status de uma chave do KMS, use a operação DescribeKey.