potp 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 572944d75dff4240e25ec32bb91202acd04ce07b2dea52e585fb765bf579076d
+  data.tar.gz: 633ba7f0dac49a1c66d71680a030571b32185806adf6e9e9111bc5561d937865
+SHA512:
+  metadata.gz: 4e6b4d5efe9da1b692486e28a56fcf20f4c858a99bb7d870889c4cee21540fff2061589088ba01917333dcf83ec9d3293e4e9741d79d468fac039d5913b0bef2
+  data.tar.gz: 5ed1543a5214cb4be08e1b0b54d7ebff17833ed7442757bc7a5605356d52860967d136bf0ed2a0eb3629024797d65df313dd70ab198dd1b3397b412740744c5f

data/LICENSE

@@ -0,0 +1,52 @@
+# BSD-2-clause license, extended by language use conditions
+
+Copyright (C) 2024, Bertram Scharpf <software@bertram-scharpf.de>.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+  * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+
+  * 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.
+
+  * Redistributions must not contain any clauses about anticipated
+    harassment or discrimination, nor must they be held in a so-called
+    "inclusive language". As far as German language is used, the
+    conditions mentioned below additionally apply.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "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 COPYRIGHT OWNER
+OR CONTRIBUTORS 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, DATA, 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.
+
+
+## Use of the German Language
+
+Beim Gebrauch deutscher Sprache sind Weiterentwicklungen und
+-verbreitungen nur gestattet unter Einhaltung sowie abermaligen
+Einforderns folgender zusätzlicher Bedingungen:
+
+  * Keine Verwendung von sogenannter „geschlechtergerechter Sprache“,
+    also Anfügen von weiblichen Endungen mit Binnen-I, Sternchen,
+    Doppelpunkt, Unterstrich oder ähnlichem, oder Konstruktionen, die
+    den Sachverhalt falsch wiedergeben („Radfahrende“, „Studierende“).
+
+  * Keine Verwendung der „reformierten Rechtschreibung“ von 1996,
+    insbesondere Doppel-S am Silbenende, „plazieren“ mit T, sowie
+    Großschreibung von Wendungen wie „des weiteren“.
+
+
+<!-- vim:set ft=markdown : -->

data/README.md

@@ -0,0 +1,142 @@
+# The Plain One Time Password Library
+
+A ruby library for generating and validating one time passwords (HOTP & TOTP)
+according to
+[RFC 4226](https://datatracker.ietf.org/doc/html/rfc4226)
+and
+[RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238).
+
+POTP aims to be compatible with
+[Google Authenticator](https://github.com/google/google-authenticator).
+
+The Base32 format conforms to
+[RFC 4648 Base32](http://en.wikipedia.org/wiki/Base32#Base_32_Encoding_per_§6)
+
+
+## Installation
+
+```bash
+sudo gem install potp
+```
+
+If you like to run the executable (instead of writing a one-liner for
+yourself), you have to install the `appl` gem.
+
+```bash
+sudo gem install appl
+```
+
+
+## Library Usage
+
+### Time based (TOTP)
+
+```ruby
+require "potp"
+
+totp = POTP::TOTP.new "GYS5L3N3E4AAYNMN562LW76TMWHQBJ4A"
+totp.now  #=> "152201"
+
+totp.verify "152201"  #=> 1735417500     # ok, value is the timestamp
+sleep 30
+totp.verify "152201"  #=> nil            # not ok
+```
+
+### Counter based (HOTP)
+
+```ruby
+hotp = POTP::HOTP.new "GYS5L3N3E4AAYNMN562LW76TMWHQBJ4A"
+hotp.at  0  #=> "178748"
+hotp.at  1  #=> "584373"
+hotp.at 73  #=> "309764"
+
+# OTP verifying with a counter
+hotp.verify "309764", 73              #=> 73
+hotp.verify "309764", 74              #=> nil
+hotp.verify "309764", 70, retries: 2  #=> nil
+hotp.verify "309764", 70, retries: 3  #=> 73
+```
+
+
+### Avoiding reuse of TOTP
+
+```ruby
+require "potp"
+totp = POTP::TOTP.new "GYS5L3N3E4AAYNMN562LW76TMWHQBJ4A"
+code = totp.now                       #=> "054626"
+last_verify = totp.verify code        #=> 1735527390
+totp.verify code, after: last_verify  #=> nil
+sleep 30
+code = totp.now                       #=> "481150"
+totp.verify code, after: last_verify  #=> 1735527420
+```
+
+
+### Verifying a TOTP with drift
+
+In case a user entered a code just after it has expired, you can allow
+the token to remain valid.
+
+```ruby
+totp = POTP::TOTP.new "GYS5L3N3E4AAYNMN562LW76TMWHQBJ4A"
+now = Time.now - 30
+code = totp.at now                 #=> "455335"
+totp.verify code                   #=> nil
+totp.verify code, drift_behind: 27 #=> 1735530510
+```
+
+
+### Generating a Base32 secret key
+
+Returns a 160 bit (32 character) Base32 secret.
+
+```ruby
+require "potp/random"
+POTP::Base32.random  #=> "GYS5L3N3E4AAYNMN562LW76TMWHQBJ4A"
+```
+
+
+### Generating QR codes for provisioning mobile apps
+
+```ruby
+require "potp"
+
+totp = POTP::TOTP.new "GYS5L3N3E4AAYNMN562LW76TMWHQBJ4A"
+uri = totp.provisioning_uri name: "jdoe@example.net", issuer: "ACME Service"
+#=> "otpauth://totp/ACME%20Service:jdoe%40example.net?secret=GYS5L3N3E4AAYNMN562LW76TMWHQBJ4A&issuer=ACME%20Service"
+
+hotp = POTP::HOTP.new "GYS5L3N3E4AAYNMN562LW76TMWHQBJ4A"
+uri = hotp.provisioning_uri name: "jdoe@example.net", issuer: "ACME Service", counter: 0
+#=> "otpauth://hotp/ACME%20Service:jdoe%40example.net?secret=GYS5L3N3E4AAYNMN562LW76TMWHQBJ4A&issuer=ACME%20Service&counter=0"
+
+# Then, do something like this:
+system *%w(qrencode -t xpm -s 1 -o), "qr.xpm", uri
+```
+
+
+## Executable Usage
+
+Generates a time-based one-time password:
+
+```bash
+potp --secret GYS5L3N3E4AAYNMN562LW76TMWHQBJ4A
+```
+
+Generates a counter-based one-time password:
+
+```bash
+potp --hmac --secret GYS5L3N3E4AAYNMN562LW76TMWHQBJ4A --counter 42
+```
+
+What you expect:
+
+```bash
+potp --help
+```
+
+
+## Copyright
+
+  * (C) 2024 Bertram Scharpf <software@bertram-scharpf.de>
+  * License: [BSD-2-Clause+](./LICENSE)
+

data/bin/potp

@@ -0,0 +1,84 @@
+#!/usr/bin/env ruby
+
+#
+#  potp  --  The Plain One-Time Password Tool
+#
+
+begin
+  require "appl"
+rescue LoadError
+  puts "This tool requires the `appl` gem."
+  exit 2
+end
+require "potp/foreign/supplement"
+require "potp"
+
+
+class POTP::Appl < Application
+
+  NAME      = "potp"
+  VERSION   = POTP::VERSION
+  SUMMARY   = "Plain One Time Password Tool"
+  COPYRIGHT = "(C) 2024 Bertram Scharpf <software@bertram-scharpf.de>"
+  LICENSE   = "BSD-2-Clause+"
+  AUTHOR    = "Bertram Scharpf <software@bertram-scharpf.de>"
+
+  DESCRIPTION = <<~EOT
+    Generate and validate one time passwords (HOTP & TOTP)
+    according to [RFC 4226] and [RFC 6238].
+
+    Examples:
+
+      potp --secret p4ssword                       # Generates a time-based one-time password
+      potp --hmac --secret p4ssword --counter 42   # Generates a counter-based one-time password
+
+  EOT
+
+  attr_writer :secret, :counter, :digest
+  attr_bang :debug
+  def time! ; @mode = :time ; end
+  def hmac! ; @mode = :hmac ; end
+
+  define_option "t", :time!, true,  "use time-based OTP according to RFC 6238"
+  alias_option  "t", "time"
+
+  define_option "m", :hmac!,     "use counter-based OTP according to RFC 4226"
+  alias_option  "m", "hmac"
+
+  define_option "s", :secret=, "STR",                      "the shared secret"
+  alias_option  "s", "secret"
+
+  define_option "d", :digest=, "ALG", "sha1",       "algorithm for the digest"
+  alias_option  "d", "digest"
+
+  define_option "c", :counter=, "NUM", 0,
+                                      "the counter for counter-based hmac OTP"
+  alias_option  "c", "counter"
+
+  define_option "g", :debug!,         "full Ruby error messages and backtrace"
+  alias_option  "g", "debug"
+  define_option "h", :help,                                     "show options"
+  alias_option  "h", "help"
+  define_option "V", :version,                                  "show version"
+  alias_option  "V", "version"
+
+  def run
+    puts generate_output
+  rescue POTP::Base32::Invalid
+    raise "Secret must be in RFC4648 Base32 format - http://en.wikipedia.org/wiki/Base32#Base_32_Encoding_per_§6"
+  end
+
+  private
+
+  def generate_output
+    @secret.notempty? or raise "You must specify a --secret. See --help."
+    case @mode
+    when :time then (POTP::TOTP.new @secret, digest: @digest).now
+    when :hmac then (POTP::HOTP.new @secret, digest: @digest).at @counter
+    end
+  end
+
+end
+
+POTP::Appl.run
+

data/lib/potp/base32.rb

@@ -0,0 +1,140 @@
+#
+#  potp/base32.rb  --  Base32 Encoding
+#
+
+require "potp/foreign/supplement"
+
+
+module POTP
+
+  class Base32
+
+    ORD_A, ORD_Z, ORD_a, ORD_z, ORD_2, ORD_7 = %w(A Z a z 2 7).map { |c| c.ord }
+    LAP = 26
+    DIFF_2 = ORD_2 - LAP
+
+    class << self
+
+      def encode bytes, width: nil, equals: true
+        res = [""]
+        scan_bufs bytes do |buf,r|
+          chunk = []
+          8.times {
+            chunk.unshift buf & 0x1f
+            buf >>= 5
+          }
+          loop do
+            r -= 5
+            break unless r > 0
+            chunk.pop
+          end
+          chunk = chunk.map { |c| (c + (c < LAP ? ORD_A : DIFF_2)).chr }
+          if equals then
+            chunk.push "=" until chunk.length >= 8
+          end
+          res.last << chunk.join
+          if width and res.last.length > width then
+            res.push res.last.slice! width, 8
+          end
+        end
+        new res.join "\n"
+      end
+
+      private
+
+      def scan_bufs bytes
+        scan_blocks bytes do |s|
+          buf, r = 0, 40
+          5.times {
+            buf <<= 8
+            if (b = s.shift) then
+              buf |= b
+              r -= 8
+            end
+          }
+          yield buf, r
+        end
+      end
+
+      def scan_blocks bytes
+        i = 0
+        loop do
+          s = bytes.byteslice i, 5
+          break unless s.notempty?
+          yield s.unpack "C*"
+          i += 5
+        end
+      end
+
+    end
+
+
+    class Invalid < ArgumentError ; end
+
+    attr_reader :data
+
+    def initialize data
+      @data = data
+    end
+
+    def decode encoding: nil
+      res = ""
+      each_block { |buf,n|
+        chunk = []
+        5.times {
+          chunk.unshift buf & 0xff
+          buf >>= 8
+        }
+        until n >= 40 do
+          chunk.pop
+          n += 8
+        end
+        res << (chunk.pack "C*")
+      }
+      encoding = Encoding.default_external if encoding == :default
+      res.force_encoding encoding if encoding
+      res
+    end
+
+    private
+
+    def each_block
+      buf, n = 0, 0
+      each_char do |c|
+        c -= case c
+          when ORD_A..ORD_Z then ORD_A
+          when ORD_a..ORD_z then ORD_a
+          when ORD_2..ORD_7 then DIFF_2
+          else                   raise Invalid, "Character '#{c}'."
+        end
+        buf <<= 5
+        buf |= c
+        n += 5
+        if n == 40 then
+          yield buf, n
+          buf, n = 0, 0
+        end
+      end
+      if n.nonzero? then
+        buf <<= 40 - n
+        yield buf, n
+      end
+      nil
+    end
+
+    def each_char
+      done = false
+      @data.each_char { |c|
+        case c
+        when "="  then done = true ; next
+        when "\n" then next
+        else           raise Invalid, "Material after '=': '#{c}'" if done
+        end
+        yield c.ord
+      }
+    end
+
+  end
+
+end
+

data/lib/potp/foreign/supplement.rb

@@ -0,0 +1,21 @@
+#
+#  potp/foreign/supplement.rb  --  Addition usefull Ruby functions
+#
+
+# The purpose of this is simply to reduce dependencies.
+
+begin
+  require "supplement____"
+rescue LoadError
+  class NilClass ; def notempty? ;                      end ; end
+  class String   ; def notempty? ; self unless empty? ; end ; end
+  class Array    ; def notempty? ; self unless empty? ; end ; end
+  class <<Struct ; alias [] new ; end
+  class String
+    def starts_with? oth ; o = oth.to_str ; o.length          if start_with? o ; end
+    def ends_with?   oth ; o = oth.to_str ; length - o.length if end_with?   o ; end
+    alias starts_with starts_with?
+    alias ends_with   ends_with?
+  end
+end
+

data/lib/potp/hotp.rb

@@ -0,0 +1,29 @@
+#
+#  potp/hotp.rb  --  HOTP class
+#
+
+require "potp/otp"
+
+
+module POTP
+
+  class HOTP < OTP
+
+    SCHEME = "hotp"
+
+    def verify input, counter, retries: 0
+      while retries >= 0 do
+        return counter if super input, counter
+        counter += 1
+        retries -= 1
+      end
+    end
+
+    def provisioning_uri counter: 0, **kwargs
+      super
+    end
+
+  end
+
+end
+

data/lib/potp/otp.rb

@@ -0,0 +1,93 @@
+#
+#  potp/otp.rb  --  OTP class
+#
+
+require "potp/foreign/supplement"
+require "openssl"
+require "potp/base32"
+
+
+module POTP
+
+  class OTP
+
+    attr_reader :secret, :digits, :digest
+
+    DEFAULT_DIGITS = 6
+
+    def initialize secret, digits: nil, digest: nil, **kwargs
+      @secret = secret
+      @digits = digits || DEFAULT_DIGITS # Google Authenticate only supports 6 currently
+      @digest = digest || "sha1"         # Google Authenticate only supports SHA1 currently
+    end
+
+    def at data
+      hmac = build_digest data
+      code = hmac[ (hmac.last & 0x0f), 4].inject do |c,e| c <<= 8 ; c |= e end
+      code &= 0x7fffffff
+      s = ""
+      @digits.times { code, d = code.divmod 10 ; s << d.to_s }
+      s.reverse!
+      s
+    end
+
+    def verify input, data
+      String === input or raise ArgumentError, "`otp` has to be a String"
+      time_constant_compare input, (at data)
+    end
+
+    # https://github.com/google/google-authenticator/wiki/Key-Uri-Format
+    # Example additional parameter: image: "https://example.com/icon.png"
+    def provisioning_uri name:, issuer: nil, **kwargs
+      label = [ issuer, name||""].map { |x| x&.tr ":", "_" }
+      parameters = {
+        **kwargs,
+        digits:    (@digits unless @digits == DEFAULT_DIGITS),
+        algorithm: (@digest.upcase unless @digest.downcase == "sha1"),
+        issuer:    issuer,
+        secret:    @secret,
+      }
+      build_uri label, parameters
+    end
+
+    private
+
+    def int_to_bytestring i, padding = 8
+      i >= 0 or raise ArgumentError, "#int_to_bytestring requires a positive number"
+      result = []
+      while i != 0 or padding > 0 do
+        c = (i & 0xff).chr
+        result.unshift c
+        i >>= 8
+        padding -= 1
+      end
+      result.join
+    end
+
+    def time_constant_compare a, b
+      a.notempty? and b.notempty? and a == b
+    end
+
+    def build_digest input
+      d = OpenSSL::Digest.new @digest
+      s = (Base32.new @secret).decode
+      i = int_to_bytestring input.to_i
+      (OpenSSL::HMAC.digest d, s, i).bytes
+    end
+
+    def build_uri label, parameters
+      label.compact!
+      label = label.map! { |s| url_encode s }.join ":"
+      parameters.reject! { |_,v| v.nil? }
+      parameters = parameters.keys.reverse.map { |k| "#{k}=#{url_encode parameters[ k]}" }.join "&"
+      "otpauth://#{self.class::SCHEME}/#{label}?#{parameters}"
+    end
+
+    def url_encode str
+      str.to_s.gsub %r/([^a-zA-Z0-9_.-])/ do |c| "%%%02X" % c.ord end
+    end
+
+  end
+
+end
+

data/lib/potp/random.rb

@@ -0,0 +1,26 @@
+#
+#  potp/random.rb  --  Generate random secrets
+#
+
+require "potp/base32"
+require "securerandom"
+
+
+module POTP
+
+  class Base32
+
+    class <<self
+
+      # A byte length of 20 means 160 bits and results in 32 character long base32 value.
+      def random byte_length = 20
+        rand_bytes = SecureRandom.random_bytes byte_length
+        (encode rand_bytes).data
+      end
+
+    end
+
+  end
+
+end
+

data/lib/potp/totp.rb

@@ -0,0 +1,61 @@
+#
+#  potp/totp.rb  --  TOTP class
+#
+
+require "potp/otp"
+
+
+module POTP
+
+  class TOTP < OTP
+
+    SCHEME = "totp"
+
+    DEFAULT_INTERVAL = 30
+
+    attr_reader :interval
+
+    # @option options [Integer] interval (30) the time interval in seconds for OTP
+    #     This defaults to 30 which is standard.
+    def initialize secret, interval: nil, **kwargs
+      @interval = interval || DEFAULT_INTERVAL
+      super secret, **kwargs
+    end
+
+    def at time ; super (timeint time) / @interval ; end
+    def now     ; at Time.now                      ; end
+
+    def verify input, drift_ahead: nil, drift_behind: nil, after: nil, at: nil
+      fin = now = timeint at||Time.now
+      now -= drift_behind     if drift_behind
+      fin += drift_ahead      if drift_ahead
+      if after then
+        after += @interval
+        now = after if now < after
+      end
+      now -= now % @interval
+      while now < fin do
+        return now if super input, now
+        now += @interval
+      end
+      nil
+    end
+
+    def provisioning_uri **kwargs
+      super **kwargs, period: (@interval unless @interval == TOTP::DEFAULT_INTERVAL)
+    end
+
+    private
+
+    def timeint time
+      case time
+      when Integer then time
+      when Time    then time.utc.to_i
+      else              time.to_i
+      end
+    end
+
+  end
+
+end
+

data/lib/potp/version.rb

@@ -0,0 +1,11 @@
+#
+#  potp/version.rb  --  Version number
+#
+
+
+module POTP
+
+  VERSION = "1.0.0".freeze
+
+end
+

data/lib/potp.rb

@@ -0,0 +1,11 @@
+#
+#  potp.rb  --  The whole potp package
+#
+
+require "potp/totp"
+require "potp/hotp"
+require "potp/version"
+
+module POTP
+end
+

data/potp.gemspec

@@ -0,0 +1,35 @@
+#
+#  potp.gemspec  --  Gem Specification
+#
+
+require "./lib/potp/version"
+
+
+Gem::Specification.new do |s|
+  s.name        = "potp"
+  s.version     = POTP::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.required_ruby_version = ">= 3.1"
+  s.summary     = "Plain One Time Password Tool"
+  s.description = <<~EOT
+    A Ruby library for generating and verifying one time passwords,
+    both HOTP and TOTP, and includes QR Code provisioning.
+  EOT
+  s.license     = "LicenseRef-LICENSE"
+  s.authors     = ["Bertram Scharpf"]
+  s.email       = ["<software@bertram-scharpf.de>"]
+  s.homepage    = "https://github.com/BertramScharpf/ruby-potp"
+
+  s.requirements      = "Just Ruby and some more if you like"
+  unless :full_dependecies then
+    s.add_dependency      "supplement", "~>2", ">=2.10"
+    s.add_dependency      "appl", "~>1"
+  end
+
+  s.require_paths = %w(lib)
+  s.extensions    = %w()
+  s.files         = Dir[ "lib/**/*.rb", "bin/*", ]
+  s.executables   = %w(potp)
+  s.extra_rdoc_files  = %w(LICENSE README.md potp.gemspec)
+end
+

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: potp
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Bertram Scharpf
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-12-31 00:00:00.000000000 Z
+dependencies: []
+description: |
+  A Ruby library for generating and verifying one time passwords,
+  both HOTP and TOTP, and includes QR Code provisioning.
+email:
+- "<software@bertram-scharpf.de>"
+executables:
+- potp
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- README.md
+- potp.gemspec
+files:
+- LICENSE
+- README.md
+- bin/potp
+- lib/potp.rb
+- lib/potp/base32.rb
+- lib/potp/foreign/supplement.rb
+- lib/potp/hotp.rb
+- lib/potp/otp.rb
+- lib/potp/random.rb
+- lib/potp/totp.rb
+- lib/potp/version.rb
+- potp.gemspec
+homepage: https://github.com/BertramScharpf/ruby-potp
+licenses:
+- LicenseRef-LICENSE
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- Just Ruby and some more if you like
+rubygems_version: 3.5.23
+signing_key:
+specification_version: 4
+summary: Plain One Time Password Tool
+test_files: []