feat(samples): add asymmetric samples (#241)

kms/asymmetricDecrypt.js

@@ -0,0 +1,68 @@
+// Copyright 2019 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_asymmetric_decrypt]
+async function asymmetricDecrypt(
+  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"
+  cryptoKeyVersionId = '1', // Version of the crypto key to use
+  ciphertextBuffer = '...' // Buffer containing ciphertext to decrypt
+) {
+  // 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';
+
+  // Construct the cyrpto key version ID
+  const name = client.cryptoKeyVersionPath(
+    projectId,
+    locationId,
+    keyRingId,
+    cryptoKeyId,
+    cryptoKeyVersionId
+  );
+
+  // Decrypt plaintext using Cloud KMS
+  //
+  // NOTE: The ciphertext must be properly formatted. In Node < 12, the
+  // crypto.publicEncrypt() function does not properly consume the OAEP padding
+  // and thus produces invalid ciphertext. If you are using Node to do public
+  // key encryption, please use version 12+.
+  const [result] = await client.asymmetricDecrypt({
+    name: name,
+    ciphertext: ciphertextBuffer,
+  });
+  const plaintext = result.plaintext.toString('utf8');
+
+  // Example of printing results
+  console.log(`Decrypted plaintext: ${plaintext}`);
+
+  return plaintext;
+}
+// [END kms_asymmetric_decrypt]
+
+const args = process.argv.slice(2);
+
+// Base64-decode the ciphertext argument. The tests invoke these files via the
+// shell, which doesn't support transferring a binary stream. As such, they
+// encode the data first, so we need to decode it here before passing it to the
+// function.
+args[4] = Buffer.from(args[4], 'base64');
+
+asymmetricDecrypt(...args).catch(console.error);

kms/asymmetricEncrypt.js

@@ -0,0 +1,76 @@
+// Copyright 2019 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_asymmetric_encrypt]
+async function asymmetricEncrypt(
+  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"
+  cryptoKeyVersionId = '1', // Version of the crypto key to use
+  plaintext = 'my data to encrypt' // Plaintext data to encrypt
+) {
+  // 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';
+
+  // Construct the cyrpto key version ID
+  const name = client.cryptoKeyVersionPath(
+    projectId,
+    locationId,
+    keyRingId,
+    cryptoKeyId,
+    cryptoKeyVersionId
+  );
+
+  // Get public key from Cloud KMS
+  const [publicKey] = await client.getPublicKey({name: name});
+
+  // Import and setup crypto
+  const crypto = require('crypto');
+  const plaintextBuffer = Buffer.from(plaintext);
+
+  // Encrypt plaintext locally using the public key. This example uses a key
+  // that was configured with sha256 hash with OAEP padding. Update these values
+  // to match the Cloud KMS key.
+  //
+  // NOTE: In Node < 12, this function does not properly consume the OAEP
+  // padding and thus produces invalid ciphertext. If you are using Node to do
+  // public key encryption, please use version 12+.
+  const encryptedBuffer = crypto.publicEncrypt(
+    {
+      key: publicKey.pem,
+      oaepHash: 'sha256',
+      padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
+    },
+    plaintextBuffer
+  );
+
+  // Example of how to display ciphertext. Because the ciphertext is in a binary
+  // format, you need to encode the output before printing it to a console or
+  // displaying it on a screen.
+  const encoded = encryptedBuffer.toString('base64');
+  console.log(`Encrypted ciphertext: ${encoded}`);
+
+  // Return the ciphertext buffer
+  return encryptedBuffer;
+}
+// [END kms_asymmetric_encrypt]
+
+const args = process.argv.slice(2);
+asymmetricEncrypt(...args).catch(console.error);

kms/asymmetricSign.js

@@ -0,0 +1,67 @@
+// Copyright 2019 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_asymmetric_sign]
+async function asymmetricSign(
+  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"
+  cryptoKeyVersionId = '1', // Version of the crypto key to use
+  message = 'my message to sign' // Message data to sign
+) {
+  // 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';
+
+  // Construct the cyrpto key version ID
+  const name = client.cryptoKeyVersionPath(
+    projectId,
+    locationId,
+    keyRingId,
+    cryptoKeyId,
+    cryptoKeyVersionId
+  );
+
+  // Create a digest of the message. The digest needs to match the digest
+  // configured for the Cloud KMS key.
+  const crypto = require('crypto');
+  const digest = crypto.createHash('sha384');
+  digest.update(message);
+
+  // Sign the message with Cloud KMS
+  const [result] = await client.asymmetricSign({
+    name: name,
+    digest: {
+      sha384: digest.digest(),
+    },
+  });
+
+  // Example of how to display signature. Because the signature is in a binary
+  // format, you need to encode the output before printing it to a console or
+  // displaying it on a screen.
+  const encoded = result.signature.toString('base64');
+  console.log(`Signature: ${encoded}`);
+
+  // Return the signature buffer
+  return result.signature;
+}
+// [END kms_asymmetric_sign]
+
+const args = process.argv.slice(2);
+asymmetricSign(...args).catch(console.error);

kms/asymmetricVerify.js

@@ -0,0 +1,70 @@
+// Copyright 2019 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_asymmetric_verify]
+async function asymmetricVerify(
+  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"
+  cryptoKeyVersionId = '1', // Version of the crypto key to use
+  message = 'my message to verify', // Message data to verify
+  signatureBuffer = '...' // Buffer containing signature to decrypt
+) {
+  // 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';
+
+  // Construct the cyrpto key version ID
+  const name = client.cryptoKeyVersionPath(
+    projectId,
+    locationId,
+    keyRingId,
+    cryptoKeyId,
+    cryptoKeyVersionId
+  );
+
+  // Get public key from Cloud KMS
+  const [publicKey] = await client.getPublicKey({name: name});
+
+  // Create the verifier. The algorithm must match the algorithm of the key.
+  const crypto = require('crypto');
+  const verify = crypto.createVerify('SHA384');
+  verify.write(message);
+  verify.end();
+
+  // Verify the signature using the public key
+  const verified = verify.verify(publicKey.pem, signatureBuffer);
+
+  // Example of printing result
+  console.log(`Signature verified: ${verified}`);
+
+  // Return boolean result
+  return verified;
+}
+// [END kms_asymmetric_verify]
+
+const args = process.argv.slice(2);
+
+// Base64-decode the signature argument. The tests invoke these files via the
+// shell, which doesn't support transferring a binary stream. As such, they
+// encode the data first, so we need to decode it here before passing it to the
+// function.
+args[5] = Buffer.from(args[5], 'base64');
+
+asymmetricVerify(...args).catch(console.error);

kms/getPublicKey.js

@@ -0,0 +1,49 @@
+// Copyright 2019 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_get_public_key]
+async function getPublicKey(
+  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"
+  cryptoKeyVersionId = '1' // Version of the crypto key to fetch
+) {
+  // 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';
+
+  // Construct the cyrpto key version ID
+  const name = client.cryptoKeyVersionPath(
+    projectId,
+    locationId,
+    keyRingId,
+    cryptoKeyId,
+    cryptoKeyVersionId
+  );
+
+  // Get public key from Cloud KMS
+  const [publicKey] = await client.getPublicKey({name: name});
+
+  // Return the public key pem
+  return publicKey.pem;
+}
+// [END kms_get_public_key]
+
+const args = process.argv.slice(2);
+getPublicKey(...args).catch(console.error);

kms/package.json

@@ -19,7 +19,7 @@
   "devDependencies": {
     "chai": "^4.2.0",
     "mocha": "^6.0.0",
-    "uuid": "^3.2.1",
+    "uuid": "^3.3.3",
     "yargs": "^15.0.0"
   }
 }