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