docs: add samples (#88)

kms/addMemberToCryptoKeyPolicy.js

@@ -0,0 +1,76 @@
+// Copyright 2018 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
+//
+//     https://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.
+
+'use strict';
+
+// [START kms_add_member_to_cryptokey_policy]
+async function addMemberToCryptoKeyPolicy(
+  projectId = 'your-project-id', // Your GCP Project Id
+  keyRingId = 'my-key-ring', // Name of the crypto key's key ring
+  cryptoKeyId = 'my-key', // Name of the crypto key
+  member = 'user:dev@example.com', // Member to add to the crypto key
+  role = 'roles/viewer' // Role to give the member
+) {
+  // Import the library and create a client
+  const kms = require('@google-cloud/kms');
+  const client = new kms.KeyManagementServiceClient();
+
+  // The location of the crypto key's key ring
+  const locationId = 'global';
+
+  // Get the full path to the crypto key
+  const resource = client.cryptoKeyPath(
+    projectId,
+    locationId,
+    keyRingId,
+    cryptoKeyId
+  );
+
+  // Gets the IAM policy of a crypto key
+  const [result] = await client.getIamPolicy({resource});
+  let policy = Object.assign({bindings: []}, result);
+  const index = policy.bindings.findIndex(binding => binding.role === role);
+
+  // Add the role/member combo to the policy
+  const members = [];
+  const binding = Object.assign({role, members}, policy.bindings[index]);
+  if (index === -1) {
+    policy.bindings.push(binding);
+  }
+  if (!binding.members.includes(member)) {
+    binding.members.push(member);
+  }
+
+  // Adds the member/role combo to the policy of the crypto key
+  [policy] = await client.setIamPolicy({resource, policy});
+  console.log(
+    `${member}/${role} combo added to policy for crypto key ${cryptoKeyId}.`
+  );
+  if (policy.bindings) {
+    policy.bindings.forEach(binding => {
+      if (binding.members && binding.members.length) {
+        console.log(`${binding.role}:`);
+        binding.members.forEach(member => {
+          console.log(`  ${member}`);
+        });
+      }
+    });
+  } else {
+    console.log(`Policy for crypto key ${cryptoKeyId} is empty.`);
+  }
+}
+// [END kms_add_member_to_cryptokey_policy]
+
+const args = process.argv.slice(2);
+addMemberToCryptoKeyPolicy(...args).catch(console.error);

kms/addMemberToKeyRingPolicy.js

@@ -0,0 +1,72 @@
+// Copyright 2018 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
+//
+//     https://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.
+
+'use strict';
+
+// [START kms_add_member_to_keyring_policy]
+async function addMemberToKeyRingPolicy(
+  projectId = 'your-project-id', // Your GCP projectId
+  keyRingId = 'my-key-ring', // Name of the crypto key's key ring
+  member = 'user:dev@example.com', // Member to add to the crypto key
+  role = 'roles/viewer' // Role to give the member
+) {
+  // Import the library and create a client
+  const kms = require('@google-cloud/kms');
+  const client = new kms.KeyManagementServiceClient();
+
+  // The location of the key ring, e.g. "global"
+  const locationId = 'global';
+
+  // Get the full path to the keyring
+  const resource = client.keyRingPath(projectId, locationId, keyRingId);
+
+  // Gets the IAM policy of a key ring
+  let [policy] = await client.getIamPolicy({resource});
+  policy.bindings = policy.bindings || [];
+
+  // find the index of the binding matching the requested role
+  const index = policy.bindings.findIndex(binding => binding.role === role);
+
+  // Add the role/member combo to the policy
+  const members = [];
+  const binding = Object.assign({role}, {members}, policy.bindings[index]);
+  if (index === -1) {
+    policy.bindings.push(binding);
+  }
+  if (!binding.members.includes(member)) {
+    binding.members.push(member);
+  }
+
+  // Adds the member/role combo to the policy of the key ring
+  [policy] = await client.setIamPolicy({resource, policy});
+  console.log(
+    `${member}/${role} combo added to policy for key ring ${keyRingId}.`
+  );
+  if (policy.bindings) {
+    policy.bindings.forEach(binding => {
+      if (binding.members && binding.members.length) {
+        console.log(`${binding.role}:`);
+        binding.members.forEach(member => {
+          console.log(`  ${member}`);
+        });
+      }
+    });
+  } else {
+    console.log(`Policy for key ring ${keyRingId} is empty.`);
+  }
+}
+// [END kms_add_member_to_keyring_policy]
+
+const args = process.argv.slice(2);
+addMemberToKeyRingPolicy(...args).catch(console.error);

kms/createCryptoKey.js

@@ -0,0 +1,46 @@
+// Copyright 2018 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
+//
+//     https://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.
+
+'use strict';
+
+// [START kms_create_cryptokey]
+async function createCryptoKey(
+  projectId = 'your-project-id', // Your GCP Project Id
+  keyRingId = 'my-key-ring', // Name of the crypto key's key ring
+  cryptoKeyId = 'my-key' // Name of the crypto key
+) {
+  // Import the library and create a client
+  const kms = require('@google-cloud/kms');
+  const client = new kms.KeyManagementServiceClient();
+
+  // The location of the new crypto key's key ring, e.g. "global"
+  const locationId = 'global';
+
+  const parent = client.keyRingPath(projectId, locationId, keyRingId);
+
+  // Creates a new key ring
+  const [cryptoKey] = await client.createCryptoKey({
+    parent,
+    cryptoKeyId,
+    cryptoKey: {
+      // This will allow the API access to the key for encryption and decryption
+      purpose: 'ENCRYPT_DECRYPT',
+    },
+  });
+  console.log(`Key ${cryptoKey.name} created.`);
+}
+// [END kms_create_cryptokey]
+
+const args = process.argv.slice(2);
+createCryptoKey(...args).catch(console.error);

kms/createCryptoKeyVersion.js

@@ -0,0 +1,45 @@
+// Copyright 2018 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
+//
+//     https://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.
+
+'use strict';
+
+// [START kms_create_cryptokey_version]
+async function createCryptoKeyVersion(
+  projectId = 'YOUR_PROJECT_ID', // Your Google Cloud Platform project ID
+  keyRingId = 'my-key-ring', // Name of the crypto key version's key ring, e.g. "my-key-ring"
+  cryptoKeyId = 'my-key' // Name of the version's crypto key
+) {
+  // Import the library and create a client
+  const kms = require('@google-cloud/kms');
+  const client = new kms.KeyManagementServiceClient();
+
+  // The location of the crypto key versions's key ring, e.g. "global"
+  const locationId = 'global';
+
+  // Get the full path to the crypto key
+  const parent = client.cryptoKeyPath(
+    projectId,
+    locationId,
+    keyRingId,
+    cryptoKeyId
+  );
+
+  // Creates a new crypto key version
+  const [result] = await client.createCryptoKeyVersion({parent});
+  console.log(`Crypto key version ${result.name} created.`);
+}
+// [END kms_create_cryptokey_version]
+
+const args = process.argv.slice(2);
+createCryptoKeyVersion(...args).catch(console.error);

kms/createKeyring.js

@@ -0,0 +1,39 @@
+// Copyright 2018 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
+//
+//     https://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.
+
+'use strict';
+
+// [START kms_create_keyring]
+async function createKeyRing(
+  projectId = 'YOUR_PROJECT_ID', // Your GCP projectId
+  keyRingId = 'my-new-key-ring' // Name of the new key ring
+) {
+  // The location of the new key ring, e.g. "global"
+  const locationId = 'global';
+
+  // Import the library and create a client
+  const kms = require('@google-cloud/kms');
+  const client = new kms.KeyManagementServiceClient();
+
+  // Get the full path to the parent
+  const parent = client.locationPath(projectId, locationId);
+
+  // Creates a new key ring
+  const [result] = await client.createKeyRing({parent, keyRingId});
+  console.log(`Key ring ${result.name} created.`);
+}
+// [END kms_create_keyring]
+
+const args = process.argv.slice(2);
+createKeyRing(...args).catch(console.error);

kms/decrypt.js

@@ -0,0 +1,59 @@
+// Copyright 2018 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
+//
+//     https://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.
+
+'use strict';
+
+// [START kms_decrypt]
+async function decrypt(
+  projectId = 'your-project-id', // Your GCP projectId
+  keyRingId = 'my-key-ring', // Name of the crypto key's key ring
+  cryptoKeyId = 'my-key', // Name of the crypto key, e.g. "my-key"
+  ciphertextFileName = './path/to/plaintext.txt.encrypted',
+  plaintextFileName = './path/to/plaintext.txt.decrypted'
+) {
+  const fs = require('fs');
+  const {promisify} = require('util');
+
+  // Import the library and create a client
+  const kms = require('@google-cloud/kms');
+  const client = new kms.KeyManagementServiceClient();
+
+  // The location of the crypto key's key ring, e.g. "global"
+  const locationId = 'global';
+
+  // Reads the file to be decrypted
+  const readFile = promisify(fs.readFile);
+  const contentsBuffer = await readFile(ciphertextFileName);
+  const name = client.cryptoKeyPath(
+    projectId,
+    locationId,
+    keyRingId,
+    cryptoKeyId
+  );
+  const ciphertext = contentsBuffer.toString('base64');
+
+  // Dencrypts the file using the specified crypto key
+  const [result] = await client.decrypt({name, ciphertext});
+
+  // Writes the dencrypted file to disk
+  const writeFile = promisify(fs.writeFile);
+  await writeFile(plaintextFileName, Buffer.from(result.plaintext, 'base64'));
+  console.log(
+    `Decrypted ${ciphertextFileName}, result saved to ${plaintextFileName}.`
+  );
+}
+// [END kms_decrypt]
+
+const args = process.argv.slice(2);
+decrypt(...args).catch(console.error);

kms/destroyCryptoKeyVersion.js

@@ -0,0 +1,47 @@
+// Copyright 2018 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
+//
+//     https://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.
+
+'use strict';
+
+// [START kms_destroy_cryptokey_version]
+async function destroyCryptoKeyVersion(
+  projectId = 'your-project-id', // Your GCP projectId
+  keyRingId = 'my-key-ring', // Name of the crypto key version's key ring
+  cryptoKeyId = 'my-key', // Name of the version's crypto key
+  version = 1234 // The version's id
+) {
+  // Import the library and create a client
+  const kms = require('@google-cloud/kms');
+  const client = new kms.KeyManagementServiceClient();
+
+  // The location of the crypto key versions's key ring, e.g. "global"
+  const locationId = 'global';
+
+  // Get the full path to the crypto key version
+  const name = client.cryptoKeyVersionPath(
+    projectId,
+    locationId,
+    keyRingId,
+    cryptoKeyId,
+    version
+  );
+
+  // destroys a crypto key version
+  const [result] = await client.destroyCryptoKeyVersion({name});
+  console.log(`Crypto key version ${result.name} destroyed.`);
+}
+// [END kms_destroy_cryptokey_version]
+
+const args = process.argv.slice(2);
+destroyCryptoKeyVersion(...args).catch(console.error);