keypairs 0.1.0.alpha.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6674e2a0a6b9e2a995950c220252b13402d1410d58d2102819cf10811275a50
-  data.tar.gz: dfd6fa3397cbce88a13b405fcf5c4f6fea0dfa20fcd94daba6d7247f0c33aca9
+  metadata.gz: b27173f10b5fa527f4bc1c1ea863ee154735fa91afd45b0b050fc07e30d3d4c1
+  data.tar.gz: 471a038be596fec5dcac92e16923fde534348288abd000c9a235178244dff4ee
 SHA512:
-  metadata.gz: c92758e1f8552b5cc461790e7779a2526d21580a962c8de2126ed441f19a548273fe049924dbf1e80e92edb08becb84fdb00a7877142a9cfcd600bc474df1977
-  data.tar.gz: d689d8a570e11ff872174a5163411427f9cd189fff972976741bae5c89b01624096f3646bb6194257e8698d6c3e7fe554faf20726b6992bc011e37a6094b7353
+  metadata.gz: 7da952c440fb88a52457fa801ac78ea318cdccd7514b44187f5fd7701c36d72e83dbbc6c436789b9fb029680b6c1b4f9197c69bcca7449b74bdc09b00ded9d94
+  data.tar.gz: 8bb70edb0ea21824d99841414f3b02bfa467f5e420c3fb7ae1ca61ee593a491123ea7826f455f549beb42f8408399d78afb15a227a399f298f5e8d41ebae15b3

data/README.md

@@ -4,13 +4,28 @@ Applications often need to have a public/private keypair so sign messages. This
 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:
+1. **Add gem**
 
-```ruby
-gem 'keypairs'
-```
+   Add this line to your application's Gemfile:
+   
+   ```ruby
+   gem 'keypairs'
+   ```
+   
+   The of course run `bundle install`. 
+
+2. **Copy migration**
+
+   The default migration file can be copied to your app with:
+   ```bash
+   bundle exec rails keypairs:install:migrations
+   ```
+   
+   Then of course run `bundle exec rails db:migrate`
+
+3. **Setup encryption key**
 
-The of course run `bundle install` and run the migrations `bundle exec rake db:migrate`. The migrations from the gem run automatically.
+   The private keys are encrypted with the [lockbox](https://github.com/ankane/lockbox) gem. In order for this to work, you need to set the master key as described in [the readme](https://github.com/ankane/lockbox#key-generation), but the easiest thing is to set the environment variable `LOCKBOX_MASTER_KEY` to a sufficient long string (you can generate one with `Lockbox.generate_key`).
 
 ## 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.

data/db/migrate/20201024100500_create_keypairs.rb

@@ -4,8 +4,7 @@ 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.text :_keypair_ciphertext, null: false
       t.timestamps precision: 6
       # Since we are ordering on created_at, let's create an index
       t.index :created_at

data/db/migrate/20201116144600_add_validity_to_keypairs.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class AddValidityToKeypairs < ActiveRecord::Migration[6.0]
+  class Keypair < ActiveRecord::Base; end
+
+  def change # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    change_table :keypairs, bulk: true do |t|
+      t.datetime :not_before, precision: 6
+      t.datetime :not_after, precision: 6
+      t.datetime :expires_at, precision: 6
+    end
+
+    reversible do |dir|
+      dir.up do
+        Keypair.find_each do |keypair|
+          keypair.update!(
+            not_before: keypair.created_at,
+            not_after: keypair.created_at + 1.month,
+            expires_at: keypair.created_at + 2.months
+          )
+        end
+      end
+    end
+
+    change_column_null :keypairs, :not_before, false
+    change_column_null :keypairs, :not_after, false
+    change_column_null :keypairs, :expires_at, false
+  end
+end

data/{app/models → lib}/keypair.rb

@@ -1,13 +1,23 @@
 # frozen_string_literal: true
 
-require 'attr_encrypted'
+require 'lockbox'
 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.
+# Keypairs are considered valid based on their {#not_before}, {#not_after} and {#expires_at} attributes.
+#
+# A keypair can be used for signing if:
+# - The current time is greater than or equal to {#not_before}
+# - The current time is less than or equal to {#not_after}
+#
+# A keypair can be used for validation if:
+# - The current time is less than {#expires_at}.
+#
+# By default, this means that when a key is created, it can be used for signing for 1 month and can still be used
+# for signature validation 1 month after it is not used for signing (i.e. for 2 months since it started being used
+# for signing).
 #
 # If you need to sign messages, use the {Keypair.current} keypair for this. This method
 # performs the rotation of the keypairs if required.
@@ -21,25 +31,36 @@ require 'jwt'
 #   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.
+# @attr [Time] not_before The time before which no payloads may be signed using the keypair.
+# @attr [Time] not_after The time after which no payloads may be signed using the keypair.
+# @attr [Time] expires_at The time after which the keypair may not be used for signature validation.
 class Keypair < ActiveRecord::Base
   ALGORITHM = 'RS256'
+  ROTATION_INTERVAL = 1.month
 
-  attr_encrypted :_keypair, key: Rails.application.secrets.secret_key_base[0, 32]
+  encrypts :_keypair
 
   validates :_keypair, presence: true
   validates :jwk_kid, presence: true
+  validates :not_before, :expires_at, presence: true
+
+  validate :not_after_after_not_before
+  validate :expires_at_after_not_after
 
   after_initialize :set_keypair
+  after_initialize :set_validity
 
   # @!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)) }
+  #   Non-expired keypairs are considered valid and can be used to validate signatures and export public jwks.
+  scope :valid, -> { where(arel_table[:expires_at].gt(Time.zone.now)) }
 
-  # @return [Keypair] the keypair used to sign messages and autorotates if it is older than 1 month.
+  # @return [Keypair] the keypair used to sign messages and autorotates if it has expired.
   def self.current
-    order(:created_at).where(arel_table[:created_at].gt(1.month.ago)).last || create!
+    order(not_before: :asc)
+      .where(arel_table[:not_before].lteq(Time.zone.now))
+      .where(arel_table[:not_after].gteq(Time.zone.now))
+      .last || create!
   end
 
   # The JWK Set of our valid keypairs.
@@ -65,11 +86,26 @@ class Keypair < ActiveRecord::Base
   #
   # @see https://www.imsglobal.org/spec/security/v1p0/#h_key-set-url
   def self.keyset
+    valid_keys = valid.order(not_before: :asc).to_a
+    # If we don't have any keys or if we don't have a future key (i.e. the last key is the current key)
+    while valid_keys.last.nil? || valid_keys.last.not_before <= Time.zone.now
+      # There is an automatic fallback to Time.zone.now if not_before is not set
+      valid_keys << create!(not_before: valid_keys.last&.not_after)
+    end
+
     {
-      keys: valid.order(created_at: :desc).map(&:public_jwk_export)
+      keys: valid_keys.map(&:public_jwk_export)
     }
   end
 
+  # @return [Hash] a cached version of the keyset
+  # @see #keyset
+  def self.cached_keyset
+    Rails.cache.fetch('keypairs/Keypair/keyset', expires_in: 12.hours) do
+      keyset
+    end
+  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.
@@ -172,4 +208,25 @@ class Keypair < ActiveRecord::Base
     self._keypair ||= OpenSSL::PKey::RSA.new(2048).to_pem
     self.jwk_kid = public_jwk.kid
   end
+
+  # Set the validity timestamps based on the rotation interval.
+  def set_validity
+    self.not_before ||= created_at || Time.zone.now
+    self.not_after ||= not_before + ROTATION_INTERVAL
+    self.expires_at ||= not_after + ROTATION_INTERVAL
+  end
+
+  def not_after_after_not_before
+    return if not_before.nil? || not_after.nil?
+    return if not_after > not_before
+
+    errors.add(:not_after, 'must be after not before')
+  end
+
+  def expires_at_after_not_after
+    return if not_after.nil? || expires_at.nil?
+    return if expires_at > not_after
+
+    errors.add(:expires_at, 'must be after not after')
+  end
 end

data/lib/keypairs/engine.rb

@@ -1,18 +1,8 @@
 # frozen_string_literal: true
 
 module Keypairs
-  # Rails engine for this gem.
-  # It ensures that the migrations are automatically ran in the applications.
+  # This engine is only needed to add the migration installation rake task.
   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
+    engine_name 'keypairs'
   end
 end

data/{app/controllers → lib}/keypairs/public_keys_controller.rb

@@ -18,7 +18,9 @@ module Keypairs
   #  }
   class PublicKeysController < ActionController::API
     def index
-      render json: Keypair.keyset
+      # Always cache for 1 week, our rotation interval is much more than a week
+      expires_in 1.week, public: true
+      render json: Keypair.cached_keyset
     end
   end
 end

data/lib/keypairs/version.rb

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

data/lib/keypairs.rb

@@ -1,3 +1,12 @@
 # frozen_string_literal: true
 
-require 'keypairs/engine'
+require 'lockbox'
+
+autoload :Keypair, 'keypair.rb'
+
+# The Keypairs module contains common functionality in support of the {Keypair} model.
+module Keypairs
+  autoload :PublicKeysController, 'keypairs/public_keys_controller'
+end
+
+require 'keypairs/engine' if defined?(Rails)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: keypairs
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Stef Schenkelaars
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-24 00:00:00.000000000 Z
+date: 2021-12-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -39,33 +39,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '6.0'
 - !ruby/object:Gem::Dependency
-  name: attr_encrypted
+  name: jwt
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '2.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
-  name: jwt
+  name: lockbox
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: brakeman
   requirement: !ruby/object:Gem::Requirement
@@ -206,6 +206,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  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
@@ -215,11 +229,12 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
-- app/controllers/keypairs/public_keys_controller.rb
-- app/models/keypair.rb
 - db/migrate/20201024100500_create_keypairs.rb
+- db/migrate/20201116144600_add_validity_to_keypairs.rb
+- lib/keypair.rb
 - lib/keypairs.rb
 - lib/keypairs/engine.rb
+- lib/keypairs/public_keys_controller.rb
 - lib/keypairs/version.rb
 homepage: https://drieam.github.io/keypairs
 licenses:
@@ -235,12 +250,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.1.4
 signing_key: