@bicycle-codes/keys

keys

Create and store keypairs in the browser with the web crypto API.

Use indexedDB to store non-extractable keypairs in the browser. "Non-extractable" means that the browser prevents you from ever reading the private key, but the keys can be persisted and re-used indefinitely.

Tip

Use the persist method to tell the browser not to delete from indexedDB.

Each instance of Keys has two keypairs -- one for signing, and another for encrypting. We are using RSA keys only right now, because we are waiting for all browsers to support ECC.

install

npm i -S @bicycle-codes/keys

Asymmetric Encryption
Modules
- exports
- ESM
- Common JS
- pre-built JS
get started
examples
AES

Asymmetric Encryption

Asymmetric encryption means using an AES key to encrypt the content, then encrypting the AES key to a public RSA key. If you encrypt something to Bob's public key, that means we create a new buffer of encrypted AES key + encrypted content, where the encrypted AES key can only be decrypted by Bob's private key.

Modules

`exports`

This exposes ESM and common JS via package.json exports field.

ESM

import { Keys } from '@bicycle-codes/keys'

Common JS

const { Keys } = require('@bicycle-codes/keys')

pre-built JS

This package exposes minified JS files too. Copy them to a location that is accessible to your web server, then link to them in HTML.

copy

cp ./node_modules/@bicycle-codes/keys/dist/index.min.js ./public/keys.min.js

HTML

<script type="module" src="./keys.min.js"></script>

get started

Create a keypair

Create a new keypair, then save it in indexedDB.

import { Keys } from '@bicycle-codes/keys'

const keys = await Keys.create()

// save the keys to indexedDB
await keys.persist()

// ... sometime in the future ...
// get our keys from indexedDB
const keysAgain = await Keys.load()

console.assert(keys.DID === keysAgain.DID)  // true

some notes about the `keys` instance

`keys.DID`

This is the DID string for the signing key for this instance. The DID looks like this:

'did:key:z13V3Sog2YaUKhdGCmgx9UZuW...'

`keys.getDeviceName` / `keys.deviceName`

Return the 32 character, DNS friendly hash of the signing public key.

const name = await keys.getDeviceName()

// a promise is exposed as property `deviceName`
const name = await keys.deviceName

`keys.persisted`

A flag indicating whether .persist has been called, meaning that these keys are saved in indexedDB.

`keys.publicEncryptKey`

The public encryption CryptoKey.

`keys.getPublicEncryptKey()`

Get the public encryption key, as a base64 string. For other formats, see below.

{
  async getPublicEncryptKey ():Promise<string>
}

`keys.getPublicEncryptKey(format)`

Get the public encryption key. The given format should be a supported encoding in uint8arrays.

{
  async getPublicEncryptKey (
    format?:SupportedEncodings
  ):Promise<string>
}

keys.getPublicEncryptKey.uint8Array

Get the public encryption key as a Uint8Array.

{
  function uint8Array:()=>Promise<Uint8Array<ArrayBufferLike>>
}

sign and verify something

.verify takes the content, the signature, and the DID for the public key used to sign. The DID is exposed as the property .DID on a Keys instance.

Note

verify is exposed as a separate function, so you don't have to include all of Keys just to verify a signature.

import { Keys, verify } from '@bicycle-codes/keys'

const keys = await Keys.create()

// sign something
const sig = await keys.sign.asString('hello string')

// verify the signature
const isOk = await verify('hello string', sig, keys.DID)

encrypt something

Take the public key we are encrypting to, return an ArrayBuffer, containing the encrypted AES key concattenated with the iv and encrypted content.

import { encryptTo } from '@bicycle-codes/keys'

// need to know the public key we are encrypting for
const publicKey = await keys.getPublicEncryptKey()

const encrypted = await encryptTo({
  content: 'hello public key',
  publicKey
})  // => ArrayBuffer

const encrypted = await encryptTo.asString({
  content: 'hello public key',
  publicKey
})
// => <encrypted text>

decrypt something

A Keys instance has a method decrypt. The encryptedMessage argument is an ArrayBuffer as returned from encryptTo, above.

import { Keys } from '@bicycle-codes/keys'

const keys = await Keys.create()
// ...
const decrypted = await keys.decrypt(encryptedMsg)

examples

Create a new `Keys` instance

Use the factory function Keys.create. The optional parameters, encryptionKeyName and signingKeyName, are added as properties to the keys instance -- ENCRYPTION_KEY_NAME and SIGNING_KEY_NAME. These are used as indexes for saving the keys in indexedDB.

class Keys {
  ENCRYPTION_KEY_NAME:string = 'encryption-key'
  SIGNING_KEY_NAME:string = 'signing-key'

  static async create (opts?:{
      encryptionKeyName:string,
      signingKeyName:string
  }):Promise<Keys>
}

`.create()` example

Use the factory function b/c async.

import { Keys } from '@bicycle-codes/keys'

const keys = await Keys.create()

Get a hash of the DID

Get a 32-character, DNS-friendly string of the hash of the given DID. Available as static or instance method. If called as an instance method, this will use the DID assigned to the given Keys instance.

The static method requires a DID string to be passed in.

static method

class Keys {
  static async deviceName (did:DID):Promise<string>
}

instance method

If used as an instance method, this will use the DID assigned to the instance.

class Keys {
  async getDeviceName ():Promise<string>
}

Persist the keys

Save the keys to indexedDB. This depends on the values of class properties ENCRYPTION_KEY_NAME and SIGNING_KEY_NAME. Set them if you want to change the indexes under which the keys are saved to indexedDB.

By default we use these:

const DEFAULT_ENC_NAME = 'encryption-key'
const DEFAULT_SIG_NAME = 'signing-key'

`.persist`

class Keys {
  async persist ():Promise<void>
}

`.persist` example

import { Keys } from '@bicycle-codes/keys'

const keys = await Keys.create()
keys.ENCRYPTION_KEY_NAME = 'encryption-key-custom-name'
keys.SIGNING_KEY_NAME = 'signing-key-custom-name'
await keys.persist()

Restore from indexedDB

Create a Keys instance from data saved to indexedDB. Pass in different indexedDB key names for the keys if you need to.

`static .load`

class Keys {
    static async load (opts:{
      encryptionKeyName,
      signingKeyName
    } = {
      encryptionKeyName: DEFAULT_ENC_NAME,
      signingKeyName: DEFAULT_SIG_NAME
    }):Promise<Keys>
}

example

import { Keys } from '@bicycle-codes/keys'

const newKeys = await Keys.load()

Sign something

Create a new signature for the given input.

class Keys {
  async sign (
    msg:ArrayBuffer|string|Uint8Array,
    charsize?:CharSize,
  ):Promise<Uint8Array>
}

example

const sig = await keys.sign('hello signatures')

Get a signature as a string

`keys.sign.asString(msg)`

{
  /**
   * Sign a message, return the signature as a base64 encoded string.
   *
   * @param {Msg} msg The message to sign
   * @param {CharSize} [charsize] Character size
   * @returns {Promise<string>}
   */
  asString: async (msg:Msg, charsize?:CharSize):Promise<string>
}

const sig = await keys.sign.asString('hello string')
// => ubW9PIjb360v...

Verify a signature

Check if a given signature is valid. This is exposed as a stateless function so that it can be used independently from any keypairs. You need to pass in the data that was signed, the signature, and the DID string of the public key used to create the signature.

async function verify (
    msg:string|Uint8Array,
    sig:string|Uint8Array,
    signingDid:DID
):Promise<boolean>

import { verify } from '@bicycle-codes/keys'

const isOk = await verify('hello string', sig, keys.DID)

Encrypt a key

Use asynchronous (RSA) encryption to encrypt an AES key to the given public key.

async function encryptKeyTo ({ key, publicKey }:{
    key:string|Uint8Array|CryptoKey;
    publicKey:CryptoKey|Uint8Array|string;
}, format?:'uint8array'|'arraybuffer'):Promise<Uint8Array|ArrayBuffer>

example

import { encryptKeyTo } from '@bicycle-codes/keys'

// pass in a CryptoKey
const encrypted = await encryptKeyTo({
    key: myAesKey,
    publicKey: keys.publicEncryptKey
})

// pass in a base64 string
const encryptedTwo = await encryptKeyTo({
  key: aesKey,
  publicKey: await keys.getPublicEncryptKey()
})  // => Uint8Array

encrypt a key, return a string

Encrypt the given key to the public key, and return the result as a base64 string.

import { encryptKeyTo } from '@bicycle-codes/keys'

encryptKeyTo.asString = async function ({ key, publicKey }:{
    key:string|Uint8Array|CryptoKey;
    publicKey:CryptoKey|string|Uint8Array;
}, format?:SupportedEncodings):Promise<string> {

format

encryptKeyTo.asString takes an optional second argument for the format of the returned string. Format is anything supported by uint8arrays. By default, if omitted, it is base64.

Asymmetrically encrypt some arbitrary data

Encrypt the given message to the given public key. If an AES key is not provided, one will be created. Use the AES key to encrypt the given content, then encrypt the AES key to the given public key.

The return value is an ArrayBuffer containing the encrypted AES key + the iv + the encrypted content.

To decrypt, pass the returned value to keys.decrypt, where keys is an instance with the corresponding private key.

async function encryptTo (
    opts:{
        content:string|Uint8Array;
        publicKey:CryptoKey|string;
    },
    aesKey?:SymmKey|Uint8Array|string,
):Promise<ArrayBuffer>

example

import { encryptTo } from '@bicycle-codes/keys'

const encrypted = await encryptTo({
    content: 'hello encryption',
    publicKey: keys.publicEncryptKey
})

// => ArrayBuffer

Asymmetrically encrypt a string, return a new string

Encrypt the given string, and return a new string that is the (encrypted) AES key concattenated with the iv and cipher text. The corresponding method keys.decrypt.asString will know how to parse and decrypt the resulting text.

Use the functions encryptTo.asString and keys.decrypt.asString.

`keys.decrypt.asString`

async function asString (msg:string, keysize?:SymmKeyLength):Promise<string>

import { Keys, encryptTo } from '@bicycle-codes/keys'

const keys = await Keys.create()
const pubKey = await keys.getPublicEncryptKey()
const msg = { type: 'test', content: 'hello' }
const cipherText = await encryptTo.asString({
    content: JSON.stringify(msg),
    // pass in a string public key or crypto key or Uint8Array
    publicKey: pubKey
})  // => string

const text = await keys.decrypt.asString(cipherText)
const data = JSON.parse(text)
// => { type: 'test', content: 'hello' }

Decrypt a message

class Keys {
  async decrypt (
    msg:string|Uint8Array|ArrayBuffer,
    keysize?:SymmKeyLength
  ):Promise<Uint8Array>
}

const decrypted = await keys.decrypt(encrypted)
// => Uint8Array

`.decrypt.asString`

Decrypt a message, and stringify the result.

{
  async function asString (msg:EncryptedMessage):Promise<string>
}

await keys.decrypt.asString(encryptedString)
// => 'hello encryption'

AES

Expose several AES functions with nice defaults.

algorithm: AES-GCM
key size: 256
iv size: 12 bytes (96 bits)

import { AES } from '@bicycle-codes/keys'

const key = await AES.create(/* ... optional arguments ... */)

`create`

Create a new AES key. By default uses 256 bits & GCM algorithm.

function create (opts:{ alg:string, length:number } = {
    alg: DEFAULT_SYMM_ALGORITHM,  // AES-GCM
    length: DEFAULT_SYMM_LENGTH  // 256
}):Promise<CryptoKey>

import { AES } from '@bicycle-codes/keys'
const aesKey = await AES.create()

`export`

Get the AES key as a Uint8Array.

  async function export (key:CryptoKey):Promise<Uint8Array>

import { AES } from '@bicycle-codes/keys'
const exported = await AES.export(aesKey)

`exportAsString`

Get the key as a string, base64 encoded.

async function asString (
  key:CryptoKey,
  format?:SupportedEncoding
):Promise<string>

import { AES } from '@bicycle-codes/keys'
const exported = await AES.export.asString(aesKey)

`AES.encrypt`

Take a Uint8Array, return an encrypted Uint8Array.

async function encrypt (
  data:Uint8Array,
  cryptoKey:CryptoKey|Uint8Array,
  iv?:Uint8Array
):Promise<Uint8Array>

import { AES } from '@bicycle-codes/keys'
import { fromString } from 'uint8arrays'

const encryptedText = await AES.encrypt(fromString('hello AES'), aesKey)

`AES.decrypt`

async function decrypt (
  encryptedData:Uint8Array|string,
  cryptoKey:CryptoKey|Uint8Array|ArrayBuffer,
  iv?:Uint8Array
):Promise<Uint8Array>

import { AES } from '@bicycle-codes/keys'

const decryptedText = await AES.decrypt(encryptedText, aesKey)

@bicycle-codes/keys

keys

install

Contents

Asymmetric Encryption

Modules

exports

ESM

Common JS

pre-built JS

copy

HTML

get started

Create a keypair

some notes about the keys instance

keys.DID

keys.getDeviceName / keys.deviceName

keys.persisted

keys.publicEncryptKey

keys.getPublicEncryptKey()

keys.getPublicEncryptKey(format)

keys.getPublicEncryptKey.uint8Array

sign and verify something

encrypt something

decrypt something

examples

Create a new Keys instance

.create() example

Get a hash of the DID

static method

instance method

Persist the keys

.persist

.persist example

Restore from indexedDB

static .load

example

Sign something

example

Get a signature as a string

keys.sign.asString(msg)

Verify a signature

Encrypt a key

example

encrypt a key, return a string

format

Asymmetrically encrypt some arbitrary data

example

Asymmetrically encrypt a string, return a new string

keys.decrypt.asString

Decrypt a message

.decrypt.asString

AES

create

export

exportAsString

AES.encrypt

AES.decrypt

Settings

On This Page

`exports`

some notes about the `keys` instance

`keys.DID`

`keys.getDeviceName` / `keys.deviceName`

`keys.persisted`

`keys.publicEncryptKey`

`keys.getPublicEncryptKey()`

`keys.getPublicEncryptKey(format)`

Create a new `Keys` instance

`.create()` example

`.persist`

`.persist` example

`static .load`

`keys.sign.asString(msg)`

`keys.decrypt.asString`

`.decrypt.asString`

`create`

`export`

`exportAsString`

`AES.encrypt`

`AES.decrypt`