data Crypto::AES::GCM(key: Bytes)
AES-GCM with one key: authenticated encryption, which keeps data
secret and detects any change to it. A data value holding the
key: immutable and Shareable; inspect and to_s never show the
key (key and to_h do, asked for explicitly).
aead = Crypto::AES::GCM.generate(256)
token = aead.encrypt("a secret", aad: "user 42")
aead.decrypt(token, aad: "user 42").decode # => "a secret"
aead.decrypt(token, aad: "user 43") # raises Crypto::AuthenticationError
A nonce must never be used twice with one key: that is the one way
to break GCM. encrypt draws a random 12-byte nonce each time and
puts it in front of what it returns, which is safe for about 2^32
messages per key; past that, rotate the key, or give seal a
counter as the nonce. seal and open are for protocols that fix
the nonce (a counter, one from the peer).
Class methods
def self.new(key: Bytes) -> Crypto::AES::GCM
Raises ArgumentError for a key that is not 16, 24 or 32 bytes.
def self.generate(bits: Int = …) -> Crypto::AES::GCM
A fresh random key of bits bits: 128, 192 or 256.
Methods
def key -> Bytes
The key: 16, 24 or 32 bytes (AES-128, -192, -256).
def to_h -> Hash[Symbol, Object]
The fields as a Hash, by name.
def with(*, key: Bytes = …) -> Crypto::AES::GCM
A copy with the fields given replaced.
def bits -> Int
The key's size in bits.
def seal(nonce: Bytes, plaintext: Bytes | String, *, aad: Bytes | String = …) -> Bytes
plaintext encrypted with nonce (12 bytes, used once with this
key), followed by the 16-byte tag that authenticates it and aad
(associated data: authenticated, not encrypted, and not included).
def open(nonce: Bytes, sealed: Bytes, *, aad: Bytes | String = …) -> Bytes
The plaintext of sealed (what seal gave for nonce and aad);
Crypto::AuthenticationError when it does not authenticate, and
then nothing of it is returned.
def open?(nonce: Bytes, sealed: Bytes, *, aad: Bytes | String = …) -> Bytes?
As open, nil instead of raising: for a caller to whom a bad
token is a normal case (an expired cookie).
def encrypt(plaintext: Bytes | String, *, aad: Bytes | String = …) -> Bytes
plaintext sealed with a fresh random nonce: the nonce (12
bytes), the ciphertext and the tag (16 bytes), as one Bytes to
store or send.
def decrypt(token: Bytes, *, aad: Bytes | String = …) -> Bytes
The plaintext of token (what encrypt gave for aad);
Crypto::AuthenticationError when it does not authenticate.
def inspect -> String
#<Crypto::AES::GCM 256 bits>: never the key.
def to_s -> String
#<Crypto::AES::GCM 256 bits>: never the key.