security/manager/ssl/nsIOSKeyStore.idl

   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 };