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
MapJSON.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.