kbpgp.js

KeyManager

You can create a KeyManager and generate new keys in one swoop.

At the end of the below process, we'll have a KeyManager instance, alice, which can be used for any crypto action.

Example 1 - RSA - with custom settings

To illustrate a common use case, we'll generate subkeys for both signing and encryption. And, by the way, when kbpgp performs actions with KeyManagers, it automatically picks the appropriate subkey(s). 

F = kbpgp.const.openpgp

# -------------------------------------------------------------
# opts: let's generate a PGP key pair with 2 subkeys,
# one for code signing and one for communication
# -------------------------------------------------------------

opts =
  userid:        "User McTester (Born 1979) <user@example.com>"
  primary:
    nbits:       4096
    flags:       F.certify_keys | F.sign_data | F.auth | F.encrypt_comm | F.encrypt_storage
    expire_in:   0 # never expire
  subkeys: [
    {
      nbits:     2048
      flags:     F.sign_data
      expire_in: 86400 * 365 * 8 # 8 years
    }
    {
      nbits:     2048
      flags:     F.encrypt_comm | F.encrypt_storage
      expire_in: 86400 * 365 * 2
    }
  ]

# -------------------------------------------------------------
# let's perform the generation
# -------------------------------------------------------------

kbpgp.KeyManager.generate opts, (err, alice) ->
  # and sign alice's subkeys
  if (not err) then alice.sign {}, (err) ->

    # ---------------------------------------------------------
    # and that's it!
    # from here we can export armored keys, perform crypto, etc.
    # as our KeyManager is complete
    # ---------------------------------------------------------

    console.log alice

    # ---------------------------------------------------------
    # quick little demo of how you export the public and private
    # keys
    # ---------------------------------------------------------

    alice.export_pgp_private {passphrase: 'booyeah!'}, (err, pgp_private) ->
      console.log "private key: ", pgp_private
    alice.export_pgp_public {}, (err, pgp_public) ->
      console.log "public key: ", pgp_public

So easy!

Example 2 - RSA - with sensible defaults

The above parameters are reasonable. If you're happy with them, you can simply call the KeyManager::generate_rsa shortcut:

kbpgp.KeyManager.generate_rsa { userid : "Bo Jackson <user@example.com>" }, (err, charlie) ->
   charlie.sign {}, (err) ->
     console.log "done!"

Example 3 - ECC Keypairs - custom

Kbpgp has support for Elliptic Curve PGP (see RFC-6637 for more details). You can provide the ecc : true option to the above generate call to make an ECC key pair rather than the standard PGP keypair. Keep in mind, though, that most GPG clients in the wild do not currently support ECC. 

F = kbpgp.const.openpgp

# -------------------------------------------------------------
# opts: let's generate a PGP key pair with 2 subkeys,
# one for code signing and one for communication
# -------------------------------------------------------------

opts =
  userid:        "User McTester (Born 1979) <user@example.com>"
  ecc:           true
  primary:
    nbits:       384
    flags:       F.certify_keys | F.sign_data | F.auth | F.encrypt_comm | F.encrypt_storage
    expire_in:   0 # never expire
  subkeys: [
    {
      nbits:     256
      flags:     F.sign_data
      expire_in: 86400 * 365 * 8 # 8 years
    }
    {
      nbits:     256
      flags:     F.encrypt_comm | F.encrypt_storage
      expire_in: 86400 * 365 * 2
    }
  ]

# -------------------------------------------------------------
# let's perform the generation
# -------------------------------------------------------------

kbpgp.KeyManager.generate opts, (err, alice) ->
   # ... and as before ...

Example 4 - ECC Keypairs - with sensible defaults

To use these default parameters, we also provide the shortcut: 

kbpgp.KeyManager.generate_ecc { userid : "<user@example.com>" }, (err, charlie) ->
   charlie.sign {}, (err) ->
     console.log "done!"

Monitoring

All kbpgp functions support passing an `ASync Package` (ASP) object, for monitoring. Your ASP can have a progress_hook function, which will get called with info about its progress. This is especially important with RSA key generation, as it can take a little while. If this is in any kind of client app, you'll want to (a) show some indicator that you're doing work, and (b) have a cancel button. 

my_asp = new kbpgp.ASP {
  progress_hook: (o) ->
    console.log "I was called with progress!", o
}

opts =
  asp:           my_asp               # note this line!
  userid:        "user@example.com"
  primary:
    nbits:       2048
  subkeys: []
  # etc.

kbpgp.KeyManager.generate opts, some_callback_function

Canceling

If you pass an ASP object, as described above, you can use it to cancel your process. 

kbpgp.KeyManager.generate opts, some_callback_function

# oh, heck, let's give up if it takes more than a second
# you might also consider a button push or some other event

setTimeout (->
  my_asp.canceler.cancel()
), 1000

In the above example, if the generation has not completed within one second, work will halt and some_callback_function will immediately get called with err, null.

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