AesGcm class abstract

AES-GCM (Galois/Counter Mode) Cipher.

In browsers, the default implementation will use Web Cryptography API. On other platforms, DartAesGcm will be used.

If you use Flutter, you can enable cryptography_flutter. It can improve performance in many cases.

Things to know

  • Three possible key lengths:
  • AES-GCM takes a 128-bit "nonce" block as a parameter. It is split into a random part and block counter. In our implementation, the random part is 96 bits by default, which means the block counter is 32 bits. When block counter is 32 bits, the maximum size of a message is block_size * 2^32 = 32 GB. If you need longer messages, use a smaller nonce.
  • AES-GCM standard specifies a MAC algorithm ("GCM"). The output is a 128-bit Mac.

Example

import 'package:cryptography/cryptography.dart';

Future<void> main() async {
  final message = <int>[1,2,3];

  final algorithm = AesGcm.with128bits();
  final secretKey = await algorithm.newSecretKey();
  final nonce = algorithm.newNonce();

  // Encrypt
  final secretBox = await algorithm.encrypt(
    message,
    secretKey: secretKey,
    nonce: nonce,
  );
  print('Nonce: ${secretBox.nonce}')
  print('Ciphertext: ${secretBox.cipherText}')
  print('MAC: ${secretBox.mac.bytes}')

  // Decrypt
  final clearText = await algorithm.encrypt(
    secretBox,
    secretKey: secretKey,
  );
  print('Cleartext: $clearText');
}
Inheritance
Implementers

Constructors

AesGcm.constructor({Random? random})
Constructor for classes that extend this class.
const
AesGcm.with128bits({int nonceLength = AesGcm.defaultNonceLength})
factory
AesGcm.with192bits({int nonceLength = AesGcm.defaultNonceLength})
factory
AesGcm.with256bits({int nonceLength = AesGcm.defaultNonceLength})
factory

Properties

hashCode → int
The hash code for this object.
no setteroverride
macAlgorithm → MacAlgorithm
Message authentication code (MacAlgorithm) used by the cipher.
no setteroverride
nonceLength → int
Number of bytes in the nonce ("Initialization Vector", "IV", "salt").
no setteroverride
random → Random?
Random number generator used by newSecretKey for generating secret keys.
finalinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
secretKeyLength → int
Number of bytes in the SecretKey.
no setterinherited

Methods

checkParameters({int? length, required SecretKey secretKey, required int nonceLength, int aadLength = 0, int keyStreamIndex = 0}) → void
Checks parameters for encrypt / decrypt and throws ArgumentError if any is invalid.
inherited
cipherTextLength(int clearTextLength) → int
Calculates the length of the ciphertext given a clear text length.
inherited
decrypt(SecretBox secretBox, {required SecretKey secretKey, List<int> aad = const <int>[], Uint8List? possibleBuffer}) → Future<List<int>>
Decrypts SecretBox and returns the bytes.
inherited
decryptStream(Stream<List<int>> stream, {required SecretKey secretKey, required List<int> nonce, required FutureOr<Mac> mac, List<int> aad = const [], bool allowUseSameBytes = false}) → Stream<List<int>>
Decrypts a Stream of bytes.
inherited
decryptString(SecretBox secretBox, {required SecretKey secretKey}) → Future<String>
Calls decrypt and then converts the bytes to a string by using utf8 codec.
inherited
encrypt(List<int> clearText, {required SecretKey secretKey, List<int>? nonce, List<int> aad = const <int>[], Uint8List? possibleBuffer}) → Future<SecretBox>
Encrypts bytes and returns SecretBox.
inherited
encryptStream(Stream<List<int>> stream, {required SecretKey secretKey, required List<int> nonce, required void onMac(Mac mac), List<int> aad = const [], bool allowUseSameBytes = false}) → Stream<List<int>>
Encrypts a Stream of bytes.
inherited
encryptString(String clearText, {required SecretKey secretKey}) → Future<SecretBox>
Converts a string to bytes using utf8 codec and then calls encrypt.
inherited
newCipherWand() → Future<CipherWand>
Constructs a CipherWand that uses this implementation and a new random secret key (that can't be extracted).
inherited
newCipherWandFromSecretKey(SecretKey secretKey, {bool allowEncrypt = true, bool allowDecrypt = true}) → Future<CipherWand>
Constructs a CipherWand that uses this implementation and the given SecretKey.
inherited
newNonce() → List<int>
Generates a new nonce.
inherited
newSecretKey() → Future<SecretKey>
Generates a new SecretKey.
inherited
newSecretKeyFromBytes(List<int> bytes) → Future<SecretKey>
Constructs a new SecretKey from the bytes.
inherited
newState() → CipherState
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
override
toSync() → DartAesGcm
Returns a synchronous, pure Dart implementation of this cipher.
override

Operators

operator ==(Object other) → bool
The equality operator.
override

Constants

aesGcmMac → const MacAlgorithm
MAC algorithm used by AES-GCM.
defaultNonceLength → const int