DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (3bdfb7bc00a0)

VCS Links

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