From 0ebf5bdf043a27fd3dfb7f92e0cb63d88954c44d Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 03:47:29 +0200 Subject: Adding upstream version 115.8.0esr. Signed-off-by: Daniel Baumann --- security/manager/ssl/nsIOSKeyStore.idl | 144 +++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 security/manager/ssl/nsIOSKeyStore.idl (limited to 'security/manager/ssl/nsIOSKeyStore.idl') diff --git a/security/manager/ssl/nsIOSKeyStore.idl b/security/manager/ssl/nsIOSKeyStore.idl new file mode 100644 index 0000000000..478f852d2b --- /dev/null +++ b/security/manager/ssl/nsIOSKeyStore.idl @@ -0,0 +1,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 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; +}; -- cgit v1.2.3