Importa una clave a Cloud KMS

En este tema, se muestra cómo importar una clave criptográfica en Cloud HSM o Cloud Key Management Service.

Para obtener más detalles sobre la importación de claves, incluidas las limitaciones y restricciones, consulta Importación de claves.

Puedes completar los pasos de este tema en 5 a 10 minutos, sin incluir los pasos Antes de comenzar. Unir la clave agrega complejidad a la tarea de forma manual.

Antes de comenzar

Se recomienda que crees un proyecto nuevo para probar esta función, para facilitar la limpieza después de las pruebas y para asegurarte de tener permisos adecuados de Cloud IAM para importar una clave.

Antes de importar una clave, debes preparar el proyecto, el sistema local y la clave.

Preparando el proyecto

  1. Accede a tu Cuenta de Google.

    Si todavía no tienes una cuenta, regístrate para obtener una nueva.

  2. En la página Selector de proyectos de Cloud Console, selecciona o crea un proyecto de Cloud.

    Ir a la página Selector de proyectos

  3. Comprueba que la facturación esté habilitada en tu proyecto.

    Descubre cómo puedes habilitar la facturación

  4. Habilita la API necesaria.

    Habilita la API

  5. Instala e inicializa el SDK de Cloud.
  6. El usuario que realiza la importación necesita los siguientes permisos de Cloud IAM para crear llaveros de claves y trabajos de importación. Si el usuario no es el propietario del proyecto, puedes asignar ambas de las siguientes dos funciones predefinidas al usuario:

    • roles/editor
    • roles/cloudkms.importer

    Para obtener más información sobre las funciones y los permisos de Cloud IAM en Cloud KMS, consulta Permisos y funciones.

Cómo preparar el sistema local

Para preparar el sistema local, elige una de las siguientes opciones. Se recomienda la unión automática de claves para la mayoría de los usuarios.

Cómo preparar la clave

  • Si no tienes una clave para importar, pero deseas probar la importación de claves, puedes crear una clave simétrica en el sistema local con el siguiente comando:

        openssl rand 32 > ${HOME}/test.bin
        

    Usa esta clave solo para realizar pruebas. Una clave creada de esta manera podría no ser adecuada para el uso en producción.

  • Asegúrate de que la clave que deseas importar esté en el formato correcto y conviértela si es necesario. Para obtener más información, consulta Cómo dar formato a las claves para la importación.

  • Si necesitas ajustar la clave manualmente, hazlo antes de continuar con los procedimientos de este tema.

Crea la clave de destino y el llavero de claves

Antes de importar una clave, debes crear una clave vacía en tu proyecto de Google Cloud para que contenga el material de clave importada. En este tema, esta clave vacía se llama clave de destino.

La clave de destino existe en un llavero de claves. Puedes crear un llavero de claves nuevo o usar uno existente. En este tema, este llavero de claves se denomina llavero de claves de destino.

La ubicación del llavero de claves objetivo determina la ubicación donde está disponible tu clave después de la importación. Las claves de Cloud HSM no se pueden crear ni importar en algunas ubicaciones, como global. No puedes mover una clave a un llavero de claves diferente.

Puedes crear la clave de destino y el llavero de claves mediante la herramienta de línea de comandos de gcloud o Google Cloud Console.

gcloud

  1. Crea el llavero de claves de destino. Si piensas importar a una clave de Cloud HSM, selecciona una ubicación compatible con Cloud HSM.

        gcloud kms keyrings create keyring-name \
          --location location
        

    Puedes obtener más información sobre cómo crear llaveros de claves.

  2. Crea la clave de destino.

    • Establece el propósito de la clave:
      • Para una clave simétrica, establece el propósito en encryption.
      • Para una clave asimétrica, establece el propósito en asymmetric-signing o asymmetric-encryption.
    • Evita que se cree una versión inicial con la marca --skip-initial-version-creation.
    • No establezcas el nivel de protección.
    • No especifiques un algoritmo para la clave de destino. Debes especificar el algoritmo de la clave importada como parte de la solicitud de importación.
        gcloud kms keys create key-name \
          --location location \
          --keyring keyring-name \
          --purpose purpose \
          --skip-initial-version-creation
        

    Puedes obtener más información sobre cómo crear claves de Cloud KMS o claves de Cloud HSM.

Console

  1. Ve a la página Claves criptográficas en Cloud Console.

    Ir a la página Claves criptográficas

  2. Haz clic en Crear llavero de claves.

  3. En el campo Nombre del llavero de claves, ingresa el nombre de tu llavero de claves.

  4. Selecciona una ubicación en el menú desplegable Ubicación.

  5. Haga clic en Crear. Se abrirá la página de detalles del llavero de claves.

  6. Haz clic en Crear clave.

  7. Selecciona Clave importada. Esto evita que se cree una versión de clave inicial.

  8. Ingresa el nombre en el campo Nombre de la clave.

  9. Establece el nivel de protección en Software o HSM.

  10. [Opcional] Para las claves importadas, la rotación automática está inhabilitada de forma predeterminada. Si habilita la rotación automática, la versión de clave importada ya no será la versión de clave predeterminada después de una rotación.

  11. [De manera opcional, si deseas agregar etiquetas a tu clave][4], haz clic en Agregar etiqueta en el campo Etiquetas.

  12. Haga clic en Crear.

El llavero de claves y la clave ahora existen, pero la clave no contiene material de claves. A continuación, cree un trabajo de importación.

Crear el trabajo de importación

Un trabajo de importación define el nivel de protección y el método de importación para las claves que importas a Cloud HSM o Cloud KMS, así como el algoritmo utilizado para crear la clave de unión que protege las claves importadas durante el tránsito desde tu sistema local al proyecto de Google Cloud de destino.

Puedes crear un trabajo de importación con la herramienta de gcloud, Cloud Console o la API de Cloud Key Management Service.

gcloud

Use un comando como el siguiente para crear un trabajo de importación.

    gcloud kms import-jobs create import-job \
      --location location \
      --keyring keyring-name \
      --import-method import-method \
      --protection-level protection-level
    

  • Usa el mismo llavero de claves y la misma ubicación que la clave de destino.
  • Configura el método de importación en rsa-oaep-3072-sha1-aes-256 o rsa-oaep-4096-sha1-aes-256. A menos que tenga requisitos específicos, se recomienda rsa-oaep-3072-sha1-aes-256.
  • Establece el nivel de protección en software o hsm.

Console

  1. Ve a la página Claves criptográficas en Cloud Console.

    Ir a la página Claves criptográficas

  2. Haz clic en el nombre del llavero de claves de destino.

  3. Establece el Nivel de protección en Software o HSM. Usa el mismo nivel de protección que estableciste para la clave de destino.

  4. Haz clic en Crear trabajo de importación.

  5. En el campo Nombre, ingresa el nombre de tu trabajo de importación.

  6. En el menú desplegable Método de importación, selecciona un método de importación. A menos que tengas requisitos específicos, se recomienda RSA de 3072 bits.

  7. Haga clic en Crear.

API

  1. Crea una instancia del tipo [ImportJob][importjob_api]. Proporciona valores iniciales para los campos ImportJob.protectionLevel y ImportJob.importMethod.

  2. Llama al método ImportJob.create con tu instancia de ImportJob como cuerpo de la solicitud.

Verifica el estado del trabajo de importación

El estado inicial de un trabajo de importación es PENDING_GENERATION. Una vez que el estado es ACTIVE, el trabajo de importación ya está listo para usar.

Un trabajo de importación vence después de tres días. Si el trabajo de importación venció, debes crear uno nuevo.

Puedes comprobar el estado de un trabajo de importación con la herramienta de línea de comandos de gcloud, Google Cloud Console o la API de Cloud Key Management Service.

gcloud

Cuando un trabajo de importación está activo, puede usarlo para importar claves. Esta operación podría tomar unos minutos. Usa este comando para verificar que el trabajo de importación esté activo. Usa la ubicación y el llavero donde creaste el trabajo de importación.

    gcloud kms import-jobs describe import-job \
      --location location \
      --keyring keyring-name \
      --format="value(state)"
    
state: ACTIVE

Console

  1. Ve a la página Claves criptográficas en Cloud Console.

    Ir a la página Claves criptográficas

  2. Haz clic en el nombre del llavero de claves que contiene tu trabajo de importación.

  3. Haz clic en la pestaña Trabajos de importación en la parte superior de la página.

  4. El estado aparecerá en Estado junto al nombre de tu trabajo de importación.

API

Llama al método ImportJob.get y verifica el campo state. Si state está en PENDING_GENERATION, el trabajo de importación todavía se está creando. Vuelve a verificar periódicamente el estado hasta que sea ACTIVE.

Tan pronto como el trabajo de importación esté activo, puedes realizar una solicitud para importar una clave.

Impedir la modificación de trabajos de importación

El trabajo de importación determina muchas características de la clave importada, incluido el algoritmo de la clave y si una clave importada es una clave de HSM o de software. Puedes configurar los permisos de Cloud Identity and Access Management para evitar que los usuarios creen trabajos de importación, mientras que les permites usar los trabajos para importar claves.

  1. Otorga solo a los administradores de claves el importjobs.create.
  2. Otorga el permiso importjobs.useToImport para un trabajo de importación específico al operador que usará ese trabajo a fin de importar claves.
  3. Cuando crees el trabajo de importación, especifica el nivel de protección y el algoritmo para las claves importadas con él.

Hasta que venza el trabajo de importación, los usuarios que tengan el permiso importjobs.useToImport y no tengan el permiso importjobs.create para un trabajo de importación determinado podrán importar las características del trabajo.

Importa la clave

Después de verificar el estado del trabajo de importación, puedes realizar una solicitud de importación.

Usa marcas diferentes para realizar la solicitud de importación, según si deseas que la herramienta de línea de comandos de gcloud una tu clave automáticamente o si la uniste manualmente.

Independientemente de si unes la clave de forma manual o automática, debes configurar el algoritmo a un algoritmo compatible con el tipo de clave que deseas importar. Por ejemplo, establece el algoritmo en google-symmetric-encryption para claves simétricas. Se admite una variedad de algoritmos para claves asimétricas.

Cómo unir e importar una clave automáticamente

Si deseas usar la unión automática, debes usar la herramienta de línea de comandos de gcloud. Usa un comando como el siguiente. Configura --target-key-file en la ubicación de la clave separada para unir e importar. No establezca -rsa-aes-wrapped-key-file.

Opcionalmente, puedes establecer la marca --public-key-file en la ubicación donde ya se descargó la clave pública. Cuando se importa una gran cantidad de claves, esto impide que la clave pública se descargue durante cada importación. Por ejemplo, puedes escribir una secuencia de comandos que descargó la clave pública una vez y, luego, proporcionar su ubicación al importar cada clave.

    gcloud kms keys versions import \
      --import-job import-job \
      --location location \
      --keyring keyring-name \
      --key KEY_NAME \
      --algorithm algorithm-name \
      --target-key-file path-to-unwrapped-key-to-import
    

Importa una clave unida de forma manual

Usa las instrucciones de esta sección para importar una clave que uniste manualmente. Configura --rsa-aes-wrapped-key-file con la ubicación de la clave que uniste manualmente. No establezcas --target-key-file.

Opcionalmente, puedes establecer la marca --public-key-file en la ubicación donde ya se descargó la clave pública. Cuando importas una gran cantidad de claves, esto evita que la clave pública se descargue durante cada importación. Por ejemplo, puedes escribir una secuencia de comandos que descargó la clave pública una vez y, luego, proporcionó su ubicación al importar cada clave.

gcloud

Use un comando como el siguiente.

    gcloud kms keys versions import \
      --import-job import-job \
      --location location \
      --keyring keyring-name \
      --key KEY_NAME \
      --algorithm algorithm-name \
      --rsa-aes-wrapped-key-file path-to-wrapped-key-to-import
    

Para obtener más información, consulta el resultado del comando gcloud kms keys versions import --help.

Console

  1. Abre la página Claves criptográficas en Cloud Console.

  2. Haz clic en el nombre del llavero de claves que contiene tu trabajo de importación. Se muestra la clave de destino, junto con cualquier otra clave del llavero de claves.

  3. Haz clic en el nombre de la clave de destino y, luego, en Importar versión de clave.

  4. Selecciona tu trabajo de importación en el menú desplegable Seleccionar trabajo de importación.

  5. En el selector Subir la clave unida (Upload the wrapped key), selecciona la clave que ya uniste.

  6. Si importas una clave asimétrica, selecciona el algoritmo en el menú desplegable Algoritmo. Tu página Importar versión de clave debe ser similar a la que se muestra a continuación:

    Importar versión de clave

  7. Haga clic en Import.

API

  1. Para el cuerpo de la solicitud del método cryptoKeyVersions.import, define el campo algorithm como el algoritmo de la clave que se está importando. No es necesario que este valor coincida con la versionTemplate de la CryptoKey que está importando esta versión. El campo algorithm es del tipo CryptoKeyVersionAlgorithm.

  2. Además, para el cuerpo de la solicitud, establece el campo wrappedKeyMaterial en el material de clave que ya uniste.

  3. Llama al método cryptoKeyVersions.import. La respuesta cryptoKeyVersions.import es del tipo CryptoKeyVersion. Cuando una clave se importa correctamente, su estado es ENABLED y puedes usarla en Cloud KMS.

Verifica el estado de la clave importada

El estado inicial de una clave importada es PENDING_IMPORT. Cuando el estado es ENABLED, la clave importada está lista para usarse. Si la importación falla, el estado es IMPORT_FAILED.

Puedes verificar el estado de una solicitud de importación con la herramienta de línea de comandos de gcloud, Google Cloud Console o la API de Cloud Key Management Service.

gcloud

Usa el comando versions list para verificar el estado. Usa la misma ubicación, el llavero de claves de destino y la clave de destino que creaste anteriormente en este tema.

    gcloud kms keys versions list \
      --keyring keyring \
      --location location \
      --key key
    

La solicitud de importación crea una versión de clave nueva con el material de clave importado y establece el estado de la clave en ACTIVE.

Console

  1. Abre la página Claves criptográficas en Cloud Console.

  2. Haz clic en el nombre del llavero de claves que contiene tu trabajo de importación.

  3. Haz clic en la pestaña Trabajos de importación en la parte superior de la página.

  4. El estado aparecerá en Estado junto al nombre de tu trabajo de importación.

API

Llama al método ImportJob.get y verifica el campo state. Si state está en PENDING_GENERATION, el trabajo de importación todavía se está creando. Vuelve a verificar periódicamente el estado hasta que sea ACTIVE.

La clave se importa y puedes usarla para firmar o proteger datos.

Qué sigue