kbpgp.js

Encrypting and/or signing

Security for the masses

The steps to encrypt, sign, or both are all the same in kbpgp. The only difference is what KeyManagers you'll need. To sign something, you'll need a KeyManager containing a private key. And to encrypt something, you'll need one containing the public key of the recipient. If your KeyManagers contain subkeys, kbpgp will automatically use the appropriate ones.

Example 1 - encrypt only

Assumption: we have a KeyManager instance, chuck, for the recipient.

params =
  msg:         "Chuck chucky, bo-bucky!"
  encrypt_for: chuck

kbpgp.box params, (err, result_string, result_buffer) ->
  console.log err, result_armored_string, result_raw_buffer

var params = {
  msg:         "Chuck chucky, bo-bucky!",
  encrypt_for: chuck
};

kbpgp.box(params, function(err, result_string, result_buffer) {
  console.log(err, result_armored_string, result_raw_buffer);
});

Example 2 - sign only

Along the same lines, it's easy to sign a cleartext message. Just provide a sign_with KeyManager but leave off the encrypt_for.

params =
  msg:         "Here is my manifesto"
  sign_with:   alice

kbpgp.box params, (err, result_string, result_buffer) ->
  console.log err, result_string, result_buffer

var params = {
  msg:        "Here is my manifesto",
  sign_with:  alice
};

kbpgp.box (params, function(err, result_string, result_buffer) {
  console.log(err, result_string, result_buffer);
});

Example 3 - sign+encrypt

Assumption: we also have a KeyManager instance, alice, for the sender.

params =
  msg:         "Chuck chucky, bo-bucky! This is Alice here!"
  encrypt_for: chuck
  sign_with:   alice

kbpgp.box params, (err, result_string, result_buffer) ->
  console.log err, result_string, result_buffer

var params = {
  msg:         "Chuck chucky, bo-bucky! This is Alice here!",
  encrypt_for: chuck,
  sign_with:   alice
};

kbpgp.box (params, function(err, result_string, result_buffer) {
  console.log(err, result_string, result_buffer);
});

Example 4 - using input and output Buffers

kbpgp can take Node.js Buffers as input, instead of strings. The following reads a .png file and writes a new encrypted copy of it. For more info, check out the kbpgp buffers documentation.

kbpgp  = require 'kbpgp'
fs     = require 'fs'

buffer = fs.readFileSync 'dirty_deeds.png'

params =
  msg:         buffer
  encrypt_for: chuck
  sign_with:   alice

kbpgp.box params, (err, result_string, result_buffer) ->
  fs.writeFileSync 'dirty_deeds.encrypted', result_buffer

var kbpgp  = require('kbpgp');
var fs     = require('fs');
var buffer = fs.readFileSync('dirty_deeds.png');
var params = {
  msg:         buffer,
  encrypt_for: chuck,
  sign_with:   alice
};

kbpgp.box (params, function(err, result_string, result_buffer) {
  fs.writeFileSync('dirty_deeds.encrypted', result_buffer);
});

Buffers are available in the browser, too, for doing HTML5 things with files. kbpgp.Buffer provides a browser-implementation that matches Node.js's.

Example 5 - progress hooks and canceling

Most kbpgp function can take a kbpgp.ASP object, which is used to monitor progress and check for cancelation requests.

# let's log progress with a custom asp
# (below we'll use this same asp to cancel, too.)

asp = new kbpgp.ASP {
  progress_hook: (info) -> console.log "progress...", info
}

params =
  msg:         "a secret not worth waiting for"
  encrypt_for: chuck
  asp:         asp

kbpgp.box params, (err, result_string, result_buffer) ->
  console.log "Done!", err, result_string, result_buffer

# sometime before it's done...
asp.canceler().cancel()

var asp = new kbpgp.ASP({
  progress_hook: function(info) {
    console.log("progress...", info);
  }
});

var params = {
  msg:         "a secret not worth waiting for",
  encrypt_for: chuck,
  asp:         asp
};

kbpgp.box(params, function(err, result_string, result_buffer) {
  console.log("Done!", err, result_string, result_buffer);
});

// sometime before it's done
asp.canceler().cancel();

We're just getting started with this tutorial and examples. Hit us up on github if anything is missing.