virgil-jwt 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cd658cbf3a3f60af8caef3f1cbbc87f4ff654bd34c10867d5dbe5d047b58a958
+  data.tar.gz: cd0faee77bbc05e9fdac6f790db75b470a5c089e3169ef71e8f1266c681e0452
+SHA512:
+  metadata.gz: 59cd27fb3338bc5b9860444abad60af31de2b85719902d00f7d80f43953609347ebca2068041b75ffa9aa7ab101b7d999d969cc65a7aef7abc1dd81db0fb7e73
+  data.tar.gz: 6cb5bd2c18e6a60ab2de063b3abab9ced403f61f52fdf0d6e05cc56a12181e27221dbaba55697f406fdb0714b2da645407b2a9c70e027688df4d9faf131476cc

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.json
+.idea/

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.5.0
+before_install: gem install bundler -v 1.16.1

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in virgil-sdk-ruby-jwt.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,37 @@
+PATH
+  remote: .
+  specs:
+    virgil-jwt (1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ansi (1.5.0)
+    builder (3.2.3)
+    envyable (1.2.0)
+      thor (>= 0.18.1, < 2.0)
+    minitest (5.10.3)
+    minitest-reporters (1.3.6)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
+    rake (10.5.0)
+    ruby-progressbar (1.10.0)
+    thor (0.20.0)
+    virgil-crypto (3.6.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.16)
+  envyable (~> 1.2)
+  minitest (~> 5.0)
+  minitest-reporters (~> 1.1)
+  rake (~> 10.0)
+  virgil-crypto (~> 3.6, >= 3.6.2)
+  virgil-jwt!
+
+BUNDLED WITH
+   1.16.4

data/LICENSE.txt

@@ -0,0 +1,33 @@
+# Copyright (C) 2015-2019 Virgil Security Inc.
+#
+# Lead Maintainer: Virgil Security Inc. <support@virgilsecurity.com>
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#   (1) Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+#
+#   (2) Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in
+#   the documentation and/or other materials provided with the
+#   distribution.
+#
+#   (3) Neither the name of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ''AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+# INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, bytes, OR PROFITS; OR BUSINESS INTERRUPTION)
+# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+# STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+# IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,203 @@
+# Virgil JWT
+[![Gem](https://img.shields.io/gem/v/virgil-jwt.svg)](https://rubygems.org/gems/virgil-jwt)
+[![GitHub license](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg)](https://github.com/VirgilSecurity/virgil/blob/master/LICENSE)
+
+### [Introduction](#introduction) | [Library purposes](#library-purposes) | [Usage examples](#usage-examples) | [Installation](#installation) | [Docs](#docs) | [License](#license) | [Contacts](#support)
+
+## Introduction
+Virgil JSON Web Token ("JWT") allows you to make call to Virgil Services without having to know how they're constructed.
+## Library purposes
+* Authentication using tokens that are based on the [JSON Web Token standard](https://jwt.io) but with some Virgil modification.
+
+## Usage examples
+
+#### Virgil developer credentials
+
+Collect your Virgil developer credentials form [Virgil Dashboard](https://dashboard.virgilsecurity.com):
+APP_ID, API_KEY_ID, API_KEY
+
+| Parameter    |Description                                                                                                                                                                                                        |
+|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| APP_ID       | ID of your Application at [Virgil Dashboard](https://dashboard.virgilsecurity.com)                                                                                                                                |
+| API_KEY_ID   | A unique string value that identifies your account at the Virgil developer portal                                                                                                                                 |
+| API_KEY      | A Private Key that is used to sign API calls to Virgil Services. For security, you will only be shown the API Private Key when the key is created. Don't forget to save it in a secure location for the next step |
+
+Generate a Private Key with the default algorithm (EC_X25519):
+
+```ruby
+require 'virgil/crypto'
+include Virgil::Crypto
+
+crypto = VirgilCrypto.new
+key_pair = crypto.generate_keys
+```
+
+### Set up Client side and send a JWT request
+After a user installs Virgil Jwt you'll need to set up JWT Provider for providing a user with a JWT. You'll need to give your users a JWT that tells Virgil who they are and what they can do.
+Requests to your app server must be authorized. You can use any kind of authentication, for example, Google auth.
+
+#### Set up JWT provider
+Use these lines of code to specify which JWT generation source you prefer to use in your project:
+
+```ruby
+require 'virgil/crypto'
+require 'virgil/jwt'
+include Virgil::Crypto
+include Virgil::Jwt
+
+# Get generated token from server-side
+obtain_token_proc = proc { authenticated_query_to_server('my_token_identity').to_s }
+
+# Setup AccessTokenProvider
+access_token_provider = CallbackJwtProvider(obtain_token_proc)
+```
+
+### Set up Server Side and Generate JWT
+
+Next, you'll set up the JwtGenerator and generate a JWT using the Virgil SDK.
+You'll use your API Key that was created at Virgil Dashboard. For security purposes, you have to generate JWT on your server side.
+
+Each JWT is granted access to specific Application and has a limited lifetime that is configured by you. However, best practice is to generate JWT for the shortest amount of time feasible for your application.
+Here is an example of how to generate a JWT:
+
+```ruby
+require 'virgil/crypto'
+require 'virgil/jwt'
+include Virgil::Crypto
+include Virgil::Jwt
+
+# API_KEY (you got this Key at Virgil Dashboard)
+api_key_base64 = "MIGhMF0GCSqGSIb3DQEFDTBQMC8GCSqGSIb3DQEFDDAiBBC7Sg/DbNzhJ/uakTvafUMoAgIUtzAKBggqhkiG9w0CCjAdBglghkgBZQMEASoEEDunQ1yhWZoKaLaDFgjpxRwEQAFdbC8e6103lJrUhY9ahyUA8+4rTJKZCmdTlCDPvoWH/5N5kxbOvTtbxtxevI421z3gRbjAtoWkfWraSLD6gj0="
+private_key_data = Bytes.from_string(api_key_base64, VirgilStringEncoding::BASE64)
+
+# Crypto library imports a private key into a necessary format
+crypto = VirgilCrypto.new
+api_key = crypto.import_private_key(private_key_data, app_key_password)
+
+#  initialize accessTokenSigner that signs users JWTs
+access_token_signer = VirgilAccessTokenSigner.new
+
+# use your App Credentials you got at Virgil Dashboard:
+app_id = "be00e10e4e1f4bf58f9b4dc85d79c77a" # APP_ID
+api_key_id = "70b447e321f3a0fd"; # API_KEY_ID
+ttl = 1*60 # 1 hour (JWT's lifetime in minutes)
+
+# setup JWT generator with necessary parameters:
+jwt_generator = JwtGenerator.new(app_id: app_id, 
+                                 api_key: api_key, 
+                                 api_public_key_id: api_key_id, 
+                                 life_time: ttl, 
+                                 access_token_signer: access_token_signer)
+
+# generate JWT for a user
+# remember that you must provide each user with his unique JWT
+# each JWT contains unique user's identity (in this case - Alice)
+# identity can be any value: name, email, some id etc.
+identity = "Alice"
+alice_jwt = jwt_generator.generate_token(identity)
+
+# as result you get users JWT, it looks like this: "eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak"
+# you can provide users with JWT at registration or authorization steps
+# Send a JWT to client-side
+jwt_string = alice_jwt.to_s
+```
+
+### Manage a JWT
+
+Each JWT consists of three parts: the `header`, the `payload`, and the `signature`.
+
+```ruby
+# JWT Token structure
+header.payload.signature
+```
+#### Header
+
+The header contains information about how the JWT signature should be computed. The header is a JSON object in the following format:
+```ruby
+{
+  # the type of token. It MUST be "JWT"
+  "typ": "JWT",
+  # Signature algorithm. Currently supports only "VEDS512" (Virgil EdDSA SHA512)
+  "alg": "VEDS512",
+  # the content-type. It MUST be "virgil-jwt;v=1
+  "cty": "virgil-jwt;v=1",
+  # fingerprint of public key, that will be used to verify token. Equals to first 8 bytes of SHA512 of Public Key in DER format
+  "kid": "70b447e321f3a0fd"
+}
+```
+
+#### Payload
+
+The payload is the data that‘s stored inside the JWT (this data is also referred to as the “claims” of the JWT). In our example, the Application server creates a JWT with the user information stored inside of it.
+```ruby
+{
+  # Issuer. Equals to virgil-
+  "iss": "virgil-be00e10e4e1f4bf58f9b4dc85d79c77a",
+  # Subject. Equals to identity-
+  "sub": "identity-Alice",
+  # Issued at. Utc timestamp that indicates when token was issued.
+  "iat": 1518612517,
+  # Expires at. Utc timestamp that shows when token will expire. Tokens have a maximum age of 24 hours
+  "exp": 1518698917
+}
+```
+Keep in mind that the size of the data will affect the overall size of the JWT. This generally isn’t an issue but having excessively large JWT may negatively affect performance and cause latency.
+
+#### Signature
+
+The signature section is a signed hash that serves to prove the authenticity of the token. It is compiled by hashing the JWT header and payload together with your API Key secret, which should only be known to your application and Virgil.
+The signature is computed using the following pseudo code:
+```ruby
+# Signature
+signature = Base64.urlsafe_encode64(EdDSA+SHA512(SHA512(Base64.urlsafe_encode64(header) + "." + Base64.urlsafe_encode64(payload))))
+```
+Base64.urlsafe_encode64 encodes the header and the payload that was created in steps 1 and 2. The algorithm then joins the resulting encoded strings together with a period `(.)` in between them. To get the JWT signature, the data string is hashed with the secret key using the hashing algorithm specified in the JWT header.
+Then, using the joined encoded header and payload and applying the specified signature algorithm(HS256) on the data string with the secret key set as the string “secret”, we get the JWT Signature.
+Now that we have created all three components, we can create the JWT. Remembering the header.payload.signature structure of the JWT, we simply need to combine the components with periods `(.)` separating them. We use the Base64.urlsafe_encode64 encoded versions of the `header` and of the `payload`, and the `signature`.
+
+Here is an example of JWT:
+
+```ruby
+# JWT Token
+eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak
+```
+
+It is important to understand that the purpose of using JWT is NOT to hide or obscure data in any way. The reason why JWT is used is to prove that the sent data was actually created by an authentic source.
+You can try creating your own JWT through your browser at [jwt.io](https://jwt.io).
+
+## Installation
+
+TThe Virgil JWT is provided as a [gem](https://rubygems.org/) named [*virgil-jwt*](https://rubygems.org/gems/virgil-jwt) and available for Ruby 2.1 and newer. The package is distributed via *bundler* package manager.
+ 
+ To install the package use the command below:
+ 
+ ```
+ gem install virgil-crypto
+ gem install virgil-jwt
+ ```
+ 
+ or add the following line to your Gemfile:
+ 
+ ```
+ gem 'virgil-crypto', '~> 3.6.2'
+ gem 'virgil-jwt'
+ ```
+and then run
+
+```
+bundle
+```
+## Docs
+- [Crypto Core Library](https://github.com/VirgilSecurity/virgil-crypto)
+- [More usage examples](https://developer.virgilsecurity.com/docs/how-to#cryptography)
+
+## License
+
+This library is released under the [3-clause BSD License](https://github.com/VirgilSecurity/virgil-sdk-javascript/blob/master/LICENSE).
+
+## Support
+Our developer support team is here to help you. Find out more information on our [Help Center](https://help.virgilsecurity.com/).
+
+You can find us on [Twitter](https://twitter.com/VirgilSecurity) or send us email support@VirgilSecurity.com.
+
+Also, get extra help from our support team on [Slack](https://virgilsecurity.com/join-community).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "virgil/sdk/ruby/jwt"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/virgil-sdk-ruby-jwt

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require "virgil/sdk/ruby/jwt"

data/lib/virgil/jwt.rb

@@ -0,0 +1,14 @@
+require 'virgil/jwt/version'
+require 'virgil/jwt/access_token'
+require 'virgil/jwt/access_token_provider'
+require 'virgil/jwt/bytes'
+require 'virgil/jwt/caching_jwt_provider'
+require 'virgil/jwt/callback_jwt_provider'
+require 'virgil/jwt/const_access_token_provider'
+require 'virgil/jwt/token_context'
+require 'virgil/jwt/jwt'
+require 'virgil/jwt/jwt_body_content'
+require 'virgil/jwt/jwt_generator'
+require 'virgil/jwt/jwt_header_content'
+require 'virgil/jwt/validation'
+require 'virgil/jwt/jwt_verifier'

data/lib/virgil/jwt/access_token.rb

@@ -0,0 +1,51 @@
+# Copyright (C) 2015-2019 Virgil Security Inc.
+#
+# Lead Maintainer: Virgil Security Inc. <support@virgilsecurity.com>
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#   (1) Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+#
+#   (2) Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in
+#   the documentation and/or other materials provided with the
+#   distribution.
+#
+#   (3) Neither the name of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ''AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+# INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, bytes, OR PROFITS; OR BUSINESS INTERRUPTION)
+# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+# STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+# IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+module Virgil
+  module Jwt
+    class AccessToken
+      # Gets token identity.
+      # @return [String]
+      def identity
+        raise NotImplementedError
+      end
+
+      # Gets token string representation.
+      # @return [String]
+      def string_representation
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/virgil/jwt/access_token_provider.rb

@@ -0,0 +1,46 @@
+# Copyright (C) 2015-2019 Virgil Security Inc.
+#
+# Lead Maintainer: Virgil Security Inc. <support@virgilsecurity.com>
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#   (1) Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+#
+#   (2) Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in
+#   the documentation and/or other materials provided with the
+#   distribution.
+#
+#   (3) Neither the name of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ''AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+# INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, bytes, OR PROFITS; OR BUSINESS INTERRUPTION)
+# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+# STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+# IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+module Virgil
+  module Jwt
+    class AccessTokenProvider
+      # Gets access token.
+      # @param token_context [TokenContext]
+      # @return [AccessToken] Access token
+      def get_token(token_context)
+        raise NotImplementedError
+      end
+    end
+  end
+end