Class: Envelope

Envelope(params)

Envelope class

A Univrse Envelope is a structure containing a set of headers, a payload, and optionally one or more Signatures and Recipients.

An Envelope can be converted to a compact CBOR encoded buffer, a Base64 encoded string, or a Bitcoin OP_RETURN Script. This allows envelopes to be easily and efficiently transferred between different parties, who in turn can decode the wrapped payload.

Constructor

new Envelope(params)

Instantiates a new Envelope instance with the given params.

Accepted params

  • headers - headers object
  • payload - data payload
  • signature - singature instance or array of signatures
  • recipient - recipient instance or array of recipients
Parameters:
Name Type Description
params Object
Source:

Classes

fromArray
fromBuffer
fromScript
fromString
wrap

Members

encodedPayload :Buffer

CBOR encoded payload

Type:
  • Buffer
Source:

encodedPayload :Buffer

Sets the payload by decoding the given encoded payload.

Type:
  • Buffer
Source:

Methods

(async) decrypt(key, opts) → {Envelope}

Decrypts the payload using the given key.

If the Envelope contains multiple recipients, it is assumed the key belongs to the first recipient. Otherwise, see decryptAt().

An second argument of options can be given for the relevant encryption algorithm.

Parameters:
Name Type Description
key Key
opts Object
Source:
Returns:
Type
Envelope

(async) decryptAt(i, key, opts) → {Envelope}

Decrypts the payload by first decrypting the content key at the specified recipient index.

The Envelope mustcontains multiple recipients.

Parameters:
Name Type Description
i Number

recipient index
key Key
opts Object
Source:
Returns:
Type
Envelope

(async) encrypt(key, headers, opts) → {Envelope}

Encrypts the payload using the given key or array of keys.

A headers object must be given including at least the encryption alg value.

A third argument of options can be given for the relevant encryption algorithm.

Where an array of keys is given, the first key is taken as the content key and used to encrypt the payload. The content key is then encrypted by each subsequent key and included in the Recipient instances that are attached to the envelope.

When encrypting to multiple recipients, it is possible to specify different algorithms for each key by giving an array of two element arrays. The first element of each pair is the key and the second is a headers object.

Examples

Encrypts for a single recipient:

envelope.encrypt(aesKey, { alg: 'A128GCM' })

Encrypts for a multiple recipients using the same algorithm:

envelope.encrypt([aesKey, recKey], { alg: 'A128GCM' })

Encrypts for a multiple recipients using different algorithms:

envelope.encrypt([ aesKey, [rec1Key, { alg: 'ECDH-ES+A128GCM' }], [rec2Key, { alg: 'ECDH-ES+A128GCM' }], ], { alg: 'A128GCM' })

Parameters:
Name Type Description
key
headers Object
opts Object
Source:
Returns:
Type
Envelope

pushRecipient(recipient) → {Envelope}

Attaches the given Recipient instance onto the Envelope.

Parameters:
Name Type Description
recipient Recipient
Source:
Returns:
Type
Envelope

pushSignature(signature) → {Envelope}

Attaches the given Signature instance onto the Envelope.

Parameters:
Name Type Description
signature Signature
Source:
Returns:
Type
Envelope

(async) sign(key, headers) → {Envelope}

Signs the payload using the given key or array of keys.

A headers object must be given including at least the signature alg value.

Where an array of keys is given, it is possible to specify different algorithms for each key by giving an array of two element arrays. The first element of each pair is the key and the second is a headers object.

Examples

Creates a signature using a single key:

envelope.sign(octKey, { alg: 'HS256' })

Creates multiple signatures using the same algorithm:

envelope.sign([userKey, appKey], { alg: 'HS256' })

Creates multiple signatures using different algorithms:

envelope.sign([ octKey, [ecKey1, { alg: 'ES256K' }], [ecKey2, { alg: 'ES256K' }] ], { alg: 'HS256' })

Parameters:
Name Type Description
key
headers Object
Source:
Returns:
Type
Envelope

toArray() → {Array}

Returns the Envelope as an array of component parts.

Used internally prior to encoding the envelope.

Source:
Returns:
Type
Array

toBuffer() → {Buffer}

Returns the Envelope as a CBOR encoded Buffer.

Source:
Returns:
Type
Buffer

toScript(falseReturnopt) → {String}

Returns the Envelope as bsv Script instance.

Parameters:
Name Type Attributes Default Description
falseReturn Boolean <optional>
 true
Source:
Returns:
Type
String

toString() → {String}

Returns the Envelope as Base64 encoded string.

Source:
Returns:
Type
String

(async) verify(key, i) → {Boolean}

Verifies the signature(s) using the given Key or array of Keys.

Where the envelope has multiple signature, can optionally specfify the signature index the key relates to.

Parameters:
Name Type Description
key Key | Array.<Key>

key or array of keys
i Number

signature index
Source:
Returns:
Type
Boolean