keypairs 0.1.0.alpha.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c6674e2a0a6b9e2a995950c220252b13402d1410d58d2102819cf10811275a50
+  data.tar.gz: dfd6fa3397cbce88a13b405fcf5c4f6fea0dfa20fcd94daba6d7247f0c33aca9
+SHA512:
+  metadata.gz: c92758e1f8552b5cc461790e7779a2526d21580a962c8de2126ed441f19a548273fe049924dbf1e80e92edb08becb84fdb00a7877142a9cfcd600bc474df1977
+  data.tar.gz: d689d8a570e11ff872174a5163411427f9cd189fff972976741bae5c89b01624096f3646bb6194257e8698d6c3e7fe554faf20726b6992bc011e37a6094b7353

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Stef Schenkelaars
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,57 @@
+# Keypairs
+Applications often need to have a public/private keypair so sign messages. This gem manages your application level key pairs with automatic rotation and support for encoding and decoding [JWTs](https://jwt.io/).
+
+Note: This gem is intended to work within Rails applications. It can probably be adjusted easily to also work for non-rails / sinatra project but that's out of scope for now. 
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'keypairs'
+```
+
+The of course run `bundle install` and run the migrations `bundle exec rake db:migrate`. The migrations from the gem run automatically.
+
+## Usage
+The central point of this gem is the `Keypair` model which is backed by the `keypairs` table. If you need to sign messages, you can get the current keypair with the `Keypair.current` method. This method performs the rotation of the keypairs if required.
+
+You can access the private an public key of the keypair (`OpenSSL::PKey::RSA`) and encrypt and decrypt messages with them:
+
+```ruby
+encoded_message = Keypair.current.private_key.private_decrypt('foobar')
+Keypair.current.public_key.public_decrypt(encoded_message)
+# => 'foobar'
+```
+
+### JWT support
+You can encode and decode JWTs directly on the class:
+```ruby 
+payload = { foo: 'bar' }
+id_token = Keypair.jwt_encode(payload)
+decoded = Keypair.jwt_decode(id_token)
+```
+
+It's almost always a good idea to add a subject to your payload and pass the same subject during decoding. That way you know that users don't use a key for other purposes (for example a key intended for an OAuth2 flow used as a session key). So for example:
+
+```ruby
+subject = 'MyAppSession'
+payload = { foo: 'bar', subject: subject }
+id_token = Keypair.jwt_encode(payload)
+decoded = Keypair.jwt_decode(id_token, subject: subject)
+``` 
+
+### Exposing public keys
+If you want others to validate your messages based on the public keys, you can share the JWK version of you current keys by adding them to your `config/routes.rb`:
+
+```ruby
+get :jwks, to: Keypairs::PublicKeysController.action(:index)
+```
+
+## Releasing new version
+Publishing a new version is handled by the publish workflow. This workflow publishes a GitHub release to rubygems and GitHub package registry with the version defined in the release.
+
+## Contributing
+Bug reports and pull requests are welcome on GitHub at https://github.com/Drieam/keypairs.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/keypairs/public_keys_controller.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Keypairs
+  # Endpoint to fetch the current valid keypairs.
+  #
+  # @example
+  #  {
+  #    "keys": [
+  #      {
+  #        "kty": "RSA",
+  #        "n": "wmi......1Gw",
+  #        "e": "AQAB",
+  #        "kid": "d8d1d4265d6c34acadce8a42fbbec167db1beaeb6ebbbf7fd555f6eb00bda76e",
+  #        "alg": "RS256",
+  #        "use": "sig"
+  #      }
+  #    ]
+  #  }
+  class PublicKeysController < ActionController::API
+    def index
+      render json: Keypair.keyset
+    end
+  end
+end

data/app/models/keypair.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require 'attr_encrypted'
+require 'jwt'
+
+# This class contains functionality needed for signing messages
+# and publishing JWK[s].
+#
+# The last three created keypairs are considered valid, so creating a new Keypair
+# will invalidate the second to last created Keypair.
+#
+# If you need to sign messages, use the {Keypair.current} keypair for this. This method
+# performs the rotation of the keypairs if required.
+#
+# You can also use the +jwt_encode+ and +jwt_decode+ methods directly to encode and
+# securely decode your payloads
+#
+# @example
+#   payload = { foo: 'bar' }
+#   id_token = Keypair.jwt_encode(payload)
+#   decoded = Keypair.jwt_decode(id_token)
+#
+# @attr [String] jwk_kid The public external id of the key used to find the associated key on decoding.
+class Keypair < ActiveRecord::Base
+  ALGORITHM = 'RS256'
+
+  attr_encrypted :_keypair, key: Rails.application.secrets.secret_key_base[0, 32]
+
+  validates :_keypair, presence: true
+  validates :jwk_kid, presence: true
+
+  after_initialize :set_keypair
+
+  # @!method valid
+  #   @!scope class
+  #   The last 3 keypairs are considered valid and can be used to validate signatures and export public jwks.
+  #   It uses a subquery to make sure a +find_by+ actually searches only the valid 3 ones.
+  scope :valid, -> { where(id: unscoped.order(created_at: :desc).limit(3)) }
+
+  # @return [Keypair] the keypair used to sign messages and autorotates if it is older than 1 month.
+  def self.current
+    order(:created_at).where(arel_table[:created_at].gt(1.month.ago)).last || create!
+  end
+
+  # The JWK Set of our valid keypairs.
+  # @return [Hash]
+  # @example
+  #   {
+  #     keys: [{
+  #       e: "AQAB",
+  #       use: "sig",
+  #       alg: "RS256",
+  #       kty: "RSA",
+  #       n: "oNqXxxWuX7LlovO5reRNauF6TEFa-RRRl8Dw==...",
+  #       kid: "1516918956_0"
+  #     }, {
+  #       e: "AQAB",
+  #       use: "sig",
+  #       alg: "RS256",
+  #       kty: "RSA",
+  #       n: "kMfHwTp2dIYybtvU-xzF2E3dRJBNm6g5kTQi8itw==...",
+  #       kid: "1516918956_1"
+  #     }]
+  #   }
+  #
+  # @see https://www.imsglobal.org/spec/security/v1p0/#h_key-set-url
+  def self.keyset
+    {
+      keys: valid.order(created_at: :desc).map(&:public_jwk_export)
+    }
+  end
+
+  # Encodes the payload with the current keypair.
+  # It forewards the call to the instance method {Keypair#jwt_encode}.
+  # @return [String] Encoded JWT token with security credentials.
+  # @param payload [Hash] Hash which should be encoded.
+  def self.jwt_encode(payload)
+    current.jwt_encode(payload)
+  end
+
+  # Decodes the payload and verifies the signature against the current valid keypairs.
+  # @param id_token [String] A JWT that should be decoded.
+  # @param options [Hash] options for decoding, passed to {JWT::Decode}.
+  # @raise [JWT::DecodeError] or any of it's subclasses if the decoding / validation fails.
+  # @return [Hash] Decoded payload hash with indifferent access.
+  def self.jwt_decode(id_token, options = {})
+    # Add default decoding options
+    options.reverse_merge!(
+      # Change the default algorithm to match the encoding algorithm
+      algorithm: ALGORITHM,
+      # Load our own keyset as valid keys
+      jwks: keyset,
+      # If the `sub` is provided, validate that it matches the payload `sub`
+      verify_sub: true
+    )
+    JWT.decode(id_token, nil, true, options).first.with_indifferent_access
+  end
+
+  # JWT encodes the payload with this keypair.
+  # It automatically adds the security attributes +iat+, +exp+ and +nonce+ to the payload.
+  # It automatically sets the +kid+ in the header.
+  # @param payload [Hash] you have to provide a hash since the security attributes have to be added.
+  # @param headers [Hash] you can optionally add additional headers to the JWT.
+  def jwt_encode(payload, headers = {})
+    # Add security claims to payload
+    payload.reverse_merge!(
+      # Time at which the Issuer generated the JWT (epoch).
+      iat: Time.now.to_i,
+
+      # Expiration time on or after which the tool MUST NOT accept the ID Token for
+      # processing (epoch). This is mostly used to allow some clock skew.
+      exp: Time.now.to_i + 5.minutes.to_i,
+
+      # String value used to associate a tool session with an ID Token, and to mitigate replay
+      # attacks. The nonce value is a case-sensitive string.
+      nonce: SecureRandom.uuid
+    )
+
+    # Add additional info into the headers
+    headers.reverse_merge!(
+      # Set the id of they key
+      kid: jwk_kid
+    )
+
+    JWT.encode(payload, private_key, ALGORITHM, headers)
+  end
+
+  # Public representation of the keypair in the JWK format.
+  # We append the +alg+, and +use+ parameters to our JWK to indicate
+  # that our intended use is to generate signatures using +RS256+.
+  #
+  # +alg+::
+  #   This (algorithm) parameter identifies the algorithm intended for use with the key.
+  #   It is based in the {Keypair::ALGORITHM}.
+  #   The IMS Security framework specifies that the +alg+ value SHOULD be the default of +RS256+.
+  #   Use of this member is OPTIONAL.
+  # +use+::
+  #   This (public key use) parameter identifies the intended use of the public key.
+  #   Use of this member is OPTIONAL, unless the application requires its presence.
+  #
+  # @see https://tools.ietf.org/html/rfc7517#section-4.4
+  # @see https://www.imsglobal.org/spec/security/v1p0#authentication-response-validation
+  def public_jwk_export
+    public_jwk.export.merge(
+      alg: ALGORITHM,
+      use: 'sig'
+    )
+  end
+
+  # @return [OpenSSL::PKey::RSA] {OpenSSL::PKey::RSA} instance loaded with our keypair.
+  def private_key
+    OpenSSL::PKey::RSA.new(_keypair)
+  end
+
+  # @return [OpenSSL::PKey::RSA] {OpenSSL::PKey::RSA} instance loaded with the public part our keypair.
+  delegate :public_key, to: :private_key
+
+  private
+
+  # @return [JWT::JWK] {JWT::JWK} instance with the public part of our keypair.
+  def public_jwk
+    JWT::JWK.create_from(public_key)
+  end
+
+  # Generate a new keypair with a key_size of 2048. Keys less than 1024 bits should be
+  # considered insecure.
+  #
+  # See:
+  # https://ruby-doc.org/stdlib-2.6.5/libdoc/openssl/rdoc/OpenSSL/PKey/RSA.html#method-c-new
+  def set_keypair
+    # The generated keypair is stored in PEM encoding.
+    self._keypair ||= OpenSSL::PKey::RSA.new(2048).to_pem
+    self.jwk_kid = public_jwk.kid
+  end
+end

data/db/migrate/20201024100500_create_keypairs.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class CreateKeypairs < ActiveRecord::Migration[6.0]
+  def change
+    create_table :keypairs do |t|
+      t.string :jwk_kid, null: false
+      t.string :encrypted__keypair, null: false
+      t.string :encrypted__keypair_iv, null: false
+      t.timestamps precision: 6
+      # Since we are ordering on created_at, let's create an index
+      t.index :created_at
+      t.index :jwk_kid, unique: true
+    end
+  end
+end

data/lib/keypairs.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'keypairs/engine'

data/lib/keypairs/engine.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Keypairs
+  # Rails engine for this gem.
+  # It ensures that the migrations are automatically ran in the applications.
+  class Engine < ::Rails::Engine
+    initializer :append_migrations do |app|
+      unless app.root.to_s.match? "#{root}/"
+        config.paths['db/migrate'].expanded.each do |expanded_path|
+          app.config.paths['db/migrate'] << expanded_path
+        end
+        # Apartment will modify this, but it doesn't fully support engine migrations,
+        # so we'll reset it here
+        ActiveRecord::Migrator.migrations_paths = app.paths['db/migrate'].to_a
+      end
+    end
+  end
+end

data/lib/keypairs/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Keypairs
+  VERSION = '0.1.0.alpha.1'
+end

metadata

@@ -0,0 +1,249 @@
+--- !ruby/object:Gem::Specification
+name: keypairs
+version: !ruby/object:Gem::Version
+  version: 0.1.0.alpha.1
+platform: ruby
+authors:
+- Stef Schenkelaars
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-10-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: attr_encrypted
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: brakeman
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: combustion
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner-active_record
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-github
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: shoulda-matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Manage application level keypairs with automatic rotation and JWT support
+email:
+- stef.schenkelaars@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- app/controllers/keypairs/public_keys_controller.rb
+- app/models/keypair.rb
+- db/migrate/20201024100500_create_keypairs.rb
+- lib/keypairs.rb
+- lib/keypairs/engine.rb
+- lib/keypairs/version.rb
+homepage: https://drieam.github.io/keypairs
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://drieam.github.io/keypairs
+  source_code_uri: https://github.com/Drieam/keypairs
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.1.4
+signing_key: 
+specification_version: 4
+summary: Manage application level keypairs with automatic rotation and JWT support
+test_files: []