feat(kms): Add samples for new KMS RNG APIs (GoogleCloudPlatform#1467)

sethvargo · web-flow · commit be7f090121f4 · 2021-08-23T11:50:22.000-07:00
diff --git a/kms/composer.json b/kms/composer.json
@@ -1,5 +1,5 @@
 {
     "require": {
-        "google/cloud-kms": "^1.10.0"
+        "google/cloud-kms": "^1.12.0"
     }
 }
diff --git a/kms/src/create_key_asymmetric_decrypt.php b/kms/src/create_key_asymmetric_decrypt.php
@@ -23,6 +23,7 @@
 use Google\Cloud\Kms\V1\CryptoKeyVersion\CryptoKeyVersionAlgorithm;
 use Google\Cloud\Kms\V1\CryptoKeyVersionTemplate;
 use Google\Cloud\Kms\V1\KeyManagementServiceClient;
+use Google\Protobuf\Duration;
 
 function create_key_asymmetric_decrypt_sample(
     string $projectId = 'my-project',
@@ -41,6 +42,11 @@ function create_key_asymmetric_decrypt_sample(
         ->setPurpose(CryptoKeyPurpose::ASYMMETRIC_DECRYPT)
         ->setVersionTemplate((new CryptoKeyVersionTemplate())
             ->setAlgorithm(CryptoKeyVersionAlgorithm::RSA_DECRYPT_OAEP_2048_SHA256)
+        )
+
+        // Optional: customize how long key versions should be kept before destroying.
+        ->setDestroyScheduledDuration((new Duration())
+            ->setSeconds(24*60*60)
         );
 
     // Call the API.
diff --git a/kms/src/create_key_asymmetric_sign.php b/kms/src/create_key_asymmetric_sign.php
@@ -23,6 +23,7 @@
 use Google\Cloud\Kms\V1\CryptoKeyVersion\CryptoKeyVersionAlgorithm;
 use Google\Cloud\Kms\V1\CryptoKeyVersionTemplate;
 use Google\Cloud\Kms\V1\KeyManagementServiceClient;
+use Google\Protobuf\Duration;
 
 function create_key_asymmetric_sign_sample(
     string $projectId = 'my-project',
@@ -41,6 +42,11 @@ function create_key_asymmetric_sign_sample(
         ->setPurpose(CryptoKeyPurpose::ASYMMETRIC_SIGN)
         ->setVersionTemplate((new CryptoKeyVersionTemplate())
             ->setAlgorithm(CryptoKeyVersionAlgorithm::RSA_SIGN_PKCS1_2048_SHA256)
+        )
+
+        // Optional: customize how long key versions should be kept before destroying.
+        ->setDestroyScheduledDuration((new Duration())
+            ->setSeconds(24*60*60)
         );
 
     // Call the API.
diff --git a/kms/src/create_key_hsm.php b/kms/src/create_key_hsm.php
@@ -24,6 +24,7 @@
 use Google\Cloud\Kms\V1\CryptoKeyVersionTemplate;
 use Google\Cloud\Kms\V1\KeyManagementServiceClient;
 use Google\Cloud\Kms\V1\ProtectionLevel;
+use Google\Protobuf\Duration;
 
 function create_key_hsm_sample(
     string $projectId = 'my-project',
@@ -43,6 +44,11 @@ function create_key_hsm_sample(
         ->setVersionTemplate((new CryptoKeyVersionTemplate())
             ->setAlgorithm(CryptoKeyVersionAlgorithm::GOOGLE_SYMMETRIC_ENCRYPTION)
             ->setProtectionLevel(ProtectionLevel::HSM)
+        )
+
+        // Optional: customize how long key versions should be kept before destroying.
+        ->setDestroyScheduledDuration((new Duration())
+            ->setSeconds(24*60*60)
         );
 
     // Call the API.
diff --git a/kms/src/create_key_mac.php b/kms/src/create_key_mac.php
@@ -0,0 +1,67 @@
+<?php
+/*
+ * Copyright 2021 Google LLC.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+// [START kms_create_key_mac]
+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\Cloud\Kms\V1\KeyManagementServiceClient;
+use Google\Protobuf\Duration;
+
+function create_key_mac_sample(
+    string $projectId = 'my-project',
+    string $locationId = 'us-east1',
+    string $keyRingId = 'my-key-ring',
+    string $id = 'my-mac-key'
+) {
+    // 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::MAC)
+        ->setVersionTemplate((new CryptoKeyVersionTemplate())
+            ->setAlgorithm(CryptoKeyVersionAlgorithm::HMAC_SHA256)
+        )
+
+        // Optional: customize how long key versions should be kept before destroying.
+        ->setDestroyScheduledDuration((new Duration())
+            ->setSeconds(24*60*60)
+        );
+
+    // Call the API.
+    $createdKey = $client->createCryptoKey($keyRingName, $id, $key);
+    printf('Created mac key: %s' . PHP_EOL, $createdKey->getName());
+    return $createdKey;
+}
+// [END kms_create_key_mac]
+
+if (isset($argv)) {
+    if (count($argv) === 0) {
+        return printf("Usage: php %s PROJECT_ID LOCATION_ID KEY_RING_ID ID\n", basename(__FILE__));
+    }
+
+    require_once __DIR__ . '/../vendor/autoload.php';
+    list($_, $projectId, $locationId, $keyRingId, $id) = $argv;
+    create_key_mac_sample($projectId, $locationId, $keyRingId, $id);
+}
diff --git a/kms/src/generate_random_bytes.php b/kms/src/generate_random_bytes.php
@@ -0,0 +1,59 @@
+<?php
+/*
+ * Copyright 2021 Google LLC.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+// [START kms_generate_random_bytes]
+use Google\Cloud\Kms\V1\KeyManagementServiceClient;
+use Google\Cloud\Kms\V1\ProtectionLevel;
+
+function generate_random_bytes_sample(
+    string $projectId = 'my-project',
+    string $locationId = 'us-east1',
+    int $numBytes = 256
+) {
+    // Create the Cloud KMS client.
+    $client = new KeyManagementServiceClient();
+
+    // Build the parent name.
+    $locationName = $client->locationName($projectId, $locationId);
+
+    // Call the API.
+    $randomBytesResponse = $client->generateRandomBytes(array(
+      'location' => $locationName,
+      'lengthBytes' => $numBytes,
+      'protectionLevel' => ProtectionLevel::HSM
+    ));
+
+    // The data comes back as raw bytes, which may include non-printable
+    // characters. This base64-encodes the result so it can be printed below.
+    $encodedData = base64_encode($randomBytesResponse->getData());
+    printf('Random bytes: %s' . PHP_EOL, $encodedData);
+
+    return $randomBytesResponse;
+}
+// [END kms_generate_random_bytes]
+
+if (isset($argv)) {
+    if (count($argv) === 0) {
+        return printf("Usage: php %s PROJECT_ID LOCATION_ID NUM_BYTES\n", basename(__FILE__));
+    }
+
+    require_once __DIR__ . '/../vendor/autoload.php';
+    list($_, $projectId, $locationId, $numBytes) = $argv;
+    generate_random_bytes_sample($projectId, $locationId, $numBytes);
+}
diff --git a/kms/src/sign_mac.php b/kms/src/sign_mac.php
@@ -0,0 +1,57 @@
+<?php
+/*
+ * Copyright 2021 Google LLC.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+// [START kms_sign_mac]
+use Google\Cloud\Kms\V1\KeyManagementServiceClient;
+
+function sign_mac_sample(
+    string $projectId = 'my-project',
+    string $locationId = 'us-east1',
+    string $keyRingId = 'my-key-ring',
+    string $keyId = 'my-key',
+    string $versionId = '123',
+    string $data = '...'
+) {
+    // Create the Cloud KMS client.
+    $client = new KeyManagementServiceClient();
+
+    // Build the key version name.
+    $keyVersionName = $client->cryptoKeyVersionName($projectId, $locationId, $keyRingId, $keyId, $versionId);
+
+    // Call the API.
+    $signMacResponse = $client->macSign($keyVersionName, $data);
+
+    // The data comes back as raw bytes, which may include non-printable
+    // characters. This base64-encodes the result so it can be printed below.
+    $signature = base64_encode($signMacResponse->getMac());
+    printf('Signature: %s' . PHP_EOL, $signature);
+
+    return $signMacResponse;
+}
+// [END kms_sign_mac]
+
+if (isset($argv)) {
+    if (count($argv) === 0) {
+        return printf("Usage: php %s PROJECT_ID LOCATION_ID KEY_RING_ID KEY_ID VERSION_ID DATA\n", basename(__FILE__));
+    }
+
+    require_once __DIR__ . '/../vendor/autoload.php';
+    list($_, $projectId, $locationId, $keyRingId, $keyId, $versionId, $data) = $argv;
+    sign_mac_sample($projectId, $locationId, $keyRingId, $keyId, $versionId, $data);
+}
diff --git a/kms/src/verify_mac.php b/kms/src/verify_mac.php
@@ -0,0 +1,54 @@
+<?php
+/*
+ * Copyright 2021 Google LLC.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+// [START kms_verify_mac]
+use Google\Cloud\Kms\V1\KeyManagementServiceClient;
+
+function verify_mac_sample(
+    string $projectId = 'my-project',
+    string $locationId = 'us-east1',
+    string $keyRingId = 'my-key-ring',
+    string $keyId = 'my-key',
+    string $versionId = '123',
+    string $data = '...',
+    string $signature = '...'
+) {
+    // Create the Cloud KMS client.
+    $client = new KeyManagementServiceClient();
+
+    // Build the key version name.
+    $keyVersionName = $client->cryptoKeyVersionName($projectId, $locationId, $keyRingId, $keyId, $versionId);
+
+    // Call the API.
+    $verifyMacResponse = $client->macVerify($keyVersionName, $data, $signature);
+
+    printf('Signature verified: %s' . PHP_EOL, $verifyMacResponse->getSuccess());
+    return $verifyMacResponse;
+}
+// [END kms_verify_mac]
+
+if (isset($argv)) {
+    if (count($argv) === 0) {
+        return printf("Usage: php %s PROJECT_ID LOCATION_ID KEY_RING_ID KEY_ID VERSION_ID DATA\n", basename(__FILE__));
+    }
+
+    require_once __DIR__ . '/../vendor/autoload.php';
+    list($_, $projectId, $locationId, $keyRingId, $keyId, $versionId, $data) = $argv;
+    verify_mac_sample($projectId, $locationId, $keyRingId, $keyId, $versionId, $data);
+}
diff --git a/kms/test/kmsTest.php b/kms/test/kmsTest.php

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`	`2`	`"require": {`
`3`		`- "google/cloud-kms": "^1.10.0"`
	`3`	`+ "google/cloud-kms": "^1.12.0"`
`4`	`4`	`}`
`5`	`5`	`}`