Merotasi kunci

Halaman ini menunjukkan cara merotasi kunci secara otomatis atau manual. Untuk mengetahui informasi selengkapnya tentang rotasi kunci secara umum, lihat Rotasi kunci.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk merotasi kunci, minta administrator untuk memberi Anda peran IAM berikut pada kunci:

• Admin Cloud KMS (roles/cloudkms.admin)
• Enkripsi ulang data: Enkripsi/Pendekripsi Cloud KMS CryptoKey (roles/cloudkms.cryptoKeyEncrypterDecrypter)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses.

Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk merotasi kunci. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk merotasi kunci:

• Ubah versi kunci utama: cloudkms.cryptoKeys.update
• Ubah atau nonaktifkan putar otomatis: cloudkms.cryptoKeys.update
• Buat versi kunci baru: cloudkms.cryptoKeyVersions.create
• Nonaktifkan versi kunci lama: cloudkms.cryptoKeyVersions.update
• Enkripsi ulang data:
  • cloudkms.cryptoKeyVersions.useToDecrypt
  • cloudkms.cryptoKeyVersions.useToEncrypt

Anda mung juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaanlainnya.

Satu pengguna dengan peran khusus yang berisi semua izin ini dapat merotasi kunci dan mengenkripsi ulang datanya sendiri. Pengguna dengan peran Admin Cloud KMS dan peran Encrypter/Decrypter Cloud KMS CryptoKey dapat bekerja sama untuk merotasi kunci dan mengenkripsi ulang data. Ikuti prinsip hak istimewa terendah saat menetapkan peran. Untuk mengetahui detail selengkapnya, lihat Izin dan peran.

Saat Anda merotasi kunci, data yang dienkripsi dengan versi kunci sebelumnya tidak akan otomatis dienkripsi ulang. Untuk mempelajari lebih lanjut, lihat mendekripsi dan mengenkripsi ulang. Memutar kunci tidak otomatis menonaktifkan atau destroy versi kunci yang ada.

Mengonfigurasi rotasi otomatis

Catatan: Rotasi otomatis tidak didukung untuk penandatanganan asimetris atau kunci enkripsi asimetris. Untuk informasi selengkapnya, lihat Pertimbangan untuk kunci asimetris.

Untuk mengonfigurasi rotasi otomatis saat membuat kunci baru:

Konsol

Saat Anda menggunakan Konsol Google Cloud untuk membuat kunci, Cloud KMS akan otomatis menetapkan periode rotasi dan waktu rotasi berikutnya secara otomatis. Anda dapat memilih untuk menggunakan nilai default atau menentukan nilai yang berbeda.

Untuk menentukan periode rotasi dan waktu mulai yang berbeda, saat Anda membuat kunci, tetapi sebelum mengklik tombol Create:

1. Untuk Key rotasi period, pilih salah satu opsi.

2. Untuk Mulai, pilih tanggal yang Anda inginkan untuk melakukan rotasi otomatis pertama. Anda dapat membiarkan Memulai dengan nilai default untuk memulai rotasi otomatis pertamanya, satu periode rotasi kunci sejak Anda membuat kunci.

gcloud

Untuk menggunakan Cloud KMS di command line, Instal atau upgrade Google Cloud CLI ke versi terbaru terlebih dahulu.

gcloud kms keys create KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --purpose "encryption" \
    --rotation-period ROTATION_PERIOD \
    --next-rotation-time NEXT_ROTATION_TIME

Ganti kode berikut:

• KEY_NAME: nama kunci.
• KEY_RING: nama key ring yang berisi kunci.
• LOCATION: lokasi Cloud KMS key ring.
• ROTATION_PERIOD: interval untuk merotasi kunci—misalnya, 30d untuk merotasi kunci setiap 30 hari. Periode rotasi minimal harus 1 hari dan maksimal 100 tahun. Untuk mengetahui informasi selengkapnya, lihat CryptoKey.rotationPeriod.
• NEXT_ROTATION_TIME: stempel waktu saat menyelesaikan rotasi pertama—misalnya, "2023-01-01T01:02:03". Anda dapat menghilangkan --next-rotation-time untuk menjadwalkan rotasi pertama selama 7 hari sejak Anda menjalankan perintah. Untuk mengetahui informasi selengkapnya, lihat CryptoKey.nextRotationTime.

Untuk mengetahui informasi tentang semua tanda dan nilai yang memungkinkan, jalankan perintah dengan tanda --help.

C#

Untuk menjalankan kode ini, siapkan lingkungan pengembangan C# terlebih dahulu lalu instal Cloud KMS C# SDK.

using Google.Cloud.Kms.V1;
using Google.Protobuf.WellKnownTypes;
using System;

public class CreateKeyRotationScheduleSample
{
    public CryptoKey CreateKeyRotationSchedule(
      string projectId = "my-project", string locationId = "us-east1", string keyRingId = "my-key-ring",
      string id = "my-key-with-rotation-schedule")
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the parent key ring name.
        KeyRingName keyRingName = new KeyRingName(projectId, locationId, keyRingId);

        // Build the key.
        CryptoKey key = new CryptoKey
        {
            Purpose = CryptoKey.Types.CryptoKeyPurpose.EncryptDecrypt,
            VersionTemplate = new CryptoKeyVersionTemplate
            {
                Algorithm = CryptoKeyVersion.Types.CryptoKeyVersionAlgorithm.GoogleSymmetricEncryption,
            },

            // Rotate the key every 30 days.
            RotationPeriod = new Duration
            {
                Seconds = 60 * 60 * 24 * 30, // 30 days
            },

            // Start the first rotation in 24 hours.
            NextRotationTime = new Timestamp
            {
                Seconds = new DateTimeOffset(DateTime.UtcNow.AddHours(24)).ToUnixTimeSeconds(),
            }
        };

        // Call the API.
        CryptoKey result = client.CreateCryptoKey(keyRingName, id, key);

        // Return the result.
        return result;
    }
}

Go

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Go terlebih dahulu lalu instal Cloud KMS Go SDK.

import (
	"context"
	"fmt"
	"io"
	"time"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
	"google.golang.org/protobuf/types/known/durationpb"
	"google.golang.org/protobuf/types/known/timestamppb"
)

// createKeyRotationSchedule creates a key with a rotation schedule.
func createKeyRotationSchedule(w io.Writer, parent, id string) error {
	// name := "projects/my-project/locations/us-east1/keyRings/my-key-ring"
	// id := "my-key-with-rotation-schedule"

	// 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_ENCRYPT_DECRYPT,
			VersionTemplate: &kmspb.CryptoKeyVersionTemplate{
				Algorithm: kmspb.CryptoKeyVersion_GOOGLE_SYMMETRIC_ENCRYPTION,
			},

			// Rotate the key every 30 days
			RotationSchedule: &kmspb.CryptoKey_RotationPeriod{
				RotationPeriod: &durationpb.Duration{
					Seconds: int64(60 * 60 * 24 * 30), // 30 days
				},
			},

			// Start the first rotation in 24 hours
			NextRotationTime: &timestamppb.Timestamp{
				Seconds: time.Now().Add(24 * time.Hour).Unix(),
			},
		},
	}

	// 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

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Java terlebih dahulu dan instal Java SDK Cloud KMS.

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.protobuf.Duration;
import com.google.protobuf.Timestamp;
import java.io.IOException;
import java.time.temporal.ChronoUnit;

public class CreateKeyRotationSchedule {

  public void createKeyRotationSchedule() 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-key";
    createKeyRotationSchedule(projectId, locationId, keyRingId, id);
  }

  // Create a new key that automatically rotates on a schedule.
  public void createKeyRotationSchedule(
      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);

      // Calculate the date 24 hours from now (this is used below).
      long tomorrow = java.time.Instant.now().plus(24, ChronoUnit.HOURS).getEpochSecond();

      // Build the key to create with a rotation schedule.
      CryptoKey key =
          CryptoKey.newBuilder()
              .setPurpose(CryptoKeyPurpose.ENCRYPT_DECRYPT)
              .setVersionTemplate(
                  CryptoKeyVersionTemplate.newBuilder()
                      .setAlgorithm(CryptoKeyVersionAlgorithm.GOOGLE_SYMMETRIC_ENCRYPTION))

              // Rotate every 30 days.
              .setRotationPeriod(
                  Duration.newBuilder().setSeconds(java.time.Duration.ofDays(30).getSeconds()))

              // Start the first rotation in 24 hours.
              .setNextRotationTime(Timestamp.newBuilder().setSeconds(tomorrow))
              .build();

      // Create the key.
      CryptoKey createdKey = client.createCryptoKey(keyRingName, id, key);
      System.out.printf("Created key with rotation schedule %s%n", createdKey.getName());
    }
  }
}

Node.js

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Node.js terlebih dahulu, lalu instal Node.js SDK Cloud KMS.

//
// 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-rotating-encryption-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 createKeyRotationSchedule() {
  const [key] = await client.createCryptoKey({
    parent: keyRingName,
    cryptoKeyId: id,
    cryptoKey: {
      purpose: 'ENCRYPT_DECRYPT',
      versionTemplate: {
        algorithm: 'GOOGLE_SYMMETRIC_ENCRYPTION',
      },

      // Rotate the key every 30 days.
      rotationPeriod: {
        seconds: 60 * 60 * 24 * 30,
      },

      // Start the first rotation in 24 hours.
      nextRotationTime: {
        seconds: new Date().getTime() / 1000 + 60 * 60 * 24,
      },
    },
  });

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

return createKeyRotationSchedule();

PHP

Untuk menjalankan kode ini, pelajari cara menggunakan PHP di Google Cloud terlebih dahulu dan instal PHP SDK Cloud KMS.

use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient;
use Google\Cloud\Kms\V1\CreateCryptoKeyRequest;
use Google\Cloud\Kms\V1\CryptoKey;
use Google\Cloud\Kms\V1\CryptoKey\CryptoKeyPurpose;
use Google\Cloud\Kms\V1\CryptoKeyVersion\CryptoKeyVersionAlgorithm;
use Google\Cloud\Kms\V1\CryptoKeyVersionTemplate;
use Google\Protobuf\Duration;
use Google\Protobuf\Timestamp;

function create_key_rotation_schedule(
    string $projectId = 'my-project',
    string $locationId = 'us-east1',
    string $keyRingId = 'my-key-ring',
    string $id = 'my-key-with-rotation-schedule'
): CryptoKey {
    // Create the Cloud KMS client.
    $client = new KeyManagementServiceClient();

    // Build the parent key ring name.
    $keyRingName = $client->keyRingName($projectId, $locationId, $keyRingId);

    // Build the key.
    $key = (new CryptoKey())
        ->setPurpose(CryptoKeyPurpose::ENCRYPT_DECRYPT)
        ->setVersionTemplate((new CryptoKeyVersionTemplate())
            ->setAlgorithm(CryptoKeyVersionAlgorithm::GOOGLE_SYMMETRIC_ENCRYPTION))

        // Rotate the key every 30 days.
        ->setRotationPeriod((new Duration())
            ->setSeconds(60 * 60 * 24 * 30)
        )

        // Start the first rotation in 24 hours.
        ->setNextRotationTime((new Timestamp())
            ->setSeconds(time() + 60 * 60 * 24)
        );

    // Call the API.
    $createCryptoKeyRequest = (new CreateCryptoKeyRequest())
        ->setParent($keyRingName)
        ->setCryptoKeyId($id)
        ->setCryptoKey($key);
    $createdKey = $client->createCryptoKey($createCryptoKeyRequest);
    printf('Created key with rotation: %s' . PHP_EOL, $createdKey->getName());

    return $createdKey;
}

Python

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Python terlebih dahulu lalu instal Cloud KMS Python SDK.

import time

from google.cloud import kms

def create_key_rotation_schedule(
    project_id: str, location_id: str, key_ring_id: str, key_id: str
) -> kms.CryptoKey:
    """
    Creates a new key in Cloud KMS that automatically rotates.

    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').
        key_id (string): ID of the key to create (e.g. 'my-rotating-key').

    Returns:
        CryptoKey: Cloud KMS key.

    """

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

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

    # Build the key.
    purpose = kms.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT
    algorithm = (
        kms.CryptoKeyVersion.CryptoKeyVersionAlgorithm.GOOGLE_SYMMETRIC_ENCRYPTION
    )
    key = {
        "purpose": purpose,
        "version_template": {
            "algorithm": algorithm,
        },
        # Rotate the key every 30 days.
        "rotation_period": {"seconds": 60 * 60 * 24 * 30},
        # Start the first rotation in 24 hours.
        "next_rotation_time": {"seconds": int(time.time()) + 60 * 60 * 24},
    }

    # Call the API.
    created_key = client.create_crypto_key(
        request={"parent": key_ring_name, "crypto_key_id": key_id, "crypto_key": key}
    )
    print(f"Created labeled key: {created_key.name}")
    return created_key

Ruby

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Ruby terlebih dahulu dan instal Ruby SDK Cloud KMS.

# TODO(developer): uncomment these values before running the sample.
# project_id  = "my-project"
# location_id = "us-east1"
# key_ring_id = "my-key-ring"
# id          = "my-key-with-rotation"

# Require the library.
require "google/cloud/kms"

# Create the client.
client = Google::Cloud::Kms.key_management_service

# Build the parent key ring name.
key_ring_name = client.key_ring_path project: project_id, location: location_id, key_ring: key_ring_id

# Build the key.
key = {
  purpose:            :ENCRYPT_DECRYPT,
  version_template:   {
    algorithm: :GOOGLE_SYMMETRIC_ENCRYPTION
  },

  # Rotate the key every 30 days.
  rotation_period:    {
    seconds: 60 * 60 * 24 * 30
  },

  # Start the first rotation in 24 hours.
  next_rotation_time: {
    seconds: (Time.now + (60 * 60 * 24)).to_i
  }
}

# Call the API.
created_key = client.create_crypto_key parent: key_ring_name, crypto_key_id: id, crypto_key: key
puts "Created rotating key: #{created_key.name}"

API

Contoh ini menggunakan curl sebagai klien HTTP untuk menunjukkan penggunaan API. Untuk informasi selengkapnya tentang kontrol akses, lihat Mengakses Cloud KMS API.

Untuk membuat kunci, gunakan metode CryptoKey.create:

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys?crypto_key_id=KEY_NAME" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{"purpose": "PURPOSE", "rotationPeriod": "ROTATION_PERIOD", "nextRotationTime": "NEXT_ROTATION_TIME"}'

Ganti kode berikut:

• PURPOSE: tujuan kunci.
• ROTATION_PERIOD: interval untuk merotasi kunci—misalnya, 30d untuk merotasi kunci setiap 30 hari. Periode rotasi minimal harus 1 hari dan maksimal 100 tahun. Untuk mengetahui informasi selengkapnya, lihat CryptoKey.rotationPeriod.
• NEXT_ROTATION_TIME: stempel waktu saat menyelesaikan rotasi pertama—misalnya, "2023-01-01T01:02:03". Anda dapat menghilangkan --next-rotation-time untuk menjadwalkan rotasi pertama selama 7 hari sejak Anda menjalankan perintah. Untuk mengetahui informasi selengkapnya, lihat CryptoKey.nextRotationTime.

Untuk mengonfigurasi rotasi otomatis pada kunci yang ada:

Konsol

1. Buka halaman Key Management di konsol Google Cloud.

   Buka halaman Key Management

2. Klik nama key ring yang berisi kunci yang ingin Anda tambahkan jadwal rotasi.

3. Klik kunci yang ingin Anda tambahi jadwal rotasi.

4. Di header, klik Edit Rotation Period.

5. Pada perintah, pilih nilai baru untuk kolom Rotation period dan Getting on.

6. Pada perintah, klik Simpan.

gcloud

Untuk menggunakan Cloud KMS di command line, Instal atau upgrade Google Cloud CLI ke versi terbaru terlebih dahulu.

gcloud kms keys update KEY_NAME \
    --location LOCATION \
    --keyring KEY_RING \
    --rotation-period ROTATION_PERIOD \
    --next-rotation-time NEXT_ROTATION_TIME

Ganti kode berikut:

• KEY_NAME: nama kunci.
• KEY_RING: nama key ring yang berisi kunci.
• LOCATION: lokasi Cloud KMS key ring.
• ROTATION_PERIOD: interval untuk merotasi kunci—misalnya, 30d untuk merotasi kunci setiap 30 hari. Periode rotasi minimal harus 1 hari dan maksimal 100 tahun. Untuk mengetahui informasi selengkapnya, lihat CryptoKey.rotationPeriod.
• NEXT_ROTATION_TIME: stempel waktu saat menyelesaikan rotasi pertama—misalnya, "2023-01-01T01:02:03". Anda dapat menghilangkan --next-rotation-time untuk menjadwalkan rotasi pertama selama 7 hari sejak Anda menjalankan perintah. Untuk mengetahui informasi selengkapnya, lihat CryptoKey.nextRotationTime.

Untuk mengetahui informasi tentang semua tanda dan nilai yang memungkinkan, jalankan perintah dengan tanda --help.

C#

Untuk menjalankan kode ini, siapkan lingkungan pengembangan C# terlebih dahulu lalu instal Cloud KMS C# SDK.

using Google.Cloud.Kms.V1;
using Google.Protobuf.WellKnownTypes;
using System;

public class UpdateKeyAddRotationSample
{
    public CryptoKey UpdateKeyAddRotation(string projectId = "my-project", string locationId = "us-east1", string keyRingId = "my-key-ring", string keyId = "my-key")
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the key.
        CryptoKey key = new CryptoKey
        {
            // Provide the name of the key to update.
            CryptoKeyName = new CryptoKeyName(projectId, locationId, keyRingId, keyId),

            // Rotate the key every 30 days.
            RotationPeriod = new Duration
            {
                Seconds = 60 * 60 * 24 * 30, // 30 days
            },

            // Start the first rotation in 24 hours.
            NextRotationTime = new Timestamp
            {
                Seconds = new DateTimeOffset(DateTime.UtcNow.AddHours(24)).ToUnixTimeSeconds(),
            }
        };

        // Build the update mask.
        FieldMask fieldMask = new FieldMask
        {
            Paths = { "rotation_period", "next_rotation_time" },
        };

        // Call the API.
        CryptoKey result = client.UpdateCryptoKey(key, fieldMask);

        // Return the updated key.
        return result;
    }
}

Go

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Go terlebih dahulu lalu instal Cloud KMS Go SDK.

import (
	"context"
	"fmt"
	"io"
	"time"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
	fieldmask "google.golang.org/genproto/protobuf/field_mask"
	"google.golang.org/protobuf/types/known/durationpb"
	"google.golang.org/protobuf/types/known/timestamppb"
)

// addRotationSchedule updates a key to add a rotation schedule. If the key
// already has a rotation schedule, it is overwritten.
func addRotationSchedule(w io.Writer, name string) error {
	// name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-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.UpdateCryptoKeyRequest{
		CryptoKey: &kmspb.CryptoKey{
			// Provide the name of the key to update
			Name: name,

			// Rotate the key every 30 days
			RotationSchedule: &kmspb.CryptoKey_RotationPeriod{
				RotationPeriod: &durationpb.Duration{
					Seconds: int64(60 * 60 * 24 * 30), // 30 days
				},
			},

			// Start the first rotation in 24 hours
			NextRotationTime: &timestamppb.Timestamp{
				Seconds: time.Now().Add(24 * time.Hour).Unix(),
			},
		},
		UpdateMask: &fieldmask.FieldMask{
			Paths: []string{"rotation_period", "next_rotation_time"},
		},
	}

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

Java

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Java terlebih dahulu dan instal Java SDK Cloud KMS.

import com.google.cloud.kms.v1.CryptoKey;
import com.google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose;
import com.google.cloud.kms.v1.CryptoKeyName;
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.protobuf.Duration;
import com.google.protobuf.FieldMask;
import com.google.protobuf.Timestamp;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;
import java.time.temporal.ChronoUnit;

public class UpdateKeyAddRotation {

  public void updateKeyAddRotation() 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 keyId = "my-key";
    updateKeyAddRotation(projectId, locationId, keyRingId, keyId);
  }

  // Update a key to add or change a rotation schedule.
  public void updateKeyAddRotation(
      String projectId, String locationId, String keyRingId, String keyId) 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 name from the project, location, and key ring.
      CryptoKeyName cryptoKeyName = CryptoKeyName.of(projectId, locationId, keyRingId, keyId);

      // Calculate the date 24 hours from now (this is used below).
      long tomorrow = java.time.Instant.now().plus(24, ChronoUnit.HOURS).getEpochSecond();

      // Build the key to update with a rotation schedule.
      CryptoKey key =
          CryptoKey.newBuilder()
              .setName(cryptoKeyName.toString())
              .setPurpose(CryptoKeyPurpose.ENCRYPT_DECRYPT)
              .setVersionTemplate(
                  CryptoKeyVersionTemplate.newBuilder()
                      .setAlgorithm(CryptoKeyVersionAlgorithm.GOOGLE_SYMMETRIC_ENCRYPTION))

              // Rotate every 30 days.
              .setRotationPeriod(
                  Duration.newBuilder().setSeconds(java.time.Duration.ofDays(30).getSeconds()))

              // Start the first rotation in 24 hours.
              .setNextRotationTime(Timestamp.newBuilder().setSeconds(tomorrow))
              .build();

      // Construct the field mask.
      FieldMask fieldMask = FieldMaskUtil.fromString("rotation_period,next_rotation_time");

      // Update the key.
      CryptoKey updatedKey = client.updateCryptoKey(key, fieldMask);
      System.out.printf("Updated key %s%n", updatedKey.getName());
    }
  }
}

Node.js

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Node.js terlebih dahulu, lalu instal Node.js SDK Cloud KMS.

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

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

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

// Build the key name
const keyName = client.cryptoKeyPath(projectId, locationId, keyRingId, keyId);

async function updateKeyAddRotation() {
  const [key] = await client.updateCryptoKey({
    cryptoKey: {
      name: keyName,

      // Rotate the key every 30 days.
      rotationPeriod: {
        seconds: 60 * 60 * 24 * 30,
      },

      // Start the first rotation in 24 hours.
      nextRotationTime: {
        seconds: new Date().getTime() / 1000 + 60 * 60 * 24,
      },
    },
    updateMask: {
      paths: ['rotation_period', 'next_rotation_time'],
    },
  });

  console.log(`Updated rotation for: ${key.name}`);
  return key;
}

return updateKeyAddRotation();

PHP

Untuk menjalankan kode ini, pelajari cara menggunakan PHP di Google Cloud terlebih dahulu dan instal PHP SDK Cloud KMS.

use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient;
use Google\Cloud\Kms\V1\CryptoKey;
use Google\Cloud\Kms\V1\UpdateCryptoKeyRequest;
use Google\Protobuf\Duration;
use Google\Protobuf\FieldMask;
use Google\Protobuf\Timestamp;

function update_key_add_rotation(
    string $projectId = 'my-project',
    string $locationId = 'us-east1',
    string $keyRingId = 'my-key-ring',
    string $keyId = 'my-key'
): CryptoKey {
    // Create the Cloud KMS client.
    $client = new KeyManagementServiceClient();

    // Build the key name.
    $keyName = $client->cryptoKeyName($projectId, $locationId, $keyRingId, $keyId);

    // Build the key.
    $key = (new CryptoKey())
        ->setName($keyName)

        // Rotate the key every 30 days.
        ->setRotationPeriod((new Duration())
            ->setSeconds(60 * 60 * 24 * 30)
        )

        // Start the first rotation in 24 hours.
        ->setNextRotationTime((new Timestamp())
            ->setSeconds(time() + 60 * 60 * 24)
        );

    // Create the field mask.
    $updateMask = (new FieldMask())
        ->setPaths(['rotation_period', 'next_rotation_time']);

    // Call the API.
    $updateCryptoKeyRequest = (new UpdateCryptoKeyRequest())
        ->setCryptoKey($key)
        ->setUpdateMask($updateMask);
    $updatedKey = $client->updateCryptoKey($updateCryptoKeyRequest);
    printf('Updated key: %s' . PHP_EOL, $updatedKey->getName());

    return $updatedKey;
}

Python

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Python terlebih dahulu lalu instal Cloud KMS Python SDK.

import time

from google.cloud import kms

def update_key_add_rotation(
    project_id: str, location_id: str, key_ring_id: str, key_id: str
) -> kms.CryptoKey:
    """
    Add a rotation schedule to an existing key.

    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').
        key_id (string): ID of the key to use (e.g. 'my-key').

    Returns:
        CryptoKey: Updated Cloud KMS key.

    """

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

    # Build the key name.
    key_name = client.crypto_key_path(project_id, location_id, key_ring_id, key_id)

    key = {
        "name": key_name,
        "rotation_period": {
            "seconds": 60 * 60 * 24 * 30  # Rotate the key every 30 days.
        },
        "next_rotation_time": {
            "seconds": int(time.time())
            + 60 * 60 * 24  # Start the first rotation in 24 hours.
        },
    }

    # Build the update mask.
    update_mask = {"paths": ["rotation_period", "next_rotation_time"]}

    # Call the API.
    updated_key = client.update_crypto_key(
        request={"crypto_key": key, "update_mask": update_mask}
    )
    print(f"Updated key: {updated_key.name}")
    return updated_key

Ruby

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Ruby terlebih dahulu dan instal Ruby SDK Cloud KMS.

# TODO(developer): uncomment these values before running the sample.
# project_id  = "my-project"
# location_id = "us-east1"
# key_ring_id = "my-key-ring"
# key_id      = "my-key"

# Require the library.
require "google/cloud/kms"

# Create the client.
client = Google::Cloud::Kms.key_management_service

# Build the parent key name.
key_name = client.crypto_key_path project:    project_id,
                                  location:   location_id,
                                  key_ring:   key_ring_id,
                                  crypto_key: key_id

# Build the key.
key = {
  name:               key_name,

  # Rotate the key every 30 days.
  rotation_period:    {
    seconds: 60 * 60 * 24 * 30
  },

  # Start the first rotation in 24 hours.
  next_rotation_time: {
    seconds: (Time.now + (60 * 60 * 24)).to_i
  }
}

# Build the field mask.
update_mask = { paths: ["rotation_period", "next_rotation_time"] }

# Call the API.
updated_key = client.update_crypto_key crypto_key: key, update_mask: update_mask
puts "Updated key: #{updated_key.name}"

API

Contoh ini menggunakan curl sebagai klien HTTP untuk menunjukkan penggunaan API. Untuk informasi selengkapnya tentang kontrol akses, lihat Mengakses Cloud KMS API.

Untuk mengupdate kunci, gunakan metode CryptoKey.patch:

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME?updateMask=rotationPeriod,nextRotationTime" \
    --request "PATCH" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{"rotationPeriod": "ROTATION_PERIOD", "nextRotationTime": "NEXT_ROTATION_TIME"}'

Ganti kode berikut:

• ROTATION_PERIOD: interval untuk merotasi kunci—misalnya, 30d untuk merotasi kunci setiap 30 hari. Periode rotasi minimal harus 1 hari dan maksimal 100 tahun. Untuk mengetahui informasi selengkapnya, lihat CryptoKey.rotationPeriod.
• NEXT_ROTATION_TIME: stempel waktu saat menyelesaikan rotasi pertama—misalnya, "2023-01-01T01:02:03". Anda dapat menghilangkan --next-rotation-time untuk menjadwalkan rotasi pertama selama 7 hari sejak Anda menjalankan perintah. Untuk mengetahui informasi selengkapnya, lihat CryptoKey.nextRotationTime.

Memutar kunci secara manual

Pertama, buat versi kunci baru:

Konsol

1. Buka halaman Key Management di konsol Google Cloud.

   Buka halaman Key Management

2. Klik nama key ring yang berisi kunci yang akan Anda buat versi kunci barunya.

3. Klik kunci yang akan dibuatkan versi kunci barunya.

4. Di header, klik Putar.

5. Pada perintah, klik Putar untuk mengonfirmasi.

gcloud

Untuk menggunakan Cloud KMS di command line, Instal atau upgrade Google Cloud CLI ke versi terbaru terlebih dahulu.

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

Ganti kode berikut:

• KEY_NAME: nama kunci.
• KEY_RING: nama key ring yang berisi kunci.
• LOCATION: lokasi Cloud KMS key ring.

Versi kunci diberi nomor secara berurutan.

Untuk mengetahui informasi tentang semua tanda dan nilai yang memungkinkan, jalankan perintah dengan tanda --help.

C#

Untuk menjalankan kode ini, siapkan lingkungan pengembangan C# terlebih dahulu lalu instal Cloud KMS C# SDK.

using Google.Cloud.Kms.V1;

public class CreateKeyVersionSample
{
    public CryptoKeyVersion CreateKeyVersion(string projectId = "my-project", string locationId = "us-east1", string keyRingId = "my-key-ring", string keyId = "my-key")
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the parent key name.
        CryptoKeyName keyName = new CryptoKeyName(projectId, locationId, keyRingId, keyId);

        // Build the key version.
        CryptoKeyVersion keyVersion = new CryptoKeyVersion { };

        // Call the API.
        CryptoKeyVersion result = client.CreateCryptoKeyVersion(keyName, keyVersion);

        // Return the result.
        return result;
    }
}

Go

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Go terlebih dahulu lalu instal Cloud KMS Go SDK.

import (
	"context"
	"fmt"
	"io"

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

// createKeyVersion creates a new key version for the given key.
func createKeyVersion(w io.Writer, parent string) error {
	// parent := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-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.CreateCryptoKeyVersionRequest{
		Parent: parent,
	}

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

Java

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Java terlebih dahulu dan instal Java SDK Cloud KMS.

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

public class CreateKeyVersion {

  public void createKeyVersion() 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 keyId = "my-key";
    createKeyVersion(projectId, locationId, keyRingId, keyId);
  }

  // Create a new key version.
  public void createKeyVersion(String projectId, String locationId, String keyRingId, String keyId)
      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.
      CryptoKeyName cryptoKeyName = CryptoKeyName.of(projectId, locationId, keyRingId, keyId);

      // Build the key version to create.
      CryptoKeyVersion keyVersion = CryptoKeyVersion.newBuilder().build();

      // Create the key.
      CryptoKeyVersion createdVersion = client.createCryptoKeyVersion(cryptoKeyName, keyVersion);
      System.out.printf("Created key version %s%n", createdVersion.getName());
    }
  }
}

Node.js

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Node.js terlebih dahulu, lalu instal Node.js SDK Cloud KMS.

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

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

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

// Build the parent key name
const keyName = client.cryptoKeyPath(projectId, locationId, keyRingId, keyId);

async function createKeyVersion() {
  const [version] = await client.createCryptoKeyVersion({
    parent: keyName,
  });

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

return createKeyVersion();

PHP

Untuk menjalankan kode ini, pelajari cara menggunakan PHP di Google Cloud terlebih dahulu dan instal PHP SDK Cloud KMS.

use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient;
use Google\Cloud\Kms\V1\CreateCryptoKeyVersionRequest;
use Google\Cloud\Kms\V1\CryptoKeyVersion;

function create_key_version(
    string $projectId = 'my-project',
    string $locationId = 'us-east1',
    string $keyRingId = 'my-key-ring',
    string $keyId = 'my-key'
): CryptoKeyVersion {
    // Create the Cloud KMS client.
    $client = new KeyManagementServiceClient();

    // Build the parent key name.
    $keyName = $client->cryptoKeyName($projectId, $locationId, $keyRingId, $keyId);

    // Build the key version.
    $version = new CryptoKeyVersion();

    // Call the API.
    $createCryptoKeyVersionRequest = (new CreateCryptoKeyVersionRequest())
        ->setParent($keyName)
        ->setCryptoKeyVersion($version);
    $createdVersion = $client->createCryptoKeyVersion($createCryptoKeyVersionRequest);
    printf('Created key version: %s' . PHP_EOL, $createdVersion->getName());

    return $createdVersion;
}

Python

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Python terlebih dahulu lalu instal Cloud KMS Python SDK.

from google.cloud import kms

def create_key_version(
    project_id: str, location_id: str, key_ring_id: str, key_id: str
) -> kms.CryptoKey:
    """
    Creates a new version of the given key.

    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').
        key_id (string): ID of the key for which to create a new version (e.g. 'my-key').

    Returns:
        CryptoKeyVersion: Cloud KMS key version.

    """

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

    # Build the parent key name.
    key_name = client.crypto_key_path(project_id, location_id, key_ring_id, key_id)

    # Build the key version.
    version = {}

    # Call the API.
    created_version = client.create_crypto_key_version(
        request={"parent": key_name, "crypto_key_version": version}
    )
    print(f"Created key version: {created_version.name}")
    return created_version

Ruby

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Ruby terlebih dahulu dan instal Ruby SDK Cloud KMS.

# TODO(developer): uncomment these values before running the sample.
# project_id  = "my-project"
# location_id = "us-east1"
# key_ring_id = "my-key-ring"
# key_id      = "my-key"

# Require the library.
require "google/cloud/kms"

# Create the client.
client = Google::Cloud::Kms.key_management_service

# Build the parent key name.
key_name = client.crypto_key_path project:    project_id,
                                  location:   location_id,
                                  key_ring:   key_ring_id,
                                  crypto_key: key_id

# Build the version.
version = {}

# Call the API.
created_version = client.create_crypto_key_version parent: key_name, crypto_key_version: version
puts "Created key version: #{created_version.name}"

API

Contoh ini menggunakan curl sebagai klien HTTP untuk menunjukkan penggunaan API. Untuk informasi selengkapnya tentang kontrol akses, lihat Mengakses Cloud KMS API.

Untuk merotasi kunci secara manual, pertama-tama buat versi kunci baru dengan memanggil metode CryptoKeyVersions.create.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions" \
    --request "POST" \
    --header "authorization: Bearer TOKEN"

Perintah ini membuat versi kunci baru, tetapi tidak menetapkannya sebagai versi utama.

Untuk menetapkan versi kunci baru sebagai utama, lihat Menetapkan versi yang ada sebagai versi kunci utama.

Jika perlu, enkripsi ulang data yang dienkripsi menggunakan versi kunci sebelumnya.

Menetapkan versi yang ada sebagai versi kunci utama

Untuk menetapkan versi kunci yang berbeda sebagai versi utama sebuah kunci, update kunci dengan informasi versi utama yang baru. Versi kunci harus diaktifkan sebelum Anda dapat mengonfigurasinya sebagai versi utama.

Konsol

1. Buka halaman Key Management di konsol Google Cloud.

   Buka halaman Key Management

2. Klik nama key ring yang berisi kunci yang versi utamanya ingin diperbarui.

3. Klik kunci yang versi utamanya ingin Anda perbarui.

4. Di baris yang sesuai dengan versi kunci yang ingin Anda jadikan sebagai utama, klik View More .

5. Klik Buat versi utama di menu.

6. Pada dialog konfirmasi, klik Jadikan sebagai utama.

gcloud

Untuk menggunakan Cloud KMS di command line, Instal atau upgrade Google Cloud CLI ke versi terbaru terlebih dahulu.

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

Ganti kode berikut:

• KEY_NAME: nama kunci.
• KEY_RING: nama key ring yang berisi kunci.
• LOCATION: lokasi Cloud KMS key ring.
• KEY_VERSION: nomor versi versi kunci utama yang baru.

Untuk mengetahui informasi tentang semua tanda dan nilai yang memungkinkan, jalankan perintah dengan tanda --help.

C#

Untuk menjalankan kode ini, siapkan lingkungan pengembangan C# terlebih dahulu lalu instal Cloud KMS C# SDK.

using Google.Cloud.Kms.V1;

public class UpdateKeySetPrimarySample
{
    public CryptoKey UpdateKeySetPrimary(
      string projectId = "my-project", string locationId = "us-east1", string keyRingId = "my-key-ring", string keyId = "my-key",
      string keyVersionId = "123")
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the key name.
        CryptoKeyName keyName = new CryptoKeyName(projectId, locationId, keyRingId, keyId);

        // Call the API.
        CryptoKey result = client.UpdateCryptoKeyPrimaryVersion(keyName, keyVersionId);

        // Return the updated key.
        return result;
    }
}

Go

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Go terlebih dahulu lalu instal Cloud KMS Go SDK.

import (
	"context"
	"fmt"
	"io"

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

// updateKeySetPrimary updates the primary key version on a Cloud KMS key.
func updateKeySetPrimary(w io.Writer, name, version string) error {
	// name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key"
	// version := "123"

	// 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.UpdateCryptoKeyPrimaryVersionRequest{
		Name:               name,
		CryptoKeyVersionId: version,
	}

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

	return nil
}

Java

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Java terlebih dahulu dan instal Java SDK Cloud KMS.

import com.google.cloud.kms.v1.CryptoKey;
import com.google.cloud.kms.v1.CryptoKeyName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import java.io.IOException;

public class UpdateKeySetPrimary {

  public void updateKeySetPrimary() 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 keyId = "my-key";
    String keyVersionId = "123";
    updateKeySetPrimary(projectId, locationId, keyRingId, keyId, keyVersionId);
  }

  // Update a key's primary version.
  public void updateKeySetPrimary(
      String projectId, String locationId, String keyRingId, String keyId, String keyVersionId)
      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 name from the project, location, key ring, and keyId.
      CryptoKeyName cryptoKeyName = CryptoKeyName.of(projectId, locationId, keyRingId, keyId);

      // Create the key.
      CryptoKey createdKey = client.updateCryptoKeyPrimaryVersion(cryptoKeyName, keyVersionId);
      System.out.printf("Updated key primary version %s%n", createdKey.getName());
    }
  }
}

Node.js

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Node.js terlebih dahulu, lalu instal Node.js SDK Cloud KMS.

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

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

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

// Build the key name
const keyName = client.cryptoKeyPath(projectId, locationId, keyRingId, keyId);

async function updateKeySetPrimary() {
  const [key] = await client.updateCryptoKeyPrimaryVersion({
    name: keyName,
    cryptoKeyVersionId: versionId,
  });

  console.log(`Set primary to ${versionId}`);
  return key;
}

return updateKeySetPrimary();

PHP

Untuk menjalankan kode ini, pelajari cara menggunakan PHP di Google Cloud terlebih dahulu dan instal PHP SDK Cloud KMS.

use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient;
use Google\Cloud\Kms\V1\UpdateCryptoKeyPrimaryVersionRequest;

function update_key_set_primary(
    string $projectId = 'my-project',
    string $locationId = 'us-east1',
    string $keyRingId = 'my-key-ring',
    string $keyId = 'my-key',
    string $versionId = '123'
) {
    // Create the Cloud KMS client.
    $client = new KeyManagementServiceClient();

    // Build the key name.
    $keyName = $client->cryptoKeyName($projectId, $locationId, $keyRingId, $keyId);

    // Call the API.
    $updateCryptoKeyPrimaryVersionRequest = (new UpdateCryptoKeyPrimaryVersionRequest())
        ->setName($keyName)
        ->setCryptoKeyVersionId($versionId);
    $updatedKey = $client->updateCryptoKeyPrimaryVersion($updateCryptoKeyPrimaryVersionRequest);
    printf('Updated primary %s to %s' . PHP_EOL, $updatedKey->getName(), $versionId);

    return $updatedKey;
}

Ruby

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Ruby terlebih dahulu dan instal Ruby SDK Cloud KMS.

# TODO(developer): uncomment these values before running the sample.
# project_id  = "my-project"
# location_id = "us-east1"
# key_ring_id = "my-key-ring"
# key_id      = "my-key"
# version_id  = "123"

# Require the library.
require "google/cloud/kms"

# Create the client.
client = Google::Cloud::Kms.key_management_service

# Build the parent key name.
key_name = client.crypto_key_path project:    project_id,
                                  location:   location_id,
                                  key_ring:   key_ring_id,
                                  crypto_key: key_id

# Call the API.
updated_key = client.update_crypto_key_primary_version name: key_name, crypto_key_version_id: version_id
puts "Updated primary #{updated_key.name} to #{version_id}"

Python

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Python terlebih dahulu lalu instal Cloud KMS Python SDK.

from google.cloud import kms

def update_key_set_primary(
    project_id: str, location_id: str, key_ring_id: str, key_id: str, version_id: str
) -> kms.CryptoKey:
    """
    Update the primary version of a key.

    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').
        key_id (string): ID of the key to use (e.g. 'my-key').
        version_id (string): ID of the key to make primary (e.g. '2').

    Returns:
        CryptoKey: Updated Cloud KMS key.

    """

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

    # Build the key name.
    key_name = client.crypto_key_path(project_id, location_id, key_ring_id, key_id)

    # Call the API.
    updated_key = client.update_crypto_key_primary_version(
        request={"name": key_name, "crypto_key_version_id": version_id}
    )
    print(f"Updated {updated_key.name} primary to {version_id}")
    return updated_key

API

Contoh ini menggunakan curl sebagai klien HTTP untuk menunjukkan penggunaan API. Untuk informasi selengkapnya tentang kontrol akses, lihat Mengakses Cloud KMS API.

Ubah versi kunci utama dengan memanggil metode CryptoKey.updatePrimaryVersion.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME:updatePrimaryVersion" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{"cryptoKeyVersionId": "KEY_VERSION"}'

Ganti kode berikut:

• PROJECT_ID: ID project yang berisi key ring.
• LOCATION: lokasi Cloud KMS key ring.
• KEY_RING: nama key ring yang berisi kunci.
• KEY_NAME: nama kunci.
• KEY_VERSION: nomor versi versi kunci utama yang baru.

Saat Anda mengubah versi kunci utama, perubahan biasanya akan menjadi konsisten dalam 1 menit. Namun, perubahan ini memerlukan waktu hingga 3 jam untuk diterapkan dalam kasus luar biasa. Selama waktu ini, versi utama sebelumnya mungkin digunakan untuk mengenkripsi data. Untuk mengetahui informasi selengkapnya, lihat Konsistensi resource Cloud KMS.

Nonaktifkan rotasi otomatis

Untuk menonaktifkan rotasi otomatis pada kunci, hapus jadwal rotasi kunci:

Konsol

1. Buka halaman Key Management di konsol Google Cloud.

   Buka halaman Key Management

2. Klik nama key ring yang berisi kunci yang ingin Anda hapus jadwal rotasinya.

3. Klik kunci yang ingin Anda hapus jadwal rotasinya.

4. Di header, klik Edit Rotation Period.

5. Pada perintah, klik kolom Rotation period, lalu pilih Never (manualRotation).

6. Pada perintah, klik Simpan.

gcloud

Untuk menggunakan Cloud KMS di command line, Instal atau upgrade Google Cloud CLI ke versi terbaru terlebih dahulu.

gcloud kms keys update KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --remove-rotation-schedule

Ganti kode berikut:

• KEY_NAME: nama kunci.
• KEY_RING: nama key ring yang berisi kunci.
• LOCATION: lokasi Cloud KMS key ring.

Untuk mengetahui informasi tentang semua tanda dan nilai yang memungkinkan, jalankan perintah dengan tanda --help.

C#

Untuk menjalankan kode ini, siapkan lingkungan pengembangan C# terlebih dahulu lalu instal Cloud KMS C# SDK.

using Google.Cloud.Kms.V1;
using Google.Protobuf.WellKnownTypes;

public class UpdateKeyRemoveRotationSample
{
    public CryptoKey UpdateKeyRemoveRotation(string projectId = "my-project", string locationId = "us-east1", string keyRingId = "my-key-ring", string keyId = "my-key")
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the key.
        CryptoKey key = new CryptoKey
        {
            CryptoKeyName = new CryptoKeyName(projectId, locationId, keyRingId, keyId),
            RotationPeriod = null,
            NextRotationTime = null,
        };

        // Build the update mask.
        FieldMask fieldMask = new FieldMask
        {
            Paths = { "rotation_period", "next_rotation_time" },
        };

        // Call the API.
        CryptoKey result = client.UpdateCryptoKey(key, fieldMask);

        // Return the updated key.
        return result;
    }
}

Go

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Go terlebih dahulu lalu instal Cloud KMS Go SDK.

import (
	"context"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
	fieldmask "google.golang.org/genproto/protobuf/field_mask"
)

// removeRotationSchedule updates a key to remove a rotation schedule, if one
// exists.
func removeRotationSchedule(w io.Writer, name string) error {
	// name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-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.UpdateCryptoKeyRequest{
		CryptoKey: &kmspb.CryptoKey{
			// Provide the name of the key to update
			Name: name,

			// Remove any rotation fields.
			RotationSchedule: nil,
			NextRotationTime: nil,
		},
		UpdateMask: &fieldmask.FieldMask{
			Paths: []string{"rotation_period", "next_rotation_time"},
		},
	}

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

Java

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Java terlebih dahulu dan instal Java SDK Cloud KMS.

import com.google.cloud.kms.v1.CryptoKey;
import com.google.cloud.kms.v1.CryptoKeyName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

public class UpdateKeyRemoveRotation {

  public void updateKeyRemoveRotation() 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 keyId = "my-key";
    updateKeyRemoveRotation(projectId, locationId, keyRingId, keyId);
  }

  // Update a key to remove all labels.
  public void updateKeyRemoveRotation(
      String projectId, String locationId, String keyRingId, String keyId) 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 name from the project, location, key ring, and keyId.
      CryptoKeyName cryptoKeyName = CryptoKeyName.of(projectId, locationId, keyRingId, keyId);

      // Build an empty key with no labels.
      CryptoKey key =
          CryptoKey.newBuilder()
              .setName(cryptoKeyName.toString())
              .clearRotationPeriod()
              .clearNextRotationTime()
              .build();

      // Construct the field mask.
      FieldMask fieldMask = FieldMaskUtil.fromString("rotation_period,next_rotation_time");

      // Create the key.
      CryptoKey createdKey = client.updateCryptoKey(key, fieldMask);
      System.out.printf("Updated key %s%n", createdKey.getName());
    }
  }
}

Node.js

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Node.js terlebih dahulu, lalu instal Node.js SDK Cloud KMS.

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

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

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

// Build the key name
const keyName = client.cryptoKeyPath(projectId, locationId, keyRingId, keyId);

async function updateKeyRemoveRotation() {
  const [key] = await client.updateCryptoKey({
    cryptoKey: {
      name: keyName,
      rotationPeriod: null,
      nextRotationTime: null,
    },
    updateMask: {
      paths: ['rotation_period', 'next_rotation_time'],
    },
  });

  console.log(`Removed rotation for: ${key.name}`);
  return key;
}

return updateKeyRemoveRotation();

PHP

Untuk menjalankan kode ini, pelajari cara menggunakan PHP di Google Cloud terlebih dahulu dan instal PHP SDK Cloud KMS.

use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient;
use Google\Cloud\Kms\V1\CryptoKey;
use Google\Cloud\Kms\V1\UpdateCryptoKeyRequest;
use Google\Protobuf\FieldMask;

function update_key_remove_rotation(
    string $projectId = 'my-project',
    string $locationId = 'us-east1',
    string $keyRingId = 'my-key-ring',
    string $keyId = 'my-key'
): CryptoKey {
    // Create the Cloud KMS client.
    $client = new KeyManagementServiceClient();

    // Build the key name.
    $keyName = $client->cryptoKeyName($projectId, $locationId, $keyRingId, $keyId);

    // Build the key.
    $key = (new CryptoKey())
        ->setName($keyName);

    // Create the field mask.
    $updateMask = (new FieldMask())
        ->setPaths(['rotation_period', 'next_rotation_time']);

    // Call the API.
    $updateCryptoKeyRequest = (new UpdateCryptoKeyRequest())
        ->setCryptoKey($key)
        ->setUpdateMask($updateMask);
    $updatedKey = $client->updateCryptoKey($updateCryptoKeyRequest);
    printf('Updated key: %s' . PHP_EOL, $updatedKey->getName());

    return $updatedKey;
}

Ruby

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Ruby terlebih dahulu dan instal Ruby SDK Cloud KMS.

# TODO(developer): uncomment these values before running the sample.
# project_id  = "my-project"
# location_id = "us-east1"
# key_ring_id = "my-key-ring"
# key_id      = "my-key"

# Require the library.
require "google/cloud/kms"

# Create the client.
client = Google::Cloud::Kms.key_management_service

# Build the parent key name.
key_name = client.crypto_key_path project:    project_id,
                                  location:   location_id,
                                  key_ring:   key_ring_id,
                                  crypto_key: key_id

# Build the key.
key = {
  name:               key_name,
  rotation_period:    nil,
  next_rotation_time: nil
}

# Build the field mask.
update_mask = { paths: ["rotation_period", "next_rotation_time"] }

# Call the API.
updated_key = client.update_crypto_key crypto_key: key, update_mask: update_mask
puts "Updated key: #{updated_key.name}"

Python

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Python terlebih dahulu lalu instal Cloud KMS Python SDK.

from google.cloud import kms

def update_key_remove_rotation(
    project_id: str, location_id: str, key_ring_id: str, key_id: str
) -> kms.CryptoKey:
    """
    Remove a rotation schedule from an existing key.

    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').
        key_id (string): ID of the key to use (e.g. 'my-key').

    Returns:
        CryptoKey: Updated Cloud KMS key.

    """

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

    # Build the key name.
    key_name = client.crypto_key_path(project_id, location_id, key_ring_id, key_id)

    key = {"name": key_name}

    # Build the update mask.
    update_mask = {"paths": ["rotation_period", "next_rotation_time"]}

    # Call the API.
    updated_key = client.update_crypto_key(
        request={"crypto_key": key, "update_mask": update_mask}
    )
    print(f"Updated key: {updated_key.name}")
    return updated_key

API

Contoh ini menggunakan curl sebagai klien HTTP untuk menunjukkan penggunaan API. Untuk informasi selengkapnya tentang kontrol akses, lihat Mengakses Cloud KMS API.

Untuk mengupdate kunci, gunakan metode CryptoKey.patch:

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME?updateMask=rotationPeriod,nextRotationTime" \
    --request "PATCH" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{"rotationPeriod": null, "nextRotationTime": null}'

Untuk detail tambahan tentang rotationPeriod dan nextRotationTime, lihat keyRings.cryptoKeys.

Merotasi kunci eksternal

Merotasi kunci eksternal terkoordinasi

Anda dapat mengonfigurasi rotasi otomatis untuk kunci eksternal terkoordinasi secara simetris. Anda juga dapat membuat versi kunci baru secara manual untuk kunci eksternal terkoordinasi simetris atau asimetris.

Memutar atau membuat versi kunci baru akan menyebabkan semua data yang baru dibuat yang dilindungi dengan kunci tersebut dienkripsi dengan versi kunci baru. Data yang dilindungi dengan versi kunci sebelumnya tidak dienkripsi ulang. Akibatnya, pengelola kunci eksternal Anda harus terus menyediakan materi kunci dari versi kunci sebelumnya agar dapat digunakan.

Untuk membuat versi kunci baru bagi kunci eksternal terkoordinasi, selesaikan langkah-langkah berikut:

Konsol

1. Di konsol Google Cloud, buka halaman Key Management.

   Buka Key Management

2. Pilih key ring, lalu pilih key ring.

3. Klik Buat versi. Sebuah pesan menunjukkan bahwa versi kunci baru Anda akan dibuat di Cloud KMS dan EKM. Jika Anda melihat kolom Jalur kunci atau URI Kunci, kunci yang dipilih bukan kunci eksternal yang terkoordinasi.

4. Untuk mengonfirmasi bahwa Anda ingin membuat versi kunci baru, klik Create version.

Versi kunci baru akan muncul dalam status Pembuatan tertunda. Untuk kunci simetris, versi kunci yang dibuat secara manual tidak otomatis ditetapkan sebagai versi kunci utama. Anda dapat menetapkan versi kunci baru Anda sebagai utama.

gcloud CLI

Untuk membuat versi kunci simetris baru dan menetapkannya sebagai versi kunci utama, gunakan perintah kms keys versions create dengan tanda --primary:

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

Ganti kode berikut:

• KEY_NAME: nama kunci.
• KEY_RING: nama key ring yang berisi kunci.
• LOCATION: lokasi Cloud KMS key ring.

Untuk membuat versi kunci asimetris baru atau membuat versi kunci simetris baru yang bukan merupakan versi kunci utama, gunakan perintah kms keys versions create:

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

Ganti kode berikut:

• KEY_NAME: nama kunci.
• KEY_RING: nama key ring yang berisi kunci.
• LOCATION: lokasi Cloud KMS key ring.

Merotasi Cloud EKM yang dikelola secara manual melalui kunci VPC

Pertama, putar materi kunci eksternal di pengelola kunci eksternal Anda. Jika hasil tersebut menghasilkan jalur kunci baru, Anda perlu merotasi atau membuat versi kunci Cloud EKM baru dengan jalur kunci baru tersebut. Untuk kunci enkripsi simetris, rotasikan kunci Cloud EKM dan tentukan jalur kunci baru dari pengelola kunci eksternal Anda. Untuk kunci asimetris, buat versi kunci baru dan tentukan jalur kunci baru.

Memutar atau membuat versi kunci baru akan menyebabkan semua data yang baru dibuat yang dilindungi dengan kunci tersebut dienkripsi dengan versi kunci baru. Data yang dilindungi dengan versi kunci sebelumnya tidak dienkripsi ulang. Akibatnya, pengelola kunci eksternal Anda harus terus menyediakan materi kunci dari versi kunci sebelumnya agar dapat digunakan.

Jika materi kunci dalam sistem partner pengelolaan kunci eksternal tidak berubah, tetapi jalur kunci berubah, Anda dapat memperbarui jalur eksternal kunci tanpa merotasi kunci.

Konsol

1. Di konsol Google Cloud, buka halaman Key Management.

   Buka Key Management

2. Pilih key ring, lalu pilih key ring.

3. Klik Rotate key.

4. Untuk Key path, masukkan jalur kunci untuk versi baru.

5. Klik Rotate Key untuk mengonfirmasi.

gcloud

Untuk menggunakan Cloud KMS di command line, Instal atau upgrade Google Cloud CLI ke versi terbaru terlebih dahulu.

Untuk membuat versi kunci simetris baru dan menetapkannya sebagai versi kunci utama, gunakan perintah kms keys versions create dengan tanda --primary:

gcloud kms keys versions create \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --ekm-connection-key-path EXTERNAL_KEY_PATH \
    --primary

Ganti kode berikut:

• KEY_NAME: nama kunci.
• KEY_RING: nama key ring yang berisi kunci.
• LOCATION: lokasi Cloud KMS key ring.
• EXTERNAL_KEY_PATH: jalur ke versi kunci eksternal baru.

Untuk membuat versi kunci asimetris baru atau membuat versi kunci simetris baru yang bukan merupakan versi kunci utama, gunakan perintah kms keys versions create:

gcloud kms keys versions create \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --ekm-connection-key-path EXTERNAL_KEY_PATH

Ganti kode berikut:

• KEY_NAME: nama kunci.
• KEY_RING: nama key ring yang berisi kunci.
• LOCATION: lokasi Cloud KMS key ring.
• EXTERNAL_KEY_PATH: jalur ke versi kunci eksternal baru.

Untuk mengetahui informasi tentang semua tanda dan nilai yang memungkinkan, jalankan perintah dengan tanda --help.

Setelah versi kunci berhasil dibuat, Anda dapat menggunakannya seperti halnya menggunakan versi kunci Cloud KMS lainnya.

Merotasi Cloud EKM yang dikelola secara manual melalui kunci internet

Pertama, putar materi kunci eksternal di pengelola kunci eksternal Anda. Jika hasilnya menghasilkan URI baru, Anda perlu merotasi atau membuat versi kunci Cloud EKM baru dengan URI baru. Untuk kunci enkripsi simetris, rotasikan kunci Cloud EKM dan tentukan URI kunci baru dari pengelola kunci eksternal Anda. Untuk kunci asimetris, buat versi kunci baru dan tentukan URI kunci baru.

Memutar atau membuat versi kunci baru akan menyebabkan semua data yang baru dibuat yang dilindungi dengan kunci tersebut dienkripsi dengan versi kunci baru. Data yang dilindungi dengan versi kunci sebelumnya tidak dienkripsi ulang. Akibatnya, pengelola kunci eksternal Anda harus terus menyediakan materi kunci dari versi kunci sebelumnya agar dapat digunakan.

Jika materi kunci dalam sistem partner pengelolaan kunci eksternal tidak berubah, tetapi URI berubah, Anda dapat mengupdate URI eksternal kunci tanpa merotasi kunci.

Konsol

1. Di konsol Google Cloud, buka halaman Key Management.

   Buka Key Management

2. Pilih key ring, lalu pilih key ring.

3. Pilih Rotate key untuk kunci simetris atau Create version untuk kunci asimetris.

4. Masukkan URI kunci baru, lalu pilih Rotate Key untuk kunci simetris atau Create version untuk kunci asimetris.

Versi kunci baru akan menjadi versi utama.

gcloud CLI

Untuk membuat versi kunci simetris baru dan menetapkannya sebagai versi kunci utama, gunakan perintah kms keys versions create dengan tanda --primary:

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

Ganti kode berikut:

• KEY_NAME: nama kunci.
• KEY_RING: nama key ring yang berisi kunci.
• LOCATION: lokasi Cloud KMS key ring.
• EXTERNAL_KEY_URI: URI kunci dari versi kunci eksternal baru.

Untuk membuat versi kunci asimetris baru atau membuat versi kunci simetris baru yang bukan merupakan versi kunci utama, gunakan perintah kms keys versions create:

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

Ganti kode berikut:

• KEY_NAME: nama kunci.
• KEY_RING: nama key ring yang berisi kunci.
• LOCATION: lokasi Cloud KMS key ring.
• EXTERNAL_KEY_URI: URI kunci dari versi kunci eksternal baru.