nexaas-cipher

Nexaas Cipher (Ruby)

This is the official Ruby support for Nexaas ID simple ciphering.

nexaas-cipher-ruby RDoc documentation: http://rubydoc.info/github/myfreecomm/nexaas-cipher-ruby/frames/

Installation

Add this line to your application’s Gemfile:

gem 'nexaas-cipher', require: 'nexaas'

And then execute:

$ bundle

Or install it yourself as:

$ gem install nexaas-cipher

API

Nexaas::Cipher::Salt

This resource manages the cipher salt. The minimal instantiation is:

salt = Nexaas::Cipher::Salt.new(raw_salt_string)

If the salt string is coded in Base64, you still can use it:

salt = Nexaas::Cipher::Salt.new(base64_salt_string, base64: true)

Methods

#salt? : returns false if the salt is empty, true otherwise.

#salt : returns the raw salt.

#salt(base64: true) : returns the salt encoded in Base64. This parâmeter is valid for all variations of this method.

#salt(code) : returns the salt sized to fit the supplied code.

#salt(code, truncate: true) : same before, but truncates the salt when the code is smaller than it.

Example:

irb> salt = Nexaas::Cipher::Salt.new('YWJjZGVm', base64: true)
=> #<Nexaas::Cipher::Salt:0x0000563848195c40 @salt="abcdef">
irb> salt.salt?
=> true
irb> salt.salt
=> "abcdef"
irb> salt.salt('test')
=> "abcdef"
irb> salt.salt('test', truncate: true)
=> "abcd"
irb> salt.salt('test', base64: true, truncate: true)
=> "YWJjZA=="

Nexaas::Cipher::XorCrypter

This class allows to perform XOR cipher encryption. Its constructor has the same signature as Nexaas::Cipher::Salt.

Methods

#salt? : returns false if its salt is empty, true otherwise.

#salt : returns its internal Nexaas::Cipher::Salt object.

#encrypt(code, **options) : encrypts the code using the salt. The options are passed to the salt#salt method to get the effective salt string. It accepts an extra option, obfuscate, that generates a random obfuscative string to be concatenated to the code in order to fill the salt length when the code is smaller and is not truncated, avoiding to expose it.

#decrypt(code, **options) : does the same of #encrypt, but truncates the result code in the firt null character. Useful when the cipher was generate with obfuscate: true.

Nexaas::Cipher::IDCrypter

This is the same crypter used by Nexaas ID to deal with application signatures.

It expects the code/cipher to be the application secret.

Features:

• The salt is always truncated and never obfuscated (makes no sense on truncation).
• On encryption, the code is expected to be Base64 by default, and the generated cipher is always Base64.
• On decryption, the cipher must be Base64, and the determinated code is Base64 by default.

Methods

#encrypt(code, base64: true) : encrypt code. The base64 controls if the code is Base64 or not (raw).

#decrypt(code, base64: true) : decrypt code. The base64 controls if the output is Base64 or not (raw).

Using the default options, #encrypt and decrypt act the same: expecting a Base64 code and xoring it with the salt. Since the XOR cipher is self-reversing, “encrypting” the generated cipher results in the original code.

Example

crypter = Nexaas::Cipher::IDCrypter.new(application.secret)

signature = Base64.encode64(Random.urandom(12)).rstrip
cipher = crypter.encrypt(signature)

# Send cipher to Nexaas ID using the access token, and getting res(ponse) back
# ...

if res.params[:signature] == signature
  puts 'OK, it is right!'
  # ...
end

Nexaas::Cipher::CrypterBase

Pretending to be an abstract class, it is used to inherit new crypters.

The constructor passes its parameters to the Nexaas::Cipher::Salt one, and stores its instance for use.

The subclasses supposed to implement the following protected methods:

#do_encrypt(code, **options) : The routine to be performed for encryption.

#do_decrypt(code, **options) : The routine to be performed for decryption.

Notes:

• The code is passed raw.
• The options are the same passed to #encrypt and #decrypt methods.
• The base64: options is not passed. If it’s false (default), the code or cipher is passed raw through and back; if it’s true, the supplied code is decoded from Base64 to raw before being passed to the #do_* method, and de returned valueis encoded in Base64.

Available methods

#salt? : returns false if the salt is empty, true otherwise.

#salt : returns the internal Nexaas::Cipher::Salt object.

Support

This gem supports Ruby 2.5 or superior.