From d2b232d5e94150fd49bbc6ea986f6bfaf195328e Mon Sep 17 00:00:00 2001 From: Errietta Kostala Date: Sat, 2 Jun 2018 19:41:05 +0100 Subject: [PATCH] Update openpgp.js type definitions to match module --- types/openpgp/index.d.ts | 275 ++++++++++++++++++++++++--------- types/openpgp/openpgp-tests.ts | 45 ++---- 2 files changed, 211 insertions(+), 109 deletions(-) diff --git a/types/openpgp/index.d.ts b/types/openpgp/index.d.ts index 79e92daa7f..6c8e073c04 100644 --- a/types/openpgp/index.d.ts +++ b/types/openpgp/index.d.ts @@ -1,22 +1,73 @@ // Type definitions for openpgpjs // Project: http://openpgpjs.org/ // Definitions by: Guillaume Lacasa +// Errietta Kostala // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped export as namespace openpgp; -export interface KeyPair { +export interface UserId { + name?: string, + email?: string, +} + +export interface SessionKey { + data: Uint8Array, + algorithm: string +} + +export interface EncryptOptions { + data: string|Uint8Array, + dataType?: 'utf8'|'binary'|'text'|'mime', + publicKeys?: key.Key | key.Key[], + privateKeys?: key.Key | key.Key[], + passwords?: string|string[], + sessionKey?: SessionKey, + filename?: string, + compression?: enums.compression, + armor?: boolean, + detached?: boolean, + signature?: Signature, + returnSessionKey?: boolean, + wildcard?: boolean, + date?: Date, + fromUserId?: UserId, + toUserId?: UserId, +} + +export interface EncryptedMessage { + data: string, + message: string, +} + +export interface DecryptOptions { + message: message.Message, + privateKeys?: key.Key | key.Key[], + passwords?: string | string[], + sessionKeys?: SessionKey | SessionKey[], + publicKeys?: key.Key | key.Key[], + format?: string, + signature?: Signature, + date?: Date, +} + +export interface KeyContainer { key: key.Key, +} + +export interface KeyPair extends KeyContainer { privateKeyArmored: string, publicKeyArmored: string } export interface KeyOptions { - keyType?: enums.publicKey, - numBits: number, - userId: string, - passphrase: string, - unlocked?: boolean + userIds?: UserId[], + passphrase?: string, + numBits?: number, + keyExpirationTime?: number, + curve?: string, + date?: Date, + subkeys?: KeyOptions[] } export interface Keyid { @@ -29,91 +80,153 @@ export interface Signature { } export interface VerifiedMessage { - text: string, - signatures: Array + data: Uint8Array|string, + signatures: Array, + filename: string, } -/** Decrypts message and verifies signatures +export interface OpenPGPWorker { + randomCallback(): void; + configure(config: any): void; + seedRandom(buffer: ArrayBuffer): void; + delegate(id: number, method: string, options: any): void; + response(event: any): void; +} - @param privateKey private key with decrypted secret key data - @param publicKeys array of keys to verify signatures - @param msg the message object with signed and encrypted data - */ -export function decryptAndVerifyMessage(privateKey: key.Key, publicKeys: Array, msg: string): Promise; -/** Decrypts message and verifies signatures +export interface WorkerOptions { + path?: string, + n?: number, + workers?: OpenPGPWorker[], + config?: any, +} - @param privateKey private key with decrypted secret key data - @param publicKey single key to verify signatures - @param msg the message object with signed and encrypted data - */ -export function decryptAndVerifyMessage(privateKey: key.Key, publicKey: key.Key, msg: string): Promise; +export class AsyncProxy { + constructor(options: WorkerOptions); + getId(): number; + seedRandom(workerId: number, size: number): Promise; + terminate(): void; + delegate(method: string, options: any): void; -/** Decrypts message + workers: OpenPGPWorker[]; +} - @param privateKey private key with decrypted secret key data - @param msg the message object with the encrypted data - */ -export function decryptMessage(privateKey: key.Key, msg: message.Message): Promise; +/** + * Set the path for the web worker script and create an instance of the async proxy + * @param {String} path relative path to the worker scripts, default: 'openpgp.worker.js' + * @param {Number} n number of workers to initialize + * @param {Array} workers alternative to path parameter: web workers initialized with 'openpgp.worker.js' + */ +export function initWorker(options: WorkerOptions): boolean; -/** Encrypts message text with keys - @param keys array of keys used to encrypt the message - @param text message as native JavaScript string - @returns encrypted ASCII armored message - */ -export function encryptMessage(keys: Array, message: string): Promise; -/** Encrypts message text with keys +/** + * Returns a reference to the async proxy if the worker was initialized with openpgp.initWorker() + * @returns {module:worker/async_proxy.AsyncProxy|null} the async proxy or null if not initialized + */ +export function getWorker(): AsyncProxy; - @param single key used to encrypt the message - @param text message as native JavaScript string - */ -export function encryptMessage(key: key.Key, message: string): Promise; +/** + * Cleanup the current instance of the web worker. + */ +export function destroyWorker(): void; -/** Generates a new OpenPGP key pair. Currently only supports RSA keys. Primary and subkey will be of same type. - @param options - */ -export function generateKeyPair(options: KeyOptions): Promise; +/** + * Encrypts message text/data with public keys, passwords or both at once. At least either public keys or passwords + * must be specified. If private keys are specified, those will be used to sign the message. + * @param {String|Uint8Array} data text/data to be encrypted as JavaScript binary string or Uint8Array + * @param {utf8|binary|text|mime} dataType (optional) data packet type + * @param {Key|Array} publicKeys (optional) array of keys or single key, used to encrypt the message + * @param {Key|Array} privateKeys (optional) private keys for signing. If omitted message will not be signed + * @param {String|Array} passwords (optional) array of passwords or a single password to encrypt the message + * @param {Object} sessionKey (optional) session key in the form: { data:Uint8Array, algorithm:String } + * @param {String} filename (optional) a filename for the literal data packet + * @param {module:enums.compression} compression (optional) which compression algorithm to compress the message with, defaults to what is specified in config + * @param {Boolean} armor (optional) if the return values should be ascii armored or the message/signature objects + * @param {Boolean} detached (optional) if the signature should be detached (if true, signature will be added to returned object) + * @param {Signature} signature (optional) a detached signature to add to the encrypted message + * @param {Boolean} returnSessionKey (optional) if the unencrypted session key should be added to returned object + * @param {Boolean} wildcard (optional) use a key ID of 0 instead of the public key IDs + * @param {Date} date (optional) override the creation date of the message and the message signature + * @param {Object} fromUserId (optional) user ID to sign with, e.g. { name:'Steve Sender', email:'steve@openpgp.org' } + * @param {Object} toUserId (optional) user ID to encrypt for, e.g. { name:'Robert Receiver', email:'robert@openpgp.org' } + * @returns {Promise} encrypted (and optionally signed message) in the form: + * {data: ASCII armored message if 'armor' is true, + * message: full Message object if 'armor' is false, signature: detached signature if 'detached' is true} + * @async + * @static + */ +export function encrypt(options: EncryptOptions): Promise; -/** Signs message text and encrypts it +/** + * Decrypts a message with the user's private key, a session key or a password. Either a private key, + * a session key or a password must be specified. + * @param {Message} message the message object with the encrypted data + * @param {Key|Array} privateKeys (optional) private keys with decrypted secret key data or session key + * @param {String|Array} passwords (optional) passwords to decrypt the message + * @param {Object|Array} sessionKeys (optional) session keys in the form: { data:Uint8Array, algorithm:String } + * @param {Key|Array} publicKeys (optional) array of public keys or single key, to verify signatures + * @param {String} format (optional) return data format either as 'utf8' or 'binary' + * @param {Signature} signature (optional) detached signature for verification + * @param {Date} date (optional) use the given date for verification instead of the current time + * @returns {Promise} decrypted and verified message in the form: + * { data:Uint8Array|String, filename:String, signatures:[{ keyid:String, valid:Boolean }] } + * @async + * @static + */ +export function decrypt(options: DecryptOptions): Promise; - @param publicKeys array of keys used to encrypt the message - @param privateKey private key with decrypted secret key data for signing - @param text private key with decrypted secret key data for signing - */ -export function signAndEncryptMessage(publicKeys: Array, privateKey: key.Key, text: string): Promise; -/** Signs message text and encrypts it +/** + * Generates a new OpenPGP key pair. Supports RSA and ECC keys. Primary and subkey will be of same type. + * @param {Array} userIds array of user IDs e.g. [{ name:'Phil Zimmermann', email:'phil@openpgp.org' }] + * @param {String} passphrase (optional) The passphrase used to encrypt the resulting private key + * @param {Number} numBits (optional) number of bits for RSA keys: 2048 or 4096. + * @param {Number} keyExpirationTime (optional) The number of seconds after the key creation time that the key expires + * @param {String} curve (optional) elliptic curve for ECC keys: + * curve25519, p256, p384, p521, secp256k1, + * brainpoolP256r1, brainpoolP384r1, or brainpoolP512r1. + * @param {Date} date (optional) override the creation date of the key and the key signatures + * @param {Array} subkeys (optional) options for each subkey, default to main key options. e.g. [{sign: true, passphrase: '123'}] + * sign parameter defaults to false, and indicates whether the subkey should sign rather than encrypt + * @returns {Promise} The generated key object in the form: + * { key:Key, privateKeyArmored:String, publicKeyArmored:String } + * @async + * @static + */ +export function generateKey(options: KeyOptions): Promise; - @param publicKeys single key used to encrypt the message - @param privateKey private key with decrypted secret key data for signing - @param text private key with decrypted secret key data for signing - */ -export function signAndEncryptMessage(publicKey: key.Key, privateKey: key.Key, text: string): Promise; +/** + * Reformats signature packets for a key and rewraps key object. + * @param {Key} privateKey private key to reformat + * @param {Array} userIds array of user IDs e.g. [{ name:'Phil Zimmermann', email:'phil@openpgp.org' }] + * @param {String} passphrase (optional) The passphrase used to encrypt the resulting private key + * @param {Number} keyExpirationTime (optional) The number of seconds after the key creation time that the key expires + * @returns {Promise} The generated key object in the form: + * { key:Key, privateKeyArmored:String, publicKeyArmored:String } + * @async + * @static + */ +export function reformatKey(options: { + privateKey: key.Key, + userIds?: UserId[], + passphrase?: string, + keyExpirationTime?: number, +}): Promise; -/** Signs a cleartext message - - @param privateKeys array of keys with decrypted secret key data to sign cleartext - @param text cleartext - */ -export function signClearMessage(privateKeys: Array, text: string): Promise; -/** Signs a cleartext message - - @param privateKeys single key with decrypted secret key data to sign cleartext - @param text cleartext - */ -export function signClearMessage(privateKey: key.Key, text: string): Promise; - -/** Verifies signatures of cleartext signed message - - @param publicKeys array of keys to verify signatures - @param msg cleartext message object with signatures - */ -export function verifyClearSignedMessage(publicKeys: Array, msg: cleartext.CleartextMessage): Promise; -/** Verifies signatures of cleartext signed message - - @param publicKeys single key to verify signatures - @param msg cleartext message object with signatures - */ -export function verifyClearSignedMessage(publicKey: key.Key, msg: cleartext.CleartextMessage): Promise; +/** + * Unlock a private key with your passphrase. + * @param {Key} privateKey the private key that is to be decrypted + * @param {String|Array} passphrase the user's passphrase(s) chosen during key generation + * @returns {Promise} the unlocked key object in the form: { key:Key } + * @async + */ +export function decryptKey(options: { + privateKey: key.Key, + passphrase?: string | string[], +}): Promise; +export function encryptKey(options: { + privateKey: key.Key, + passphrase?: string +}): Promise; export namespace armor { /** Armor an OpenPGP binary packet block @@ -471,6 +584,14 @@ export namespace message { @param armoredText text to be parsed */ function readArmored(armoredText: string): Message; + + /** + * reads an OpenPGP message as byte array and returns a message object + * @param {Uint8Array} input binary message + * @returns {Message} new message object + * @static + */ + function read(data: Uint8Array): Message; } export namespace packet { diff --git a/types/openpgp/openpgp-tests.ts b/types/openpgp/openpgp-tests.ts index fbe8a2e691..3bd3551d0b 100644 --- a/types/openpgp/openpgp-tests.ts +++ b/types/openpgp/openpgp-tests.ts @@ -2,11 +2,14 @@ var options: openpgp.KeyOptions = { numBits: 2048, - userId: 'Jon Smith ', + userIds: [{ + name: 'Jon Smith', + email: 'jon.smith@example.org', + }], passphrase: 'super long and hard to guess secret' }; -openpgp.generateKeyPair(options).then(function (keypair) { +openpgp.generateKey(options).then(function (keypair) { // success var privkey = keypair.privateKeyArmored; var pubkey = keypair.publicKeyArmored; @@ -18,14 +21,15 @@ openpgp.generateKeyPair(options).then(function (keypair) { var spubkey = '-----BEGIN PGP PUBLIC KEY BLOCK ... END PGP PUBLIC KEY BLOCK-----'; var publicKey = openpgp.key.readArmored(spubkey); -openpgp.encryptMessage(publicKey.keys, 'Hello, World!').then(function (pgpMessage) { +openpgp.encrypt({ + data: 'Hello, World!', + publicKeys: publicKey.keys +}).then(function (pgpMessage) { // success }).catch(function (error) { // failure }); - - var sprivkey = '-----BEGIN PGP PRIVATE KEY BLOCK ... END PGP PRIVATE KEY BLOCK-----'; var privateKey = openpgp.key.readArmored(sprivkey).keys[0]; privateKey.decrypt('passphrase'); @@ -33,7 +37,10 @@ privateKey.decrypt('passphrase'); var pgpMessageStr = '-----BEGIN PGP MESSAGE ... END PGP MESSAGE-----'; var pgpMessage = openpgp.message.readArmored(pgpMessageStr); -openpgp.decryptMessage(privateKey, pgpMessage).then(function (plaintext) { +openpgp.decrypt({ + privateKeys: privateKey, + message: pgpMessage +}).then(function (plaintext) { // success }).catch(function (error) { // failure @@ -44,35 +51,9 @@ openpgp.decryptMessage(privateKey, pgpMessage).then(function (plaintext) { var keyoptions: openpgp.KeyOptions; -var key= openpgp.key.generate(keyoptions); -var keys: Array; -var message = openpgp.message.readArmored(""); -var cleartextmessage = openpgp.cleartext.readArmored(""); var mpi: openpgp.crypto.Mpi; var mpis: Array; - -openpgp.decryptAndVerifyMessage(key, key, "").then(); -openpgp.decryptAndVerifyMessage(key, keys, "").then(); - -openpgp.decryptMessage(key, message).then(); - -openpgp.encryptMessage(key, "").then(); -openpgp.encryptMessage(keys, "").then(); - -openpgp.generateKeyPair(keyoptions).then(function (keypair) { - key = keypair.key; -}); - -openpgp.signAndEncryptMessage(key, key, "").then(); -openpgp.signAndEncryptMessage(keys, key, "").then(); - -openpgp.signClearMessage(key, "").then(); -openpgp.signClearMessage(keys, "").then(); - -openpgp.verifyClearSignedMessage(key, cleartextmessage); -openpgp.verifyClearSignedMessage(keys, cleartextmessage); - openpgp.armor.armor(openpgp.enums.armor.message, {}, 0, 1); openpgp.armor.dearmor("");