Migra claves externas

En este documento, se muestra cómo migrar tus claves de Cloud EKM entre los niveles de protección externo a través de Internet (EXTERNAL) y externo a través de VPC (EXTERNAL_VPC). La migración de claves externas solo se admite en gcloud CLI y la API de Cloud KMS.

Casos de uso de la migración

Cuando una clave tiene el nivel de protección EXTERNAL o EXTERNAL_VPC, puedes realizar cualquiera de las siguientes acciones:

  • Rota la clave y crea una versión de clave nueva con un nivel de protección de Cloud EKM diferente al de la clave principal. Por ejemplo, puedes rotar una clave en el nivel de protección EXTERNAL para crear una nueva versión de la clave en el nivel de protección EXTERNAL_VPC.
  • Actualiza una versión de clave para usar un nivel de protección de Cloud EKM diferente para el mismo material de clave. Por ejemplo, puedes actualizar una versión de clave en el nivel de protección EXTERNAL para usar el mismo material de clave y el mismo recurso de versión de clave con el nivel de protección EXTERNAL_VPC.
  • Rotar una clave EXTERNAL_VPC o actualizar una versión de clave EXTERNAL_VPC para usar una EkmConnection diferente de la clave principal

Migrar una versión de clave existente entre los dos niveles de protección de Cloud EKM te permite cambiar la forma en que accedes a tu material de clave externo sin necesidad de volver a configurar tus aplicaciones ni volver a encriptar tus datos, y sin tiempo de inactividad. Tu clave migrada usa el mismo material de clave y el mismo identificador de recurso.

Cuando migras una versión de clave del nivel de protección EXTERNAL al nivel de protección EXTERNAL_VPC, asocias un recurso EkmConnection con la versión de clave y agregas el ekmConnectionKeyPath. Cuando migras una versión de clave del nivel de protección EXTERNAL_VPC al nivel de protección EXTERNAL, agregas un externalKeyUri para reemplazar el EkmConnection y el ekmConnectionKeyPath.

Si una versión de clave tiene un objeto EkmConnection asociado, esa conexión se usa para todas las operaciones de la versión de clave, incluso si la clave principal tiene un objeto EkmConnection diferente.

Migración a externo a través de VPC

La migración del nivel de protección externo a través de Internet al nivel de protección externo a través de la VPC proporciona una mayor confiabilidad para tus claves de Cloud EKM. Obtienes los beneficios de las redes de nube privada virtual (VPC), incluido un aislamiento sólido y una mejor asistencia operativa.

También puedes migrar entre diferentes configuraciones de VPC, por ejemplo, para actualizar el uso de la VPC con Interconexión de socio al uso de la VPC con Interconexión dedicada.

Antes de comenzar

Antes de migrar claves de Cloud EKM, debes tener lo siguiente:

  1. Un proyecto Google Cloud con la facturación y la API de Cloud KMS habilitadas

  2. Para obtener el permiso que necesitas para migrar claves externas, pídele a tu administrador que te otorgue el rol de IAM de administrador de Cloud KMS (roles/cloudkms.admin) en el proyecto o en un recurso principal. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

    Este rol predefinido contiene el permiso cloudkms.cryptoKeys.update, que se requiere para migrar claves externas.

    También puedes obtener este permiso con roles personalizados o con otros roles predefinidos.

  3. Si migras al nivel de protección externo a través de Internet (EXTERNAL), debes configurar Cloud EKM a través de Internet si aún no lo hiciste.
  4. Si migras al nivel de protección externo a través de VPC (EXTERNAL_VPC) o a una nueva red de VPC, debes crear una conexión de EKM si aún no lo hiciste.

Crea una versión de clave externa administrada manualmente a través de una VPC

gcloud

Para usar Cloud KMS en la línea de comandos, primero instala o actualiza a la versión más reciente de Google Cloud CLI.

Para crear una nueva versión de clave externa a través de la VPC en una clave existente de Cloud EKM, usa el comando kms keys versions create con las marcas --protection-level, --crypto-key-backend y --ekm-connection-key-path:

gcloud kms keys versions create \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external-vpc" \
    --crypto-key-backend EKM_CONNECTION_PATH \
    --ekm-connection-key-path EXTERNAL_KEY_PATH

Reemplaza lo siguiente:

  • KEY_NAME: el nombre de la clave.
  • KEY_RING: el nombre del llavero de claves que incluye la clave
  • LOCATION: la ubicación de Cloud KMS del llavero de claves.
  • EKM_CONNECTION_PATH: Es el identificador de recurso de la conexión de EKM que deseas usar para la nueva versión de la clave, por ejemplo, projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION.
  • EXTERNAL_KEY_PATH: Es la ruta de acceso a la nueva versión de la clave externa desde tu conexión de EKM, por ejemplo, v0/path/to/my/key.

Si la clave principal es

Si la clave es una clave de encriptación simétrica y deseas que la nueva versión sea la principal, agrega la marca --primary.

Para obtener información sobre todas las marcas y los valores posibles, ejecuta el comando con la marca --help.

REST

En estos ejemplos, se usa curl como un cliente HTTP para demostrar el uso de la API. Para obtener más información sobre el control de acceso, consulta Accede a la API de Cloud KMS.

Para crear una versión de clave externa a través de una VPC en una clave de Cloud EKM existente, llama al método CryptoKeyVersions.create para crear una versión de clave nueva.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL_VPC",
            "externalProtectionLevelOptions": {
              "ekmConnectionKeyPath": "EXTERNAL_KEY_PATH",
              "ekmConnectionBackendOverride": "EKM_CONNECTION_PATH"
              },
            }'
  • PROJECT_ID: Es el identificador del proyecto que contiene la clave que deseas rotar.
  • KEY_NAME: el nombre de la clave.
  • KEY_RING: el nombre del llavero de claves que incluye la clave
  • LOCATION: la ubicación de Cloud KMS del llavero de claves.
  • EKM_CONNECTION_PATH: Es el identificador de recurso de la conexión de EKM que deseas usar para la nueva versión de la clave, por ejemplo, projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION.
  • EXTERNAL_KEY_PATH: Es la ruta de acceso a la nueva versión de la clave externa desde tu conexión de EKM, por ejemplo, v0/path/to/my/key.

Este comando crea una versión de clave nueva, pero no la establece como la versión principal.

Para establecer tu nueva versión de clave como primaria, consulta Cómo configurar una versión existente como la versión de clave primaria.

Crea una versión de clave externa nueva a través de Internet

gcloud

Para usar Cloud KMS en la línea de comandos, primero instala o actualiza a la versión más reciente de Google Cloud CLI.

Para crear una versión de clave externa a través de Internet en una clave de Cloud EKM existente, usa el comando kms keys versions create con las marcas --protection-level y --external-key-uri:

gcloud kms keys versions create \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external" \
    --external-key-uri EXTERNAL_KEY_URI

Reemplaza lo siguiente:

  • KEY_NAME: el nombre de la clave.
  • KEY_RING: el nombre del llavero de claves que incluye la clave
  • LOCATION: la ubicación de Cloud KMS del llavero de claves.
  • EXTERNAL_KEY_URI: Es el URI de la nueva versión de la clave externa.

Si la clave es una clave de encriptación simétrica y deseas que la nueva versión de la clave sea la versión principal, agrega la marca --primary.

Para obtener información sobre todas las marcas y los valores posibles, ejecuta el comando con la marca --help.

REST

En estos ejemplos, se usa curl como un cliente HTTP para demostrar el uso de la API. Para obtener más información sobre el control de acceso, consulta Accede a la API de Cloud KMS.

Para crear una versión de clave externa a través de Internet en una clave existente de Cloud EKM, llama al método CryptoKeyVersions.create para crear una versión de clave nueva.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL",
            "externalProtectionLevelOptions": {
              "externalKeyUri": "EXTERNAL_KEY_URI",
              },
            }'
  • PROJECT_ID: Es el identificador del proyecto que contiene la clave que deseas rotar.
  • KEY_NAME: el nombre de la clave.
  • KEY_RING: el nombre del llavero de claves que incluye la clave
  • LOCATION: la ubicación de Cloud KMS del llavero de claves.
  • EXTERNAL_KEY_URI: Es el URI de la nueva versión de la clave externa.

Este comando crea una versión de clave nueva, pero no la establece como la versión principal.

Para establecer tu nueva versión de clave como primaria, consulta Cómo configurar una versión existente como la versión de clave primaria.

Actualiza una versión de clave para usar el modo de protección externa a través de VPC

gcloud

Para usar Cloud KMS en la línea de comandos, primero instala o actualiza a la versión más reciente de Google Cloud CLI.

Para actualizar una versión de clave external existente al nivel de protección external-vpc, usa el comando kms keys versions update con las marcas --protection-level, --crypto-key-backend y --ekm-connection-key-path:

gcloud kms keys versions update KEY_VERSION \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external-vpc" \
    --crypto-key-backend EKM_CONNECTION_PATH \
    --ekm-connection-key-path EXTERNAL_KEY_PATH

Reemplaza lo siguiente:

  • KEY_VERSION: Es el número de la versión de la clave que deseas migrar, por ejemplo, 3.
  • KEY_NAME: el nombre de la clave.
  • KEY_RING: el nombre del llavero de claves que incluye la clave
  • LOCATION: la ubicación de Cloud KMS del llavero de claves.
  • EKM_CONNECTION_PATH: Es el identificador de recurso de la conexión de EKM que deseas usar para la versión de la clave, por ejemplo, projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION.
  • EXTERNAL_KEY_PATH: Es la nueva ruta de acceso al material de clave externa existente de tu conexión al EKM, por ejemplo, v0/path/to/my/key. La conexión del EKM y la ruta de la clave deben apuntar al mismo material de clave que el URI de la clave actual.

Para obtener información sobre todas las marcas y los valores posibles, ejecuta el comando con la marca --help.

REST

En estos ejemplos, se usa curl como un cliente HTTP para demostrar el uso de la API. Para obtener más información sobre el control de acceso, consulta Accede a la API de Cloud KMS.

Para actualizar una versión de clave external existente al nivel de protección external-vpc, llama al método CryptoKeyVersions.patch.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION?updateMask=protectionLevel,externalProtectionLevelOptions" \
    --request "PATCH" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL_VPC",
            "externalProtectionLevelOptions": {
              "ekmConnectionKeyPath": "EXTERNAL_KEY_PATH",
              "ekmConnectionBackendOverride": "EKM_CONNECTION_PATH"
              },
            }'
  • PROJECT_ID: Es el identificador del proyecto que contiene la clave que deseas migrar.
  • KEY_NAME: el nombre de la clave.
  • KEY_RING: el nombre del llavero de claves que incluye la clave
  • LOCATION: la ubicación de Cloud KMS del llavero de claves.
  • EKM_CONNECTION_PATH: Es el identificador de recurso de la conexión de EKM que deseas usar para la versión de la clave, por ejemplo, projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION.
  • EXTERNAL_KEY_PATH: Es la nueva ruta de acceso al material de clave externa existente de tu conexión al EKM, por ejemplo, v0/path/to/my/key. La conexión del EKM y la ruta de la clave deben apuntar al mismo material de clave que el URI de la clave actual.

Actualiza una versión de clave para usar el modo de protección externa a través de Internet

gcloud

Para usar Cloud KMS en la línea de comandos, primero instala o actualiza a la versión más reciente de Google Cloud CLI.

Para actualizar una versión de clave external-vpc existente al nivel de protección external, usa el comando kms keys versions update con las marcas --protection-level y --external-key-uri:

gcloud kms keys versions update KEY_VERSION \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external" \
    --external-key-uri EXTERNAL_KEY_URI

Reemplaza lo siguiente:

  • KEY_VERSION: Es el número de la versión de la clave que deseas migrar, por ejemplo, 3.
  • KEY_NAME: el nombre de la clave.
  • KEY_RING: el nombre del llavero de claves que incluye la clave
  • LOCATION: la ubicación de Cloud KMS del llavero de claves.
  • EXTERNAL_KEY_URI: Es el nuevo URI del material de clave externa existente en tu EKM. El URI debe apuntar al mismo material de clave que la conexión EKM y la clave externa actuales.

Para obtener información sobre todas las marcas y los valores posibles, ejecuta el comando con la marca --help.

REST

En estos ejemplos, se usa curl como un cliente HTTP para demostrar el uso de la API. Para obtener más información sobre el control de acceso, consulta Accede a la API de Cloud KMS.

Para actualizar una versión de clave external-vpc existente al nivel de protección external, llama al método CryptoKeyVersions.patch.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION?updateMask=protectionLevel,externalProtectionLevelOptions" \
    --request "PATCH" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL",
            "externalProtectionLevelOptions": {
              "externalKeyUri": "EXTERNAL_KEY_URI",
              },
            }'
  • PROJECT_ID: Es el identificador del proyecto que contiene la clave que deseas migrar.
  • KEY_NAME: el nombre de la clave.
  • KEY_RING: el nombre del llavero de claves que incluye la clave
  • LOCATION: la ubicación de Cloud KMS del llavero de claves.
  • EXTERNAL_KEY_URI: Es el nuevo URI del material de clave externa existente en tu EKM. El URI debe apuntar al mismo material de clave que la conexión EKM y la clave externa actuales.