Identity SDK

Identity generation in Ruby for the Tanker SDK.

Requirements

This gem requires Ruby v2.5 or greater (transitive requirement from rbnacl).

Older Ruby versions are not supported.

Installation

This project depends on the rbnacl gem, which requires the libsodium cryptographic library.

Before going further, please follow instructions to install libsodium.

Then, add this line to your application's Gemfile:

gem 'tanker-identity', 'X.Y.Z'

Finally, execute:

bundle

API

Tanker::Identity.create_identity(app_id, app_secret, user_id)

Create a new Tanker identity. This identity is secret and must only be given to a user who has been authenticated by your application. This identity is used by the Tanker client SDK to open a Tanker session.

app_id
The app ID. You can access it from the Tanker dashboard.

app_secret
The app secret. A secret that you have saved right after the creation of your app on the Tanker dashboard.

user_id
The unique ID of a user in your application.

Tanker::Identity.create_provisional_identity(app_id, 'email', email)

Create a Tanker provisional identity. It allows you to share a resource with a user who does not have an account in your application yet.

app_id
The app ID. You can access it from the Tanker dashboard.

email
The email of the potential recipient of the resource.

Tanker::Identity.get_public_identity(identity)

Return the public identity from an identity. This public identity can be used by the Tanker client SDK to share encrypted resource.

identity
A secret identity.

Usage example

The server-side pseudo-code below demonstrates a typical flow to safely deliver identities to your users:

require 'tanker-identity'

# 1. store these configurations in a safe place
app_id = '<app-id>'
app_secret = '<app-secret>'

# 2. you will typically have methods to check user authentication
def authenticated? # check user is authenticated on the server
def current_user   # current authenticated user

# 3. you will need to add internal methods to store / load identities
def db_store_identity(user_id, identity)
def db_load_identity(user_id)

# 4. finally, add user facing functionality
def tanker_secret_identity(user_id)
  raise 'Not authenticated' unless authenticated?
  raise 'Not authorized' unless current_user.id == user_id

  identity = db_load_identity(user_id)

  if identity.nil?
    identity = Tanker::Identity.create_identity(app_id, app_secret, user_id)
    db_store_identity(user_id, identity)
  end

  identity
end

def tanker_public_identity(user_id)
  raise 'Not authenticated' unless authenticated?

  identity = db_load_identity(user_id)

  raise 'User does not exist or has no identity yet' unless identity

  Tanker::Identity.get_public_identity(identity)
end

Read more about identities in the Tanker documentation.

Check the examples folder for usage examples.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

To audit the Gemfile.lock against the advisory database, run bundle exec bundle-audit check --update.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/TankerHQ/identity-ruby.