ruby-paseto 0.1.0

data/lib/paseto/token_types.rb

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  class TokenTypes < T::Enum
+    extend T::Sig
+
+    enums do
+      V3Local = new('v3.local')
+      V3Public = new('v3.public')
+      V4Local = new('v4.local')
+      V4Public = new('v4.public')
+    end
+
+    sig { returns(T.nilable(T.class_of(Interface::Key))) }
+    def key_klass
+      case self
+      in V3Local then V3::Local
+      in V3Public then V3::Public
+      in V4Local if Paseto.rbnacl?
+        V4::Local
+      in V4Public if Paseto.rbnacl?
+        V4::Public
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/paseto/util.rb

@@ -0,0 +1,105 @@
+# encoding: binary
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module Util
+    extend T::Sig
+
+    sig { params(str: String).returns(String) }
+    def self.encode64(str)
+      Base64.urlsafe_encode64(str, padding: false)
+    end
+
+    sig { params(str: String).returns(String) }
+    def self.decode64(str)
+      # Ruby's Base64 library does not care about whether or not padding is present,
+      # but the PASETO test vectors do.
+      return '' if str.include?('=')
+
+      Base64.urlsafe_decode64(str).b
+    rescue ArgumentError
+      ''
+    end
+
+    sig { params(str: String).returns(String) }
+    def self.decode_hex(str)
+      [str].pack('H*')
+    end
+
+    sig { params(num: Integer).returns(String) }
+    def self.le64(num)
+      raise ArgumentError, 'num too large' if num.bit_length > 64
+      raise ArgumentError, 'num must not be signed' if num.negative?
+
+      [num].pack('Q<')
+    end
+
+    sig { params(num: Integer).returns(String) }
+    def self.int_to_be32(num)
+      raise ArgumentError, 'num too large' if num.bit_length > 32
+      raise ArgumentError, 'num must not be signed' if num.negative?
+
+      [num].pack('N')
+    end
+
+    sig { params(num: Integer).returns(String) }
+    def self.int_to_be64(num)
+      raise ArgumentError, 'num too large' if num.bit_length > 64
+      raise ArgumentError, 'num must not be signed' if num.negative?
+
+      [num].pack('Q>')
+    end
+
+    sig { params(val: String).returns(Integer) }
+    def self.be64_to_int(val)
+      raise ArgumentError, 'input size incorrect' unless val.bytesize == 8
+
+      val.unpack1('Q>')
+    end
+
+    sig { params(val: String).returns(Integer) }
+    def self.be32_to_int(val)
+      raise ArgumentError, 'input size incorrect' unless val.bytesize == 4
+
+      val.unpack1('N')
+    end
+
+    sig { params(parts: String).returns(String) }
+    def self.pre_auth_encode(*parts)
+      parts.inject(le64(parts.size)) do |memo, part|
+        "#{memo}#{le64(part.bytesize)}#{part}"
+      end
+    end
+
+    # rubocop:disable Naming/MethodParameterName, Style/IdenticalConditionalBranches
+    # Moving the sig out of the conditional triggers a bug in rubocop-sorbet
+
+    # Use a faster comparison when RbNaCl is available
+    if Paseto.rbnacl?
+      sig { params(a: String, b: String).returns(T::Boolean) }
+      def self.constant_compare(a, b)
+        h_a = RbNaCl::Hash.blake2b(a)
+        h_b = RbNaCl::Hash.blake2b(b)
+        RbNaCl::Util.verify64(h_a, h_b)
+      end
+    else
+      sig { params(a: String, b: String).returns(T::Boolean) }
+      def self.constant_compare(a, b)
+        OpenSSL.secure_compare(a, b)
+      end
+    end
+
+    # rubocop:enable Naming/MethodParameterName, Style/IdenticalConditionalBranches
+
+    # Check if the libcrypto version that's running is actually openssl, and that the version
+    # is at least the provided major/minor/fix/patch level.
+    sig { params(major: Integer, minor: Integer, fix: Integer, patch: Integer).returns(T::Boolean) }
+    def self.openssl?(major, minor = 0, fix = 0, patch = 0)
+      return false if OpenSSL::OPENSSL_VERSION.include?('LibreSSL')
+
+      OpenSSL::OPENSSL_VERSION_NUMBER >=
+        (major * 0x10000000) + (minor * 0x100000) + (fix * 0x1000) + (patch * 0x10)
+    end
+  end
+end

data/lib/paseto/v3/local.rb

@@ -0,0 +1,63 @@
+# encoding: binary
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module V3
+    # PASETOv3 `local` token interface providing symmetric encryption of tokens.
+    class Local < SymmetricKey
+      extend T::Sig
+      extend T::Helpers
+
+      # Size in bytes of a SHA384 digest
+      SHA384_DIGEST_LEN = 48
+
+      # String initialized to \x00 for use in key derivation
+      NULL_SALT = T.let(0.chr * SHA384_DIGEST_LEN, String)
+
+      final!
+
+      sig(:final) { override.returns(Protocol::Version3) }
+      attr_reader :protocol
+
+      # Create a new Local instance with a randomly generated key.
+      sig(:final) { returns(T.attached_class) }
+      def self.generate
+        new(ikm: SecureRandom.random_bytes(32))
+      end
+
+      sig(:final) { params(ikm: String).void }
+      def initialize(ikm:)
+        @protocol = T.let(Protocol::Version3.new, Paseto::Protocol::Version3)
+
+        super(ikm)
+      end
+
+      private
+
+      # Derive an encryption key, nonce, and authentication key from an input nonce.
+      sig(:final) { override.params(nonce: String).returns([String, String, String]) }
+      def calc_keys(nonce)
+        tmp = OpenSSL::KDF.hkdf(key, info: "paseto-encryption-key#{nonce}", salt: NULL_SALT, length: 48, hash: 'SHA384')
+        ek = T.must(tmp[0, 32])
+        n2 = T.must(tmp[-16, 16])
+        ak = OpenSSL::KDF.hkdf(key, info: "paseto-auth-key-for-aead#{nonce}", salt: NULL_SALT, length: 48, hash: 'SHA384')
+        [ek, n2, ak]
+      end
+
+      # Split `payload` into the following parts:
+      # - nonce, 32 leftmost bytes
+      # - tag, 48 rightmost bytes
+      # - ciphertext, everything in between
+      sig(:final) { override.params(payload: String).returns([String, String, String]) }
+      def split_payload(payload)
+        n = T.must(payload.slice(0, 32))
+        c = T.must(payload.slice(32, payload.size - 80))
+        t = T.must(payload.slice(-48, 48))
+        [n, c, t]
+      rescue TypeError
+        raise ParseError
+      end
+    end
+  end
+end

data/lib/paseto/v3/public.rb

@@ -0,0 +1,204 @@
+# encoding: binary
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module V3
+    # PASETOv3 `public` token interface providing asymmetric signature signing and verification of tokens.
+    class Public < AsymmetricKey
+      extend T::Sig
+      extend T::Helpers
+
+      final!
+
+      # Size of (r || s) in an ECDSA secp384r1 signature
+      SIGNATURE_BYTE_LEN = 96
+
+      # Size of r | s in an ECDSA secp384r1 signature
+      SIGNATURE_PART_LEN = T.let(SIGNATURE_BYTE_LEN / 2, Integer)
+
+      sig(:final) { override.returns(Protocol::Version3) }
+      attr_reader :protocol
+
+      # Create a new Public instance with a brand new EC key.
+      sig(:final) { returns(T.attached_class) }
+      def self.generate
+        OpenSSL::PKey::EC.generate('secp384r1')
+                         .then(&:to_der)
+                         .then { |der| new(der) }
+      end
+
+      sig(:final) { params(bytes: String).returns(T.attached_class) }
+      def self.from_public_bytes(bytes)
+        ASN1.p384_public_bytes_to_spki_der(bytes)
+            .then { |der| new(der) }
+      end
+
+      sig(:final) { params(bytes: String).returns(T.attached_class) }
+      def self.from_scalar_bytes(bytes)
+        ASN1.p384_scalar_bytes_to_oak_der(bytes)
+            .then { |der| new(der) }
+      end
+
+      # `key` must be either a DER or PEM encoded secp384r1 key.
+      # Encrypted PEM inputs are not supported.
+      sig(:final) { params(key: String).void }
+      def initialize(key)
+        @key = T.let(OpenSSL::PKey::EC.new(key), OpenSSL::PKey::EC)
+        @private = T.let(@key.private?, T::Boolean)
+
+        raise LucidityError unless @key.group.curve_name == 'secp384r1'
+        raise InvalidKeyPair unless custom_check_key
+
+        @protocol = T.let(Protocol::Version3.new, Protocol::Version3)
+
+        super
+      rescue OpenSSL::PKey::ECError => e
+        raise CryptoError, e.message
+      end
+
+      # Sign `message` and optional non-empty `footer` and return a Token.
+      # The resulting token may be bound to a particular use by passing a non-empty `implicit_assertion`.
+      sig(:final) { override.params(message: String, footer: String, implicit_assertion: String).returns(Token) }
+      def sign(message:, footer: '', implicit_assertion: '')
+        raise ArgumentError, 'no private key available' unless private?
+
+        Util.pre_auth_encode(public_bytes, pae_header, message, footer, implicit_assertion)
+            .then { |m2| protocol.digest(m2) }
+            .then { |data| @key.sign_raw(nil, data) }
+            .then { |sig_asn| ASN1::ECDSASignature.from_asn1(sig_asn) }
+            .then { |ecdsa_sig| ecdsa_sig.to_rs(SIGNATURE_PART_LEN) }
+            .then { |sig| Token.new(payload: "#{message}#{sig}", purpose: purpose, version: version, footer: footer) }
+      rescue Encoding::CompatibilityError
+        raise ParseError, 'invalid message encoding, must be UTF-8'
+      end
+
+      # Verify the signature of `token`, with an optional binding `implicit_assertion`. `token` must be a `v3.public` type Token.
+      # Returns the verified payload if successful, otherwise raises an exception.
+      sig(:final) { override.params(token: Token, implicit_assertion: String).returns(String) }
+      def verify(token:, implicit_assertion: '') # rubocop:disable Metrics/AbcSize
+        raise LucidityError unless header == token.header
+
+        payload = token.raw_payload
+        raise ParseError, 'message too short' if payload.bytesize < SIGNATURE_BYTE_LEN
+
+        m = T.must(payload.slice(0, payload.bytesize - SIGNATURE_BYTE_LEN))
+
+        s = T.must(payload.slice(-SIGNATURE_BYTE_LEN, SIGNATURE_BYTE_LEN))
+             .then { |bytes| ASN1::ECDSASignature.from_rs(bytes, SIGNATURE_PART_LEN).to_der }
+
+        Util.pre_auth_encode(public_bytes, pae_header, m, token.raw_footer, implicit_assertion)
+            .then { |m2| protocol.digest(m2) }
+            .then { |data| @key.verify_raw(nil, s, data) }
+            .then { |valid| raise InvalidSignature unless valid }
+            .then { m.encode(Encoding::UTF_8) }
+      rescue Encoding::UndefinedConversionError
+        raise ParseError, 'invalid payload encoding'
+      end
+
+      sig(:final) { override.returns(String) }
+      def public_to_pem = @key.public_to_pem
+
+      sig(:final) { override.returns(String) }
+      def private_to_pem
+        raise ArgumentError, 'no private key available' unless private?
+
+        @key.to_pem
+      end
+
+      sig(:final) { override.returns(String) }
+      def to_bytes
+        raise ArgumentError, 'no private key available' unless private?
+
+        @key.private_key.to_s(2).rjust(48, "\x00")
+      end
+
+      sig(:final) { override.returns(T::Boolean) }
+      def private? = @private
+
+      sig(:final) { override.returns(String) }
+      def public_bytes = @key.public_key.to_octet_string(:compressed)
+
+      sig(:final) { override.params(other: T.any(OpenSSL::PKey::EC, OpenSSL::PKey::EC::Point)).returns(String) }
+      def ecdh(other)
+        case other
+        when OpenSSL::PKey::EC::Point
+          @key.dh_compute_key(other)
+        when OpenSSL::PKey::EC
+          other.dh_compute_key(@key.public_key)
+        end
+      end
+
+      private
+
+      # TODO: Figure out how to get SimpleCov to cover this consistently. With OSSL1.1.1, most of
+      # this doesn't run. With OSSL3, check_key never raises...
+      # :nocov:
+
+      # The openssl gem as of 3.0.0 will prefer EVP_PKEY_public_check over EC_KEY_check_key
+      # whenever the EVP api is available, which is always for the library here as we're requiring
+      # 3.0.0 or greater. However, this has some problems.
+      #
+      # The behavior of EVP_PKEY_public_check is different between 1.1.1 and 3.x. Specifically,
+      # it no longer calls the custom verifier method in EVP_PKEY_METHOD, and only checks the
+      # correctness of the public component. This leads to a problem when calling EC#key_check,
+      # as the private component is NEVER verified for an ECDSA key through the APIs that the gem
+      # makes available to us.
+      #
+      # Until this is fixed in ruby/openssl, I am working around this by implementing the algorithm
+      # used by EVP_PKEY_pairwise_check through the OpenSSL API.
+      #
+      # BUG: https://github.com/ruby/openssl/issues/563
+      # https://www.openssl.org/docs/man1.1.1/man3/EVP_PKEY_public_check.html
+      # https://www.openssl.org/docs/man3.0/man3/EVP_PKEY_public_check.html
+      sig(:final) { returns(T::Boolean) }
+      def custom_check_key
+        begin
+          @key.check_key
+        rescue StandardError
+          return false
+        end
+
+        return true unless private? && Util.openssl?(3)
+
+        priv_key = @key.private_key
+        group = @key.group
+
+        # int ossl_ec_key_private_check(const EC_KEY *eckey)
+        # {
+        # ...
+        #   if (BN_cmp(eckey->priv_key, BN_value_one()) < 0
+        #     || BN_cmp(eckey->priv_key, eckey->group->order) >= 0) {
+        #     ERR_raise(ERR_LIB_EC, EC_R_INVALID_PRIVATE_KEY);
+        #     return 0;
+        #   }
+        # ...
+        # }
+        #
+        # https://github.com/openssl/openssl/blob/5ac7cfb56211d18596e3c35baa942542f3c0189a/crypto/ec/ec_key.c#L510
+        # private keys must be in range [1, order-1]
+        return false if priv_key < OpenSSL::BN.new(1) || priv_key > group.order
+
+        # int ossl_ec_key_pairwise_check(const EC_KEY *eckey, BN_CTX *ctx)
+        # {
+        # ...
+        #   if (!EC_POINT_mul(eckey->group, point, eckey->priv_key, NULL, NULL, ctx)) {
+        #       ERR_raise(ERR_LIB_EC, ERR_R_EC_LIB);
+        #       goto err;
+        #   }
+        #   if (EC_POINT_cmp(eckey->group, point, eckey->pub_key, ctx) != 0) {
+        #       ERR_raise(ERR_LIB_EC, EC_R_INVALID_PRIVATE_KEY);
+        #       goto err;
+        #   }
+        # ...
+        # }
+        #
+        # https://github.com/openssl/openssl/blob/5ac7cfb56211d18596e3c35baa942542f3c0189a/crypto/ec/ec_key.c#L529
+        # Check generator * priv_key = pub_key
+        @key.public_key == group.generator.mul(priv_key)
+      end
+
+      # :nocov:
+    end
+  end
+end

data/lib/paseto/v4/local.rb

@@ -0,0 +1,56 @@
+# encoding: binary
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module V4
+    # PASETOv4 `local` token interface providing symmetric encryption of tokens.
+    class Local < SymmetricKey
+      extend T::Sig
+
+      final!
+
+      sig(:final) { override.returns(Protocol::Version4) }
+      attr_reader :protocol
+
+      # Create a new Local instance with a randomly generated key.
+      sig(:final) { returns(T.attached_class) }
+      def self.generate
+        new(ikm: RbNaCl::Random.random_bytes(32))
+      end
+
+      sig(:final) { params(ikm: String).void }
+      def initialize(ikm:)
+        @protocol = T.let(Protocol::Version4.new, Paseto::Protocol::Version4)
+
+        super(ikm)
+      end
+
+      private
+
+      # Derive an encryption key, nonce, and authentication key from an input nonce.
+      sig(:final) { override.params(nonce: String).returns([String, String, String]) }
+      def calc_keys(nonce)
+        tmp = protocol.hmac("paseto-encryption-key#{nonce}", key: key, digest_size: 56)
+        ek = T.must(tmp[0, 32])
+        n2 = T.must(tmp[-24, 24])
+        ak = protocol.hmac("paseto-auth-key-for-aead#{nonce}", key: key, digest_size: 32)
+        [ek, n2, ak]
+      end
+
+      # Separate a token payload into:
+      # - nonce, 32 leftmost bytes
+      # - tag, 32 rightmost bytes
+      # - ciphertext, everything in between
+      sig(:final) { override.params(payload: String).returns([String, String, String]) }
+      def split_payload(payload)
+        n = T.must(payload.slice(0, 32))
+        c = T.must(payload.slice(32, payload.size - 64))
+        t = T.must(payload.slice(-32, 32))
+        [n, c, t]
+      rescue TypeError
+        raise ParseError
+      end
+    end
+  end
+end

data/lib/paseto/v4/public.rb

@@ -0,0 +1,169 @@
+# encoding: binary
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module V4
+    # PASETOv4 `public` token interface providing asymmetric signature signing and verification of tokens.
+    class Public < AsymmetricKey
+      extend T::Sig
+      extend T::Helpers
+
+      final!
+
+      # Number of bytes in an Ed25519 signature
+      SIGNATURE_BYTES = 64
+
+      sig(:final) { returns(T.any(RbNaCl::SigningKey, RbNaCl::VerifyKey)) }
+      attr_reader :key
+
+      sig(:final) { override.returns(Protocol::Version4) }
+      attr_reader :protocol
+
+      # Create a new Public instance with a brand new Ed25519 key.
+      sig(:final) { returns(T.attached_class) }
+      def self.generate
+        new(RbNaCl::SigningKey.generate)
+      end
+
+      sig(:final) { params(keypair: String).returns(T.attached_class) }
+      def self.from_keypair(keypair)
+        new(Sodium::SafeEd25519Loader.from_keypair(keypair))
+      end
+
+      sig(:final) { params(bytes: String).returns(T.attached_class) }
+      def self.from_public_bytes(bytes)
+        new(RbNaCl::VerifyKey.new(bytes))
+      end
+
+      # If `key` is a String, it must be a PEM- or DER- encoded ED25519 key.
+      sig(:final) { params(key: T.any(String, RbNaCl::SigningKey, RbNaCl::VerifyKey)).void }
+      def initialize(key)
+        key = ed25519_pkey_ossl_to_nacl(key) if key.is_a?(String)
+
+        @key = T.let(key, T.any(RbNaCl::SigningKey, RbNaCl::VerifyKey))
+
+        @private = T.let(@key.is_a?(RbNaCl::SigningKey), T::Boolean)
+        @protocol = T.let(Protocol::Version4.new, Paseto::Protocol::Version4)
+
+        super
+      end
+
+      # Sign `message` and optional non-empty `footer` and return a Token.
+      # The resulting token may be bound to a particular use by passing a non-empty `implicit_assertion`.
+      sig(:final) { override.params(message: String, footer: String, implicit_assertion: String).returns(Token) }
+      def sign(message:, footer: '', implicit_assertion: '')
+        raise ArgumentError, 'no private key available' unless @key.is_a?(RbNaCl::SigningKey)
+
+        Util.pre_auth_encode(pae_header, message, footer, implicit_assertion)
+            .then { |m2| @key.sign(m2) }
+            .then { |sig| "#{message}#{sig}" }
+            .then { |payload| Token.new(payload: payload, purpose: purpose, version: version, footer: footer) }
+      end
+
+      # Verify the signature of `token`, with an optional binding `implicit_assertion`. `token` must be a `v4.public`` type Token.
+      # Returns the verified payload if successful, otherwise raises an exception.
+      sig(:final) { override.params(token: Token, implicit_assertion: String).returns(String) }
+      def verify(token:, implicit_assertion: '') # rubocop:disable Metrics/AbcSize
+        raise LucidityError unless header == token.header
+
+        payload = token.raw_payload
+        raise ParseError, 'message too short' if payload.bytesize < SIGNATURE_BYTES
+
+        m = T.must(payload.slice(0, payload.size - SIGNATURE_BYTES))
+        s = T.must(payload.slice(-SIGNATURE_BYTES, SIGNATURE_BYTES))
+
+        Util.pre_auth_encode(pae_header, m, token.raw_footer, implicit_assertion)
+            .then { |m2| public_key.verify(s, m2) }
+            .then { m.encode(Encoding::UTF_8) }
+      rescue RbNaCl::BadSignatureError
+        raise InvalidSignature
+      rescue Encoding::UndefinedConversionError
+        raise ParseError, 'invalid payload encoding'
+      end
+
+      sig(:final) { override.returns(String) }
+      def public_to_pem
+        ASN1.ed25519_pubkey_nacl_to_pem(public_bytes)
+      end
+
+      sig(:final) { override.returns(String) }
+      def private_to_pem
+        raise ArgumentError, 'no private key available' unless @key.is_a? RbNaCl::SigningKey
+
+        ASN1.ed25519_rs_to_oak_pem(@key.keypair_bytes)
+      end
+
+      sig(:final) { override.returns(String) }
+      def to_bytes
+        raise ArgumentError, 'no private key available' unless @key.is_a? RbNaCl::SigningKey
+
+        @key.keypair_bytes
+      end
+
+      sig(:final) { override.returns(T::Boolean) }
+      def private? = @private
+
+      sig(:final) { override.returns(String) }
+      def public_bytes
+        public_key.to_bytes
+      end
+
+      sig(:final) { override.params(other: T.any(RbNaCl::PrivateKey, RbNaCl::PublicKey)).returns(String) }
+      def ecdh(other)
+        case other
+        when RbNaCl::PrivateKey
+          RbNaCl::GroupElement.new(x25519_public_key).mult(other).to_bytes
+        when RbNaCl::PublicKey
+          RbNaCl::GroupElement.new(other).mult(x25519_private_key).to_bytes
+        end
+      end
+
+      sig(:final) { returns(RbNaCl::PrivateKey) }
+      def x25519_private_key
+        Sodium::Curve25519.new(self).to_x25519_private_key
+      end
+
+      sig(:final) { returns(RbNaCl::PublicKey) }
+      def x25519_public_key
+        Sodium::Curve25519.new(self).to_x25519_public_key
+      end
+
+      private
+
+      # Convert a PEM- or DER- encoded ED25519 key into either a `RbNaCl::VerifyKey`` or `RbNaCl::SigningKey`
+      sig(:final) { params(pem_or_der: String).returns(T.any(RbNaCl::VerifyKey, RbNaCl::SigningKey)) }
+      def ed25519_pkey_ossl_to_nacl(pem_or_der)
+        key = OpenSSL::PKey.read(pem_or_der)
+
+        if ossl_ed25519_private_key?(key)
+          bytes = OpenSSL::ASN1.decode(key.private_to_der).value[2].value[2..]
+          RbNaCl::SigningKey.new(bytes)
+        else
+          bytes = OpenSSL::ASN1.decode(key.public_to_der).value[1].value
+          RbNaCl::VerifyKey.new(bytes)
+        end
+      rescue OpenSSL::PKey::PKeyError => e
+        raise ParseError, e.message
+      end
+
+      # ruby/openssl doesn't give us any API to detect if a PKey has a private component
+      sig(:final) { params(key: OpenSSL::PKey::PKey).returns(T::Boolean) }
+      def ossl_ed25519_private_key?(key)
+        raise LucidityError, "expected Ed25519 key, got #{key.oid}" unless key.oid == 'ED25519'
+
+        return key.to_text.start_with?('ED25519 Private-Key') if Util.openssl?(3)
+        return key.to_text != "<INVALID PRIVATE KEY>\n" if Util.openssl?(1, 1, 1)
+
+        false
+      end
+
+      sig(:final) { returns(RbNaCl::VerifyKey) }
+      def public_key
+        return @key.verify_key if @key.is_a?(RbNaCl::SigningKey)
+
+        @key
+      end
+    end
+  end
+end