https://github.com/chrisliaw/roqs
Ruby wrapper to the liboqs library
https://github.com/chrisliaw/roqs
liboqs
Last synced: 3 months ago
JSON representation
Ruby wrapper to the liboqs library
- Host: GitHub
- URL: https://github.com/chrisliaw/roqs
- Owner: chrisliaw
- Created: 2023-11-16T13:51:28.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-04-16T14:52:01.000Z (about 1 year ago)
- Last Synced: 2025-01-09T14:54:10.213Z (5 months ago)
- Topics: liboqs
- Language: Ruby
- Homepage:
- Size: 16.6 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Roqs
Roqs is the Ruby wrapper to the [Open Quantum Safe library](https://openquantumsafe.org). The native library was tested against the liboqs at [liboqs](https://github.com/open-quantum-safe/liboqs)
## Installation
Add this line to your application's Gemfile:
```ruby
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:
1. 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.
```ruby
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
```
2. Generate keypair
```ruby
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
```
3. Key encapsulation - KEM is meant for key encapsulation which similar with Diffie-Hellman kind of key exchange
```ruby
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
```
4. Key decapsulation - Re-generate the session key from the private key
```ruby
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.
1. List all supported Signature PQ algorithms - It is same as KEM as algorithm can be turned on or off during compile time
```ruby
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
```
2. Generate keypair
```ruby
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
```
3. Generate data signature
```rubyion
require 'roqs'
# sign data using sender secretKey/private key
signature = dili.sign("this is message", secretKey)
```
4. Verify data signature
```ruby
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](https://github.com/chrisliaw/liboqs-ruby/blob/master/TEST-RESULT.md) for details.
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).