ייבוא גרסת מפתח ל-Cloud KMS

במדריך הזה נסביר איך לייבא מפתח קריפטוגרפי ל-Cloud HSM או ל-Cloud Key Management Service כגרסה חדשה של מפתח.

מידע נוסף על ייבוא מפתחות, כולל מגבלות והגבלות, מופיע במאמר בנושא ייבוא מפתחות.

אפשר להשלים את השלבים במדריך הזה תוך 5 עד 10 דקות, לא כולל השלבים שבקטע לפני שמתחילים. הצפנה ידנית של המפתח מוסיפה מורכבות למשימה.

לפני שמתחילים

מומלץ ליצור פרויקט חדש כדי לבדוק את התכונה הזו, כדי להקל על הניקוי אחרי הבדיקה וכדי לוודא שיש לכם הרשאות מספיקות לניהול זהויות והרשאות גישה (IAM) לייבוא מפתח.

כדי לייבא מפתח, צריך להכין את הפרויקט, את המערכת המקומית ואת המפתח עצמו.

הכנת הפרויקט

נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

התקינו את ה-CLI של Google Cloud.

אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

התקינו את ה-CLI של Google Cloud.

אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

gcloud init

1. למשתמש שמבצע את הייבוא צריכות להיות ההרשאות הבאות ב-IAM כדי ליצור אוספי מפתחות, מפתחות ועבודות ייבוא. אם המשתמש לא מוגדר כבעלים של הפרויקט, אפשר להקצות לו את שני התפקידים המוגדרים מראש הבאים:

   • roles/editor
   • roles/cloudkms.importer

   מידע נוסף על ההרשאות והתפקידים הזמינים ב-IAM ל-Cloud KMS מופיע במאמר הרשאות ותפקידים.

הכנת המערכת המקומית

בוחרים אחת מהאפשרויות הבאות כדי להכין את המערכת המקומית. מומלץ להשתמש בעטיפת מפתח אוטומטית ברוב המקרים.

• אם רוצים לאפשר ל-Google Cloud CLI לעטוף את המפתחות באופן אוטומטי לפני שידור שלהם אל Google Cloud, צריך להתקין את ספריית הקריפטוגרפיה Pyca במערכת המקומית. ספריית Pyca משמשת את עבודת הייבוא שעוטפת ומגנה על המפתח באופן מקומי לפני שליחתו אל Google Cloud.
• אם רוצים לעטוף את המפתחות באופן ידני, צריך להגדיר את OpenSSL לעטיפת מפתחות ידנית.

הכנת המפתח

מוודאים שהאלגוריתם והאורך של המפתח נתמכים. האלגוריתמים המותרים למפתח תלויים בשימוש במפתח – להצפנה סימטרית, להצפנה אסימטרית או לחתימה אסימטרית – וגם במיקום האחסון של המפתח – בתוכנה או ב-HSM. מציינים את האלגוריתם של המפתח כחלק מבקשת הייבוא.

בנוסף, צריך גם לאמת את אופן הקידוד של המפתח ולבצע התאמות אם צריך.

אחרי שיוצרים או מייבאים גרסת מפתח, אי אפשר לשנות את הפרטים הבאים:

• רמת ההגנה מציינת אם המפתח נשמר בתוכנה, ב-HSM מרובה-דיירים, ב-HSM של דייר יחיד או במערכת חיצונית לניהול מפתחות. אי אפשר להעביר חומר מפתח מאחת מסביבות האחסון האלה לאחרת. לכל הגרסאות של מפתח יש את אותה רמת הגנה.

• המטרה מציינת אם גרסאות המפתח משמשות להצפנה סימטרית, להצפנה אסימטרית או לחתימה אסימטרית. המטרה של המפתח מגבילה את האלגוריתמים האפשריים שאפשר להשתמש בהם כדי ליצור גרסאות של המפתח הזה. לכל הגרסאות של מפתח יש אותה מטרה.

אם אין לכם מפתח לייבוא אבל אתם רוצים לאמת את התהליך של ייבוא מפתחות, אתם יכולים ליצור מפתח סימטרי במערכת המקומית באמצעות הפקודה הבאה:

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

השתמשו במפתח הזה לבדיקה בלבד. יכול להיות שמפתח שנוצר בדרך הזו לא מתאים לשימוש בייצור.

אם אתם צריכים לעטוף את המפתח באופן ידני, עליכם לעשות זאת לפני שתמשיכו בהליכים שמתוארים במדריך הזה.

יצירת מפתח יעד ואוסף מפתחות

מפתח Cloud KMS הוא אובייקט קונטיינר שמכיל אפס גרסאות מפתח או יותר. כל גרסת מפתח מכילה מפתח קריפטוגרפי.

כשמייבאים מפתח ל-Cloud KMS או ל-Cloud HSM, המפתח המיובא הופך לגרסת מפתח חדשה במפתח קיים ב-Cloud KMS או ב-Cloud HSM. בהמשך המדריך הזה, המפתח הזה נקרא מפתח היעד. מפתח היעד חייב להתקיים לפני שניתן לייבא אליו חומר מפתח.

ייבוא של גרסת מפתח לא משפיע על הגרסאות הקיימות של המפתח. עם זאת, מומלץ ליצור מפתח ריק כשבודקים ייבוא מפתח. למפתח ריק אין גרסה, הוא לא פעיל ואי אפשר להשתמש בו.

אפשר גם לציין שהמפתח החדש שנוצר יכיל רק גרסאות מיובאות, כדי למנוע יצירה לא מכוונת של גרסאות חדשות ב-Cloud KMS.

מפתח קיים באוסף מפתחות. במדריך הזה, אוסף המפתחות הזה נקרא אוסף מפתחות היעד. המיקום של מחזיק המפתחות של היעד קובע את המיקום שבו חומר המפתח יהיה זמין אחרי הייבוא. אי אפשר ליצור או לייבא מפתחות Cloud HSM בחלק מהמיקומים. אחרי שיוצרים מפתח, אי אפשר להעביר אותו למחזיק מפתחות או למיקום אחר.

כדי ליצור מפתח ריק בצרור מפתחות חדש באמצעות Google Cloud CLI או מסוף Google Cloud , פועלים לפי השלבים הבאים.

המסוף

1. נכנסים לדף Key Management במסוף Google Cloud .

   כניסה אל Key Management

2. לוחצים על Create key ring (יצירת מחזיק מפתחות).

3. בשדה Key ring name (שם אוסף המפתחות), מזינים את השם של אוסף המפתחות.

4. בקטע Location type, בוחרים סוג מיקום ומיקום.

5. לוחצים על יצירה. ייפתח הדף Create key.

6. בשדה שם המפתח, מזינים את השם של המפתח.

7. בשדה רמת הגנה, בוחרים באפשרות תוכנה, HSM או HSM עם דייר יחיד.

8. אם בחרתם באפשרות Single-tenant HSM, בוחרים את המופע של Single-tenant HSM שבו רוצים ליצור את המפתח.

9. בקטע Key material (חומר מפתח), בוחרים באפשרות Imported key (מפתח מיובא) ולוחצים על Continue (המשך). כך נמנעת יצירה של גרסת מפתח ראשונית.

10. מגדירים את המטרה ואת האלגוריתם של המפתח ולוחצים על המשך.

11. אופציונלי: אם רוצים שהמפתח הזה יכיל רק גרסאות מפתח מיובאות, בוחרים באפשרות הגבלת גרסאות המפתח לייבוא בלבד. כך לא תוכלו ליצור בטעות גרסאות מפתח חדשות ב-Cloud KMS.

12. אופציונלי: במפתחות מיובאים, הרוטציה האוטומטית מושבתת כברירת מחדל. כדי להפעיל רוטציית מפתחות אוטומטית, בוחרים ערך בשדה תקופת רוטציית מפתחות.

    אם מפעילים רוטציה אוטומטית, גרסאות מפתח חדשות ייווצרו ב-Cloud KMS, וגרסת המפתח המיובאת לא תהיה יותר גרסת המפתח שמוגדרת כברירת מחדל אחרי הרוטציה.

13. לוחצים על יצירה.

gcloud

כדי להשתמש ב-Cloud KMS בשורת הפקודה, קודם צריך להתקין את הגרסה האחרונה של Google Cloud CLI או לשדרג אליה.

1. יוצרים את אוסף מפתחות היעד. בוחרים מיקום שתואם לרמת ההגנה שבה רוצים להשתמש. מידע נוסף על המיקומים הנתמכים מופיע במאמר מיקומים ב-Cloud KMS.

   gcloud kms keyrings create KEY_RING \
     --location LOCATION
   

   מידע נוסף על יצירת מחזיקי מפתחות

2. יוצרים את מפתח היעד באמצעות הפקודה kms keys create עם הדגל --skip-initial-version-creation. כך נוצר מפתח ללא גרסת מפתח ראשונית, וחומר המפתח שיובא הוא גרסה 1. משתמשים בדגל --import-only כדי למנוע מ-Cloud KMS ליצור חומר מפתח לגרסאות חדשות של מפתחות. אם הדגל הזה מוגדר, צריך לייבא גרסאות חדשות של המפתח הזה. מפתחות שנוצרו כ---import-only חייבים להיות מוחלפים ידנית.

   gcloud kms keys create KEY_NAME \
     --location LOCATION \
     --keyring KEY_RING \
     --purpose PURPOSE \
     --protection-level PROTECTION_LEVEL \
     --skip-initial-version-creation \
     --import-only
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫KEY_NAME: השם שרוצים להשתמש בו עבור המפתח.
   • ‫LOCATION: המיקום של אוסף המפתחות.
   • ‫KEY_RING: מחזיק המפתחות שבו רוצים ליצור את המפתח.
   • ‫PURPOSE: המטרה שלשמה רוצים להשתמש במפתח.
   • ‫PROTECTION_LEVEL: רמת ההגנה שרוצים להשתמש בה עבור המפתח, לדוגמה HSM.

   ‫ כדי ליצור מפתח Cloud HSM בדייר יחיד, מוסיפים את הדגל --cryptoKeyBackend לפקודה הזו ומוסיפים את מזהה המשאב של מופע Cloud HSM בדייר יחיד שאליו רוצים לייבא את המפתח:

   --crypto-key-backend="projects/INSTANCE_PROJECT/locations/LOCATION/singleTenantHsmInstances/INSTANCE_NAME"

Go

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Go ולהתקין את Cloud KMS Go SDK.

import (
	"context"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
)

// createKeyForImport creates a new asymmetric signing key in Cloud HSM.
func createKeyForImport(w io.Writer, parent, id string) error {
	// parent := "projects/my-project/locations/us-east1/keyRings/my-key-ring"
	// id := "my-imported-key"

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %w", err)
	}
	defer client.Close()

	// Build the request.
	req := &kmspb.CreateCryptoKeyRequest{
		Parent:      parent,
		CryptoKeyId: id,
		CryptoKey: &kmspb.CryptoKey{
			Purpose: kmspb.CryptoKey_ASYMMETRIC_SIGN,
			VersionTemplate: &kmspb.CryptoKeyVersionTemplate{
				ProtectionLevel: kmspb.ProtectionLevel_HSM,
				Algorithm:       kmspb.CryptoKeyVersion_EC_SIGN_P256_SHA256,
			},
			// Ensure that only imported versions may be added to this key.
			ImportOnly: true,
		},
		SkipInitialVersionCreation: true,
	}

	// Call the API.
	result, err := client.CreateCryptoKey(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to create key: %w", err)
	}
	fmt.Fprintf(w, "Created key: %s\n", result.Name)
	return nil
}

Java

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח ב-Java ולהתקין את Cloud KMS Java SDK.

import com.google.cloud.kms.v1.CreateCryptoKeyRequest;
import com.google.cloud.kms.v1.CryptoKey;
import com.google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose;
import com.google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionAlgorithm;
import com.google.cloud.kms.v1.CryptoKeyVersionTemplate;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.cloud.kms.v1.KeyRingName;
import com.google.cloud.kms.v1.ProtectionLevel;
import java.io.IOException;

public class CreateKeyForImport {

  public void createKeyForImport() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "us-east1";
    String keyRingId = "my-key-ring";
    String id = "my-import-key";
    createKeyForImport(projectId, locationId, keyRingId, id);
  }

  // Create a new crypto key to hold imported key versions.
  public void createKeyForImport(String projectId, String locationId, String keyRingId, String id)
      throws IOException {
    // Initialize client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests. After
    // completing all of your requests, call the "close" method on the client to
    // safely clean up any remaining background resources.
    try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {
      // Build the parent name from the project, location, and key ring.
      KeyRingName keyRingName = KeyRingName.of(projectId, locationId, keyRingId);

      // Create the crypto key.
      CryptoKey createdKey =
          client.createCryptoKey(
              CreateCryptoKeyRequest.newBuilder()
                  .setParent(keyRingName.toString())
                  .setCryptoKeyId(id)
                  .setCryptoKey(
                      CryptoKey.newBuilder()
                          .setPurpose(CryptoKeyPurpose.ASYMMETRIC_SIGN)
                          .setVersionTemplate(
                              CryptoKeyVersionTemplate.newBuilder()
                                  .setProtectionLevel(ProtectionLevel.HSM)
                                  .setAlgorithm(CryptoKeyVersionAlgorithm.EC_SIGN_P256_SHA256))
                          // Ensure that only imported versions may be
                          // added to this key.
                          .setImportOnly(true))
                  .setSkipInitialVersionCreation(true)
                  .build());

      System.out.printf("Created crypto key %s%n", createdKey.getName());
    }
  }
}

Node.js

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Node.js ולהתקין את Cloud KMS Node.js SDK.

//
// TODO(developer): Uncomment these variables before running the sample.
//
// const projectId = 'my-project';
// const locationId = 'us-east1';
// const keyRingId = 'my-key-ring';
// const id = 'my-imported-key';

// Imports the Cloud KMS library
const {KeyManagementServiceClient} = require('@google-cloud/kms');

// Instantiates a client
const client = new KeyManagementServiceClient();

// Build the parent key ring name
const keyRingName = client.keyRingPath(projectId, locationId, keyRingId);

async function createKeyForImport() {
  const [key] = await client.createCryptoKey({
    parent: keyRingName,
    cryptoKeyId: id,
    cryptoKey: {
      purpose: 'ENCRYPT_DECRYPT',
      versionTemplate: {
        algorithm: 'GOOGLE_SYMMETRIC_ENCRYPTION',
        protectionLevel: 'HSM',
      },
      // Optional: ensure that only imported versions may be added to this
      // key.
      importOnly: true,
    },
    // Do not allow KMS to generate an initial version of this key.
    skipInitialVersionCreation: true,
  });

  console.log(`Created key for import: ${key.name}`);
  return key;
}

return createKeyForImport();

Python

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Python ולהתקין את Cloud KMS Python SDK.

from google.cloud import kms


def create_key_for_import(
    project_id: str, location_id: str, key_ring_id: str, crypto_key_id: str
) -> None:
    """

    Sets up an empty CryptoKey within a KeyRing for import.


    Args:
        project_id (string): Google Cloud project ID (e.g. 'my-project').
        location_id (string): Cloud KMS location (e.g. 'us-east1').
        key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring').
        crypto_key_id (string): ID of the key to import (e.g. 'my-asymmetric-signing-key').
    """

    # Create the client.
    client = kms.KeyManagementServiceClient()

    # Build the key. For more information regarding allowed values of these fields, see:
    # https://googleapis.dev/python/cloudkms/latest/_modules/google/cloud/kms_v1/types/resources.html
    purpose = kms.CryptoKey.CryptoKeyPurpose.ASYMMETRIC_SIGN
    algorithm = kms.CryptoKeyVersion.CryptoKeyVersionAlgorithm.EC_SIGN_P256_SHA256
    protection_level = kms.ProtectionLevel.HSM
    key = {
        "purpose": purpose,
        "version_template": {
            "algorithm": algorithm,
            "protection_level": protection_level,
        },
    }

    # Build the parent key ring name.
    key_ring_name = client.key_ring_path(project_id, location_id, key_ring_id)

    # Call the API.
    created_key = client.create_crypto_key(
        request={
            "parent": key_ring_name,
            "crypto_key_id": crypto_key_id,
            "crypto_key": key,
            # Do not allow KMS to generate an initial version of this key.
            "skip_initial_version_creation": True,
        }
    )
    print(f"Created hsm key: {created_key.name}")

API

בדוגמאות האלה נעשה שימוש ב-curl כלקוח HTTP כדי להדגים את השימוש ב-API. מידע נוסף על בקרת גישה זמין במאמר גישה ל-Cloud KMS API.

1. יצירת אוסף מפתחות חדש:

   curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings?keyRingId=KEY_RING" \
       --request "POST" \
       --header "authorization: Bearer TOKEN" \
       --header "content-type: application/json" \
       --header "x-goog-user-project: PROJECT_ID" \
       --data "{}"
   

   מידע נוסף מופיע במאמרי העזרה של KeyRing.create API.

2. יצירה של מפתח ריק לייבוא בלבד:

   curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys?cryptoKeyId=KEY_NAME&skipInitialVersionCreation=true" \
       --request "POST" \
       --header "authorization: Bearer TOKEN" \
       --header "content-type: application/json" \
       --header "x-goog-user-project: PROJECT_ID" \
       --data "{"purpose":"PURPOSE", "importOnly": "true", "versionTemplate":{"protectionLevel":"PROTECTION_LEVEL","algorithm":"ALGORITHM"}}"
   

   מידע נוסף מופיע במאמרי העזרה של CryptoKey.create API.‫ אם רוצים ליצור את המפתח ב-Cloud HSM עם דייר יחיד, מוסיפים את השדה cryptoKeyBackend לגוף הפקודה ומוסיפים את מזהה המשאב של מופע Cloud HSM עם דייר יחיד שאליו רוצים לייבא את המפתח:

   "crypto-key-backend": "projects/INSTANCE_PROJECT/locations/LOCATION/singleTenantHsmInstances/INSTANCE_NAME"

מחזיק המפתחות והמפתח קיימים עכשיו, אבל המפתח לא מכיל חומר מפתח, אין לו גרסה והוא לא פעיל. בשלב הבא יוצרים משימת ייבוא.

יצירת משימת ייבוא

משימת ייבוא מגדירה את המאפיינים של המפתחות שהיא מייבאת, כולל מאפיינים שלא ניתן לשנות אחרי ייבוא המפתח.

רמת ההגנה מגדירה אם המפתחות שיובאו באמצעות עבודת הייבוא הזו יאוחסנו בתוכנה, ב-HSM מרובה-דיירים, ב-HSM של דייר יחיד או במערכת חיצונית לניהול מפתחות. אחרי שמבצעים ייבוא של המפתח, אי אפשר לשנות את רמת ההגנה.

שיטת הייבוא מגדירה את האלגוריתם שמשמש ליצירת מפתח האריזה שמגן על המפתחות המיובאים במהלך ההעברה מהמערכת המקומית לפרויקט היעד Google Cloud . אפשר לבחור מפתח RSA של 3,072 ביט או של 4,096 ביט. אלא אם יש לכם דרישות ספציפיות, מומלץ להשתמש במפתח העוטף באורך 3,072 ביט.

הערה: שיטת הייבוא שונה מהאלגוריתם של המפתח שמייבאים. האלגוריתם של המפתח מצוין במהלך בקשת הייבוא.

אפשר ליצור משימת ייבוא באמצעות ה-CLI של gcloud,‏Google Cloud מסוף Google Cloud או Cloud Key Management Service API.

המסוף

1. נכנסים לדף Key Management במסוף Google Cloud .

   כניסה לדף Key Management

2. לוחצים על השם של אוסף מפתחות היעד.

3. מגדירים את רמת ההגנה לתוכנה, ל-HSM או ל-HSM עם דייר יחיד. משתמשים באותה רמת הגנה שהגדרתם למפתח היעד.

4. לוחצים על יצירת פעולת ייבוא.

5. בשדה שם, מזינים את השם של עבודת הייבוא.

6. בתפריט הנפתח Import method (שיטת ייבוא), בוחרים באפשרות 3072 bit RSA (מפתח RSA של 3,072 ביט) או 4096 bit RSA (מפתח RSA של 4,096 ביט).

7. לוחצים על יצירה.

gcloud

כדי להשתמש ב-Cloud KMS בשורת הפקודה, קודם צריך להתקין את הגרסה האחרונה של Google Cloud CLI או לשדרג אליה.

כדי ליצור משימת ייבוא, משתמשים בפקודה כמו זו שבהמשך.

gcloud kms import-jobs create IMPORT_JOB \
  --location LOCATION \
  --keyring KEY_RING \
  --import-method IMPORT_METHOD \
  --protection-level PROTECTION_LEVEL

• משתמשים באותו מחזיק מפתחות ובאותו מיקום כמו מפתח היעד.
• מגדירים את רמת ההגנה לאותו ערך שבו השתמשתם עבור מפתח היעד.
• מגדירים את שיטת הייבוא לאחת מהאפשרויות הבאות:
  • rsa-oaep-3072-sha1-aes-256
  • rsa-oaep-4096-sha1-aes-256
  • rsa-oaep-3072-sha256-aes-256
  • rsa-oaep-4096-sha256-aes-256
  • rsa-oaep-3072-sha256
  • rsa-oaep-4096-sha256

Go

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Go ולהתקין את Cloud KMS Go SDK.

import (
	"context"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
)

// createImportJob creates a new job for importing keys into KMS.
func createImportJob(w io.Writer, parent, id string) error {
	// parent := "projects/PROJECT_ID/locations/global/keyRings/my-key-ring"
	// id := "my-import-job"

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %w", err)
	}
	defer client.Close()

	// Build the request.
	req := &kmspb.CreateImportJobRequest{
		Parent:      parent,
		ImportJobId: id,
		ImportJob: &kmspb.ImportJob{
			// See allowed values and their descriptions at
			// https://cloud.google.com/kms/docs/algorithms#protection_levels
			ProtectionLevel: kmspb.ProtectionLevel_HSM,
			// See allowed values and their descriptions at
			// https://cloud.google.com/kms/docs/key-wrapping#import_methods
			ImportMethod: kmspb.ImportJob_RSA_OAEP_3072_SHA1_AES_256,
		},
	}

	// Call the API.
	result, err := client.CreateImportJob(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to create import job: %w", err)
	}
	fmt.Fprintf(w, "Created import job: %s\n", result.Name)
	return nil
}

Java

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח ב-Java ולהתקין את Cloud KMS Java SDK.

import com.google.cloud.kms.v1.ImportJob;
import com.google.cloud.kms.v1.ImportJob.ImportMethod;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.cloud.kms.v1.KeyRingName;
import com.google.cloud.kms.v1.ProtectionLevel;
import java.io.IOException;

public class CreateImportJob {

  public void createImportJob() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "us-east1";
    String keyRingId = "my-key-ring";
    String id = "my-import-job";
    createImportJob(projectId, locationId, keyRingId, id);
  }

  // Create a new import job.
  public void createImportJob(String projectId, String locationId, String keyRingId, String id)
      throws IOException {
    // Initialize client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests. After
    // completing all of your requests, call the "close" method on the client to
    // safely clean up any remaining background resources.
    try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {
      // Build the parent name from the project, location, and key ring.
      KeyRingName keyRingName = KeyRingName.of(projectId, locationId, keyRingId);

      // Build the import job to create, with parameters.
      ImportJob importJob =
          ImportJob.newBuilder()
              // See allowed values and their descriptions at
              // https://cloud.google.com/kms/docs/algorithms#protection_levels
              .setProtectionLevel(ProtectionLevel.HSM)
              // See allowed values and their descriptions at
              // https://cloud.google.com/kms/docs/key-wrapping#import_methods
              .setImportMethod(ImportMethod.RSA_OAEP_3072_SHA1_AES_256)
              .build();

      // Create the import job.
      ImportJob createdImportJob = client.createImportJob(keyRingName, id, importJob);
      System.out.printf("Created import job %s%n", createdImportJob.getName());
    }
  }
}

Node.js

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Node.js ולהתקין את Cloud KMS Node.js SDK.

//
// TODO(developer): Uncomment these variables before running the sample.
//
// const projectId = 'my-project';
// const locationId = 'us-east1';
// const keyRingId = 'my-key-ring';
// const id = 'my-import-job';

// Imports the Cloud KMS library
const {KeyManagementServiceClient} = require('@google-cloud/kms');

// Instantiates a client
const client = new KeyManagementServiceClient();

// Build the parent key ring name
const keyRingName = client.keyRingPath(projectId, locationId, keyRingId);

async function createImportJob() {
  const [importJob] = await client.createImportJob({
    parent: keyRingName,
    importJobId: id,
    importJob: {
      protectionLevel: 'HSM',
      importMethod: 'RSA_OAEP_3072_SHA256',
    },
  });

  console.log(`Created import job: ${importJob.name}`);
  return importJob;
}

return createImportJob();

Python

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Python ולהתקין את Cloud KMS Python SDK.

from google.cloud import kms


def create_import_job(
    project_id: str, location_id: str, key_ring_id: str, import_job_id: str
) -> None:
    """
    Create a new import job in Cloud KMS.

    Args:
        project_id (string): Google Cloud project ID (e.g. 'my-project').
        location_id (string): Cloud KMS location (e.g. 'us-east1').
        key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring').
        import_job_id (string): ID of the import job (e.g. 'my-import-job').
    """

    # Create the client.
    client = kms.KeyManagementServiceClient()

    # Retrieve the fully-qualified key_ring string.
    key_ring_name = client.key_ring_path(project_id, location_id, key_ring_id)

    # Set paramaters for the import job, allowed values for ImportMethod and ProtectionLevel found here:
    # https://googleapis.dev/python/cloudkms/latest/_modules/google/cloud/kms_v1/types/resources.html

    import_method = kms.ImportJob.ImportMethod.RSA_OAEP_3072_SHA1_AES_256
    protection_level = kms.ProtectionLevel.HSM
    import_job_params = {
        "import_method": import_method,
        "protection_level": protection_level,
    }

    # Call the client to create a new import job.
    import_job = client.create_import_job(
        {
            "parent": key_ring_name,
            "import_job_id": import_job_id,
            "import_job": import_job_params,
        }
    )

    print(f"Created import job: {import_job.name}")

API

בדוגמאות האלה נעשה שימוש ב-curl כלקוח HTTP כדי להדגים את השימוש ב-API. מידע נוסף על בקרת גישה זמין במאמר גישה ל-Cloud KMS API.

כדי ליצור משימת ייבוא, משתמשים בשיטה ImportJobs.create:

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/importJobs?import_job_id=IMPORT_JOB_ID" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{"import_method": "IMPORT_METHOD", "protection_level": "PROTECTION_LEVEL"}'

מחליפים את מה שכתוב בשדות הבאים:

• ‫IMPORT_METHOD: שיטת עטיפת מפתח נתמכת.
• ‫PROTECTION_LEVEL: רמת ההגנה של גרסאות המפתח שיובאו על ידי עבודת הייבוא הזו.

בדיקת הסטטוס של משימת הייבוא

הסטטוס ההתחלתי של משימת ייבוא הוא PENDING_GENERATION. כשהמצב הוא ACTIVE, אפשר להשתמש בו כדי לייבא מפתחות.

התוקף של עבודת ייבוא יפוג אחרי שלושה ימים. אם תוקף משימת הייבוא פג, צריך ליצור משימה חדשה.

אפשר לבדוק את הסטטוס של עבודת ייבוא באמצעות Google Cloud CLI, מסוףGoogle Cloud או Cloud Key Management Service API.

המסוף

1. נכנסים לדף Key Management במסוף Google Cloud .

   כניסה לדף Key Management

2. לוחצים על השם של אוסף המפתחות שמכיל את עבודת הייבוא.

3. לוחצים על הכרטיסייה Import Jobs (פעולות ייבוא) בחלק העליון של הדף.

4. הסטטוס יופיע מתחת לסטטוס לצד השם של עבודת הייבוא.

gcloud

כדי להשתמש ב-Cloud KMS בשורת הפקודה, קודם צריך להתקין את הגרסה האחרונה של Google Cloud CLI או לשדרג אליה.

כשמשימת ייבוא פעילה, אפשר להשתמש בה כדי לייבא מפתחות. הפעולה הזו עשויה להימשך כמה דקות. משתמשים בפקודה הזו כדי לוודא שמשימת הייבוא פעילה. משתמשים במיקום ובמחזיק המפתחות שבהם יצרתם את עבודת הייבוא.

gcloud kms import-jobs describe IMPORT_JOB \
  --location LOCATION \
  --keyring KEY_RING \
  --format="value(state)"

הפלט אמור להיראות כך:

state: ACTIVE

Go

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Go ולהתקין את Cloud KMS Go SDK.

import (
	"context"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
)

// checkStateImportJob checks the state of an ImportJob in KMS.
func checkStateImportJob(w io.Writer, name string) error {
	// name := "projects/PROJECT_ID/locations/global/keyRings/my-key-ring/importJobs/my-import-job"

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %w", err)
	}
	defer client.Close()

	// Call the API.
	result, err := client.GetImportJob(ctx, &kmspb.GetImportJobRequest{
		Name: name,
	})
	if err != nil {
		return fmt.Errorf("failed to get import job: %w", err)
	}
	fmt.Fprintf(w, "Current state of import job %q: %s\n", result.Name, result.State)
	return nil
}

Java

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח ב-Java ולהתקין את Cloud KMS Java SDK.

import com.google.cloud.kms.v1.ImportJob;
import com.google.cloud.kms.v1.ImportJobName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import java.io.IOException;

public class CheckStateImportJob {

  public void checkStateImportJob() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "us-east1";
    String keyRingId = "my-key-ring";
    String importJobId = "my-import-job";
    checkStateImportJob(projectId, locationId, keyRingId, importJobId);
  }

  // Check the state of an import job in Cloud KMS.
  public void checkStateImportJob(
      String projectId, String locationId, String keyRingId, String importJobId)
      throws IOException {
    // Initialize client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests. After
    // completing all of your requests, call the "close" method on the client to
    // safely clean up any remaining background resources.
    try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {
      // Build the parent name from the project, location, and key ring.
      ImportJobName importJobName = ImportJobName.of(projectId, locationId, keyRingId, importJobId);

      // Retrieve the state of an existing import job.
      ImportJob importJob = client.getImportJob(importJobName);
      System.out.printf(
          "Current state of import job %s: %s%n", importJob.getName(), importJob.getState());
    }
  }
}

Node.js

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Node.js ולהתקין את Cloud KMS Node.js SDK.

//
// TODO(developer): Uncomment these variables before running the sample.
//
// const projectId = 'my-project';
// const locationId = 'us-east1';
// const keyRingId = 'my-key-ring';
// const importJobId = 'my-import-job';

// Imports the Cloud KMS library
const {KeyManagementServiceClient} = require('@google-cloud/kms');

// Instantiates a client
const client = new KeyManagementServiceClient();

// Build the import job name
const importJobName = client.importJobPath(
  projectId,
  locationId,
  keyRingId,
  importJobId
);

async function checkStateImportJob() {
  const [importJob] = await client.getImportJob({
    name: importJobName,
  });

  console.log(
    `Current state of import job ${importJob.name}: ${importJob.state}`
  );
  return importJob;
}

return checkStateImportJob();

Python

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Python ולהתקין את Cloud KMS Python SDK.

from google.cloud import kms


def check_state_import_job(
    project_id: str, location_id: str, key_ring_id: str, import_job_id: str
) -> None:
    """
    Check the state of an import job in Cloud KMS.

    Args:
        project_id (string): Google Cloud project ID (e.g. 'my-project').
        location_id (string): Cloud KMS location (e.g. 'us-east1').
        key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring').
        import_job_id (string): ID of the import job (e.g. 'my-import-job').
    """

    # Create the client.
    client = kms.KeyManagementServiceClient()

    # Retrieve the fully-qualified import_job string.
    import_job_name = client.import_job_path(
        project_id, location_id, key_ring_id, import_job_id
    )

    # Retrieve the state from an existing import job.
    import_job = client.get_import_job(name=import_job_name)

    print(f"Current state of import job {import_job.name}: {import_job.state}")

API

בדוגמאות האלה נעשה שימוש ב-curl כלקוח HTTP כדי להדגים את השימוש ב-API. מידע נוסף על בקרת גישה זמין במאמר גישה ל-Cloud KMS API.

כדי לבדוק את הסטטוס של משימת ייבוא, משתמשים בשיטה ImportJobs.get:

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/importJobs/IMPORT_JOB_ID" \
    --request "GET" \
    --header "authorization: Bearer TOKEN"

ברגע שעבודת הייבוא פעילה, אפשר לשלוח בקשה לייבוא מפתח.

מניעת שינוי של משימות ייבוא

עבודת הייבוא קובעת מאפיינים רבים של המפתח המיובא, כולל האלגוריתם של המפתח והאם מדובר במפתח HSM או במפתח תוכנה. אתם יכולים להגדיר הרשאות IAM כדי למנוע מהמשתמשים ליצור משימות ייבוא, אבל לאפשר להם להשתמש במשימות ייבוא כדי לייבא מפתחות.

1. מומלץ להעניק את ההרשאה importjobs.create רק לאדמינים מרכזיים.
2. נותנים את ההרשאה importjobs.useToImport למפעיל שישתמש במשימת הייבוא כדי לייבא מפתחות.
3. כשיוצרים את עבודת הייבוא, מציינים את רמת ההגנה ואת האלגוריתם של גרסאות המפתח שמייבאים באמצעותה.

עד שתוקף משימת הייבוא יפוג, משתמשים שיש להם הרשאה importjobs.useToImport אבל אין להם הרשאה importjobs.create למשימת ייבוא מסוימת יכולים לייבא מפתחות, אבל לא יכולים לשנות את המאפיינים של משימת הייבוא.

ייבוא המפתח

אחרי בדיקת הסטטוס של משימת הייבוא, אפשר לשלוח בקשת ייבוא.

משתמשים בדגלים שונים כדי לשלוח את בקשת הייבוא, בהתאם לשאלה אם רוצים ש-Google Cloud CLI יעטוף את המפתח באופן אוטומטי או אם כבר עטפתם את המפתח באופן ידני.

בין אם עטפתם את המפתח באופן ידני או אוטומטי, אתם צריכים להגדיר את האלגוריתם לאלגוריתם נתמך שתואם לאורך המפתח בפועל שאתם רוצים לייבא, ולציין את מטרת המפתח.

• מפתחות עם המטרה ENCRYPT_DECRYPT משתמשים באלגוריתם google-symmetric-encryption, והאורך שלהם הוא 32.

• מפתחות עם המטרה ASYMMETRIC_DECRYPT או ASYMMETRIC_SIGN תומכים במגוון אלגוריתמים ואורכים.

  אי אפשר לשנות את המטרה של מפתח אחרי שיוצרים אותו, אבל אפשר ליצור גרסאות עוקבות של המפתח באורכים שונים מאלה של גרסת המפתח הראשונית.

חשוב: חובה לציין את האלגוריתם ואת האורך בפועל של המפתח שמייבאים. למידע נוסף, אפשר לעיין במאמר בנושא הכנת המפתח.

הוספה וייבוא אוטומטיים של מפתח

אם רוצים להשתמש בהוספת שורות אוטומטית, צריך להשתמש ב-Google Cloud CLI. משתמשים בפקודה כמו זו שבהמשך. מגדירים את --target-key-file למיקום של המפתח הלא עטוף כדי לעטוף ולייבא אותו. לא להגדיר את --wrapped-key-file.

אפשר להגדיר את הדגל --public-key-file למיקום שבו המפתח הציבורי כבר הורד. כשמייבאים מספר גדול של מפתחות, האפשרות הזו מונעת את ההורדה של המפתח הציבורי במהלך כל ייבוא. לדוגמה, אפשר לכתוב סקריפט שיוריד את המפתח הציבורי פעם אחת, ואז יספק את המיקום שלו כשמייבאים כל מפתח.

gcloud kms keys versions import \
    --import-job IMPORT_JOB \
    --location LOCATION \
    --keyring KEY_RING \
    --key KEY_NAME \
    --algorithm ALGORITHM \
    --target-key-file PATH_TO_UNWRAPPED_KEY

המפתח נארז על ידי מפתח האריזה שמשויך לעבודת הייבוא, מועבר אל Google Cloudומיובא כגרסת מפתח חדשה במפתח היעד.

ייבוא של מפתח שעטוף באופן ידני

בקטע הזה מוסבר איך לייבא מפתח שעטפתם באופן ידני. מגדירים את --wrapped-key-file למיקום של המפתח שעטפתם באופן ידני. לא להגדיר את --target-key-file.

אפשר להגדיר את הדגל --public-key-file למיקום שבו המפתח הציבורי כבר הורד. כשמייבאים מספר גדול של מפתחות, האפשרות הזו מונעת את ההורדה של המפתח הציבורי במהלך כל ייבוא. לדוגמה, אפשר לכתוב סקריפט שיוריד את המפתח הציבורי פעם אחת, ואז יספק את המיקום שלו כשמייבאים כל מפתח.

המסוף

1. פותחים את הדף Key Management במסוףGoogle Cloud .

2. לוחצים על השם של אוסף המפתחות שמכיל את עבודת הייבוא. מפתח היעד מוצג, יחד עם כל המפתחות האחרים בצרור המפתחות.

3. לוחצים על השם של מפתח היעד ואז על ייבוא גרסת מפתח.

4. בוחרים את משימת הייבוא מהתפריט הנפתח בחירת משימת ייבוא.

5. בבורר Upload the wrapped key, בוחרים את המפתח שכבר עטפתם.

6. אם מייבאים מפתח אסימטרי, בוחרים את האלגוריתם מהתפריט הנפתח Algorithm (אלגוריתם). הדף ייבוא גרסת מפתח אמור להיראות כך:

   

7. לוחצים על Import.

gcloud

כדי להשתמש ב-Cloud KMS בשורת הפקודה, קודם צריך להתקין את הגרסה האחרונה של Google Cloud CLI או לשדרג אליה.

משתמשים בפקודה כמו זו שבהמשך.

gcloud kms keys versions import \
  --import-job IMPORT_JOB \
  --location LOCATION \
  --keyring KEY_RING \
  --key KEY_NAME \
  --algorithm ALGORITHM \
  --wrapped-key-file PATH_TO_WRAPPED_KEY

מידע נוסף זמין בפלט של הפקודה gcloud kms keys versions import --help.

Go

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Go ולהתקין את Cloud KMS Go SDK.

import (
	"context"
	"crypto/ecdsa"
	"crypto/elliptic"
	"crypto/rand"
	"crypto/rsa"
	"crypto/sha1"
	"crypto/x509"
	"encoding/pem"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
	"github.com/google/tink/go/kwp/subtle"
)

// importManuallyWrappedKey wraps key material and imports it into KMS.
func importManuallyWrappedKey(w io.Writer, importJobName, cryptoKeyName string) error {
	// importJobName := "projects/PROJECT_ID/locations/global/keyRings/my-key-ring/importJobs/my-import-job"
	// cryptoKeyName := "projects/PROJECT_ID/locations/global/keyRings/my-key-ring/cryptoKeys/my-imported-key"

	// Generate a ECDSA keypair, and format the private key as PKCS #8 DER.
	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
	if err != nil {
		return fmt.Errorf("failed to generate keypair: %w", err)
	}
	keyBytes, err := x509.MarshalPKCS8PrivateKey(key)
	if err != nil {
		return fmt.Errorf("failed to format private key: %w", err)
	}

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %w", err)
	}
	defer client.Close()

	// Generate a temporary 32-byte key for AES-KWP and wrap the key material.
	kwpKey := make([]byte, 32)
	if _, err := rand.Read(kwpKey); err != nil {
		return fmt.Errorf("failed to generate AES-KWP key: %w", err)
	}
	kwp, err := subtle.NewKWP(kwpKey)
	if err != nil {
		return fmt.Errorf("failed to create KWP cipher: %w", err)
	}
	wrappedTarget, err := kwp.Wrap(keyBytes)
	if err != nil {
		return fmt.Errorf("failed to wrap target key with KWP: %w", err)
	}

	// Retrieve the public key from the import job.
	importJob, err := client.GetImportJob(ctx, &kmspb.GetImportJobRequest{
		Name: importJobName,
	})
	if err != nil {
		return fmt.Errorf("failed to retrieve import job: %w", err)
	}
	pubBlock, _ := pem.Decode([]byte(importJob.PublicKey.Pem))
	pubAny, err := x509.ParsePKIXPublicKey(pubBlock.Bytes)
	if err != nil {
		return fmt.Errorf("failed to parse import job public key: %w", err)
	}
	pub, ok := pubAny.(*rsa.PublicKey)
	if !ok {
		return fmt.Errorf("unexpected public key type %T, want *rsa.PublicKey", pubAny)
	}

	// Wrap the KWP key using the import job key.
	wrappedWrappingKey, err := rsa.EncryptOAEP(sha1.New(), rand.Reader, pub, kwpKey, nil)
	if err != nil {
		return fmt.Errorf("failed to wrap KWP key: %w", err)
	}

	// Concatenate the wrapped KWP key and the wrapped target key.
	combined := append(wrappedWrappingKey, wrappedTarget...)

	// Build the request.
	req := &kmspb.ImportCryptoKeyVersionRequest{
		Parent:     cryptoKeyName,
		ImportJob:  importJobName,
		Algorithm:  kmspb.CryptoKeyVersion_EC_SIGN_P256_SHA256,
		WrappedKey: combined,
	}

	// Call the API.
	result, err := client.ImportCryptoKeyVersion(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to import crypto key version: %w", err)
	}
	fmt.Fprintf(w, "Created crypto key version: %s\n", result.Name)
	return nil
}

Java

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח ב-Java ולהתקין את Cloud KMS Java SDK.

import com.google.cloud.kms.v1.CryptoKeyName;
import com.google.cloud.kms.v1.CryptoKeyVersion;
import com.google.cloud.kms.v1.ImportCryptoKeyVersionRequest;
import com.google.cloud.kms.v1.ImportJob;
import com.google.cloud.kms.v1.ImportJobName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.crypto.tink.subtle.Kwp;
import com.google.protobuf.ByteString;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.security.KeyFactory;
import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.PublicKey;
import java.security.SecureRandom;
import java.security.spec.ECGenParameterSpec;
import java.security.spec.MGF1ParameterSpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;
import javax.crypto.Cipher;
import javax.crypto.spec.OAEPParameterSpec;
import javax.crypto.spec.PSource;

public class ImportManuallyWrappedKey {

  public void importManuallyWrappedKey() throws GeneralSecurityException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "us-east1";
    String keyRingId = "my-key-ring";
    String cryptoKeyId = "my-crypto-key";
    String importJobId = "my-import-job";
    importManuallyWrappedKey(projectId, locationId, keyRingId, cryptoKeyId, importJobId);
  }

  // Generates and imports local key material into Cloud KMS.
  public void importManuallyWrappedKey(
      String projectId, String locationId, String keyRingId, String cryptoKeyId, String importJobId)
      throws GeneralSecurityException, IOException {

    // Generate a new ECDSA keypair, and format the private key as PKCS #8 DER.
    KeyPairGenerator generator = KeyPairGenerator.getInstance("EC");
    generator.initialize(new ECGenParameterSpec("secp256r1"));
    KeyPair kp = generator.generateKeyPair();
    byte[] privateBytes = kp.getPrivate().getEncoded();

    // Initialize client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests. After
    // completing all of your requests, call the "close" method on the client to
    // safely clean up any remaining background resources.
    try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {
      // Build the crypto key and import job names from the project, location,
      // key ring, and ID.
      final CryptoKeyName cryptoKeyName =
          CryptoKeyName.of(projectId, locationId, keyRingId, cryptoKeyId);
      final ImportJobName importJobName =
          ImportJobName.of(projectId, locationId, keyRingId, importJobId);

      // Generate a temporary 32-byte key for AES-KWP and wrap the key material.
      byte[] kwpKey = new byte[32];
      new SecureRandom().nextBytes(kwpKey);
      Kwp kwp = new Kwp(kwpKey);
      final byte[] wrappedTargetKey = kwp.wrap(privateBytes);

      // Retrieve the public key from the import job.
      ImportJob importJob = client.getImportJob(importJobName);
      String publicKeyStr = importJob.getPublicKey().getPem();
      // Manually convert PEM to DER. :-(
      publicKeyStr = publicKeyStr.replace("-----BEGIN PUBLIC KEY-----", "");
      publicKeyStr = publicKeyStr.replace("-----END PUBLIC KEY-----", "");
      publicKeyStr = publicKeyStr.replaceAll("\n", "");
      byte[] publicKeyBytes = Base64.getDecoder().decode(publicKeyStr);
      PublicKey publicKey =
          KeyFactory.getInstance("RSA").generatePublic(new X509EncodedKeySpec(publicKeyBytes));

      // Wrap the KWP key using the import job key.
      Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding");
      cipher.init(
          Cipher.ENCRYPT_MODE,
          publicKey,
          new OAEPParameterSpec(
              "SHA-1", "MGF1", MGF1ParameterSpec.SHA1, PSource.PSpecified.DEFAULT));
      byte[] wrappedWrappingKey = cipher.doFinal(kwpKey);

      // Concatenate the wrapped KWP key and the wrapped target key.
      ByteString combinedWrappedKeys =
          ByteString.copyFrom(wrappedWrappingKey).concat(ByteString.copyFrom(wrappedTargetKey));

      // Import the wrapped key material.
      CryptoKeyVersion version =
          client.importCryptoKeyVersion(
              ImportCryptoKeyVersionRequest.newBuilder()
                  .setParent(cryptoKeyName.toString())
                  .setImportJob(importJobName.toString())
                  .setAlgorithm(CryptoKeyVersion.CryptoKeyVersionAlgorithm.EC_SIGN_P256_SHA256)
                  .setRsaAesWrappedKey(combinedWrappedKeys)
                  .build());

      System.out.printf("Imported: %s%n", version.getName());
    }
  }
}

Node.js

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Node.js ולהתקין את Cloud KMS Node.js SDK.

//
// TODO(developer): Uncomment these variables before running the sample.
//
// const projectId = 'my-project';
// const locationId = 'us-east1';
// const keyRingId = 'my-key-ring';
// const cryptoKeyId = 'my-imported-key';
// const importJobId = 'my-import-job';

// Imports the Cloud KMS library
const {KeyManagementServiceClient} = require('@google-cloud/kms');

// Instantiates a client
const client = new KeyManagementServiceClient();

// Build the crypto key and importjob resource names
const cryptoKeyName = client.cryptoKeyPath(
  projectId,
  locationId,
  keyRingId,
  cryptoKeyId
);
const importJobName = client.importJobPath(
  projectId,
  locationId,
  keyRingId,
  importJobId
);

async function wrapAndImportKey() {
  // Generate a 32-byte key to import.
  const crypto = require('crypto');
  const targetKey = crypto.randomBytes(32);

  const [importJob] = await client.getImportJob({name: importJobName});

  // Wrap the target key using the import job key
  const wrappedTargetKey = crypto.publicEncrypt(
    {
      key: importJob.publicKey.pem,
      oaepHash: 'sha256',
      padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
    },
    targetKey
  );

  // Import the target key version
  const [version] = await client.importCryptoKeyVersion({
    parent: cryptoKeyName,
    importJob: importJobName,
    algorithm: 'GOOGLE_SYMMETRIC_ENCRYPTION',
    wrappedKey: wrappedTargetKey,
  });

  console.log(`Imported key version: ${version.name}`);
  return version;
}

return wrapAndImportKey();

Python

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Python ולהתקין את Cloud KMS Python SDK.

import os

# Import the client library and Python standard cryptographic libraries.
from cryptography.hazmat import backends
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives import keywrap
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives.asymmetric import padding
from google.cloud import kms


def import_manually_wrapped_key(
    project_id: str,
    location_id: str,
    key_ring_id: str,
    crypto_key_id: str,
    import_job_id: str,
) -> None:
    """
    Generates and imports local key material to Cloud KMS.

    Args:
        project_id (string): Google Cloud project ID (e.g. 'my-project').
        location_id (string): Cloud KMS location (e.g. 'us-east1').
        key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring').
        crypto_key_id (string): ID of the key to import (e.g. 'my-asymmetric-signing-key').
        import_job_id (string): ID of the import job (e.g. 'my-import-job').
    """

    # Generate some key material in Python and format it in PKCS #8 DER as
    # required by Google Cloud KMS.
    key = ec.generate_private_key(ec.SECP256R1, backends.default_backend())
    formatted_key = key.private_bytes(
        serialization.Encoding.DER,
        serialization.PrivateFormat.PKCS8,
        serialization.NoEncryption(),
    )

    print(f"Generated key bytes: {formatted_key!r}")

    # Create the client.
    client = kms.KeyManagementServiceClient()

    # Retrieve the fully-qualified crypto_key and import_job string.
    crypto_key_name = client.crypto_key_path(
        project_id, location_id, key_ring_id, crypto_key_id
    )
    import_job_name = client.import_job_path(
        project_id, location_id, key_ring_id, import_job_id
    )

    # Generate a temporary 32-byte key for AES-KWP and wrap the key material.
    kwp_key = os.urandom(32)
    wrapped_target_key = keywrap.aes_key_wrap_with_padding(
        kwp_key, formatted_key, backends.default_backend()
    )

    # Retrieve the public key from the import job.
    import_job = client.get_import_job(name=import_job_name)
    import_job_pub = serialization.load_pem_public_key(
        bytes(import_job.public_key.pem, "UTF-8"), backends.default_backend()
    )

    # Wrap the KWP key using the import job key.
    wrapped_kwp_key = import_job_pub.encrypt(
        kwp_key,
        padding.OAEP(
            mgf=padding.MGF1(algorithm=hashes.SHA1()),
            algorithm=hashes.SHA1(),
            label=None,
        ),
    )

    # Import the wrapped key material.
    client.import_crypto_key_version(
        {
            "parent": crypto_key_name,
            "import_job": import_job_name,
            "algorithm": kms.CryptoKeyVersion.CryptoKeyVersionAlgorithm.EC_SIGN_P256_SHA256,
            "rsa_aes_wrapped_key": wrapped_kwp_key + wrapped_target_key,
        }
    )

    print(f"Imported: {import_job.name}")

API

בדוגמאות האלה נעשה שימוש ב-curl כלקוח HTTP כדי להדגים את השימוש ב-API. מידע נוסף על בקרת גישה זמין במאמר גישה ל-Cloud KMS API.

משתמשים ב-method ‏cryptoKeyVersions.import כדי לייבא מפתח.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions:import" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{"importJob": "IMPORT_JOB_ID", "algorithm": "ALGORITHM", "wrappedKey": "WRAPPED_KEY"}'

מחליפים את מה שכתוב בשדות הבאים:

• IMPORT_JOB_ID: שם המשאב המלא של עבודת הייבוא המתאימה.

• ‫ALGORITHM: algorithm של המפתח שמייבאים, שהוא מסוג CryptoKeyVersionAlgorithm.

• ‫WRAPPED_KEY: המפתח שעטפתם באופן ידני בפורמט base64.

הבקשה לייבוא המפתח נשלחת. אפשר לעקוב אחרי הסטטוס שלו.

בדיקת המצב של גרסת המפתח המיובאת

המצב הראשוני של גרסת מפתח מיובאת הוא PENDING_IMPORT. כשהמצב הוא ENABLED, גרסת המפתח יובאה בהצלחה. אם הייבוא נכשל, הסטטוס הוא IMPORT_FAILED.

אפשר לבדוק את הסטטוס של בקשת ייבוא באמצעות Google Cloud CLI,Google Cloud המסוף או Cloud Key Management Service API.

המסוף

1. פותחים את הדף Key Management במסוףGoogle Cloud .

2. לוחצים על השם של אוסף המפתחות שמכיל את עבודת הייבוא.

3. לוחצים על הכרטיסייה Import Jobs (פעולות ייבוא) בחלק העליון של הדף.

4. הסטטוס יופיע מתחת לסטטוס לצד השם של עבודת הייבוא.

gcloud

כדי להשתמש ב-Cloud KMS בשורת הפקודה, קודם צריך להתקין את הגרסה האחרונה של Google Cloud CLI או לשדרג אליה.

משתמשים בפקודה versions list כדי לבדוק את המצב. משתמשים באותו מיקום, באותו אוסף מפתחות יעד ובאותו מפתח יעד שיצרתם קודם בנושא הזה.

gcloud kms keys versions list \
  --keyring KEY_RING \
  --location LOCATION \
  --key KEY_NAME

Go

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Go ולהתקין את Cloud KMS Go SDK.

import (
	"context"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
)

// checkStateImportedKey checks the state of a CryptoKeyVersion in KMS.
func checkStateImportedKey(w io.Writer, name string) error {
	// name := "projects/PROJECT_ID/locations/global/keyRings/my-key-ring/cryptoKeys/my-imported-key/cryptoKeyVersions/1"

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %w", err)
	}
	defer client.Close()

	// Call the API.
	result, err := client.GetCryptoKeyVersion(ctx, &kmspb.GetCryptoKeyVersionRequest{
		Name: name,
	})
	if err != nil {
		return fmt.Errorf("failed to get crypto key version: %w", err)
	}
	fmt.Fprintf(w, "Current state of crypto key version %q: %s\n", result.Name, result.State)
	return nil
}

Java

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח ב-Java ולהתקין את Cloud KMS Java SDK.

import com.google.cloud.kms.v1.CryptoKeyVersion;
import com.google.cloud.kms.v1.CryptoKeyVersionName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import java.io.IOException;

public class CheckStateImportedKey {

  public void checkStateImportedKey() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "us-east1";
    String keyRingId = "my-key-ring";
    String cryptoKeyId = "my-crypto-key";
    String cryptoKeyVersionId = "1";
    checkStateImportedKey(projectId, locationId, keyRingId, cryptoKeyId, cryptoKeyVersionId);
  }

  // Check the state of an imported key in Cloud KMS.
  public void checkStateImportedKey(
      String projectId,
      String locationId,
      String keyRingId,
      String cryptoKeyId,
      String cryptoKeyVersionId)
      throws IOException {
    // Initialize client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests. After
    // completing all of your requests, call the "close" method on the client to
    // safely clean up any remaining background resources.
    try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {
      // Build the version name from its path components.
      CryptoKeyVersionName versionName =
          CryptoKeyVersionName.of(
              projectId, locationId, keyRingId, cryptoKeyId, cryptoKeyVersionId);

      // Retrieve the state of an existing version.
      CryptoKeyVersion version = client.getCryptoKeyVersion(versionName);
      System.out.printf(
          "Current state of crypto key version %s: %s%n", version.getName(), version.getState());
    }
  }
}

Node.js

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Node.js ולהתקין את Cloud KMS Node.js SDK.

//
// TODO(developer): Uncomment these variables before running the sample.
//
// const projectId = 'my-project';
// const locationId = 'us-east1';
// const keyRingId = 'my-key-ring';
// const cryptoKeyId = 'my-imported-key';
// const cryptoKeyVersionId = '1';

// Imports the Cloud KMS library
const {KeyManagementServiceClient} = require('@google-cloud/kms');

// Instantiates a client
const client = new KeyManagementServiceClient();

// Build the key version name
const keyVersionName = client.cryptoKeyVersionPath(
  projectId,
  locationId,
  keyRingId,
  cryptoKeyId,
  cryptoKeyVersionId
);

async function checkStateCryptoKeyVersion() {
  const [keyVersion] = await client.getCryptoKeyVersion({
    name: keyVersionName,
  });

  console.log(
    `Current state of key version ${keyVersion.name}: ${keyVersion.state}`
  );
  return keyVersion;
}

return checkStateCryptoKeyVersion();

Python

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Python ולהתקין את Cloud KMS Python SDK.

from google.cloud import kms


def check_state_imported_key(
    project_id: str, location_id: str, key_ring_id: str, import_job_id: str
) -> None:
    """
    Check the state of an import job in Cloud KMS.

    Args:
        project_id (string): Google Cloud project ID (e.g. 'my-project').
        location_id (string): Cloud KMS location (e.g. 'us-east1').
        key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring').
        import_job_id (string): ID of the import job (e.g. 'my-import-job').
    """

    # Create the client.
    client = kms.KeyManagementServiceClient()

    # Retrieve the fully-qualified import_job string.
    import_job_name = client.import_job_path(
        project_id, location_id, key_ring_id, import_job_id
    )

    # Retrieve the state from an existing import job.
    import_job = client.get_import_job(name=import_job_name)

    print(f"Current state of import job {import_job.name}: {import_job.state}")

API

בדוגמאות האלה נעשה שימוש ב-curl כלקוח HTTP כדי להדגים את השימוש ב-API. מידע נוסף על בקרת גישה זמין במאמר גישה ל-Cloud KMS API.

מבצעים קריאה ל-ImportJob.get ובודקים את השדה state. אם הערך של state הוא PENDING_GENERATION, משימת הייבוא עדיין בתהליך יצירה. בודקים מחדש את הסטטוס מדי פעם עד שהוא משתנה ל-ACTIVE.

אחרי שמייבאים את גרסת המפתח הראשונית, הסטטוס של המפתח משתנה לפעיל. לפני שמשתמשים במפתחות סימטריים, צריך להגדיר את גרסת המפתח המיובאת כגרסה הראשית.

מפתחות סימטריים: הגדרת הגרסה הראשית

השלב הזה נדרש כשמייבאים מפתחות סימטריים, והוא לא רלוונטי למפתחות אסימטריים. למפתח אסימטרי אין גרסה ראשית. צריך להשתמש ב-Google Cloud CLI כדי להגדיר את הגרסה הראשית.

טיפ: בדרך כלל KEY_VERSION הוא 1, כי הגרסה המיובאת היא הגרסה הראשונה של המפתח.

gcloud kms keys set-primary-version KEY_NAME\
    --location=LOCATION\
    --keyring=KEY_RING\
    --version=KEY_VERSION

ייבוא מחדש של מפתח שהושמד בעבר

‫Cloud Key Management Service תומך בייבוא מחדש של מפתחות, שמאפשר לשחזר גרסת מפתח שיוצאה בעבר במצב DESTROYED או IMPORT_FAILED למצב ENABLED על ידי אספקת חומר המפתח המקורי. אם לא בוצע ייבוא של חומר מפתח מקורי בגלל כשל בייבוא הראשוני, אפשר לספק כל חומר מפתח.

הגבלות

• אפשר לייבא מחדש רק את CryptoKeyVersions שיוצאו בעבר.
• אם הגרסה יובאה בהצלחה בעבר, חומר המפתח שיובא מחדש חייב להיות זהה לחומר המפתח המקורי.
• אי אפשר לייבא מחדש קבצים שנמחקו לפני השקת התכונה הזו.CryptoKeyVersions השדה reimport_eligible של CryptoKeyVersion הוא true אם הגרסה כשירה לייבוא מחדש, ו-false אם היא לא כשירה.

אפשר לייבא מחדש מפתחות תוכנה ומפתחות Cloud HSM, אבל אי אפשר לייבא מחדש מפתחות חיצוניים.

ייבוא מחדש של מפתח שהושמד

יוצרים ImportJob לייבוא מחדש לפי השלבים במאמר יצירת משימת ייבוא. אתם יכולים להשתמש בImportJob קיים או בImportJob חדש, כל עוד רמת ההגנה תואמת לרמת ההגנה המקורית.

המסוף

1. נכנסים לדף Key Management במסוף Google Cloud .

   כניסה לדף Key Management

2. לוחצים על השם של אוסף המפתחות שמכיל את המפתח שאת גרסת המפתח שלו רוצים לייבא מחדש.

3. לוחצים על המפתח שאת גרסת המפתח שלו רוצים לייבא מחדש.

4. לוחצים על סמל האפשרויות הנוספות (3 נקודות) לצד גרסת המפתח שרוצים לייבא מחדש.

5. בוחרים באפשרות ייבוא מחדש של גרסת המפתח.

6. בוחרים את משימת הייבוא מהתפריט הנפתח בחירת משימת ייבוא.

7. בבורר Upload the wrapped key, בוחרים את המפתח שכבר עטפתם. המפתח הזה צריך להיות זהה לחומר המפתח המקורי.

8. לוחצים על ייבוא מחדש.

gcloud

כדי להשתמש ב-Cloud KMS בשורת הפקודה, קודם צריך להתקין את הגרסה האחרונה של Google Cloud CLI או לשדרג אליה.

1. מייבאים מחדש את גרסת המפתח באמצעות חומר המפתח המקורי.

   gcloud kms keys versions import \
   --location LOCATION \
   --keyring KEY_RING \
   --key KEY_NAME \
   --version KEY_VERSION \
   --algorithm ALGORITHM \
   --import-job IMPORT_JOB \
   --target-key-file PATH_TO_KEY \
   

API

בדוגמאות האלה נעשה שימוש ב-curl כלקוח HTTP כדי להדגים את השימוש ב-API. מידע נוסף על בקרת גישה זמין במאמר גישה ל-Cloud KMS API.

1. בגוף הבקשה של שיטת cryptoKeyVersions.import, מגדירים את השדה cryptoKeyVersion לשם גרסת המפתח של הגרסה שמייבאים. הוא חייב להיות צאצא של מפתח ההצפנה.

2. בגוף הבקשה, מגדירים את השדה algorithm לאלגוריתם של המפתח שמייבאים. הערך הזה צריך להיות זהה לאלגוריתם של גרסת המפתח המקורית. השדה algorithm הוא מסוג CryptoKeyVersionAlgorithm.

3. בגוף הבקשה, מגדירים את השדה wrappedKeyMaterial לחומרי המפתח שכבר עברו עטיפה.

4. מבצעים קריאה ל-method‏ cryptoKeyVersions.import. התגובה cryptoKeyVersions.import היא מסוג CryptoKeyVersion. אחרי שמייבאים מפתח בהצלחה, המצב שלו הוא ENABLED ואפשר להשתמש בו ב-Cloud KMS.

המאמרים הבאים

• אימות מפתח מיובא אחרי שתאשרו שחומר המפתח המיובא זהה למפתח המקורי, תוכלו להשתמש במפתח לחתימה או להגנה על נתונים.
• פתרון בעיות שקשורות לייבוא מפתחות שנכשל