Cifrado de AWS KMS para los parámetros SecureString del Parameter Store de AWS Systems Manager

Con el Parameter Store de AWS Systems Manager, puede crear parámetros SecureString, que son parámetros que tienen un nombre de parámetro en texto no cifrado y un valor de parámetro cifrado. El Parameter Store utiliza AWS KMS para cifrar y descifrar los valores de los parámetros SecureString.

Con el Parameter Store, puede crear, almacenar y administrar datos como parámetros con valores. Puede crear un parámetro en Parameter Store y utilizarlo en varias aplicaciones y servicios de acuerdo con las políticas y los permisos que diseñe. Cuando necesite cambiar el valor de un parámetro, cambiará una instancia, y no tendrá que administrar una modificación propensa a errores en varios orígenes. Parameter Store admite una estructura jerárquica para los nombres de los parámetros, por lo que puede asignar un parámetro para usos específicos.

Para administrar información confidencial, puede crear parámetros SecureString. El Parameter Store utiliza AWS KMS keys para cifrar los valores de los parámetros SecureString cuando estos se crean o se modifican. También utiliza claves KMS para descifrar los valores de los parámetros cuando se obtiene acceso a ellos. Puede utilizar la Clave administrada de AWS que el Parameter Store crea para su cuenta o especificar su propia clave administrada por el cliente.

Parameter Store admite dos niveles de SecureString parámetros: estándar y avanzados. Los parámetros estándar, que no pueden superar los 4096 bytes, se cifran y descifran directamente con la clave KMS que especifique. Para cifrar y descifrar parámetros SecureString avanzados, Parameter Store utiliza el cifrado de sobre con el AWS Encryption SDK. Puede convertir un parámetro SecureString estándar en un parámetro avanzado, pero no puede convertir un parámetro avanzado en uno estándar. Para obtener más información acerca de la diferencia entre los parámetros SecureString estándar y avanzados, consulte Administración de niveles de parámetros.

Protección de los parámetros SecureString estándar

Parameter Store no realiza ninguna operación criptográfica. En lugar de ello, utiliza AWS KMS para cifrar y descifrar los valores de los parámetros SecureString. Cuando se crea o cambia el valor de un parámetro SecureString estándar, el Parameter Store llama a la operación Encrypt de AWS KMS. Esta operación utiliza directamente una clave KMS de cifrado simétrica para cifrar el valor del parámetro en lugar de utilizar la clave KMS para generar una clave de datos.

Puede seleccionar la clave de KMS que utiliza el Parameter Store para cifrar el valor del parámetro. Si no especifica una clave de KMS, el Parameter Store utiliza la Clave administrada de AWS que Systems Manager crea automáticamente en su cuenta. Esta clave KMS tiene el alias aws/ssm.

Si desea ver la clave KMS aws/ssm predeterminada de su cuenta, utilice la operación DescribeKey de la API de AWS KMS. El siguiente ejemplo utiliza el comando describe-key de la AWS Command Line Interface (AWS CLI) con el nombre de alias aws/ssm.

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

Para crear un parámetro SecureString estándar, utilice la operación PutParameter de la API de Systems Manager. Omita el parámetro Tier o especifique un valor de Standard, que es el valor predeterminado. Incluya un parámetro Type con el valor SecureString. Para especificar una clave KMS, utilice el parámetro KeyId. El valor predeterminado es la Clave administrada de AWS de su cuenta, aws/ssm.

A continuación, el Parameter Store llama a la operación Encrypt de AWS KMS con la clave de KMS y el valor del parámetro en texto no cifrado. AWS KMS devuelve el valor del parámetro cifrado y el Parameter Store lo almacena junto con el nombre del parámetro.

El siguiente ejemplo utiliza el comando put-parameter de Systems Manager y su parámetro --type en la AWS CLI para crear un parámetro SecureString. Como el comando omite los parámetros opcionales --tier y --key-id, el Parameter Store crea un parámetro SecureString estándar y lo cifra con la Clave administrada de AWS.

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

El siguiente ejemplo similar utiliza el parámetro --key-id para especificar una clave KMS administrada por el cliente. En el ejemplo se utiliza un ID de clave KMS para identificar la clave KMS, pero se puede utilizar cualquier identificador de clave KMS válido. Como el comando omite el parámetro Tier (--tier), Parameter Store crea un parámetro SecureString estándar, no uno avanzado.

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

Cuando se obtiene un parámetro SecureString de Parameter Store, su valor está cifrado. Para obtener un parámetro, utilice la operación GetParameter de la API de Systems Manager.

El siguiente ejemplo utiliza el comando get-parameter de Systems Manager en la AWS CLI para obtener el parámetro MyParameter del Parameter Store sin descifrar su valor.

aws ssm get-parameter --name MyParameter

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

Para descifrar el valor del parámetro antes de devolverlo, establezca el parámetro WithDecryption de GetParameter en true. Al utilizar WithDecryption, el Parameter Store llama a la operación Decrypt de AWS KMS en su nombre para descifrar el valor del parámetro. En consecuencia, la solicitud GetParameter devuelve el parámetro con un valor en texto no cifrado, tal y como se muestra en el siguiente ejemplo.

aws ssm get-parameter \
    --name MyParameter \
    --with-decryption

{
    "Parameter": {
        "Type": "SecureString", 
        "Name": "MyParameter", 
        "Value": "secret_value"
    }
}

En el siguiente flujo de trabajo se muestra cómo el Parameter Store utiliza una clave de KMS para cifrar y descifrar un parámetro SecureString estándar.

Cifrar un parámetro estándar

Descifrar un parámetro estándar

Protección de parámetros Secure String avanzados

Cuando se utiliza PutParameter para crear un parámetro SecureString avanzado, el Parameter Store usa el cifrado de sobre con el AWS Encryption SDK y una AWS KMS key de cifrado simétrica para proteger el valor del parámetro. Cada valor del parámetro avanzado se cifra con una clave de datos única y la clave de datos se cifra con una clave KMS. Puede usar la Clave administrada de AWS de la cuenta (aws/ssm) o cualquier clave administrada por el cliente.

El AWS Encryption SDK es una biblioteca cliente de código abierto que le ayuda a cifrar y descifrar datos mediante estándares y prácticas recomendadas del sector. Es compatible con varias plataformas y varios lenguajes de programación, incluida una interfaz de línea de comandos. Puede ver el código fuente y contribuir a su desarrollo en GitHub.

Para cada valor de un parámetro SecureString, Parameter Store llama al AWS Encryption SDK para descifrar el valor del parámetro utilizando una clave de datos única que AWS KMS genera (GenerateDataKey). El AWS Encryption SDK devuelve a Parameter Store un mensaje cifrado que incluye el valor del parámetro cifrado y una copia cifrada de la clave de datos única. Parameter Store almacena todo el mensaje cifrado en el valor del parámetro SecureString. A continuación, cuando se obtiene el valor de un parámetro SecureString, Parameter Store utiliza el AWS Encryption SDK para descifrar el valor del parámetro. Esto requiere una llamada a AWS KMS para descifrar la clave de datos cifrada.

Para crear un parámetro SecureString avanzado, utilice la operación PutParameter de la API de Systems Manager. Establezca el valor del parámetro Tier en Advanced. Incluya un parámetro Type con el valor SecureString. Para especificar una clave KMS, utilice el parámetro KeyId. El valor predeterminado es la Clave administrada de AWS de su cuenta, aws/ssm.

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

El siguiente ejemplo similar utiliza el parámetro --key-id para especificar una clave administrada por el cliente. El ejemplo utiliza el Nombre de recurso de Amazon (ARN) de la clave KMS, pero puede utilizar cualquier identificador de clave KMS válido.

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

Cuando se obtiene un parámetro SecureString de Parameter Store, su valor es el mensaje cifrado que devuelve el AWS Encryption SDK. Para obtener un parámetro, utilice la operación GetParameter de la API de Systems Manager.

En el siguiente ejemplo se utiliza la operación GetParameter de Systems Manager para obtener el parámetro MyParameter del Parameter Store sin descifrar su valor.

aws ssm get-parameter --name MyParameter

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

Para descifrar el valor del parámetro antes de devolverlo, establezca el parámetro WithDecryption de GetParameter en true. Al utilizar WithDecryption, el Parameter Store llama a la operación Decrypt de AWS KMS en su nombre para descifrar el valor del parámetro. En consecuencia, la solicitud GetParameter devuelve el parámetro con un valor en texto no cifrado, tal y como se muestra en el siguiente ejemplo.

aws ssm get-parameter \
    --name MyParameter \
    --with-decryption

{
    "Parameter": {
        "Type": "SecureString", 
        "Name": "MyParameter", 
        "Value": "secret_value"
    }
}

No se puede convertir un parámetro SecureString avanzado en uno estándar, pero puede convertir un parámetro SecureString estándar en uno avanzado. Para convertir un parámetro SecureString estándar en un parámetro SecureString avanzado, utilice la operación PutParameter con el parámetro Overwrite. El valor de Type debe ser SecureString y el valor de Tier debe ser Advanced. El parámetro KeyId, que identifica una clave administrada por el cliente, es opcional. Si lo omite, el Parameter Store utiliza la Clave administrada de AWS de la cuenta. Puede especificar cualquier clave KMS para la que la entidad principal tenga permiso, aunque utilice una clave KMS diferente para cifrar el parámetro estándar.

Cuando se utiliza el parámetro Overwrite, Parameter Store usa el AWS Encryption SDK para cifrar el valor del parámetro. A continuación, almacena el nuevo mensaje cifrado en Parameter Store.

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

El siguiente flujo de trabajo muestra cómo el Parameter Store utiliza una clave de KMS para cifrar y descifrar un parámetro SecureString avanzado.

Cifrar un parámetro avanzado

Descifrar un parámetro avanzado

Configurar permisos para cifrar y descifrar valores de parámetros

Para cifrar el valor de un parámetro SecureString estándar, el usuario necesita el permiso kms:Encrypt. Para cifrar el valor de un parámetro SecureString avanzado, el usuario necesita el permiso kms:GenerateDataKey. Para descifrar cualquier tipo de valor de un parámetro SecureString, el usuario necesita el permiso kms:Decrypt.

Puede utilizar las políticas de AWS Identity and Access Management (IAM) para conceder o denegar permisos a un usuario para llamar a las operaciones PutParameter y GetParameter de Systems Manager.

Además, si utiliza claves administradas por el cliente para cifrar valores de parámetros SecureString, puede utilizar políticas de IAM y de claves para administrar los permisos de cifrado y descifrado. Sin embargo, no puede establecer políticas de control de acceso para la clave KMS aws/ssm predeterminada. Para obtener más información acerca del control del acceso a las clave administradas por el cliente, consulte KMS key access and permissions en la Guía para desarrolladores de AWS Key Management Service.

En el siguiente ejemplo se muestra una política de IAM diseñada para parámetros SecureString estándar. Permite que el usuario llame a la operación PutParameter de Systems Manager en todos los parámetros de la ruta FinancialParameters. La política también permite al usuario llamar a la operación Encrypt de AWS KMS en una clave administrada por el cliente de ejemplo.

{
    "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"
        }
    ]
}

En el siguiente ejemplo se muestra una política de IAM diseñada para parámetros SecureString avanzados. Permite que el usuario llame a la operación PutParameter de Systems Manager en todos los parámetros de la ruta ReservedParameters. La política también permite al usuario llamar a la operación GenerateDataKey de AWS KMS en una clave administrada por el cliente de ejemplo.

{
    "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"
        }
    ]
}

El último ejemplo también muestra una política de IAM que se puede utilizar para parámetros SecureString estándar o avanzados. Permite al usuario llamar a las operaciones GetParameter de Systems Manager (y a las operaciones relacionadas) en todos los parámetros de la ruta ITParameters. La política también permite al usuario llamar a la operación Decrypt de AWS KMS en una clave administrada por el cliente de ejemplo.

{
    "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 cifrado de Parameter Store

Un contexto de cifrado es un conjunto de pares de clave-valor que contienen datos no secretos arbitrarios. Cuando se incluye un contexto de cifrado en una solicitud para cifrar datos, AWS KMS vincula criptográficamente el contexto de cifrado a los datos cifrados. Para descifrar los datos, es necesario pasar el mismo contexto de cifrado.

También se puede utilizar el contexto de cifrado para identificar una operación criptográfica en los registros y los registros de auditoría. El contexto de cifrado aparece en texto no cifrado en los registros, como los registros de AWS CloudTrail.

El AWS Encryption SDK también tiene un contexto de cifrado, aunque se administra de forma distinta. Parameter Store proporciona el contexto de cifrado al método de cifrado. El AWS Encryption SDK vincula criptográficamente el contexto de cifrado a los datos cifrados. También incluye el contexto de cifrado en texto no cifrado en el encabezado del mensaje cifrado que devuelve. Sin embargo, a diferencia de AWS KMS, los métodos de descifrado de AWS Encryption SDK no toman un contexto de cifrado como entrada. En lugar de ello, cuando se descifran los datos, el AWS Encryption SDK obtiene el contexto de cifrado del mensaje cifrado. Parameter Store verifica que el contexto de cifrado incluye el valor que espera antes de devolverle el valor del parámetro en texto no cifrado.

Parameter Store utiliza el siguiente contexto de cifrado en sus operaciones criptográficas:

El formato del contexto de cifrado es el siguiente:

"PARAMETER_ARN":"arn:aws:ssm:region-id:account-id:parameter/parameter-name"

Por ejemplo, el Parameter Store incluye este contexto de cifrado en las llamadas para cifrar y descifrar el parámetro MyParameter en una región y Cuenta de AWS de ejemplo.

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

Si el parámetro está en una ruta jerárquica de Parameter Store, la ruta y el nombre se incluyen en el contexto de cifrado. Por ejemplo, este contexto de cifrado se utiliza al cifrar y descifrar el parámetro MyParameter en la ruta /ReadableParameters en una Cuenta de AWS y región de ejemplo.

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

Puede descifrar el valor de un parámetro SecureString cifrado llamando a la operación Decrypt de AWS KMS con el contexto de cifrado correcto y el valor del parámetro cifrado devuelto por la operación GetParameter de Systems Manager. No obstante, le animamos a que utilice la operación GetParameter con el parámetro WithDecryption para cifrar valores de parámetros de Parameter Store.

También puede incluir el contexto de cifrado en una política de IAM. Por ejemplo, puede permitir a un usuario que descifre únicamente el valor de un parámetro o un conjunto de valores de parámetros determinados.

La siguiente declaración de política de IAM de ejemplo permite al usuario obtener el valor del parámetro MyParameter y descifrar su valor mediante la clave KMS especificada. Sin embargo, los permisos solo se aplican cuando el contexto de cifrado coincide con la cadena especificada. Estos permisos no se aplican a ningún otro parámetro ni clave KMS, y la llamada a GetParameter da un error si el contexto de cifrado no coincide con la cadena.

Antes de utilizar una declaración de política como esta, sustituya los ARN de ejemplo 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"
                }
            }
        }
    ]
}

Solución de problemas de las claves de KMS en el Parameter Store

Para realizar operaciones en un parámetro SecureString, el Parameter Store debe poder utilizar la clave de AWS KMS especificada para la operación que se pretende realizar. La mayoría de los errores del Parameter Store relacionados con las claves de KMS los provocan los siguientes problemas: