Skip to content

Commit

Permalink
Updating declarations of openpgpjs and adding sign and verify (Defini…
Browse files Browse the repository at this point in the history 
…telyTyped#31740)

* Updating declarations of openpgpjs for existing methods and adding sign and verify

* Fixing linter error

* Fixing compilation errors

* Making same changes to ts3.2 and fixing String/string typos

* Adding name to authors
  • Loading branch information
@ecamellini @weswigham
ecamellini authored and weswigham committed Dec 31, 2018
1 parent 09f738c commit 86d7939
Show file tree
Hide file tree
Showing 5 changed files with 379 additions and 31 deletions.
3 changes: 2 additions & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,5 +23,6 @@
"devDependencies": {
"dtslint": "github:Microsoft/dtslint#production",
"types-publisher": "github:Microsoft/types-publisher#production"
}
},
"dependencies": {}
}
179 changes: 164 additions & 15 deletions types/openpgp/index.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
// Errietta Kostala <https://github.com/errietta>
// Daniel Montesinos <https://github.com/damonpam>
// Carlos Villavicencio <https://github.com/po5i>
// Eric Camellini <https://github.com/ecamellini>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
// TypeScript Version: 2.2

Expand All @@ -27,6 +28,7 @@ export interface EncryptOptions {
sessionKey?: SessionKey,
compression?: enums.compression,
armor?: boolean,
streaming?: 'web' | 'node' | false
detached?: boolean,
signature?: Signature,
returnSessionKey?: boolean,
Expand All @@ -39,6 +41,8 @@ export interface EncryptOptions {
export interface EncryptedMessage {
data?: string,
message?: message.Message,
signature?: string | ReadableStream | Signature // TODO add NodeStream
sessionKey?: SessionKey
}

export interface DecryptOptions {
Expand All @@ -48,17 +52,35 @@ export interface DecryptOptions {
sessionKeys?: SessionKey | SessionKey[],
publicKeys?: key.Key | key.Key[],
format?: string,
streaming?: 'web' | 'node' | false,
signature?: Signature,
date?: Date,
}

export interface SignOptions {
message: message.Message,
privateKeys?: key.Key | key.Key[],
armor?: boolean,
streaming?: 'web' | 'node' | false,
detached?: boolean
date?: Date,
fromUserIds?: UserId[]
}

export interface SignedMessage {
signature?: string | ReadableStream | Signature, // TODO add NodeStream
data?: string | ReadableStream, // TODO add NodeStream
message?: message.Message
}

export interface KeyContainer {
key: key.Key,
}

export interface KeyPair extends KeyContainer {
privateKeyArmored: string,
publicKeyArmored: string
publicKeyArmored: string,
revocationCertificate: string
}

export interface KeyOptions {
Expand All @@ -77,13 +99,27 @@ export interface Keyid {

export interface Signature {
keyid: Keyid,
valid: boolean
valid: boolean,
verified?: boolean
}

export interface VerifyOptions {
message: message.Message,
publicKeys: key.Key | key.Key[],
streaming?: 'web' | 'node' | false,
signature?: Signature,
date?: Date
}

export interface VerifiedMessage {
data: Uint8Array | string,
data: Uint8Array | string | ReadableStream, // TODO add NodeStream
signatures: Array<Signature>,
}

export interface DecryptedMessage {
data: Uint8Array | string | ReadableStream, // TODO add NodeStream
signatures: Array<Signature>,
filename: string,
filename: string
}

export interface OpenPGPWorker {
Expand All @@ -98,7 +134,7 @@ export interface WorkerOptions {
path?: string,
n?: number,
workers?: OpenPGPWorker[],
config?: any,
config?: any
}

export class AsyncProxy {
Expand Down Expand Up @@ -140,16 +176,23 @@ export function destroyWorker(): void;
* @param {Object} sessionKey (optional) session key in the form: { data:Uint8Array, algorithm:String }
* @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 {'web'|'node'|false} streaming (optional) whether to return data as a stream. Defaults to the type of stream `message` was created from, if any.
* @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 {Date} date (optional) override the creation date of 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<Object>} 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}
* @returns {Promise<Object>} Object containing encrypted (and optionally signed) message in the form:
*
* {
* data: String|ReadableStream<String>|NodeStream, (if `armor` was true, the default)
* message: Message, (if `armor` was false)
* signature: String|ReadableStream<String>|NodeStream, (if `detached` was true and `armor` was true)
* signature: Signature (if `detached` was true and `armor` was false)
* sessionKey: { data, algorithm, aeadAlgorithm } (if `returnSessionKey` was true)
* }
* @async
* @static
*/
Expand All @@ -164,14 +207,79 @@ export function encrypt(options: EncryptOptions): Promise<EncryptedMessage>;
* @param {Object|Array<Object>} sessionKeys (optional) session keys in the form: { data:Uint8Array, algorithm:String }
* @param {Key|Array<Key>} 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 {'web'|'node'|false} streaming (optional) whether to return data as a stream. Defaults to the type of stream `message` was created from, if any.
* @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<Object>} decrypted and verified message in the form:
* { data:Uint8Array|String, filename:String, signatures:[{ keyid:String, valid:Boolean }] }
* @returns {Promise<Object>} Object containing decrypted and verified message in the form:
*
* {
* data: String|ReadableStream<String>|NodeStream, (if format was 'utf8', the default)
* data: Uint8Array|ReadableStream<Uint8Array>|NodeStream, (if format was 'binary')
* filename: String,
* signatures: [
* {
* keyid: module:type/keyid,
* verified: Promise<Boolean>,
* valid: Boolean (if streaming was false)
* }, ...
* ]
* }
* @async
* @static
*/
export function decrypt(options: DecryptOptions): Promise<VerifiedMessage>;
export function decrypt(options: DecryptOptions): Promise<DecryptedMessage>;

/**
* Signs a cleartext message.
* @param {CleartextMessage|Message} message (cleartext) message to be signed
* @param {Key|Array<Key>} privateKeys array of keys or single key with decrypted secret key data to sign cleartext
* @param {Boolean} armor (optional) if the return value should be ascii armored or the message object
* @param {'web'|'node'|false} streaming (optional) whether to return data as a stream. Defaults to the type of stream `message` was created from, if any.
* @param {Boolean} detached (optional) if the return value should contain a detached signature
* @param {Date} date (optional) override the creation date of the signature
* @param {Array} fromUserIds (optional) array of user IDs to sign with, one per key in `privateKeys`, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }]
* @returns {Promise<Object>} Object containing signed message in the form:
*
* {
* data: String|ReadableStream<String>|NodeStream, (if `armor` was true, the default)
* message: Message (if `armor` was false)
* }
*
* Or, if `detached` was true:
*
* {
* signature: String|ReadableStream<String>|NodeStream, (if `armor` was true, the default)
* signature: Signature (if `armor` was false)
* }
* @async
* @static
*/
export function sign(options: SignOptions): Promise<SignedMessage>;

/**
* Verifies signatures of cleartext signed message
* @param {Key|Array<Key>} publicKeys array of publicKeys or single key, to verify signatures
* @param {CleartextMessage|Message} message (cleartext) message object with signatures
* @param {'web'|'node'|false} streaming (optional) whether to return data as a stream. Defaults to the type of stream `message` was created from, if any.
* @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<Object>} Object containing verified message in the form:
*
* {
* data: String|ReadableStream<String>|NodeStream, (if `message` was a CleartextMessage)
* data: Uint8Array|ReadableStream<Uint8Array>|NodeStream, (if `message` was a Message)
* signatures: [
* {
* keyid: module:type/keyid,
* verified: Promise<Boolean>,
* valid: Boolean (if `streaming` was false)
* }, ...
* ]
* }
* @async
* @static
*/
export function verify(options: VerifyOptions): Promise<VerifiedMessage>;

/**
* Generates a new OpenPGP key pair. Supports RSA and ECC keys. Primary and subkey will be of same type.
Expand All @@ -186,7 +294,7 @@ export function decrypt(options: DecryptOptions): Promise<VerifiedMessage>;
* @param {Array<Object>} 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<Object>} The generated key object in the form:
* { key:Key, privateKeyArmored:String, publicKeyArmored:String }
* { key:Key, privateKeyArmored:String, publicKeyArmored:String, revocationCertificate:String }
* @async
* @static
*/
Expand All @@ -198,8 +306,9 @@ export function generateKey(options: KeyOptions): Promise<KeyPair>;
* @param {Array<Object>} 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
* @param {Boolean} revocationCertificate (optional) Whether the returned object should include a revocation certificate to revoke the public key
* @returns {Promise<Object>} The generated key object in the form:
* { key:Key, privateKeyArmored:String, publicKeyArmored:String }
* { key:Key, privateKeyArmored:String, publicKeyArmored:String, revocationCertificate:String }
* @async
* @static
*/
Expand All @@ -208,6 +317,29 @@ export function reformatKey(options: {
userIds?: UserId[],
passphrase?: string,
keyExpirationTime?: number,
revocationCertificate?: boolean
}): Promise<KeyPair>;

/**
* Revokes a key. Requires either a private key or a revocation certificate.
* If a revocation certificate is passed, the reasonForRevocation parameters will be ignored.
* @param {Key} key (optional) public or private key to revoke
* @param {String} revocationCertificate (optional) revocation certificate to revoke the key with
* @param {Object} reasonForRevocation (optional) object indicating the reason for revocation
* @param {module:enums.reasonForRevocation} reasonForRevocation.flag (optional) flag indicating the reason for revocation
* @param {String} reasonForRevocation.string (optional) string explaining the reason for revocation
* @returns {Promise<Object>} The revoked key object in the form:
* { privateKey:Key, privateKeyArmored:String, publicKey:Key, publicKeyArmored:String }
* (if private key is passed) or { publicKey:Key, publicKeyArmored:String } (otherwise)
* @static
*/
export function revokeKey(options: {
key?: key.Key,
revocationCertificate?: string
reasonForRevocation?: {
flag: enums.reasonForRevocation,
'string': string
},
}): Promise<KeyPair>;

/**
Expand All @@ -222,11 +354,20 @@ export function decryptKey(options: {
passphrase?: string | string[],
}): Promise<KeyContainer>;

/**
* Lock a private key with your passphrase.
* @param {Key} privateKey the private key that is to be decrypted
* @param {String|Array<String>} passphrase the user's passphrase(s) chosen during key generation
* @returns {Promise<Object>} the locked key object in the form: { key:Key }
* @async
*/
export function encryptKey(options: {
privateKey: key.Key,
passphrase?: string
passphrase?: string | string[],
}): Promise<KeyContainer>;

// TODO add typings for encryptSessionKey and decryptSessionKeys

export namespace armor {
/** Armor an OpenPGP binary packet block
Expand Down Expand Up @@ -485,6 +626,14 @@ export namespace enums {
valid,
no_self_cert
}

enum reasonForRevocation {
no_reason,
key_superseded,
key_compromised,
key_retired,
userid_invalid
}
}

export namespace key {
Expand Down
25 changes: 25 additions & 0 deletions types/openpgp/openpgp-tests.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,31 @@ openpgp.initWorker({ path:'openpgp.worker.js' });
})();


(async () => {
const publicKey = (await openpgp.key.readArmored(spubkey))
const privateKey = (await openpgp.key.readArmored(sprivkey))
const signOptions: openpgp.SignOptions = {
message: openpgp.message.fromText('hello world'),
privateKeys: privateKey.keys,
detached: true
};

const signed = await openpgp.sign(signOptions);

const signature = signed.signature as openpgp.Signature;
const message = signed.message;

const verifyOptions: openpgp.VerifyOptions = {
message,
signature,
publicKeys: publicKey.keys
};

let verified = await openpgp.verify(verifyOptions);

return verified.signatures[0].valid;
})();

// Open PGP Tests


Expand Down
Loading

0 comments on commit 86d7939

Please sign in to comment.