CryptEnvelope class

Envelope seguro e versionado para dados cifrados — nunca serializa a chave.

Substituto recomendado para EncryptedPayload.toJson / EncryptedPayload.toBase64 quando o payload for persistido ou transmitido segundo o protocolo da aplicação. Não registre envelopes completos em logs. Use-o através da fachada AllCrypto, que gerencia a chave externamente.

Por que um novo formato

EncryptedPayload.toJson inclui o campo key — qualquer sistema que receba esse JSON/Base64 recebe também a chave e consegue decifrar o conteúdo. Esse formato legado nunca ofereceu confidencialidade contra quem possui o payload; ele só protege dados em repouso quando o próprio armazenamento é a fronteira de segurança (ex.: sandbox do app). Veja SECURITY.md para detalhes.

CryptEnvelope corrige isso: serializa apenas algoritmo, ciphertext, nonce/IV, tag e AAD. A chave nunca é serializada — deve ser fornecida externamente (keychain, flutter_secure_storage, variável de ambiente, KMS) no momento da decifragem.

Versionamento

version identifica o schema do envelope, independente da versão do pacote Dart. A versão atual é currentVersion (2). Payloads legados do EncryptedPayload (sem campo de versão, com chave embutida) são tratados como "v1" apenas para fins de migração — veja AllCrypto.migrateLegacy.

fromJson e fromBase64 rejeitam:

versão ausente ou diferente de currentVersion — ArgumentError;
algoritmo desconhecido — ArgumentError (via CryptAlgorithm.fromString);
JSON/Base64 malformado — FormatException.

Exemplo

final key = AllCrypto.generateKey();
final envelope = AllCrypto.encryptText('segredo', key: key);
final b64 = envelope.toBase64(); // NÃO contém a chave

final restored = CryptEnvelope.fromBase64(b64);
final texto = AllCrypto.decryptText(restored, key: key); // chave externa

Constructors

CryptEnvelope({int version = currentVersion, required CryptAlgorithm algorithm, required Uint8List ciphertext, required Uint8List nonce, Uint8List? tag, Uint8List? aad}): Cria um CryptEnvelope. Não aceita chave — por design, este tipo nunca carrega material de chave.
CryptEnvelope.fromBase64(String encoded): Reconstrói um CryptEnvelope a partir de uma string produzida por toBase64.
factory
CryptEnvelope.fromJson(Map<String, dynamic> json): Reconstrói um CryptEnvelope a partir de um Map JSON.
factory

Properties

aad → Uint8List: Dados autenticados adicionais. Uint8List(0) quando não houver AAD.
final
algorithm → CryptAlgorithm: Algoritmo usado na cifragem.
final
ciphertext → Uint8List: Dados cifrados.
final
hashCode → int: The hash code for this object.
no setterinherited
nonce → Uint8List: Nonce, IV ou bloco de contador inicial — mesma semântica de EncryptedPayload.nonce, depende do algoritmo.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
tag → Uint8List: Tag de autenticação (MAC). Vazia para AES-CBC/AES-CTR (não autenticados).
final
version → int: Versão do schema deste envelope específico.
final

Methods

noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toBase64() → String: Serializa o envelope completo como uma string Base64 única (JSON → UTF-8 → Base64). Nunca inclui a chave.
toJson() → Map<String, dynamic>: Serializa para Map<String, dynamic>. Nunca inclui chave.
toString() → String: A string representation of this object.
override

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Constants

currentVersion → const int: Versão atual do schema de envelope. Incrementada apenas quando o formato serializado muda de forma incompatível.