Mailvelope API

Class: Keyring

Keyring

Not accessible, instance can be obtained using Mailvelope#getKeyring
or Mailvelope#createKeyring.

new Keyring(identifier, options)

Parameters:
Name Type Description
identifier String

the keyring identifier
options object

the options
Properties:
Name Type Description
logoRev number

revision number of the keyring logo, initial value: 0
Source:

Methods

additionalHeadersForOutgoingEmail(headers)

Returns headers that should be added to an outgoing email.
So far this is only the autocrypt header.

Parameters:
Name Type Description
headers outgoingMailHeaders

headers of the outgoing mail.

In particular from to select the key
Source:
Throws:

error.code = 'NO_KEY_FOR_ADDRESS'

Type
Error
Returns:
Type
Promise.<additionalMailHeaders, Error>
Example
keyring.additionalHeadersForOutgoingEmail(from: 'abc@web.de').then(function(additional) {
  console.log('additionalHeadersForOutgoingEmail', additional);
  // logs: {autocrypt: "addr=abc@web.de; prefer-encrypt=mutual; keydata=..."}
});

addSyncHandler(syncHandlerObj)

Add various functions for keyring synchronization

Parameters:
Name Type Description
syncHandlerObj SyncHandlerObject
Source:
Returns:
Type
Promise.<undefined, Error>

createKeyBackupContainer(selector, options)

Creates an iframe to initiate the key backup process.

Parameters:
Name Type Description
selector CssSelector

target container
options KeyBackupContainerOptions
Source:
Returns:
Type
Promise.<KeyBackupPopup, Error>

createKeyGenContainer(selector, options)

Creates an iframe to display the key generation container.
The iframe will be injected into the container identified by selector.

Parameters:
Name Type Description
selector CssSelector

target container
options KeyGenContainerOptions
Source:
Throws:

error.code = 'INPUT_NOT_VALID'

Type
Error
Returns:
Type
Promise.<Generator, Error>

exportOwnPublicKey(emailAddr)

Exports the public key as an ascii armored string.
Only keys belonging to the user (corresponding private key exists) can be exported.

Parameters:
Name Type Description
emailAddr String

email address to identify the public+private key
Source:
Throws:

error.code = 'NO_KEY_FOR_ADDRESS'

Type
Error
Returns:
Type
Promise.<AsciiArmored, Error>
Example
keyring.exportOwnPublicKey('abc@web.de').then(function(armoredPublicKey) {
  console.log('exportOwnPublicKey', armoredPublicKey);
  // prints: "-----BEGIN PGP PUBLIC KEY BLOCK..."
});

hasPrivateKey(fingerprint)

Check if keyring contains valid private key with given fingerprint

Parameters:
Name Type Description
fingerprint String | Object

or Object with fingerprint or email property
Source:
Returns:
Type
Promise.<boolean, Error>

importPublicKey(armored)

Asks the user if they want to import the public key.

Parameters:
Name Type Description
armored AsciiArmored

public key to import
Source:
Throws:

error.code = 'IMPORT_ERROR'

error.code = 'WRONG_ARMORED_TYPE'

Type
Error
Returns:

'IMPORTED' - key has been imported

'UPDATED' - key already in keyring, new key merged with existing key

'INVALIDATED' - key has been updated, new status of key is 'invalid' (e.g. revoked)

'REJECTED' - key import rejected by user

Type
Promise.<String, Error>

openSettings( [options])

Open the extension settings in a new browser tab

Parameters:
Name Type Argument Description
options OpenSettingsOptions <optional>
Source:
Returns:
Type
Promise.<undefined, Error>

processAutocryptHeader(headers)

Process Autocrypt header from message being read.

Parameters:
Name Type Description
headers AutocryptMailHeaders

the relevant mail headers
Source:
Throws:

error.code = 'INVALID_HEADER'

error.code = 'STORAGE_ERROR'

Type
Error
Returns:
Type
Promise.<undefined, Error>

restoreBackupContainer(selector, options)

Creates an iframe to restore the backup.

Parameters:
Name Type Description
selector CssSelector

target container
options PrivateKeyContainerOptions
Source:
Returns:
Type
Promise.<undefined, Error>

Set logo for keyring. The image is persisted in Mailvelope with a revision number,
therefore the method is only required after new keyring generation or if logo and revision number changes.

Parameters:
Name Type Description
dataURL String

data-URL representing the logo, max. file size: ~10KB, max. image size: 192x96px, content-type: image/png
revision number

revision number
Source:
Throws:

error.code = 'LOGO_INVALID'

error.code = 'REVISION_INVALID'

Type
Error
Returns:
Type
Promise.<undefined, Error>
Example
keyring.setLogo('data:image/png;base64,iVBORS==', 3).then(function() {
  // keyring.logoRev == 3
}).catch(function(error) {
  // logo update failed
});

validKeyForAddress(recipients)

Checks for valid key in the keyring for provided email addresses
If none is found also checks in other sources (see LookupResult).

Parameters:
Name Type Description
recipients Array

list of email addresses for key lookup
Source:
Returns:

The object maps email addresses to:

false: no valid key

{keys: [LookupResult]}: valid keys

Type
Promise.<Object, Error>
Example
keyring.validKeyForAddress(['abc@web.de', 'info@mailvelope.com']).then(function(result) {
    console.log(result);
// {
//   'abc@web.de': false,
//   'info@mailvelope.com': {
//     keys: [
//       {
//         fingerprint: 'f37377c39898d05ffd39157a98bbec557ce08def',
//         lastModified: Tue May 19 2015 10:36:53 GMT+0200 (CEST),
//         source: 'LOC'
//       }
//     ]
//   }
// }
});