Module: Asherah

Extended by:
Cobhan
Defined in:
lib/asherah.rb,
lib/asherah/error.rb,
lib/asherah/config.rb,
lib/asherah/version.rb

Overview

Asherah is a Ruby wrapper around Asherah Go application-layer encryption SDK.

Defined Under Namespace

Modules: Error Classes: Config

Constant Summary collapse

LIB_ROOT_PATH = 
File.expand_path('asherah/native', __dir__)
ESTIMATED_ENCRYPTION_OVERHEAD = 
48
ESTIMATED_ENVELOPE_OVERHEAD = 
185
BASE64_OVERHEAD = 
1.34
VERSION = 
'0.5.2'

Class Method Summary collapse

Class Method Details

.configure {|Config| ... } ⇒ void

This method returns an undefined value.

Configures Asherah

Yields:

Raises:



46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/asherah.rb', line 46

def configure
  raise Asherah::Error::AlreadyInitialized if @initialized

  config = Config.new
  yield config
  config.validate!
  @intermediated_key_overhead_bytesize = config.product_id.bytesize + config.service_name.bytesize

  config_buffer = string_to_cbuffer(config.to_json)

  result = SetupJson(config_buffer)
  Error.check_result!(result, 'SetupJson failed')
  @initialized = true
end

.decrypt(partition_id, json) ⇒ String

Decrypts a DataRowRecord in JSON format for a partition_id and returns decrypted data.

Parameters:

  • partition_id (String)
  • json (String) —

    , DataRowRecord in JSON format

Returns:

  • (String) —

    , Decrypted data



95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/asherah.rb', line 95

def decrypt(partition_id, json)
  partition_id_buffer = string_to_cbuffer(partition_id)
  data_buffer = string_to_cbuffer(json)
  output_buffer = allocate_cbuffer(json.bytesize)

  result = DecryptFromJson(partition_id_buffer, data_buffer, output_buffer)
  Error.check_result!(result, 'DecryptFromJson failed')

  cbuffer_to_string(output_buffer)
ensure
  [partition_id_buffer, data_buffer, output_buffer].map(&:free)
end

.encrypt(partition_id, data) ⇒ String

Encrypts data for a given partition_id and returns DataRowRecord in JSON format.

DataRowRecord contains the encrypted key and data, as well as the information required to decrypt the key encryption key. This object data should be stored in your data persistence as it’s required to decrypt data.

EnvelopeKeyRecord represents an encrypted key and is the data structure used to persist the key in the key table. It also contains the meta data of the key used to encrypt it.

KeyMeta contains the ‘id` and `created` timestamp for an encryption key.

Parameters:

  • partition_id (String)
  • data (String)

Returns:

  • (String) —

    , DataRowRecord in JSON format



76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/asherah.rb', line 76

def encrypt(partition_id, data)
  partition_id_buffer = string_to_cbuffer(partition_id)
  data_buffer = string_to_cbuffer(data)
  estimated_buffer_bytesize = estimate_buffer(data.bytesize, partition_id.bytesize)
  output_buffer = allocate_cbuffer(estimated_buffer_bytesize)

  result = EncryptToJson(partition_id_buffer, data_buffer, output_buffer)
  Error.check_result!(result, 'EncryptToJson failed')

  cbuffer_to_string(output_buffer)
ensure
  [partition_id_buffer, data_buffer, output_buffer].map(&:free)
end

.set_env(env = {}) {|Config| ... } ⇒ void

This method returns an undefined value.

Set environment variables needed by Asherah dependencies for when Go os.Getenv() doesn’t see variables set by C.setenv(). References:

https://github.com/golang/go/wiki/cgo#environmental-variables
https://github.com/golang/go/issues/44108

Parameters:

  • env (Hash) (defaults to: {}) —

    , Key-value pairs to set Asherah ENV

Yields:



35
36
37
38
39
40
 
# File 'lib/asherah.rb', line 35

def set_env(env = {})
  env_buffer = string_to_cbuffer(env.to_json)

  result = SetEnv(env_buffer)
  Error.check_result!(result, 'SetEnv failed')
end

.shutdown ⇒ Object

Stop the Asherah instance

Raises:



109
110
111
112
113
114
 
# File 'lib/asherah.rb', line 109

def shutdown
  raise Asherah::Error::NotInitialized unless @initialized

  Shutdown()
  @initialized = false
end