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.7.0'

Class Method Summary collapse

Class Method Details

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

This method returns an undefined value.

Configures Asherah

Yields:



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/asherah.rb', line 48

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
ensure
  config_buffer&.free
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



101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/asherah.rb', line 101

def decrypt(partition_id, json)
  raise Asherah::Error::NotInitialized unless @initialized

  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].compact.each(&: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



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/asherah.rb', line 80

def encrypt(partition_id, data)
  raise Asherah::Error::NotInitialized unless @initialized

  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].compact.each(&: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
41
42
 
# 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')
ensure
  env_buffer&.free
end

.shutdown ⇒ Object

Stop the Asherah instance

Raises:



117
118
119
120
121
122
 
# File 'lib/asherah.rb', line 117

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

  Shutdown()
  @initialized = false
end