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