Class: Keyring

Constructor

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: client-api.js, line 209

Methods

addSyncHandler(syncHandlerObj) → {Promise.<undefined, Error>}

Add various functions for keyring synchronization

Parameters:

Name	Type	Description
`syncHandlerObj`	SyncHandlerObject

Source: client-api.js, line 490

Returns:

Type:: Promise.<undefined, Error>

additionalHeadersForOutgoingEmail(headers) → {Promise.<additionalMailHeaders, Error>}

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: client-api.js, line 310

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=..."}
});

createKeyBackupContainer(selector, options) → {Promise.<KeyBackupPopup, Error>}

Creates an iframe to initiate the key backup process.

Parameters:

Name	Type	Description
`selector`	CssSelector	target container
`options`	KeyBackupContainerOptions

Source: client-api.js, line 403

Returns:

Type:: Promise.<KeyBackupPopup, Error>

createKeyGenContainer(selector, options) → {Promise.<Generator, Error>}

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: client-api.js, line 388

Throws:

error.code = 'INPUT_NOT_VALID'
Type Error

Returns:

Type:: Promise.<Generator, Error>

exportOwnPublicKey(emailAddr) → {Promise.<AsciiArmored, Error>}

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: client-api.js, line 282

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(query) → {Promise.<boolean, Error>}

Check if keyring contains valid private key with given fingerprint

Parameters:

Name	Type	Description
`query`	String \| Object	fingerprint string, or an object with `fingerprint` and/or `email`

Source: client-api.js, line 427

Returns:

Type:: Promise.<boolean, Error>

importPublicKey(armored) → {Promise.<String, Error>}

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

Parameters:

Name	Type	Description
`armored`	AsciiArmored	public key to import

Source: client-api.js, line 324

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(optionsopt) → {Promise.<undefined, Error>}

Open the extension settings in a new browser tab

Parameters:

Name	Type	Attributes	Description
`options`	OpenSettingsOptions	<optional>

Source: client-api.js, line 513

Returns:

Type:: Promise.<undefined, Error>

processAutocryptHeader(headers) → {Promise.<undefined, Error>}

Process Autocrypt header from message being read.

Parameters:

Name	Type	Description
`headers`	AutocryptMailHeaders	the relevant mail headers

Source: client-api.js, line 342

Throws:

error.code = 'INVALID_HEADER' error.code = 'STORAGE_ERROR'
Type Error

Returns:

Type:: Promise.<undefined, Error>

restoreBackupContainer(selector, options) → {Promise.<undefined, Error>}

Creates an iframe to restore the backup.

Parameters:

Name	Type	Description
`selector`	CssSelector	target container
`options`	PrivateKeyContainerOptions

Source: client-api.js, line 418

Returns:

Type:: Promise.<undefined, Error>

setLogo(dataURL, revision) → {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: client-api.js, line 362

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) → {Promise.<Object, Error>}

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: client-api.js, line 257

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'
//       }
//     ]
//   }
// }
});