clarion 0.1.0

data/docs/api.md

@@ -0,0 +1,113 @@
+# Clarion API
+
+- Registration flow:
+  - _app_ redirects or submits `<form>` post to `/register`
+  - _Clarion_ does key registration work with user
+  - _Clarion_ redirects user back to a specified _callback_ 
+  - _app_ stores the key information
+- Authentication flow:
+  - _app_ requests _Clarion_ for authentication (POST `/api/authn`)
+  - _app_ navigates user to authentication URL presented by _Clarion_
+  - _Clarion_ does U2F authentication work
+  - _app_ polls `/api/authn/:id` for authentication result
+
+Pro Tips: _app_ could be anything (browser, CLI, etc) and _app_ for registration, and _app_ for authentication may be different.
+
+## POST `/api/authn` (Request authentication)
+
+### Request
+
+application/json
+
+``` json
+{
+  "name": "USERNAME",
+  "comment": "COMMENT",
+  "keys": [
+    {
+      "handle": "KEYHANDLE",
+      "public_key": "PUBLICKEY",
+      "counter": COUNTER
+    }
+  ]
+}
+```
+
+### Response
+
+Same with /api/authn/:id
+
+## GET `/api/authn/:id` (Check authentication result)
+
+### Request
+
+- `:id` authn ID
+
+### Response
+
+``` json
+{
+  "authn": {
+    "id": "AUTHN_ID",
+    "expires_at": "EXPIRY",
+    "html_url": "HTML_URL",
+    "url": "API_URL",
+    "status": "STATUS",
+    "verified_at": "VERIFIED_AT",
+    "verified_key": {
+      "handle": "KEYHANDLE",
+      "public_key": "PUBLICKEY",
+      "counter": COUNTER
+    }
+  }
+}
+```
+
+## GET/POST `/register` (Security Key Registration page)
+
+Navigate user to this page for key registration. Clarion redirects back to _callback_ with registered key information.
+
+### Request
+
+form encoded body on POST, or query string on GET
+
+```
+name=NAME&comment=COMMENT&state=STATE&callback=CALLBACK&public_key=PUBKEY
+```
+
+CALLBACK may start with `js:`, when `js:$ORIGIN` (where `$ORIGIN` is a page origin) is specified, `/register` page will return a result using [window.opener.postMessage()](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).
+
+### Response
+
+HTML for user
+
+## POST (callback) (Security Key Registration callback)
+
+callback (by redirection) that notifies key registration, with the registered key information to the _app_
+
+### Request
+
+form encoded
+
+```
+state=STATE&data=DATA
+```
+
+- `DATA` is a JSON string `{"data": "ENCRYPT_DATA_BASE64", "key": "ENCRYPTED_SHARED_KEY_BASE64"}`.
+  - `ENCRYPTED_SHARED_KEY_BASE64` contains base64 encoded binary, which is a encrypted JSON string using the given RSA public key to `/register`.
+    - it's decrypted like as `{"iv": "IV_BASE64", "tag": "TAG_BASE64", "key": "KEY_BASE64"}`.
+    - `IV_BASE64` is a base64 encoded IV.
+    - `TAG_BASE64` is a AES-GCM auth tag.
+    - `KEY_BASE64` is a base64 encoded shared key used for AES-256-GCM.
+  - `ENCRYPTED_DATA_BASE64` is a base64 encoded binary, which is a AES-256-GCM encrypted JSON string. Use `IV_BASE64`, `TAG_BASE64`, `KEY_BASE64` to decrypt.
+
+`ENCRYPTED_DATA_BASE64` decrypted as like the following JSON string:
+
+``` json
+{
+  "name": "KEYNAME",
+  "handle": "KEYHANDLE",
+  "public_key": "PUBLICKEY"
+}
+```
+

data/docs/counters.md

@@ -0,0 +1,14 @@
+# Counters
+
+Clarion _counter_ is responsible to store U2F device counters. It's optional but highly recommended to set up.
+
+## `memory`: Memory
+
+Memory store for development purpose.
+
+## `dynamodb`: AWS DynamoDB
+
+- `table_name`
+- `region`
+
+Table should have partition key `handle` (String).

data/docs/stores.md

@@ -0,0 +1,13 @@
+# Stores
+
+Clarion _store_ is responsible to store in-progress authentication data.
+
+## `memory`: Memory
+
+Memory store for development purpose.
+
+## `s3`: Amazon S3
+
+- `region`
+- `bucket`
+- `prefix` (recommended to end with `/`)

data/lib/clarion.rb

@@ -0,0 +1,3 @@
+require 'clarion/config'
+require 'clarion/app'
+require "clarion/version"

data/lib/clarion/app.rb

@@ -0,0 +1,271 @@
+require 'erubis'
+require 'sinatra/base'
+require 'u2f'
+require 'securerandom'
+
+require 'clarion/registrator'
+require 'clarion/authenticator'
+require 'clarion/authn'
+
+module Clarion
+  def self.app(*args)
+    App.rack(*args)
+  end
+
+  class App < Sinatra::Base
+    CONTEXT_RACK_ENV_NAME = 'clarion.ctx'
+
+    def self.initialize_context(config)
+      {
+        config: config,
+      }
+    end
+
+    def self.rack(config={})
+      klass = App
+
+      context = initialize_context(config)
+      lambda { |env|
+        env[CONTEXT_RACK_ENV_NAME] = context
+        klass.call(env)
+      }
+    end
+
+    configure do
+      enable :logging
+    end
+
+    set :root, File.expand_path(File.join(__dir__, '..', '..', 'app'))
+    set :erb, :escape_html => true
+
+    helpers do
+      def data
+        begin
+          @data = JSON.parse(request.body.tap(&:rewind).read, symbolize_names: true)
+        rescue JSON::ParserError
+          content_type :json
+          halt 400, '{"error": "invalid_payload"}'
+        end
+      end
+
+      def context
+        request.env[CONTEXT_RACK_ENV_NAME]
+      end
+
+      def conf
+        context[:config]
+      end
+
+      def u2f
+        @u2f ||= U2F::U2F.new(conf.app_id || request.base_url)
+      end
+
+      def counter
+        conf.counter
+      end
+
+      def store
+        conf.store
+      end
+
+      def render_authn_json(authn)
+        {
+          authn: authn.as_json.merge(
+            url: "#{request.base_url}/api/authn/#{authn.id}",
+            html_url: "#{request.base_url}/authn/#{authn.id}",
+          )
+        }.to_json
+      end
+    end
+
+    ## UI
+
+    get '/' do
+      content_type :text
+      "Clarion\n"
+    end
+
+    get '/authn/:id' do
+      @authn = store.find_authn(params[:id])
+      unless @authn
+        halt 404, "authn not found"
+      end
+      if @authn.verified?
+        halt 410, "Authn already processed"
+      end
+      if @authn.expired?
+        halt 410, "Authn expired"
+      end
+
+
+      authenticator = Authenticator.new(@authn, u2f, counter, store)
+      @app_id, @requests, @challenge = authenticator.request
+
+      @req_id = SecureRandom.urlsafe_base64(12)
+      session[:reqs] ||= {}
+      session[:reqs][@req_id] = {challenge: @challenge}
+
+      erb :authn
+    end
+
+    ## API (returns user-facing UI)
+
+    register = Proc.new do
+      unless params[:name] && params[:callback] && params[:public_key]
+        halt 400, 'missing params'
+      end
+      if params[:callback].start_with?('js:') && !(conf.registration_allowed_url === params[:callback])
+        halt 400, 'invalid callback'
+      end
+
+      public_key = begin
+        OpenSSL::PKey::RSA.new(params[:public_key].unpack('m*')[0], '')
+      rescue OpenSSL::PKey::RSAError
+        halt 400, 'invalid public key'
+      end
+
+      @reg_id = SecureRandom.urlsafe_base64(12)
+      registrator = Registrator.new(u2f, counter)
+      @app_id, @requests = registrator.request
+      session[:regs] ||= {}
+      session[:regs][@reg_id] = {
+        challenges: @requests.map(&:challenge),
+        key: public_key.to_der,
+      }
+
+      @callback = params[:callback]
+      @state = params[:state]
+      @name = params[:name]
+      @comment = params[:comment]
+      erb :register
+    end
+    get '/register', &register
+    post '/register', &register
+
+    ## Internal APIs (used from UI)
+
+    post '/ui/register' do
+      content_type :json
+      unless data[:reg_id] && data[:response]
+        halt 400, '{"error": "Missing params"}'
+      end
+
+      session[:regs] ||= {}
+      reg = session[:regs][data[:reg_id]]
+      unless reg && reg[:challenges] && reg[:key]
+        halt 400, '{"error": "Invalid :reg"}'
+      end
+
+      public_key = begin
+        OpenSSL::PKey::RSA.new(reg[:key], '') # der
+      rescue OpenSSL::PKey::RSAError
+        halt 400, '{"error": "Invalid public key"}'
+      end
+
+      registrator = Registrator.new(u2f, counter)
+      key = registrator.register!(reg[:challenges], data[:response])
+
+      session[:regs].delete(data[:reg_id])
+
+      {ok: true, encrypted_key: key.to_encrypted_json(public_key, :all)}.to_json
+    end
+
+    post '/ui/verify/:id' do
+      content_type :json
+      unless data[:req_id] && data[:response]
+        halt 400, '{"error": "missing params"}'
+      end
+      session[:reqs] ||= {}
+      unless session[:reqs][data[:req_id]]
+        halt 400, '{"error": "invalid :req_id"}'
+      end
+      challenge = session[:reqs][data[:req_id]][:challenge]
+      unless challenge
+        halt 400, '{"error": "invalid :req_id"}'
+      end
+
+      @authn = store.find_authn(params[:id])
+      unless @authn
+        halt 404, '{"error": "authn not found"}'
+      end
+      if @authn.verified?
+        halt 410, '{"error": "authn already processed"}'
+      end
+      if @authn.expired?
+        halt 410, '{"error": "authn expired"}'
+      end
+
+      authenticator = Authenticator.new(@authn, u2f, counter, store)
+
+      begin
+        authenticator.verify!(
+          challenge,
+          data[:response]
+        )
+      rescue U2F::Error => e
+        halt 400, {error: "U2F Error: #{e.message}"}.to_json
+      rescue Authenticator::InvalidKey => e
+        halt 400, {error: "It is an unregistered key"}.to_json
+      end
+
+      session[:reqs].delete data[:req_id]
+      '{"ok": true}'
+    end
+
+    ## API
+
+    post '/api/authn' do
+      content_type :json
+      @authn = begin
+        Authn.make(
+          name: data[:name],
+          comment: data[:comment],
+          keys: data[:keys],
+          expires_at: Time.now + conf.authn_default_expires_in,
+          status: :open,
+        )
+      rescue ArgumentError
+        halt 400, '{"error": "invalid params"}'
+      end
+      store.store_authn(@authn)
+      render_authn_json @authn
+    end
+
+    get '/api/authn/:id' do
+      content_type :json
+      @authn = store.find_authn(params[:id])
+      unless @authn
+        halt 404, '{"error": "authn not found"}'
+      end
+      render_authn_json @authn
+    end
+
+    ## Testing purpose
+    
+    get '/test' do
+      key = conf.options[:register_test_key] ||= OpenSSL::PKey::RSA.generate(2048)
+      @name = 'testuser'
+      @comment = 'test comment'
+      @register_url = "#{request.base_url}/register"
+      @callback =  "#{request.base_url}/test/callback"
+      @public_key = [key.public_key.to_der].pack('m*').gsub(/\r?\n/, '')
+      @state = SecureRandom.urlsafe_base64(12)
+      erb :test
+    end
+
+    post '/test/callback' do
+      key = conf.options[:register_test_key] ||= OpenSSL::PKey::RSA.generate(2048)
+      if params[:data]
+        @state = params[:state]
+        json = params[:data]
+        @key = Key.from_encrypted_json(key, json)
+      elsif params[:key]
+        @state = 'dummy'
+        @key = Key.new(**JSON.parse(params[:key], symbolize_names))
+      else
+        halt 400, "what?"
+      end
+      erb :test_callback
+    end
+  end
+end

data/lib/clarion/authenticator.rb

@@ -0,0 +1,51 @@
+require 'base64'
+require 'u2f'
+
+module Clarion
+  class Authenticator
+    class Error < StandardError; end
+    class InvalidKey < Error; end
+
+    def initialize(authn, u2f, counter, store)
+      @authn = authn
+      @u2f = u2f
+      @counter = counter
+      @store = store
+    end
+
+    attr_reader :authn, :u2f, :counter, :store
+
+    def request
+      [u2f.app_id, u2f.authentication_requests(authn.keys.map(&:handle)), u2f.challenge]
+    end
+
+    def verify!(challenge, response_json)
+      response = U2F::SignResponse.load_from_json(response_json)
+      key = authn.key_for_handle(response.key_handle)
+      unless key
+        raise InvalidKey, "#{response.key_handle.inspect} is invalid token for authn #{authn.id}"
+      end
+      count = counter ? counter.get(key) : 0
+
+      u2f.authenticate!(
+        challenge,
+        response,
+        Base64.decode64(key.public_key),
+        count,
+      )
+
+      unless authn.verify(key)
+        raise Authenticator::InvalidKey
+      end
+
+      key.counter = response.counter
+      if counter
+        counter.store(key)
+      end
+
+      store.store_authn(authn)
+
+      true
+    end
+  end
+end