1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "nsISupports.idl"
[scriptable, uuid(57972956-5718-42d2-8070-b3fc72212eaf)]
interface nsIOSKeyStore: nsISupports {
/**
* This interface provides encryption and decryption operations for data at
* rest. The key used to encrypt and decrypt the data is stored in the OS
* key store.
*
* Usage:
*
* // obtain the singleton OSKeyStore instance
* const oskeystore = Cc["@mozilla.org/security/oskeystore;1"].getService(Ci.nsIOSKeyStore);
*
* const PASSWORD_LABEL = "mylabel1";
* const COOKIE_LABEL = "mylabel2";
*
* // Unlock the key store.
* // Note that this is not necesssary. The key store will be unlocked
* // automatically when an operation is performed on it.
* await oskeystore.asyncUnlock();
*
* // Check if there's a secret for your label already.
* if (!await oskeystore.asyncSecretAvailable(PASSWORD_LABEL)) {
* // Fail or generate a new secret for your label.
* // If you want to generate a new secret, do.
* // Hold onto `recoveryPhrase` to present to the user.
* let recoveryPhrase = await oskeystore.asyncGenerateSecret(PASSWORD_LABEL);
* }
*
* // Assuming there's a secret with your label. Encrypt/Decrypt as follows.
* let encryptedPasswordBytes = await oskeystore.asyncEncryptBytes(PASSWORD_LABEL, passwordBytes);
* let newPasswordBytes = await oskeystore.asyncDecryptBytes(PASSWORD_LABEL, encryptedPasswordBytes);
*
* // Delete the secret from the key store.
* await oskeystore.asyncDeleteSecret(PASSWORD_LABEL);
*
* // Recover a secret from a recovery code.
* await oskeystore.asyncRecoverSecret(PASSWORD_LABEL, recoveryPhrase);
*
* // Lock the key store to prompt the user to log into her OS key store again.
* await oskeystore.asyncLock();
*/
/**
* Generate a new secret and store it in the OS key store with the given label.
* The caller should make sure that no other secrets with the same label are
* present before calling this function.
* This invalidates all previous ciphertexts created with the key
* corresponding to the given label.
*
* @param label The label to use for the secret.
* @return Promise that resolves to the recoveryPhrase string used to generate
* the secret.
*/
[implicit_jscontext, must_use]
Promise asyncGenerateSecret(in ACString label);
/**
* Check whether a secret for a given label exists.
*
* @param label The label to lookup.
* @return Promise that resolves to a bool (whether a secret with label is
* known or not) or an error.
*/
[implicit_jscontext, must_use]
Promise asyncSecretAvailable(in ACString label);
/**
* Set a secret from a given recovery phrase.
* This might not be implemented on all platforms.
* This invalidates all previous ciphertexts.
*
* @param label The label to use for the secret.
* @param recoveryPhrase The recovery phrase that's used to generate the secret.
* @return Promise that resolves to undefined or an error.
*/
[implicit_jscontext, must_use]
Promise asyncRecoverSecret(in ACString label, in ACString recoveryPhrase);
/**
* Delete secret with a given label. If there is no secret with the given
* label, no action is taken.
*
* @param label The label of the secret to delete.
* @return Promise that resolves to undefined or an error.
*/
[implicit_jscontext, must_use]
Promise asyncDeleteSecret(in ACString label);
/**
* Encrypt the given data and then return the result as a base64-encoded
* string.
*
* @param label The label of the key to use to encrypt.
* @param inBytes The bytes to encrypt.
* @return Promise resolving to the encrypted text, encoded as Base64, or an
* error.
*/
[implicit_jscontext, must_use]
Promise asyncEncryptBytes(in ACString label, in Array<uint8_t> inBytes);
/**
* Decode and then decrypt the given base64-encoded string.
*
* @param label The label of the key to use to decrypt.
* @param encryptedBase64Text Encrypted input text, encoded as Base64.
* @return Promise resolving to the plaintext bytes or an error.
*/
[implicit_jscontext, must_use]
Promise asyncDecryptBytes(in ACString label, in ACString encryptedBase64Text);
/**
* Lock the key store.
* The actual behaviour of this depends on the OS.
*
* @return Promise resolving to undefined or an error.
*/
[implicit_jscontext, must_use]
Promise asyncLock();
/**
* Unlock the key store.
* The actual behaviour of this depends on the OS.
*
* @return Promise resolving to undefined or an error.
*/
[implicit_jscontext, must_use]
Promise asyncUnlock();
/**
* Check if the implementation is using the NSS key store.
* This is a special case because Firefox has to handle the locking and
* unlocking.
*/
readonly attribute bool isNSSKeyStore;
};
|
