850f9f18c258efbd7a942de64c6ba869ce4abb35
[gpgme.git] / lang / js / src / Keyring.js
1 /* gpgme.js - Javascript integration for gpgme
2  * Copyright (C) 2018 Bundesamt für Sicherheit in der Informationstechnik
3  *
4  * This file is part of GPGME.
5  *
6  * GPGME is free software; you can redistribute it and/or modify it
7  * under the terms of the GNU Lesser General Public License as
8  * published by the Free Software Foundation; either version 2.1 of
9  * the License, or (at your option) any later version.
10  *
11  * GPGME is distributed in the hope that it will be useful, but
12  * WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this program; if not, see <https://www.gnu.org/licenses/>.
18  * SPDX-License-Identifier: LGPL-2.1+
19  *
20  * Author(s):
21  *     Maximilian Krambach <mkrambach@intevation.de>
22  */
23
24
25 import { createMessage } from './Message';
26 import { createKey } from './Key';
27 import { isFingerprint } from './Helpers';
28 import { gpgme_error } from './Errors';
29
30 /**
31  * This class offers access to the gnupg keyring
32  */
33 export class GPGME_Keyring {
34
35     /**
36      * Queries Keys (all Keys or a subset) from gnupg.
37      *
38      * @param {Object} options:
39      * @param {String | Array<String>} options.pattern (optional) A pattern to
40      * search for in userIds or KeyIds.
41      * @param {Boolean} options.prepare_sync (optional) if set to true, most
42      * data (with the exception of armored Key blocks) will be cached for the
43      * Keys. This enables direct, synchronous use of these properties for
44      * all keys. It does not check for changes on the backend. The cached
45      * information can be updated with the {@link Key.refresh} method.
46      * @param {Boolean} options.search (optional) retrieve Keys from external
47      * servers with the method(s) defined in gnupg (e.g. WKD/HKP lookup)
48      * @returns {Promise<GPGME_Key[]>}
49      * @static
50      * @async
51      */
52     getKeys ({ pattern, prepare_sync = false, search = false } = {}){
53         if (typeof arguments[0] !== 'object') {
54             return Promise.reject(gpgme_error('PARAM_WRONG'));
55         }
56         if (arguments.length && typeof arguments[0] !== 'object') {
57             return Promise.reject(gpgme_error('PARAM_WRONG'));
58         }
59         return new Promise(function (resolve, reject) {
60             let msg = createMessage('keylist');
61             if (pattern) {
62                 msg.setParameter('keys', pattern);
63             }
64             msg.setParameter('sigs', true);
65             if (search === true){
66                 msg.setParameter('locate', true);
67             }
68             msg.post().then(function (result){
69                 let resultset = [];
70                 if (result.keys.length === 0){
71                     resolve([]);
72                 } else {
73                     let secondrequest;
74                     if (prepare_sync === true) {
75                         secondrequest = function () {
76                             let msg2 = createMessage('keylist');
77                             if (pattern){
78                                 msg2.setParameter('keys', pattern);
79                             }
80                             msg2.setParameter('secret', true);
81                             return msg2.post();
82                         };
83                     } else {
84                         secondrequest = function () {
85                             return Promise.resolve(true);
86                         };
87                     }
88                     secondrequest().then(function (answer) {
89                         for (let i=0; i < result.keys.length; i++){
90                             if (prepare_sync === true){
91                                 if (answer && answer.keys) {
92                                     for (let j=0;
93                                         j < answer.keys.length; j++ ){
94                                         const a = answer.keys[j];
95                                         const b = result.keys[i];
96                                         if (
97                                             a.fingerprint === b.fingerprint
98                                         ) {
99                                             if (a.secret === true){
100                                                 b.hasSecret = true;
101                                             } else {
102                                                 b.hasSecret = false;
103                                             }
104                                             break;
105                                         }
106                                     }
107                                 }
108                             }
109                             let k = createKey(result.keys[i].fingerprint,
110                                 !prepare_sync, result.keys[i]);
111                             resultset.push(k);
112                         }
113                         resolve(resultset);
114                     }, function (error){
115                         reject(error);
116                     });
117                 }
118             });
119         });
120     }
121
122     /**
123      * @typedef {Object} exportResult The result of a getKeysArmored
124      * operation.
125      * @property {String} armored The public Key(s) as armored block. Note
126      * that the result is one armored block, and not a block per key.
127      * @property {Array<String>} secret_fprs (optional) list of
128      * fingerprints for those Keys that also have a secret Key available in
129      * gnupg. The secret key will not be exported, but the fingerprint can
130      * be used in operations needing a secret key.
131      */
132
133     /**
134      * Fetches the armored public Key blocks for all Keys matching the
135      * pattern (if no pattern is given, fetches all keys known to gnupg).
136      * @param {Object} options (optional)
137      * @param {String|Array<String>} options.pattern The Pattern to
138      * search for
139      * @param {Boolean} options.with_secret_fpr also return a list of
140      * fingerprints for the keys that have a secret key available
141      * @returns {Promise<exportResult>} Object containing the
142      * armored Key(s) and additional information.
143      * @static
144      * @async
145      */
146     getKeysArmored ({ pattern, with_secret_fpr }) {
147         return new Promise(function (resolve, reject) {
148             let msg = createMessage('export');
149             msg.setParameter('armor', true);
150             if (with_secret_fpr === true) {
151                 msg.setParameter('with-sec-fprs', true);
152             }
153             if (pattern){
154                 msg.setParameter('keys', pattern);
155             }
156             msg.post().then(function (answer){
157                 const result = { armored: answer.data };
158                 if (with_secret_fpr === true){
159                     if (answer.hasOwnProperty('sec-fprs')){
160                         result.secret_fprs = answer['sec-fprs'];
161                     } else {
162                         result.secret_fprs = [];
163                     }
164                 }
165                 resolve(result);
166             }, function (error){
167                 reject(error);
168             });
169         });
170     }
171
172     /**
173      * Returns the Key used by default in gnupg.
174      * (a.k.a. 'primary Key or 'main key').
175      * It looks up the gpg configuration if set, or the first key that
176      * contains a secret key.
177      *
178      * @returns {Promise<GPGME_Key>}
179      * @async
180      * @static
181      */
182     getDefaultKey (prepare_sync = false) {
183         let me = this;
184         return new Promise(function (resolve, reject){
185             let msg = createMessage('config_opt');
186             msg.setParameter('component', 'gpg');
187             msg.setParameter('option', 'default-key');
188             msg.post().then(function (resp){
189                 if (resp.option !== undefined
190                     && resp.option.hasOwnProperty('value')
191                     && resp.option.value.length === 1
192                     && resp.option.value[0].hasOwnProperty('string')
193                     && typeof (resp.option.value[0].string) === 'string'){
194                     me.getKeys({ pattern: resp.option.value[0].string,
195                         prepare_sync: true }).then(
196                         function (keys){
197                             if (keys.length === 1){
198                                 resolve(keys[0]);
199                             } else {
200                                 reject(gpgme_error('KEY_NO_DEFAULT'));
201                             }
202                         }, function (error){
203                             reject(error);
204                         });
205                 } else {
206                     let msg = createMessage('keylist');
207                     msg.setParameter('secret', true);
208                     msg.post().then(function (result){
209                         if (result.keys.length === 0){
210                             reject(gpgme_error('KEY_NO_DEFAULT'));
211                         } else {
212                             for (let i=0; i< result.keys.length; i++ ) {
213                                 if (
214                                     result.keys[i].invalid === false &&
215                                     result.keys[i].expired === false &&
216                                     result.keys[i].revoked === false &&
217                                     result.keys[i].can_sign === true
218                                 ) {
219                                     let k = createKey(
220                                         result.keys[i].fingerprint,
221                                         !prepare_sync,
222                                         result.keys[i]);
223                                     resolve(k);
224                                     break;
225                                 } else if (i === result.keys.length - 1){
226                                     reject(gpgme_error('KEY_NO_DEFAULT'));
227                                 }
228                             }
229                         }
230                     }, function (error){
231                         reject(error);
232                     });
233                 }
234             }, function (error){
235                 reject(error);
236             });
237         });
238     }
239
240     /**
241      * @typedef {Object} importResult The result of a Key update
242      * @property {Object} summary Numerical summary of the result. See the
243      * feedbackValues variable for available Keys values and the gnupg
244      * documentation.
245      * https://www.gnupg.org/documentation/manuals/gpgme/Importing-Keys.html
246      * for details on their meaning.
247      * @property {Array<importedKeyResult>} Keys Array of Object containing
248      * GPGME_Keys with additional import information
249      *
250      */
251
252     /**
253      * @typedef {Object} importedKeyResult
254      * @property {GPGME_Key} key The resulting key
255      * @property {String} status:
256      *  'nochange' if the Key was not changed,
257      *  'newkey' if the Key was imported in gpg, and did not exist
258      *    previously,
259      *  'change' if the key existed, but details were updated. For details,
260      *    Key.changes is available.
261      * @property {Boolean} changes.userId Changes in userIds
262      * @property {Boolean} changes.signature Changes in signatures
263      * @property {Boolean} changes.subkey Changes in subkeys
264      */
265
266     /**
267      * Import an armored Key block into gnupg. Note that this currently
268      * will not succeed on private Key blocks.
269      * @param {String} armored Armored Key block of the Key(s) to be
270      * imported into gnupg
271      * @param {Boolean} prepare_sync prepare the keys for synched use
272      * (see {@link getKeys}).
273      * @returns {Promise<importResult>} A summary and Keys considered.
274      * @async
275      * @static
276      */
277     importKey (armored, prepare_sync) {
278         let feedbackValues = ['considered', 'no_user_id', 'imported',
279             'imported_rsa', 'unchanged', 'new_user_ids', 'new_sub_keys',
280             'new_signatures', 'new_revocations', 'secret_read',
281             'secret_imported', 'secret_unchanged', 'skipped_new_keys',
282             'not_imported', 'skipped_v3_keys'];
283         if (!armored || typeof (armored) !== 'string'){
284             return Promise.reject(gpgme_error('PARAM_WRONG'));
285         }
286         let me = this;
287         return new Promise(function (resolve, reject){
288             let msg = createMessage('import');
289             msg.setParameter('data', armored);
290             msg.post().then(function (response){
291                 let infos = {};
292                 let fprs = [];
293                 let summary = {};
294                 for (let i=0; i < feedbackValues.length; i++ ){
295                     summary[feedbackValues[i]] =
296                         response.result[feedbackValues[i]];
297                 }
298                 if (!response.result.hasOwnProperty('imports') ||
299                     response.result.imports.length === 0
300                 ){
301                     resolve({ Keys:[],summary: summary });
302                     return;
303                 }
304                 for (let res=0; res<response.result.imports.length; res++){
305                     let result = response.result.imports[res];
306                     let status = '';
307                     if (result.status === 0){
308                         status = 'nochange';
309                     } else if ((result.status & 1) === 1){
310                         status = 'newkey';
311                     } else {
312                         status = 'change';
313                     }
314                     let changes = {};
315                     changes.userId = (result.status & 2) === 2;
316                     changes.signature = (result.status & 4) === 4;
317                     changes.subkey = (result.status & 8) === 8;
318                     // 16 new secret key: not implemented
319                     fprs.push(result.fingerprint);
320                     infos[result.fingerprint] = {
321                         changes: changes,
322                         status: status
323                     };
324                 }
325                 let resultset = [];
326                 if (prepare_sync === true){
327                     me.getKeys({ pattern: fprs, prepare_sync: true })
328                         .then(function (result){
329                             for (let i=0; i < result.length; i++) {
330                                 resultset.push({
331                                     key: result[i],
332                                     changes:
333                                         infos[result[i].fingerprint].changes,
334                                     status: infos[result[i].fingerprint].status
335                                 });
336                             }
337                             resolve({ Keys:resultset,summary: summary });
338                         }, function (error){
339                             reject(error);
340                         });
341                 } else {
342                     for (let i=0; i < fprs.length; i++) {
343                         resultset.push({
344                             key: createKey(fprs[i]),
345                             changes: infos[fprs[i]].changes,
346                             status: infos[fprs[i]].status
347                         });
348                     }
349                     resolve({ Keys:resultset,summary:summary });
350                 }
351
352             }, function (error){
353                 reject(error);
354             });
355
356
357         });
358
359
360     }
361
362     /**
363      * Convenience function for deleting a Key. See {@link Key#delete} for
364      * further information about the return values.
365      * @param {String} fingerprint
366      * @returns {Promise<Boolean>}
367      * @async
368      * @static
369      */
370     deleteKey (fingerprint){
371         if (isFingerprint(fingerprint) === true) {
372             let key = createKey(fingerprint);
373             return key.delete();
374         } else {
375             return Promise.reject(gpgme_error('KEY_INVALID'));
376         }
377     }
378
379     /**
380      * Generates a new Key pair directly in gpg, and returns a GPGME_Key
381      * representing that Key. Please note that due to security concerns,
382      * secret Keys can not be deleted or exported from inside gpgme.js.
383      * @param {Object} options
384      * @param {String} option.userId The user Id, e.g. 'Foo Bar <foo@bar.baz>'
385      * @param {String} option.algo (optional) algorithm (and optionally key
386      * size) to be used. See {@link supportedKeyAlgos} below for supported
387      * values. If ommitted, 'default' is used.
388      * @param {Number} option.expires (optional) Expiration time in seconds
389      * from now. If not set or set to 0, expiration will be 'never'
390      *
391      * @return {Promise<Key|GPGME_Error>}
392      * @async
393      */
394     generateKey ({ userId, algo = 'default', expires= 0 } = {}){
395         if (typeof userId !== 'string'
396             // eslint-disable-next-line no-use-before-define
397             || (algo && supportedKeyAlgos.indexOf(algo) < 0 )
398             || (!Number.isInteger(expires) || expires < 0 )
399         ){
400             return Promise.reject(gpgme_error('PARAM_WRONG'));
401         }
402         // eslint-disable-next-line no-use-before-define
403         let me = this;
404         return new Promise(function (resolve, reject){
405             let msg = createMessage('createkey');
406             msg.setParameter('userid', userId);
407             msg.setParameter('algo', algo);
408             msg.setParameter('expires', expires);
409             msg.post().then(function (response){
410                 me.getKeys({
411                     pattern: response.fingerprint,
412                     prepare_sync: true
413                 }).then(function (result){
414                     resolve(result);
415                 }, function (error){
416                     reject(error);
417                 });
418             }, function (error) {
419                 reject(error);
420             });
421         });
422     }
423 }
424
425
426 /**
427  * List of algorithms supported for key generation. Please refer to the gnupg
428  * documentation for details
429  */
430 const supportedKeyAlgos = [
431     'default', 'future-default',
432     'rsa', 'rsa2048', 'rsa3072', 'rsa4096',
433     'dsa', 'dsa2048', 'dsa3072', 'dsa4096',
434     'elg', 'elg2048', 'elg3072', 'elg4096',
435     'ed25519',
436     'cv25519',
437     'brainpoolP256r1', 'brainpoolP384r1', 'brainpoolP512r1',
438     'NIST P-256', 'NIST P-384', 'NIST P-521'
439 ];