class Marten::Core::Encryptor

Overview

Provides the ability to easily encrypt string values.

The Marten::Core::Encryptor class makes it easy to build encrypted value that are stored in untrusted places. In addition, encrypted values are also signed to prevent tampering.

encryptor = Marten::Core::Encryptor.new
encrypted_value = encryptor.encrypt("hello world") # => "aGVsb..."
encryptor.decrypt(encrypted_value)                 # => "hello world"

Marten::Core::Encryptor objects require a key that must be at least as long as the cipher key size. By default, an 'aes-256-cbc' cipher is used, which means that keys must be at least 32 characters long. Both the cipher algorithm and the key used to generate encrypted values can be defined at initialization time using the cipher_algorithm and the key arguments.

Defined in:

marten/core/encryptor.cr

Constructors

Instance Method Summary

Constructor Detail

def self.new(key : String | Nil = nil, cipher_algorithm : String = "aes-256-cbc") #

[View source]

Instance Method Detail

def decrypt(value : String) : Nil | String #

Verifies and decrypt the passed value and returns the original value if it is valid, or nil otherwise.

This method verifies that the signed value has not been tampered, decrypt it, and returns the original value if the signature is valid, and if it is not expired:

encryptor = Marten::Core::Encryptor.new
encrypted_value = encryptor.encrypt("hello world") # => "aGVsb..."
encryptor.encrypt(encrypted_value)                 # => "hello world"

If the passed value is invalid, or if the associated signature is invalid, a nil value is returned:

encryptor = Marten::Core::Encryptor.new
encryptor.encrypt("bad_value") # => nil

[View source]
def decrypt!(value : String) : String #

Verifies and decrypt the passed value and returns the original value if it is valid, or raise an error.

This method verifies that the signed value has not been tampered, decrypt it, and returns the original value if the signature is valid, and if it is not expired:

encryptor = Marten::Core::Encryptor.new
encrypted_value = encryptor.encrypt("hello world") # => "aGVsb..."
encryptor.encrypt(encrypted_value)                 # => "hello world"

If the passed value is invalid, or if the associated signature is invalid, a Marten::Core::Encryptor::InvalidValueError exception is raised:

encryptor = Marten::Core::Encryptor.new
encryptor.encrypt!("bad_value") # => Marten::Core::Encryptor::InvalidValueError

[View source]
def encrypt(value : String, expires : Time | Nil = nil) : String #

Generates a encrypted ans signed value for the passed value.

The value is encrypted and signed by using the key used when initializing the encryptor instance:

encryptor = Marten::Core::Encryptor.new
encryptor.encrypt("hello world") # => "aGVsb..."

It is also possible to define an expiry time for the generated signature by using the expires argument:

encryptor = Marten::Core::Encryptor.new
encryptor.encrypt("hello world", expires: Time.local + Time::Span.new(hours: 20)) # => "eyJfb..."

[View source]