roqs

Roqs

Roqs is the Ruby wrapper to the Open Quantum Safe library. The native library was tested against the liboqs at liboqs

Due to the direct invocation of the shared library via the libffi toolkit, unless there are major API changes at the liboqs side, this library will keep working as the library is just a bridge between liboqs and Ruby runtime via the API called. Any new supported algorithms internal to the liboqs can be just immediately utilized by the Ruby runtime.

Installation

Add this line to your application's Gemfile:

gem 'roqs'

And then execute:

bundle install

Or install it yourself as:

gem install roqs

Usage

OQS mainly only has two group of functions: Key Encapsulation Mechanism (KEM) and Signature (SIG).

Therefore the Ruby wrapper abstraction is following the liboqs C version as baseline.

Key Encapsulation Mechanism (KEM)

For KEM, the API is simple:

• List all supported KEM PQ algorithms - PQ algorithms can be enable or disabled at compile time so it all depends on the liboqs native library. This API listed down the algorithms which are supported as reported by the native library. If you're using your own version of the library, you might have different output.

require 'roqs'

supported_algo = Roqs::KEM.supported_kem_algo
supported_algo.each do |al|
  # al is the algorithm name (string) which is required by subsequent API
  ...
end

• Generate keypair

require 'roqs'

kyber = Roqs::KEM.new('Kyber768')
pubKey, secretKey = kyber.genkeypair
# note pubKey and secretKey (or private key) is Fiddle::Pointer type and 
# is required to be used by the C API in the subsequent phase.
# Note that pubKey and secretKey are required to be free manually
# Refer spec file for usage

• Key encapsulation - KEM is meant for key encapsulation which similar with Diffie-Hellman kind of key exchange

require 'roqs'

sessionKey, cipher = kyber.derive_encapsulation_key(pubKey)
# cipher is required to be sent to recipient end to re-generate the sessionKey at recipient end.
# Returned sessionKey is meant to convert into the final AES (or any other symmetric key) 
# for the actual data encryption

• Key decapsulation - Re-generate the session key from the private key

require 'roqs'

sessionKey = kyber.derive_decapsulation_key(cipher, secretKey)
# cipher is given by sender and privKey is the recipient own private key

sessionKey returned from derive_encapsulation_key() shall be same as the sessionKey from derive_decapsulation_key(). That session key shall be the AES key (any other symmetric key) for the data encryption.

Signature mechanism

Signature mechanism is similar with KEM.

• List all supported Signature PQ algorithms - It is same as KEM as algorithm can be turned on or off during compile time

require 'roqs'

supported_algo = Roqs::SIG.supported_signature_algo
supported_algo.each do |al|
  # al is the algorithm name (string) which is required by subsequent API
  ...
end

• Generate keypair

require 'roqs'

dili = Roqs::SIG.new('Dilithium5')
pubKey, secretKey = dili.genkeypair
# note pubKey and secretKey (or private key) is Fiddle::Pointer type and 
# is required to be used by the C API in the subsequent phase.
# Note that pubKey and secretKey are required to be free manually
# Refer spec file for usage

• Generate data signature

require 'roqs'

# sign data using sender secretKey/private key
signature = dili.sign("this is message", secretKey)

• Verify data signature

require 'roqs'

# verify signature with given data using sender public key
res = dili.verify("this is message", signature, pubKey)
# res is boolean to indicate the signature verification is passed or failed

spec folder has the necessary API example usage.

Test Results

Refer to test result for details.

License

The gem is available as open source under the terms of the MIT License.