diff --git a/pem/index.d.ts b/pem/index.d.ts index 8a5f71b729..c523fb8fa7 100644 --- a/pem/index.d.ts +++ b/pem/index.d.ts @@ -1,155 +1,265 @@ -// Type definitions for PEM v1.8.3 +// Type definitions for PEM 1.9 // Project: https://github.com/andris9/pem -// Definitions by: Anthony Trinh +// Definitions by: Anthony Trinh , Ruslan Arkhipau // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped -declare module "pem" { +interface ModuleConfiguration { /** - * Creates a private key - * - * @param {Number} [keyBitsize=2048] Size of the key, defaults to 2048bit (can also be a function) - * @param {Object} [options] object of cipher and password {cipher:'aes128',password:'xxx'}, defaults empty object - * @param {Function} callback Callback function with an error object and {key} + * Path to OpenSSL binaries */ - function createPrivateKey(keyBitsize: Number, options: Object, callback: Function): void; - function createPrivateKey(keyBitsize: Number, callback: Function): void; - function createPrivateKey(options: Object, callback: Function): void; - function createPrivateKey(callback: Function): void; - - /** - * Creates a dhparam key - * - * @param {Number} [keyBitsize=512] Size of the key, defaults to 512bit - * @param {Function} callback Callback function with an error object and {dhparam} - */ - function createDhparam(keyBitsize: Number, callback: Function): void; - function createDhparam(callback: Function): void; - - /** - * Creates a Certificate Signing Request - * - * If client key is undefined, a new key is created automatically. The used key is included - * in the callback return as clientKey - * - * @param {Object} [options] Optional options object - * @param {String} [options.clientKey] Optional client key to use - * @param {Number} [options.keyBitsize] If clientKey is undefined, bit size to use for generating a new key (defaults to 2048) - * @param {String} [options.hash] Hash function to use (either md5 sha1 or sha256, defaults to sha256) - * @param {String} [options.country] CSR country field - * @param {String} [options.state] CSR state field - * @param {String} [options.locality] CSR locality field - * @param {String} [options.organization] CSR organization field - * @param {String} [options.organizationUnit] CSR organizational unit field - * @param {String} [options.commonName='localhost'] CSR common name field - * @param {String} [options.emailAddress] CSR email address field - * @param {String} [options.csrConfigFile] CSR config file - * @param {Array} [options.altNames] is a list of subjectAltNames in the subjectAltName field - * @param {Function} callback Callback function with an error object and {csr, clientKey} - */ - function createCSR(options: Object, callback: Function): void; - function createCSR(callback: Function): void; - - /** - * Creates a certificate based on a CSR. If CSR is not defined, a new one - * will be generated automatically. For CSR generation all the options values - * can be used as with createCSR. - * - * @param {Object} [options] Optional options object - * @param {String} [options.serviceKey] Private key for signing the certificate, if not defined a new one is generated - * @param {String} [options.serviceKeyPassword] Password of the service key - * @param {Boolean} [options.selfSigned] If set to true and serviceKey is not defined, use clientKey for signing - * @param {String} [options.hash] Hash function to use (either md5 sha1 or sha256, defaults to sha256) - * @param {String} [options.csr] CSR for the certificate, if not defined a new one is generated - * @param {Number} [options.days] Certificate expire time in days - * @param {String} [options.clientKeyPassword] Password of the client key - * @param {String} [options.extFile] extension config file - without '-extensions v3_req' - * @param {String} [options.config] extension config file - with '-extensions v3_req' - * @param {Function} callback Callback function with an error object and {certificate, csr, clientKey, serviceKey} - */ - function createCertificate(options: Object, callback: Function): void; - function createCertificate(callback: Function): void; - - /** - * Reads subject data from a certificate or a CSR - * - * @param {String} certificate PEM encoded CSR or certificate - * @param {Function} callback Callback function with an error object and {country, state, locality, organization, organizationUnit, commonName, emailAddress} - */ - function readCertificateInfo(certificate: string, callback: Function): void; - function readCertificateInfo(callback: Function): void; - - /** - * Exports a public key from a private key, CSR or certificate - * - * @param {String} certificate PEM encoded private key, CSR or certificate - * @param {Function} callback Callback function with an error object and {publicKey} - */ - function getPublicKey(certificate: string, callback: Function): void; - function getPublicKey(callback: Function): void; - - /** - * Gets the fingerprint for a certificate - * - * @param {String} certificate PEM encoded certificate - * @param {String} hash Hash function to use (either md5 sha1 or sha256, defaults to sha256) - * @param {Function} callback Callback function with an error object and {fingerprint} - */ - function getFingerprint(certificate: string, hash: string, callback: Function): void; - function getFingerprint(certificate: string, callback: Function): void; - function getFingerprint(callback: Function): void; - - /** - * Gets the modulus from a certificate, a CSR or a private key - * - * @param {String} certificate PEM encoded, CSR PEM encoded, or private key - * @param {String} password password for the certificate - * @param {Function} callback Callback function with an error object and {modulus} - */ - function getModulus(certificate: string, password: string, callback: Function): void; - function getModulus(certificate: string, callback: Function): void; - - /** - * Gets the size and prime of DH parameters - * - * @param {String} dh DH parameters PEM encoded - * @param {Function} callback Callback function with an error object and {size, prime} - */ - function getDhparamInfo(dh: string, callback: Function): void; - - /** - * Exports private key and certificate to a PKCS12 keystore - * - * @param {String} key PEM encoded private key - * @param {String} certificate PEM encoded certificate - * @param {String} password Password of the result PKCS12 file - * @param {Object} [options] object of cipher and optional client key password {cipher:'aes128', clientKeyPassword: 'xxx'} - * @param {Function} callback Callback function with an error object and {pkcs12} - */ - function createPkcs12(key: string, certificate: string, password: string, options: Object, callback: Function): void; - function createPkcs12(key: string, certificate: string, password: string, callback: Function): void; - - /** - * Reads private key and certificate from a PKCS12 keystore - * @param {String} bufferOrPath - * @param {Object} [options] object of cipher and optional client key password {cipher:'aes128', clientKeyPassword: 'xxx'} - * @param {Function} callback Callback function with an error object and {pkcs12} - * @returns the result of the callback - */ - function readPkcs12(bufferOrPath: string, options: Object, callback: Function): any; - function readPkcs12(options: Object, callback: Function): any; - - /** - * Verifies the signing chain of the passed certificate - * - * @param {String} certificate PEM encoded certificate - * @param {Array} ca List of CA certificates - * @param {Function} callback Callback function with an error object and a boolean valid - */ - function verifySigningChain(certificate: string, ca: Array, callback: Function): void; - - /** - * config the pem module - * @param {Object} options - */ - function config(options: Object): void; + pathOpenSSL: string; } + +export type PrivateKeyCipher = "aes128" | "aes192" | "aes256" | "camellia128" | "camellia192" | "camellia256" | "des" | "des3" | "idea" | string; // allow for additions in future + +interface PrivateKeyCreationOptions { + cipher: PrivateKeyCipher; + password: string; +} + +interface Pkcs12CreationOptions { + cipher?: PrivateKeyCipher; + clientKeyPassword?: string; + certFiles?: string[]; +} + +interface Pkcs12ReadOptions { + p12Password?: string; + clientKeyPassword?: string; +} + +export type HashFunction = 'md5' | 'sha1' | 'sha256' | string; +interface CSRCreationOptions { + /** + * Optional client key to use + */ + clientKey?: string; + clientKeyPassword?: string; + /** + * If clientKey is undefined, bit size to use for generating a new key (defaults to 2048) + */ + keyBitsize?: number; + /** + * Hash function to use, defaults to sha256 + */ + hash?: HashFunction; + /** + * CSR country field + */ + country?: string; + /** + * CSR state field + */ + state?: string; + /** + * CSR locality field + */ + locality?: string; + /** + * CSR organization field + */ + organization?: string; + /** + * CSR organizational unit field + */ + organizationUnit?: string; + /** + * CSR common name field, defaults to 'localhost' + */ + commonName?: string; + /** + * CSR email address field + */ + emailAddress?: string; + /** + * CSR config file + */ + csrConfigFile?: string; + /** + * A list of subjectAltNames in the subjectAltName field + */ + altNames?: string[]; +} + +interface CertificateCreationOptions extends CSRCreationOptions { + /** + * Private key for signing the certificate, if not defined a new one is generated + */ + serviceKey?: string; + /** + * Password of the service key + */ + serviceKeyPassword?: string; + serviceCertificate?: any; + serial?: any; + /** + * If set to true and serviceKey is not defined, use clientKey for signing + */ + selfSigned?: boolean; + /** + * CSR for the certificate, if not defined a new one is generated from the provided parameters + */ + csr?: string; + /** + * Certificate expire time in days, defaults to 365 + */ + days?: number; + /** + * Password of the client key + */ + clientKeyPassword?: string; + /** + * extension config file - without '-extensions v3_req' + */ + extFile?: string; + /** + * extension config file - with '-extensions v3_req' + */ + config?: string; +} + +interface CertificateCreationResult { + certificate: any; + csr: string; + clientKey: string; + serviceKey: string; +} + +interface CertificateSubjectReadResult { + country: string; + state: string; + locality: string; + organization: string; + organizationUnit: string; + commonName: string; + emailAddress: string; +} + +type Callback = (error: any, result: T) => any; + +/** + * Creates a private key + * + * @param {number} [keyBitsize=2048] Size of the key, defaults to 2048bit (can also be a function) + * @param {PrivateKeyCreationOptions} [options] private key encryption settings, defaults to empty object (no enryption) + * @param {Callback<{ key: string }>} callback Callback function with an error object and {key} + */ +declare function createPrivateKey(keyBitsize: number, options: PrivateKeyCreationOptions, callback: Callback<{ key: string }>): void; +declare function createPrivateKey(optionsOrKeyBitsize: number | PrivateKeyCreationOptions, callback: Callback<{ key: string }>): void; +declare function createPrivateKey(callback: Callback<{ key: string }>): void; + +/** + * Creates a dhparam key + * + * @param {Number} [keyBitsize=512] Size of the key, defaults to 512bit + * @param {Callback<{ dhparam: any }>} callback Callback function with an error object and {dhparam} + */ +declare function createDhparam(keyBitsize: number, callback: Callback<{ dhparam: any }>): void; +declare function createDhparam(callback: Callback<{ dhparam: any }>): void; + +/** + * Creates a Certificate Signing Request + * + * If options.clientKey is undefined, a new key is created automatically. The used key is included + * in the callback return as clientKey + * + * @param {CSRCreationOptions} [options] Optional options object + * @param {Callback<{ csr: string, clientKey: string }>} callback Callback function with an error object and {csr, clientKey} + */ +declare function createCSR(options: CSRCreationOptions, callback: Callback<{ csr: string, clientKey: string }>): void; +declare function createCSR(callback: Callback<{ csr: string, clientKey: string }>): void; + +/** + * Creates a certificate based on a CSR. If CSR is not defined, a new one + * will be generated automatically. For CSR generation all the options values + * can be used as with createCSR. + * + * @param {Object} [CertificateCreationOptions] Optional options object + * @param {Callback} callback Callback function with an error object and {certificate, csr, clientKey, serviceKey} + */ +declare function createCertificate(options: CertificateCreationOptions, callback: Callback): void; +declare function createCertificate(callback: Callback): void; + +/** + * Reads subject data from a certificate or a CSR + * + * @param {String} certificate PEM encoded CSR or certificate + * @param {Callback} callback Callback function with an error object and {country, state, locality, organization, organizationUnit, commonName, emailAddress} + */ +declare function readCertificateInfo(certificate: string, callback: Callback): void; +declare function readCertificateInfo(callback: Callback): void; + +/** + * Exports a public key from a private key, CSR or certificate + * + * @param {String} certificate PEM encoded private key, CSR or certificate + * @param {Callback<{ publicKey: string }>} callback Callback function with an error object and {publicKey} + */ +declare function getPublicKey(certificate: string, callback: Callback<{ publicKey: string }>): void; +declare function getPublicKey(callback: Callback<{ publicKey: string }>): void; + +/** + * Gets the fingerprint for a certificate + * + * @param {String} certificate PEM encoded certificate + * @param {HashFunction} hash Hash function to use (either md5 sha1 or sha256, defaults to sha256) + * @param {Callback<{ fingerprint: string }>} callback Callback function with an error object and {fingerprint} + */ +declare function getFingerprint(certificate: string, hash: HashFunction, callback: Callback<{ fingerprint: string }>): void; +declare function getFingerprint(certificate: string, callback: Callback<{ fingerprint: string }>): void; +declare function getFingerprint(callback: Callback<{ fingerprint: string }>): void; + +/** + * Gets the modulus from a certificate, a CSR or a private key + * + * @param {String} certificate PEM encoded, CSR PEM encoded, or private key + * @param {String} password password for the certificate + * @param {Callback<{ modulus: any }>} callback Callback function with an error object and {modulus} + */ +declare function getModulus(certificate: string, password: string, callback: Callback<{ modulus: any }>): void; +declare function getModulus(certificate: string, callback: Callback<{ modulus: any }>): void; + +/** + * Gets the size and prime of DH parameters + * + * @param {String} dh DH parameters PEM encoded + * @param {Callback<{ size: any, prime: any }>} callback Callback function with an error object and {size, prime} + */ +declare function getDhparamInfo(dh: string, callback: Callback<{ size: any, prime: any }>): void; + +/** + * Exports private key and certificate to a PKCS12 keystore + * + * @param {String} key PEM encoded private key + * @param {String} certificate PEM encoded certificate + * @param {String} password Password of the result PKCS12 file + * @param {Pkcs12CreationOptions} [options] object of cipher and optional client key password {cipher:'aes128', clientKeyPassword: 'xxx'} + * @param {Callback<{ pkcs12: any }>} callback Callback function with an error object and {pkcs12} + */ +declare function createPkcs12(key: string, certificate: string, password: string, options: Pkcs12CreationOptions, callback: Callback<{ pkcs12: any }>): void; +declare function createPkcs12(key: string, certificate: string, password: string, callback: Callback<{ pkcs12: any }>): void; + +/** + * Reads private key and certificate from a PKCS12 keystore + * @param {String} bufferOrPath + * @param {Pkcs12ReadOptions} [options] + * @param {Function} callback Callback function with an error object and {pkcs12} + * @returns the result of the callback + */ +declare function readPkcs12(bufferOrPath: string, options: Pkcs12ReadOptions, callback: Callback<{ pkcs12: any }>): any; +declare function readPkcs12(bufferOrPath: string, callback: Callback<{ pkcs12: any }>): any; + +/** + * Verifies the signing chain of the passed certificate + * + * @param {String} certificate PEM encoded certificate + * @param {string[]} ca List of CA certificates + * @param {Function} callback Callback function with an error object and a boolean valid + */ +declare function verifySigningChain(certificate: string, ca: string[], callback: Callback): void; + +/** + * config the pem module + * @param {ModuleConfiguration} options + */ +declare function config(options: ModuleConfiguration): void; diff --git a/pem/tslint.json b/pem/tslint.json new file mode 100644 index 0000000000..377cc837d4 --- /dev/null +++ b/pem/tslint.json @@ -0,0 +1 @@ +{ "extends": "../tslint.json" }