Package com.codename1.security.vault

package com.codename1.security.vault

Password-protected storage that works the same way on Android, iOS and in a browser, and that says what it does and does not protect.

Vault is the entry point: enroll with a password, unlock, store secrets, seal records, synchronise the encrypted state to another device. One random data key protects the contents and is itself stored only in wrapped form -- under the password, under a recovery code, and optionally under this device's key store so the user does not have to type the password again.

The browser is the reason this package exists. There is no key store in a page, and the previous answer -- a plain string in origin-private storage -- gave persistence and no protection. What a browser does have is AES-GCM through Web Crypto and a CryptoKey that can be marked non-extractable and kept in IndexedDB, and that is enough to make what is written to disk ciphertext under a key that cannot be copied out. It is not enough to hide anything from script running in the page, and nothing in this package claims otherwise: see the table on Vault and the field notes on Protection.

The pieces

• Vault -- the facade applications use.
• UnlockPolicy -- session only, remembered device, or gated on user verification.
• Protection and ProtectionReport -- independent capability flags with a real "cannot say" answer, rather than a security level.
• VaultError -- typed failures, including the distinction between a key that is missing and a key that could not be read.
• SecureEnvelope and AssociatedData -- the versioned authenticated format every port reads and writes, specified byte for byte.
• KdfProfile -- the portable password KDF and its bounds.
• KeyHandle -- a key you can use and cannot read.
• DeviceProtection -- the one piece each port implements.

Related Packages

Package	Description
com.codename1.security	Cryptographic primitives and conveniences: hashing, message authentication, symmetric/asymmetric encryption, digital signatures, JWTs, OTPs and random number generation.
com.codename1.security.vault.spi	The single extension point a port implements to take part in Vault.
com.codename1.security.hardening	Read-only reporting of Codename One App Hardening status for the current build.
com.codename1.security.shield	API shielding: attestation tokens, over-the-air certificate pinning, and runtime self-protection reporting.

Class	Description
AssociatedData	The context an envelope is bound to, serialized to bytes exactly one way.
KdfProfile	The portable password key derivation this package uses, as a versioned profile rather than a set of numbers each caller picks.
KeyHandle	A key you can use and cannot read.
KeyUsage	What a KeyHandle is allowed to do.
Protection	One protection a store or a key either has or does not have.
ProtectionReport	What a store, a key or a vault actually provides, one Protection at a time.
ProtectionReport.Builder	Accumulates the answers for a ProtectionReport.
SecureEnvelope	The one encrypted-blob format this package writes, and the only one it reads.
SecureStorageDeviceProtection	The DeviceProtection every port gets when it does not supply one of its own: a random wrapping key in SecureStorage, and AES-GCM performed in shared code.
UnlockPolicy	How a vault may be reopened, chosen by the application and explained to the user.
Vault	A password-protected store an application opens once and then uses, without choosing a cipher, a nonce, a KDF or a wrapping scheme.
VaultCapabilities	What this device can do, asked before an application offers the user a choice.
VaultError	Why a vault or protected-storage operation failed, as a code rather than a message.
VaultException	The failure every vault and protected-storage operation reports, carrying a VaultError rather than only a message.
VaultOptions	What a caller insists on when opening or enrolling a vault.