Skip to main content
@tevm/voltaire
@tevm/voltaire / crypto/AesGcm

crypto/AesGcm

Classes

AesGcmError

Defined in: src/crypto/AesGcm/errors.js:21 Base error for AES-GCM operations

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

Example

import { AesGcmError } from './crypto/AesGcm/index.js';
throw new AesGcmError('Operation failed', {
  code: 'AES_GCM_ERROR',
  context: { operation: 'encrypt' },
  docsPath: '/crypto/aes-gcm#error-handling',
  cause: originalError
});

Extends

Extended by

Constructors

Constructor
new AesGcmError(message, options?): AesGcmError
Defined in: src/crypto/AesGcm/errors.js:26
Parameters
message
string
options?
cause?
Error
code?
string
context?
Record<string, unknown>
docsPath?
string
Returns
AesGcmError
Overrides
CryptoError.constructor

Properties

cause?
optional cause: Error
Defined in: src/primitives/errors/AbstractError.ts:56 Root cause of this error (for error chaining)
Inherited from
CryptoError.cause
code
code: string
Defined in: src/primitives/errors/AbstractError.ts:39 Machine-readable error code for programmatic handling
Example
'INVALID_FORMAT', 'INVALID_LENGTH'
Inherited from
CryptoError.code
context?
optional context: Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:45 Additional context metadata for debugging
Example
{ value: '0x123', expected: '20 bytes' }
Inherited from
CryptoError.context
docsPath?
optional docsPath: string
Defined in: src/primitives/errors/AbstractError.ts:51 Path to documentation for this error
Example
'/primitives/address/from-hex#error-handling'
Inherited from
CryptoError.docsPath
name
name: string
Defined in: src/crypto/AesGcm/errors.js:33
Inherited from
CryptoError.name

Methods

getErrorChain()
getErrorChain(): string
Defined in: src/primitives/errors/AbstractError.ts:94 Get full error chain as string for logging
Returns
string
Inherited from
CryptoError.getErrorChain
toJSON()
toJSON(): Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:110 Serialize error to JSON for logging/telemetry
Returns
Record<string, unknown>
Inherited from
CryptoError.toJSON

DecryptionError

Defined in: src/crypto/AesGcm/errors.js:118 Decryption failure error

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

Example

import { DecryptionError } from './crypto/AesGcm/index.js';
throw new DecryptionError('Authentication failed', {
  code: 'AES_GCM_DECRYPTION_FAILED',
  context: { operation: 'decrypt' },
  docsPath: '/crypto/aes-gcm/decrypt#error-handling',
  cause: originalError
});

Extends

Constructors

Constructor
new DecryptionError(message, options?): DecryptionError
Defined in: src/crypto/AesGcm/errors.js:123
Parameters
message
string
options?
cause?
Error
code?
string
context?
Record<string, unknown>
docsPath?
string
Returns
DecryptionError
Overrides
AesGcmError.constructor

Properties

cause?
optional cause: Error
Defined in: src/primitives/errors/AbstractError.ts:56 Root cause of this error (for error chaining)
Inherited from
AesGcmError.cause
code
code: string
Defined in: src/primitives/errors/AbstractError.ts:39 Machine-readable error code for programmatic handling
Example
'INVALID_FORMAT', 'INVALID_LENGTH'
Inherited from
AesGcmError.code
context?
optional context: Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:45 Additional context metadata for debugging
Example
{ value: '0x123', expected: '20 bytes' }
Inherited from
AesGcmError.context
docsPath?
optional docsPath: string
Defined in: src/primitives/errors/AbstractError.ts:51 Path to documentation for this error
Example
'/primitives/address/from-hex#error-handling'
Inherited from
AesGcmError.docsPath
name
name: string
Defined in: src/crypto/AesGcm/errors.js:130
Inherited from
AesGcmError.name

Methods

getErrorChain()
getErrorChain(): string
Defined in: src/primitives/errors/AbstractError.ts:94 Get full error chain as string for logging
Returns
string
Inherited from
AesGcmError.getErrorChain
toJSON()
toJSON(): Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:110 Serialize error to JSON for logging/telemetry
Returns
Record<string, unknown>
Inherited from
AesGcmError.toJSON

InvalidKeyError

Defined in: src/crypto/AesGcm/errors.js:53 Invalid key error

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

Example

import { InvalidKeyError } from './crypto/AesGcm/index.js';
throw new InvalidKeyError('Invalid key size', {
  code: 'AES_GCM_INVALID_KEY_SIZE',
  context: { size: 16, expected: '16, 24, or 32 bytes' },
  docsPath: '/crypto/aes-gcm/import-key#error-handling'
});

Extends

Constructors

Constructor
new InvalidKeyError(message, options?): InvalidKeyError
Defined in: src/crypto/AesGcm/errors.js:58
Parameters
message
string
options?
cause?
Error
code?
string
context?
Record<string, unknown>
docsPath?
string
Returns
InvalidKeyError
Overrides
AesGcmError.constructor

Properties

cause?
optional cause: Error
Defined in: src/primitives/errors/AbstractError.ts:56 Root cause of this error (for error chaining)
Inherited from
AesGcmError.cause
code
code: string
Defined in: src/primitives/errors/AbstractError.ts:39 Machine-readable error code for programmatic handling
Example
'INVALID_FORMAT', 'INVALID_LENGTH'
Inherited from
AesGcmError.code
context?
optional context: Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:45 Additional context metadata for debugging
Example
{ value: '0x123', expected: '20 bytes' }
Inherited from
AesGcmError.context
docsPath?
optional docsPath: string
Defined in: src/primitives/errors/AbstractError.ts:51 Path to documentation for this error
Example
'/primitives/address/from-hex#error-handling'
Inherited from
AesGcmError.docsPath
name
name: string
Defined in: src/crypto/AesGcm/errors.js:65
Inherited from
AesGcmError.name

Methods

getErrorChain()
getErrorChain(): string
Defined in: src/primitives/errors/AbstractError.ts:94 Get full error chain as string for logging
Returns
string
Inherited from
AesGcmError.getErrorChain
toJSON()
toJSON(): Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:110 Serialize error to JSON for logging/telemetry
Returns
Record<string, unknown>
Inherited from
AesGcmError.toJSON

InvalidNonceError

Defined in: src/crypto/AesGcm/errors.js:85 Invalid nonce error

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

Example

import { InvalidNonceError } from './crypto/AesGcm/index.js';
throw new InvalidNonceError('Nonce must be 12 bytes', {
  code: 'AES_GCM_INVALID_NONCE_LENGTH',
  context: { length: 8, expected: 12 },
  docsPath: '/crypto/aes-gcm/encrypt#error-handling'
});

Extends

Constructors

Constructor
new InvalidNonceError(message, options?): InvalidNonceError
Defined in: src/crypto/AesGcm/errors.js:90
Parameters
message
string
options?
cause?
Error
code?
string
context?
Record<string, unknown>
docsPath?
string
Returns
InvalidNonceError
Overrides
AesGcmError.constructor

Properties

cause?
optional cause: Error
Defined in: src/primitives/errors/AbstractError.ts:56 Root cause of this error (for error chaining)
Inherited from
AesGcmError.cause
code
code: string
Defined in: src/primitives/errors/AbstractError.ts:39 Machine-readable error code for programmatic handling
Example
'INVALID_FORMAT', 'INVALID_LENGTH'
Inherited from
AesGcmError.code
context?
optional context: Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:45 Additional context metadata for debugging
Example
{ value: '0x123', expected: '20 bytes' }
Inherited from
AesGcmError.context
docsPath?
optional docsPath: string
Defined in: src/primitives/errors/AbstractError.ts:51 Path to documentation for this error
Example
'/primitives/address/from-hex#error-handling'
Inherited from
AesGcmError.docsPath
name
name: string
Defined in: src/crypto/AesGcm/errors.js:97
Inherited from
AesGcmError.name

Methods

getErrorChain()
getErrorChain(): string
Defined in: src/primitives/errors/AbstractError.ts:94 Get full error chain as string for logging
Returns
string
Inherited from
AesGcmError.getErrorChain
toJSON()
toJSON(): Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:110 Serialize error to JSON for logging/telemetry
Returns
Record<string, unknown>
Inherited from
AesGcmError.toJSON

Type Aliases

Key

Key = CryptoKey
Defined in: src/crypto/AesGcm/KeyTypes.ts:13 AES-GCM CryptoKey type

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

Example

import type { Key } from './crypto/AesGcm/KeyTypes.js';
const key: Key = await crypto.subtle.generateKey(...);

KeyMaterial

KeyMaterial = Uint8Array
Defined in: src/crypto/AesGcm/KeyTypes.ts:27 Raw key material (bytes)

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

Example

import type { KeyMaterial } from './crypto/AesGcm/KeyTypes.js';
const material: KeyMaterial = new Uint8Array(32);

Variables

AES128_KEY_SIZE

const AES128_KEY_SIZE: 16 = 16
Defined in: src/crypto/AesGcm/constants.js:13 AES-128 key size in bytes

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

Example

import * as AesGcm from './crypto/AesGcm/index.js';
const keyBytes = new Uint8Array(AesGcm.AES128_KEY_SIZE);

AES256_KEY_SIZE

const AES256_KEY_SIZE: 32 = 32
Defined in: src/crypto/AesGcm/constants.js:27 AES-256 key size in bytes

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

Example

import * as AesGcm from './crypto/AesGcm/index.js';
const keyBytes = new Uint8Array(AesGcm.AES256_KEY_SIZE);

AesGcm

const AesGcm: object
Defined in: src/crypto/AesGcm/AesGcm.js:54 AES-GCM (Galois/Counter Mode) Authenticated Encryption Provides authenticated encryption using AES in GCM mode. Uses native WebCrypto API for optimal performance and security. Supports both AES-128-GCM and AES-256-GCM.

Type Declaration

AES128_KEY_SIZE
AES128_KEY_SIZE: number
AES-128 key size in bytes
See
https://voltaire.tevm.sh/crypto for crypto documentation
Since
0.0.0
Throws
Example
import * as AesGcm from './crypto/AesGcm/index.js';
const keyBytes = new Uint8Array(AesGcm.AES128_KEY_SIZE);
AES256_KEY_SIZE
AES256_KEY_SIZE: number
AES-256 key size in bytes
See
https://voltaire.tevm.sh/crypto for crypto documentation
Since
0.0.0
Throws
Example
import * as AesGcm from './crypto/AesGcm/index.js';
const keyBytes = new Uint8Array(AesGcm.AES256_KEY_SIZE);
decrypt()
decrypt: (ciphertext, key, nonce, additionalData?) => Promise<Uint8Array<ArrayBufferLike>>
Decrypt data with AES-GCM
Parameters
ciphertext
Uint8Array<ArrayBufferLike> Encrypted data with authentication tag
key
CryptoKey AES key (128 or 256 bit)
nonce
Uint8Array<ArrayBufferLike> 12-byte nonce (IV) used during encryption
additionalData?
Uint8Array<ArrayBufferLike> Optional additional authenticated data
Returns
Promise<Uint8Array<ArrayBufferLike>> Decrypted plaintext
See
https://voltaire.tevm.sh/crypto for crypto documentation
Since
0.0.0
Throws
If authentication fails or decryption error
Example
import * as AesGcm from './crypto/AesGcm/index.js';
const key = await AesGcm.generateKey(256);
const nonce = AesGcm.generateNonce();
const decrypted = await AesGcm.decrypt(ciphertext, key, nonce);
const message = new TextDecoder().decode(decrypted);
deriveKey()
deriveKey: (password, salt, iterations, bits) => Promise<CryptoKey>
Derive key from password using PBKDF2
Parameters
password
Password string or bytes string | Uint8Array<ArrayBufferLike>
salt
Uint8Array<ArrayBufferLike> Salt for key derivation (at least 16 bytes recommended)
iterations
number Number of iterations (at least 100000 recommended)
bits
Key size in bits (128 or 256) 128 | 256
Returns
Promise<CryptoKey> Derived CryptoKey
See
https://voltaire.tevm.sh/crypto for crypto documentation
Since
0.0.0
Throws
If key derivation fails
Example
import * as AesGcm from './crypto/AesGcm/index.js';
const salt = crypto.getRandomValues(new Uint8Array(16));
const key = await AesGcm.deriveKey('mypassword', salt, 100000, 256);
encrypt()
encrypt: (plaintext, key, nonce, additionalData?) => Promise<Uint8Array<ArrayBufferLike>>
Encrypt data with AES-GCM
Parameters
plaintext
Uint8Array<ArrayBufferLike> Data to encrypt
key
CryptoKey AES key (128 or 256 bit)
nonce
Uint8Array<ArrayBufferLike> 12-byte nonce (IV)
additionalData?
Uint8Array<ArrayBufferLike> Optional additional authenticated data
Returns
Promise<Uint8Array<ArrayBufferLike>> Ciphertext with authentication tag appended
See
https://voltaire.tevm.sh/crypto for crypto documentation
Since
0.0.0
Throws
If encryption fails
Example
import * as AesGcm from './crypto/AesGcm/index.js';
const plaintext = new TextEncoder().encode('Secret message');
const key = await AesGcm.generateKey(256);
const nonce = AesGcm.generateNonce();
const ciphertext = await AesGcm.encrypt(plaintext, key, nonce);
exportKey()
exportKey: (key) => Promise<Uint8Array<ArrayBufferLike>>
Export CryptoKey to raw bytes
Parameters
key
CryptoKey CryptoKey to export
Returns
Promise<Uint8Array<ArrayBufferLike>> Raw key bytes
See
https://voltaire.tevm.sh/crypto for crypto documentation
Since
0.0.0
Throws
If key export fails
Example
import * as AesGcm from './crypto/AesGcm/index.js';
const key = await AesGcm.generateKey(256);
const keyBytes = await AesGcm.exportKey(key);
generateKey()
generateKey: (bits) => Promise<CryptoKey>
Generate AES-GCM key
Parameters
bits
Key size in bits (128 or 256) 128 | 256
Returns
Promise<CryptoKey> CryptoKey for use with WebCrypto API
See
https://voltaire.tevm.sh/crypto for crypto documentation
Since
0.0.0
Throws
If key generation fails
Example
import * as AesGcm from './crypto/AesGcm/index.js';
const key128 = await AesGcm.generateKey(128);
const key256 = await AesGcm.generateKey(256);
generateNonce()
generateNonce: () => Uint8Array<ArrayBufferLike>
Generate random nonce
Returns
Uint8Array<ArrayBufferLike> 12-byte random nonce
See
https://voltaire.tevm.sh/crypto for crypto documentation
Since
0.0.0
Throws
Example
import * as AesGcm from './crypto/AesGcm/index.js';
const nonce = AesGcm.generateNonce();
importKey()
importKey: (keyMaterial) => Promise<CryptoKey>
Import raw key material as CryptoKey
Parameters
keyMaterial
Uint8Array<ArrayBufferLike> 16-byte (128-bit) or 32-byte (256-bit) key
Returns
Promise<CryptoKey> CryptoKey for use with WebCrypto API
See
https://voltaire.tevm.sh/crypto for crypto documentation
Since
0.0.0
Throws
If key import fails or key size is invalid
Example
import * as AesGcm from './crypto/AesGcm/index.js';
const keyBytes = crypto.getRandomValues(new Uint8Array(32));
const key = await AesGcm.importKey(keyBytes);
NONCE_SIZE
NONCE_SIZE: number
Nonce/IV size in bytes (standard for GCM)
See
https://voltaire.tevm.sh/crypto for crypto documentation
Since
0.0.0
Throws
Example
import * as AesGcm from './crypto/AesGcm/index.js';
const nonce = new Uint8Array(AesGcm.NONCE_SIZE);
TAG_SIZE
TAG_SIZE: number
Authentication tag size in bytes
See
https://voltaire.tevm.sh/crypto for crypto documentation
Since
0.0.0
Throws
Example
import * as AesGcm from './crypto/AesGcm/index.js';
console.log('Tag size:', AesGcm.TAG_SIZE);

Example

import { AesGcm } from './AesGcm.js';

// Generate key
const key = await AesGcm.generateKey(256);

// Encrypt data
const plaintext = new TextEncoder().encode('Hello, world!');
const nonce = AesGcm.generateNonce();
const ciphertext = await AesGcm.encrypt(plaintext, key, nonce);

// Decrypt data
const decrypted = await AesGcm.decrypt(ciphertext, key, nonce);

NONCE_SIZE

const NONCE_SIZE: 12 = 12
Defined in: src/crypto/AesGcm/constants.js:41 Nonce/IV size in bytes (standard for GCM)

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

Example

import * as AesGcm from './crypto/AesGcm/index.js';
const nonce = new Uint8Array(AesGcm.NONCE_SIZE);

TAG_SIZE

const TAG_SIZE: 16 = 16
Defined in: src/crypto/AesGcm/constants.js:55 Authentication tag size in bytes

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

Example

import * as AesGcm from './crypto/AesGcm/index.js';
console.log('Tag size:', AesGcm.TAG_SIZE);

Functions

decrypt()

decrypt(ciphertext, key, nonce, additionalData?): Promise<Uint8Array<ArrayBufferLike>>
Defined in: src/crypto/AesGcm/decrypt.js:24 Decrypt data with AES-GCM

Parameters

ciphertext
Uint8Array<ArrayBufferLike> Encrypted data with authentication tag
key
CryptoKey AES key (128 or 256 bit)
nonce
Uint8Array<ArrayBufferLike> 12-byte nonce (IV) used during encryption
additionalData?
Uint8Array<ArrayBufferLike> Optional additional authenticated data

Returns

Promise<Uint8Array<ArrayBufferLike>> Decrypted plaintext

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

If authentication fails or decryption error

Example

import * as AesGcm from './crypto/AesGcm/index.js';
const key = await AesGcm.generateKey(256);
const nonce = AesGcm.generateNonce();
const decrypted = await AesGcm.decrypt(ciphertext, key, nonce);
const message = new TextDecoder().decode(decrypted);

deriveKey()

deriveKey(password, salt, iterations, bits): Promise<CryptoKey>
Defined in: src/crypto/AesGcm/deriveKey.js:21 Derive key from password using PBKDF2

Parameters

password
Password string or bytes string | Uint8Array<ArrayBufferLike>
salt
Uint8Array<ArrayBufferLike> Salt for key derivation (at least 16 bytes recommended)
iterations
number Number of iterations (at least 100000 recommended)
bits
Key size in bits (128 or 256) 128 | 256

Returns

Promise<CryptoKey> Derived CryptoKey

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

If key derivation fails

Example

import * as AesGcm from './crypto/AesGcm/index.js';
const salt = crypto.getRandomValues(new Uint8Array(16));
const key = await AesGcm.deriveKey('mypassword', salt, 100000, 256);

encrypt()

encrypt(plaintext, key, nonce, additionalData?): Promise<Uint8Array<ArrayBufferLike>>
Defined in: src/crypto/AesGcm/encrypt.js:24 Encrypt data with AES-GCM

Parameters

plaintext
Uint8Array<ArrayBufferLike> Data to encrypt
key
CryptoKey AES key (128 or 256 bit)
nonce
Uint8Array<ArrayBufferLike> 12-byte nonce (IV)
additionalData?
Uint8Array<ArrayBufferLike> Optional additional authenticated data

Returns

Promise<Uint8Array<ArrayBufferLike>> Ciphertext with authentication tag appended

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

If encryption fails

Example

import * as AesGcm from './crypto/AesGcm/index.js';
const plaintext = new TextEncoder().encode('Secret message');
const key = await AesGcm.generateKey(256);
const nonce = AesGcm.generateNonce();
const ciphertext = await AesGcm.encrypt(plaintext, key, nonce);

exportKey()

exportKey(key): Promise<Uint8Array<ArrayBufferLike>>
Defined in: src/crypto/AesGcm/exportKey.js:18 Export CryptoKey to raw bytes

Parameters

key
CryptoKey CryptoKey to export

Returns

Promise<Uint8Array<ArrayBufferLike>> Raw key bytes

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

If key export fails

Example

import * as AesGcm from './crypto/AesGcm/index.js';
const key = await AesGcm.generateKey(256);
const keyBytes = await AesGcm.exportKey(key);

generateKey()

generateKey(bits): Promise<CryptoKey>
Defined in: src/crypto/AesGcm/generateKey.js:18 Generate AES-GCM key

Parameters

bits
Key size in bits (128 or 256) 128 | 256

Returns

Promise<CryptoKey> CryptoKey for use with WebCrypto API

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

If key generation fails

Example

import * as AesGcm from './crypto/AesGcm/index.js';
const key128 = await AesGcm.generateKey(128);
const key256 = await AesGcm.generateKey(256);

generateNonce()

generateNonce(): Uint8Array<ArrayBufferLike>
Defined in: src/crypto/AesGcm/generateNonce.js:16 Generate random nonce

Returns

Uint8Array<ArrayBufferLike> 12-byte random nonce

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

Example

import * as AesGcm from './crypto/AesGcm/index.js';
const nonce = AesGcm.generateNonce();

importKey()

importKey(keyMaterial): Promise<CryptoKey>
Defined in: src/crypto/AesGcm/importKey.js:19 Import raw key material as CryptoKey

Parameters

keyMaterial
Uint8Array<ArrayBufferLike> 16-byte (128-bit) or 32-byte (256-bit) key

Returns

Promise<CryptoKey> CryptoKey for use with WebCrypto API

See

https://voltaire.tevm.sh/crypto for crypto documentation

Since

0.0.0

Throws

If key import fails or key size is invalid

Example

import * as AesGcm from './crypto/AesGcm/index.js';
const keyBytes = crypto.getRandomValues(new Uint8Array(32));
const key = await AesGcm.importKey(keyBytes);