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.

Types

`class AssociatedData`	The context an envelope is bound to, serialized to bytes exactly one way.
`class KdfProfile`	The portable password key derivation this package uses, as a versioned profile rather than a set of numbers each caller picks.
`class KeyHandle`	A key you can use and cannot read.
`enum KeyUsage`	What a `KeyHandle` is allowed to do.
`enum Protection`	One protection a store or a key either has or does not have.
`class ProtectionReport`	What a store, a key or a vault actually provides, one `Protection` at a time.
`class SecureEnvelope`	The one encrypted-blob format this package writes, and the only one it reads.
`class 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.
`enum UnlockPolicy`	How a vault may be reopened, chosen by the application and explained to the user.
`class Vault`	A password-protected store an application opens once and then uses, without choosing a cipher, a nonce, a KDF or a wrapping scheme.
`class VaultCapabilities`	What this device can do, asked before an application offers the user a choice.
`enum VaultError`	Why a vault or protected-storage operation failed, as a code rather than a message.
`class VaultException`	The failure every vault and protected-storage operation reports, carrying a `VaultError` rather than only a message.
`class VaultOptions`	What a caller insists on when opening or enrolling a vault.