summaryrefslogtreecommitdiffstats
path: root/security/manager/ssl/nsIOSKeyStore.idl
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
commit26a029d407be480d791972afb5975cf62c9360a6 (patch)
treef435a8308119effd964b339f76abb83a57c29483 /security/manager/ssl/nsIOSKeyStore.idl
parentInitial commit. (diff)
downloadfirefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz
firefox-26a029d407be480d791972afb5975cf62c9360a6.zip
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'security/manager/ssl/nsIOSKeyStore.idl')
-rw-r--r--security/manager/ssl/nsIOSKeyStore.idl112
1 files changed, 112 insertions, 0 deletions
diff --git a/security/manager/ssl/nsIOSKeyStore.idl b/security/manager/ssl/nsIOSKeyStore.idl
new file mode 100644
index 0000000000..1306ba4ae1
--- /dev/null
+++ b/security/manager/ssl/nsIOSKeyStore.idl
@@ -0,0 +1,112 @@
+/* -*- 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);
+};