121 lines
4.5 KiB
Text
121 lines
4.5 KiB
Text
/* -*- 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.
|
|
*
|
|
* NB: To first authenticate the user to the system, use
|
|
* nsIOSReauthenticator.
|
|
*
|
|
* Usage:
|
|
*
|
|
* // obtain the singleton OSKeyStore instance
|
|
* const oskeystore = Cc["@mozilla.org/security/oskeystore;1"].getService(Ci.nsIOSKeyStore);
|
|
*
|
|
* const PASSWORD_LABEL = "mylabel1";
|
|
*
|
|
* // 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);
|
|
*/
|
|
|
|
/**
|
|
* 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);
|
|
|
|
/**
|
|
* Retrieve the recovery phrase from the key store.
|
|
*
|
|
* @param aLabel The label of the secret to retrieve.
|
|
* @return Promise resolving to the recovery phrase or an error.
|
|
*/
|
|
[implicit_jscontext, must_use]
|
|
Promise asyncGetRecoveryPhrase(in ACString aLabel);
|
|
};
|