Add Cloud Storage encryption samples and tests.

pubsub/system-test/subscriptions.test.js

@@ -39,7 +39,8 @@ describe('pubsub:subscriptions', function () {
         assert.ifError(err);
         assert.equal(subscription.name, name);
         assert(console.log.calledWith('Created subscription %s to topic %s', subscriptionName, topicName));
-        done();
+        // The next test sometimes fails, so, slow this test down
+        setTimeout(done, 2000);
       });
     });
   });

storage/README.md

@@ -33,13 +33,19 @@ View the [documentation][buckets_docs] or the [source code][buckets_code].
 __Usage:__ `node buckets --help`
 
 ```
-Usage: node buckets [COMMAND] [ARGS...]
+Usage: node buckets COMMAND [ARGS...]
 
 Commands:
 
-  create [BUCKET_NAME]
+  create BUCKET_NAME
   list
-  delete [BUCKET_NAME]
+  delete BUCKET_NAME
+
+Examples:
+
+  node buckets create my-bucket
+  node buckets list
+  node buckets delete my-bucket
 ```
 
 [buckets_docs]: https://cloud.google.com/storage/docs
@@ -52,20 +58,60 @@ View the [documentation][files_docs] or the [source code][files_code].
 __Usage:__ `node files --help`
 
 ```
-Usage: node files [COMMAND] [ARGS...]
+Usage: node files COMMAND [ARGS...]
 
 Commands:
 
-  list [BUCKET_NAME]
-  listByPrefix [BUCKET_NAME] [PREFIX] [DELIMITER]
-  upload [BUCKET_NAME] [FILE_NAME]
-  download [BUCKET_NAME] [SRC_FILE_NAME] [DEST_FILE_NAME]
-  delete [BUCKET_NAME] [FILE_NAME]
-  getMetadata [BUCKET_NAME] [FILE_NAME]
-  makePublic [BUCKET_NAME] [FILE_NAME]
-  move [BUCKET_NAME] [SRC_FILE_NAME] [DEST_FILE_NAME]
-  copy [BUCKET_NAME] [SRC_FILE_NAME] [DEST_BUCKET_NAME] [DEST_FILE_NAME]
+  list BUCKET_NAME
+  listByPrefix BUCKET_NAME PREFIX [DELIMITER]
+  upload BUCKET_NAME FILE_NAME
+  download BUCKET_NAME SRC_FILE_NAME DEST_FILE_NAME
+  delete BUCKET_NAME FILE_NAME
+  getMetadata BUCKET_NAME FILE_NAME
+  makePublic BUCKET_NAME FILE_NAME
+  move BUCKET_NAME SRC_FILE_NAME DEST_FILE_NAME
+  copy BUCKET_NAME SRC_FILE_NAME DEST_BUCKET_NAME DEST_FILE_NAME
+
+Examples:
+
+  list my-bucket
+  listByPrefix my-bucket /some-folder
+  listByPrefix my-bucket /some-folder -
+  upload my-bucket ./file.txt
+  download my-bucket file.txt ./file.txt
+  delete my-bucket file.txt
+  getMetadata my-bucket file.txt
+  makePublic my-bucket file.txt
+  move my-bucket file.txt file2.txt
+  copy my-bucket file.txt my-other-bucket file.txt
 ```
 
 [files_docs]: https://cloud.google.com/storage/docs
 [files_code]: files.js
+
+### Encryption
+
+View the [documentation][encryption_docs] or the [source code][encryption_code].
+
+__Usage:__ `node encryption --help`
+
+```
+Usage: node encryption COMMAND [ARGS...]
+
+Commands:
+
+  generate-encryption-key
+  upload BUCKET_NAME SRC_FILE_NAME DEST_FILE_NAME KEY
+  download BUCKET_NAME SRC_FILE_NAME DEST_FILE_NAME KEY
+  rotate BUCKET_NAME FILE_NAME OLD_KEY NEW_KEY
+
+Examples:
+
+  node encryption generate-encryption-key
+  node encryption upload my-bucket resources/test.txt file_encrypted.txt QxhqaZEqBGVTW55HhQw9Q=
+  node encryption download my-bucket file_encrypted.txt ./file.txt QxhqaZEqBGVTW55HhQw9Q=
+  node encryption rotate my-bucket file_encrypted.txt QxhqaZEqBGVTW55HhQw9Q= SxafpsdfSDFS89sds9Q=
+```
+
+[encryption_docs]: https://cloud.google.com/storage/docs
+[encryption_code]: encryption.js

storage/buckets.js

@@ -21,7 +21,7 @@
 // https://googlecloudplatform.github.io/gcloud-node/#/docs/guides/authentication
 var gcloud = require('gcloud');
 
-// Get a reference to the storage component
+// Instantiate a storage client
 var storage = gcloud.storage();
 // [END setup]
 
@@ -93,11 +93,15 @@ function deleteBucket (name, callback) {
 
 // [START usage]
 function printUsage () {
-  console.log('Usage: node buckets [COMMAND] [ARGS...]');
+  console.log('Usage: node buckets COMMAND [ARGS...]');
   console.log('\nCommands:\n');
-  console.log('\tcreate [BUCKET_NAME]');
+  console.log('\tcreate BUCKET_NAME');
   console.log('\tlist');
-  console.log('\tdelete [BUCKET_NAME]');
+  console.log('\tdelete BUCKET_NAME');
+  console.log('\nExamples:\n');
+  console.log('\tnode buckets create my-bucket');
+  console.log('\tnode buckets list');
+  console.log('\tnode buckets delete my-bucket');
 }
 // [END usage]
 

storage/encryption.js

@@ -0,0 +1,193 @@
+// Copyright 2015-2016, Google, Inc.
+// 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.
+
+'use strict';
+
+// [START all]
+// [START setup]
+// By default, gcloud will authenticate using the service account file specified
+// by the GOOGLE_APPLICATION_CREDENTIALS environment variable and use the
+// project specified by the GCLOUD_PROJECT environment variable. See
+// https://googlecloudplatform.github.io/gcloud-node/#/docs/guides/authentication
+var gcloud = require('gcloud');
+
+// Instantiate a storage client
+var storage = gcloud.storage();
+
+var crypto = require('crypto');
+// [END setup]
+
+// [START generate_encryption_key]
+/**
+ * Generates a 256 bit (32 byte) AES encryption key and prints the base64
+ * representation.
+ *
+ * This is included for demonstration purposes. You should generate your own
+ * key. Please remember that encryption keys should be handled with a
+ * comprehensive security policy.
+ *
+ * @returns {string} The encryption key.
+ */
+function generateEncryptionKey () {
+  var buffer = crypto.randomBytes(32);
+  var encodedKey = buffer.toString('base64');
+
+  console.log('Base 64 encoded encryption key: %s', encodedKey);
+
+  return encodedKey;
+}
+// [END generate_encryption_key]
+
+// [START upload_encrypted_file]
+/**
+ * Uploads a file to a Google Cloud Storage bucket using a custom encryption key.
+ *
+ * The file will be encrypted by Google Cloud Storage and only retrievable using
+ * the provided encryption key.
+ *
+ * @param {string} bucketName The bucket where the file will be uploaded.
+ * @param {string} srcFileName The local file to be uploaded.
+ * @param {string} destFileName The name of the destination file.
+ * @param {string} key The encryption key.
+ * @param {function} callback The callback function.
+ */
+function uploadEncryptedFile (bucketName, srcFileName, destFileName, key, callback) {
+  if (!bucketName) {
+    return callback(new Error('"bucketName" is required!'));
+  } else if (!srcFileName) {
+    return callback(new Error('"srcFileName" is required!'));
+  } else if (!destFileName) {
+    return callback(new Error('"destFileName" is required!'));
+  } else if (!key) {
+    return callback(new Error('"key" is required!'));
+  }
+
+  var bucket = storage.bucket(bucketName);
+  var options = {
+    destination: destFileName,
+    encryptionKey: new Buffer(key, 'base64')
+  };
+
+  bucket.upload(srcFileName, options, function (err, file) {
+    if (err) {
+      return callback(err);
+    }
+
+    console.log('Uploaded encrypted file: %s', destFileName);
+    return callback(null, file);
+  });
+}
+// [END upload_encrypted_file]
+
+// [START download_encrypted_file]
+/**
+ * Downloads a previously-encrypted file from Google Cloud Storage.
+ *
+ * The encryption key provided must be the same key provided when uploading the
+ * file.
+ *
+ * @param {string} bucketName The bucket from which the file will be downloaded.
+ * @param {string} srcFileName The name of the file to be downloaded.
+ * @param {string} destFileName The local path to which to save the file.
+ * @param {string} key The encryption key.
+ * @param {function} key The callback function.
+ */
+function downloadEncryptedFile (bucketName, srcFileName, destFileName, key, callback) {
+  if (!bucketName) {
+    return callback(new Error('"bucketName" is required!'));
+  } else if (!srcFileName) {
+    return callback(new Error('"srcFileName" is required!'));
+  } else if (!destFileName) {
+    return callback(new Error('"destFileName" is required!'));
+  } else if (!key) {
+    return callback(new Error('"key" is required!'));
+  }
+
+  var bucket = storage.bucket(bucketName);
+  var file = bucket.file(srcFileName);
+  var options = {
+    destination: destFileName
+  };
+
+  file.setEncryptionKey(new Buffer(key, 'base64'));
+
+  file.download(options, function (err) {
+    if (err) {
+      return callback(err);
+    }
+
+    console.log('Downloaded encrypted file: %s', destFileName);
+    return callback(null);
+  });
+}
+// [END download_encrypted_file]
+
+// [START rotate_encryption_key]
+/**
+ * Performs a key rotation by re-writing an encrypted blob with a new encryption
+ * key.
+ *
+ * @param {function} key The callback function.
+ */
+function rotateEncryptionKey (callback) {
+  callback(new Error('This is currently not available using the Cloud Client Library.'));
+}
+// [END rotate_encryption_key]
+
+// [START usage]
+function printUsage () {
+  console.log('Usage: node encryption COMMAND [ARGS...]');
+  console.log('\nCommands:\n');
+  console.log('\tgenerate-encryption-key');
+  console.log('\tupload BUCKET_NAME SRC_FILE_NAME DEST_FILE_NAME KEY');
+  console.log('\tdownload BUCKET_NAME SRC_FILE_NAME DEST_FILE_NAME KEY');
+  console.log('\trotate BUCKET_NAME FILE_NAME OLD_KEY NEW_KEY');
+  console.log('\nExamples:\n');
+  console.log('\tnode encryption generate-encryption-key');
+  console.log('\tnode encryption upload my-bucket resources/test.txt file_encrypted.txt QxhqaZEqBGVTW55HhQw9Q=');
+  console.log('\tnode encryption download my-bucket file_encrypted.txt ./file.txt QxhqaZEqBGVTW55HhQw9Q=');
+  console.log('\tnode encryption rotate my-bucket file_encrypted.txt QxhqaZEqBGVTW55HhQw9Q= SxafpsdfSDFS89sds9Q=');
+}
+// [END usage]
+
+// The command-line program
+var program = {
+  generateEncryptionKey: generateEncryptionKey,
+  uploadEncryptedFile: uploadEncryptedFile,
+  downloadEncryptedFile: downloadEncryptedFile,
+  rotateEncryptionKey: rotateEncryptionKey,
+  printUsage: printUsage,
+
+  // Executed when this program is run from the command-line
+  main: function (args, cb) {
+    var command = args.shift();
+    if (command === 'generate-encryption-key') {
+      this.generateEncryptionKey();
+    } else if (command === 'upload') {
+      this.uploadEncryptedFile(args[0], args[1], args[2], args[3], cb);
+    } else if (command === 'download') {
+      this.downloadEncryptedFile(args[0], args[1], args[2], args[3], cb);
+    } else if (command === 'rotate') {
+      this.rotateEncryptionKey(cb);
+    } else {
+      this.printUsage();
+    }
+  }
+};
+
+if (module === require.main) {
+  program.main(process.argv.slice(2), console.log);
+}
+// [END all]
+
+module.exports = program;

storage/files.js

@@ -21,7 +21,7 @@
 // https://googlecloudplatform.github.io/gcloud-node/#/docs/guides/authentication
 var gcloud = require('gcloud');
 
-// Get a reference to the storage component
+// Instantiate a storage client
 var storage = gcloud.storage();
 // [END setup]
 
@@ -324,17 +324,28 @@ function copyFile (name, srcFileName, destBucketName, destFileName, callback) {
 
 // [START usage]
 function printUsage () {
-  console.log('Usage: node files [COMMAND] [ARGS...]');
+  console.log('Usage: node files COMMAND [ARGS...]');
   console.log('\nCommands:\n');
-  console.log('\tlist [BUCKET_NAME]');
-  console.log('\tlistByPrefix [BUCKET_NAME] [PREFIX] [DELIMITER]');
-  console.log('\tupload [BUCKET_NAME] [FILE_NAME]');
-  console.log('\tdownload [BUCKET_NAME] [SRC_FILE_NAME] [DEST_FILE_NAME]');
-  console.log('\tdelete [BUCKET_NAME] [FILE_NAME]');
-  console.log('\tgetMetadata [BUCKET_NAME] [FILE_NAME]');
-  console.log('\tmakePublic [BUCKET_NAME] [FILE_NAME]');
-  console.log('\tmove [BUCKET_NAME] [SRC_FILE_NAME] [DEST_FILE_NAME]');
-  console.log('\tcopy [BUCKET_NAME] [SRC_FILE_NAME] [DEST_BUCKET_NAME] [DEST_FILE_NAME]');
+  console.log('\tlist BUCKET_NAME');
+  console.log('\tlistByPrefix BUCKET_NAME PREFIX [DELIMITER]');
+  console.log('\tupload BUCKET_NAME FILE_NAME');
+  console.log('\tdownload BUCKET_NAME SRC_FILE_NAME DEST_FILE_NAME');
+  console.log('\tdelete BUCKET_NAME FILE_NAME');
+  console.log('\tgetMetadata BUCKET_NAME FILE_NAME');
+  console.log('\tmakePublic BUCKET_NAME FILE_NAME');
+  console.log('\tmove BUCKET_NAME SRC_FILE_NAME DEST_FILE_NAME');
+  console.log('\tcopy BUCKET_NAME SRC_FILE_NAME DEST_BUCKET_NAME DEST_FILE_NAME');
+  console.log('\nExamples:\n');
+  console.log('\tlist my-bucket');
+  console.log('\tlistByPrefix my-bucket /some-folder');
+  console.log('\tlistByPrefix my-bucket /some-folder -');
+  console.log('\tupload my-bucket ./file.txt');
+  console.log('\tdownload my-bucket file.txt ./file.txt');
+  console.log('\tdelete my-bucket file.txt');
+  console.log('\tgetMetadata my-bucket file.txt');
+  console.log('\tmakePublic my-bucket file.txt');
+  console.log('\tmove my-bucket file.txt file2.txt');
+  console.log('\tcopy my-bucket file.txt my-other-bucket file.txt');
 }
 // [END usage]