Criptografia do AWS KMS para parâmetros SecureString do AWS Systems Manager Parameter Store

Com o AWS Systems Manager Parameter Store, você pode criar parâmetros SecureString, que são parâmetros cujos nomes estão em texto sem formatação e os valores são criptografados. O Parameter Store usa o AWS KMS para criptografar e descriptografar os valores de parâmetro de parâmetros SecureString.

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

Para gerenciar dados confidenciais, é possível criar parâmetros SecureString. O Parameter Store usa o AWS KMS keys para criptografar os valores de parâmetros SecureString quando você os cria ou altera. Ele também usa chaves do KMS para descriptografar os valores do parâmetro quando você os acessa. É possível usar a Chave gerenciada pela AWS gerenciada que o Parameter Store cria para sua conta ou especificar sua própria chave gerenciada pelo cliente.

O Parameter Store oferece suporte a dois níveis de parâmetros de SecureString: 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 SecureString avançados, o Parameter Store usa a criptografia de envelope com o AWS Encryption SDK. Você pode converter um parâmetro de SecureString padrão para um parâmetro avançado, mas não pode converter um parâmetro avançado para um padrão. Para obter mais informações sobre a diferença entre parâmetros SecureString padrão e avançados, consulte Gerenciar camadas de parâmetros.

Proteger parâmetros SecureString padrão

O Parameter Store não executa nenhuma operação de criptografia. Em vez disso, ele se baseia no AWS KMS para criptografar e descriptografar valores de parâmetro SecureString. Quando você cria ou altera um valor de parâmetro SecureString padrão, o Parameter Store chama a operação do Criptografar do AWS KMS. 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.

É possível selecionar a chave do KMS que o Parameter Store usa para criptografar o valor do parâmetro. Se você não especificar uma chave do KMS, o Parameter Store usará a Chave gerenciada pela AWS criada automaticamente pelo Systems Manager 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 SecureString 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.

O Parameter Store então chama a operação Encrypt do AWS KMS com a chave do KMS e o valor do parâmetro em texto não criptografado. 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 SecureString. Como o comando omite os parâmetros --tier e --key-id opcionais, o Parameter Store cria um parâmetro SecureString 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 Parameter Store cria um parâmetro de SecureString padrão, 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 SecureString do Parameter Store, seu valor é 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 do Parameter Store sem descriptografar seu valor.

aws ssm get-parameter --name MyParameter

{
    "Parameter": {
        "Type": "SecureString", 
        "Name": "MyParameter", 
        "Value": "AQECAHgnOkMROh5LaLXkA4j0+vYi6tmM17Lg"
    }
}

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 Descriptografar do AWS KMS em seu nome para descriptografar o valor do 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 SecureString padrão.

Criptografar um parâmetro padrão

Descriptografar um parâmetro padrão

Proteger parâmetros SecureString avançados

Quando você usa o PutParameter para criar um parâmetro SecureString avançado, o Parameter Store usa a criptografia de envelope com o AWS Encryption SDK e uma AWS KMS key de criptografia simétrica para proteger o valor de 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 SecureString, o Parameter Store chama o AWS Encryption SDK para criptografar o valor do parâmetro usando uma chave de dados exclusiva que o AWS KMS gera (GenerateDataKey). O AWS Encryption SDK retorna para o 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 de parâmetro de SecureString. Quando você obtém um parâmetro de SecureString avançado, Parameter Store usa o valor AWS Encryption SDK para descriptografar o valor de parâmetro. Isso requer uma chamada para o AWS KMS descriptografar a chave de dados criptografada.

Para criar um parâmetro SecureString 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-east-2:987654321098:key/1234abcd-12ab-34cd-56ef-1234567890ab

Quando você obtém um parâmetro de SecureString o Parameter Store, seu valor é a mensagem criptografada que o AWS Encryption SDK retornou. 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 do Parameter Store sem descriptografar seu valor.

aws ssm get-parameter --name MyParameter

{
    "Parameter": {
        "Type": "SecureString", 
        "Name": "MyParameter", 
        "Value": "AQECAHgnOkMROh5LaLXkA4j0+vYi6tmM17Lg"
    }
}

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 Descriptografar do AWS KMS em seu nome para descriptografar o valor do 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 SecureString avançado para um padrão, mas pode converter um SecureString padrão para um avançado. Para converter um parâmetro de SecureString padrão para um de SecureString avançado, 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ê o omitir, o Parameter Store usará a Chave gerenciada pela AWS para a 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 de 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 SecureString avançado.

Criptografar um parâmetro avançado

Descriptografar um parâmetro avançado

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

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

É possível usar políticas do AWS Identity and Access Management (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âmetros SecureString, você poderá usar políticas do IAM e políticas de chaves para gerenciar permissões de criptografia e descriptografia. 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 sobre como controlar o acesso a chaves gerenciadas pelo cliente, consulte Acesso e permissões de chaves do KMS no Guia do desenvolvedor do AWS Key Management Service.

O exemplo a seguir mostra uma política do IAM criada para parâmetros SecureString 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-east-2:111122223333:parameter/FinancialParameters/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "kms:Encrypt"
            ],
            "Resource": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
        }
    ]
}

O exemplo seguinte mostra uma política do IAM criada para parâmetros SecureString 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-east-2:111122223333:parameter/ReservedParameters/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "kms:GenerateDataKey"
            ],
            "Resource": "arn:aws:kms:us-east-2:987654321098: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 SecureString 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-east-2:111122223333:parameter/ITParameters/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": "arn:aws:kms:us-east-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 ele lide com ele de forma 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, ao descriptografar dados, o AWS Encryption SDK obté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 de parâmetro de texto simples para você.

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

O formato do contexto de criptografia é o seguinte:

"PARAMETER_ARN":"arn:aws:ssm:region-id: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 região e Conta da AWS.

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

Se o parâmetro estiver em um caminho hierárquico do Parameter Store, o caminho e o nome serã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-east-2:111122223333:parameter/ReadableParameters/MyParameter"

Você pode descriptografar um valor de parâmetro SecureString criptografado chamando a operação do AWS KMS Decrypt com o contexto de criptografia correto e o valor de parâmetro criptografado retornado pela operação GetParameter do Systems Manager. No entanto, recomendamos que você descriptografe valores de parâmetro 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-east-2:111122223333:parameter/MyParameter"
        },
        {
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": "arn:aws:kms:us-east-2:987654321098:key/1234abcd-12ab-34cd-56ef-1234567890ab",
            "Condition": {
                "StringEquals": {
                    "kms:EncryptionContext:PARAMETER_ARN":"arn:aws:ssm:us-east-2:111122223333:parameter/MyParameter"
                }
            }
        }
    ]
}

Solucionar problemas de chaves do KMS no Parameter Store

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