krypt-cmac 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 625c065a66091f29a4ba6f4c362021440776de5c970f0bab96acf746c4b4cee5
+  data.tar.gz: 955abe821538bf06e71ebe8bef363693acaac7ecec8654f2673ec6472e0b69dc
+SHA512:
+  metadata.gz: 8354e0d2338081a7600f14d977c534ea25c4c67ba392ff4eaa28aae1b4229a9a291c6f3de071ca71472679b58fff54f1476054be35ada47b304c268e1ccc54fa
+  data.tar.gz: 5ca01c08aa99204e1b509db1298024ddc5dd0b6d1fea419a72a58b17f785d389454bdd94e3ad08da02db69977f06a7ef43e4443cce52e73e252f45d85f87e474

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Martin Boßlet
+
+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,156 @@
+# Krypt::Cmac
+
+[![Gem Version](https://badge.fury.io/rb/krypt-cmac.svg)](https://badge.fury.io/rb/krypt-cmac)
+
+First off, don't use CMAC unless you really need to. HMAC is usually faster, more robust, and easier to use.
+Only go for CMAC if it's already been decided and you need to work with it.
+
+Krypt::Cmac provides implementations for all versions of the AES-CMAC algorithm as specified in:
+
+- [NIST SP 800-38B](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38b.pdf)
+- [RFC 4493](https://tools.ietf.org/html/rfc4493)
+- [RFC 4494](https://tools.ietf.org/html/rfc4494)
+- [RFC 4615](https://tools.ietf.org/html/rfc4615)
+
+It supports 128, 192, and 256-bit keys, variable length keys, and can handle streaming processing.
+Only AES is supported as the underlying block cipher algorithm. The implementations offer the same
+public API as `OpenSSL::HMAC` except for the `reset` method.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'krypt-cmac'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+If you aren't using `bundler` for managing dependencies, you may install the gem directly by executing:
+
+```bash
+gem install krypt-cmac
+```
+
+## Usage
+
+### AES-CMAC with 128, 192 or 256 bits (NIST SP 800-38B, RFC 4493)
+
+When using the default implementation, the size of the key determines the version of AES being used. This
+implies that keys must be either 128, 192 or 256 bits long, resulting in AES-128-CMAC, AES-192-CMAC or
+AES-256-CMAC tags. See below for variable key lengths.
+
+```ruby
+require 'krypt/cmac'
+
+key = ["2b7e151628aed2a6abf7158809cf4f3c"].pack("H*")
+message = ["6bc1bee22e409f96e93d7e117393172a"].pack("H*")
+
+# One-shot computation
+cmac = Krypt::Cmac.new(key)
+tag = cmac.digest(message)
+
+# Streaming computation
+cmac = Krypt::Cmac.new(key)
+cmac.update(message)
+tag = cmac.digest
+```
+
+### AES-CMAC-96 (RFC 4494)
+
+To generate CMAC tags that are 96 bits long instead of the default 128 bits, use `Krypt::Cmac::Cmac96`.
+Note that CMAC-96 tags are simply regular tags truncated to 96 bits. If you need any other tag size
+below 128 bits, you can truncate the regular tag manually.
+
+```ruby
+require 'krypt/cmac'
+
+key = ["2b7e151628aed2a6abf7158809cf4f3c"].pack("H*")
+message = ["6bc1bee22e409f96e93d7e117393172a"].pack("H*")
+
+# AES-CMAC-96 one-shot computation
+cmac = Krypt::Cmac::Cmac96.new(key)
+tag = cmac.digest(message)
+
+# AES-CMAC-96 streaming computation
+cmac = Krypt::Cmac::Cmac96.new(key)
+cmac.update(message)
+tag = cmac.digest
+```
+
+### AES-CMAC-PRF-128 (RFC 4615)
+
+If you need to generate CMAC tags from keys of varying lengths and not the usual 128, 192, or 256 bit
+range, use AES-CMAC-PRF-128 as provided by `Krypt::Cmac::CmacPrf128`. It computes a regular AES-CMAC on the
+key first and uses the 128 bit result as the actual key for CMAC computation. You might also use it if
+you need an AES-128-CMAC tag for keys that are 192 or 256 bits long. Using regular AES-CMAC with such
+keys would compute AES-192-CMAC and AES-256-CMAC tags respectively.
+
+```ruby
+require 'krypt/cmac'
+
+key = ["2b7e151628aed2a6abf7158809cf4f3c"].pack("H*")
+message = ["6bc1bee22e409f96e93d7e117393172a"].pack("H*")
+
+# AES-CMAC-PRF-128 one-shot computation
+cmac = Krypt::Cmac::CmacPrf128.new(key)
+tag = cmac.digest(message)
+
+# AES-CMAC-PRF-128 streaming computation
+cmac = Krypt::Cmac::CmacPrf128.new(key)
+cmac.update(message)
+tag = cmac.digest
+```
+
+### Tag verification
+
+Verifying a given tag means recomputing it and then comparing the two. However, it is crucial for security reasons
+to avoid comparing them with `==` or similar comparisons subject to
+[short-circuiting](https://en.wikipedia.org/wiki/Short-circuit_evaluation). To securely verify a tag, use:
+
+```ruby
+require 'krypt/cmac'
+
+key = ["2b7e151628aed2a6abf7158809cf4f3c"].pack("H*")
+message = ["6bc1bee22e409f96e93d7e117393172a"].pack("H*")
+tag = ["070a16b46b4d4144f79bdd9dd04a287c"].pack("H*")
+
+# Verifying a tag with data supplied to the method
+cmac = Krypt::Cmac.new(key)
+valid = cmac.verify(tag, message)
+
+# Verifying a tag without data supplied to the method
+cmac = Krypt::Cmac.new(key)
+cmac.update(message)
+begin
+  valid = cmac.verify(tag)
+  puts "Tag successfully verified"
+rescue Krypt::Cmac::TagMismatchError => e
+  # tag invalid
+end
+```
+
+Even though the `verify` method returns `true` on successful verification, it still raises a
+`Krypt::Cmac::TagMismatchError` on invalid tags. This ensures that invalid tags cannot go undetected if the
+verifying code forgets to check for `true` explicitly.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can 
+also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the 
+version number in `lib/krypt/cmac/version.rb`, and then run `bundle exec rake release`, which will create a git tag for 
+the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/krypt/krypt-cmac.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/krypt/cmac/cmac_96.rb

@@ -0,0 +1,31 @@
+module Krypt
+  class Cmac
+    # Implements AES-CMAC-96 as defined in RFC 4494. Computes a regular
+    # 128 bit tag and truncates it at 96 bit. All methods of Krypt::Cmac are available.
+    #
+    # @example
+    #   key = ["2b7e151628aed2a6abf7158809cf4f3c"].pack("H*")
+    #   message = ["6bc1bee22e409f96e93d7e117393172a"].pack("H*")
+    #   prf = Krypt::Cmac::Cmac96.new(key)
+    #   tag = prf.digest("data")
+    #
+    # @see Krypt::Cmac
+    #
+    # References:
+    # - AES-CMAC-96 RFC: https://tools.ietf.org/html/rfc4494
+    class Cmac96 < Cmac
+      def initialize(key)
+        super
+      end
+
+      # Returns the computed MAC tag as a 96-bit string as described in RFC 4494.
+      #
+      # @param data [String] The data to update the CMAC computation with before finalizing.
+      #   If nil, the CMAC computation is finalized without updating with any data.
+      # @return [String] The computed MAC tag as a 96-bit string.
+      def digest(data = nil)
+        super.byteslice(0, 12)
+      end
+    end
+  end
+end

data/lib/krypt/cmac/cmac_prf_128.rb

@@ -0,0 +1,48 @@
+module Krypt
+  class Cmac
+    # Implements AES-CMAC-PRF-128 as defined in RFC 4615. Variable length keys are supported,
+    # but if the key is not 128 bits long, it is derived using the AES-CMAC algorithm to enforce
+    # a 128 bit key and a CMAC computed with AES-128. All methods of Krypt::Cmac are available.
+    #
+    # @example
+    #   key = ["0102030405"].pack("H*")
+    #   prf = Krypt::Cmac::CmacPrf128.new(key)
+    #   tag = prf.digest("data")
+    #
+    # @see Krypt::Cmac
+    #
+    # References:
+    # - AES-CMAC-PRF-128 RFC: https://tools.ietf.org/html/rfc4615
+    class CmacPrf128
+      def initialize(key)
+        @key = derive_key(key)
+        @cmac = Krypt::Cmac.new(@key)
+      end
+
+      # Delegates to the underlying Krypt::Cmac instance.
+      def method_missing(method, *args, &block)
+        if @cmac.respond_to?(method)
+          @cmac.send(method, *args, &block)
+        else
+          super
+        end
+      end
+
+      # Delegates to the underlying Krypt::Cmac instance.
+      def respond_to_missing?(method, include_private = false)
+        @cmac.respond_to?(method) || super
+      end
+
+      private
+
+      def derive_key(key)
+        # If the key is already 128 bits, return it as is
+        return key if key.bytesize == 16
+
+        # Otherwise, derive a 128-bit key using the AES-CMAC algorithm
+        cmac = Krypt::Cmac.new(Krypt::Cmac::BLOCK_OF_ZEROS)
+        cmac.digest(key)
+      end
+    end
+  end
+end

data/lib/krypt/cmac/errors.rb

@@ -0,0 +1,10 @@
+module Krypt
+  class Cmac
+    # Raised when the CMAC is in an invalid state for the operation, e.g. when calling `update` after `digest`
+    # or by supplying additional data to `digest` after finalization.
+    class InvalidStateError < StandardError; end
+
+    # Raised when MAC tag verification fails.
+    class TagMismatchError < StandardError; end
+  end
+end

data/lib/krypt/cmac/version.rb

@@ -0,0 +1,5 @@
+module Krypt
+  class Cmac
+    VERSION = "1.1.0"
+  end
+end

data/lib/krypt/cmac.rb

@@ -0,0 +1,245 @@
+require "openssl"
+require_relative "cmac/version"
+require_relative "cmac/errors"
+require_relative "cmac/cmac_96"
+require_relative "cmac/cmac_prf_128"
+
+module Krypt
+  # Based on the CMAC algorithm described in RFC 4493 and NIST SP 800-38B.
+  # Calculates a message authentication code (MAC) for a message using AES as the block cipher.
+  # The underlying AES key size can be 128, 192, or 256 bits, this governs the
+  # version of AES being used to compute the MAC. The MAC size is always 128 bits.
+  #
+  # If a 96-bit MAC is required (as in RFC 4494), {#cmac_96} can be used. If other
+  # reduced versions are required, the MAC tag can be truncated manually after calling
+  # {#digest}.
+  #
+  # If variable length keys such as in AES-CMAC-PRF-128 (RFC 4615) must be supported,
+  # or if the MAC shall be computed with AES-128 - regardless of the key length,
+  # {Krypt::Cmac::CmacPrf128} can be used. This class derives a 128-bit key from the
+  # given key using the AES-CMAC algorithm.
+  #
+  # The CMAC computation can be updated with data in multiple calls to {#update}
+  # or by using the << operator. The MAC tag is finalized by calling {#digest}.
+  # The computation can be updated with data before finalizing by passing the
+  # data as an argument to {#digest}, allowing for one-shot tag computation.
+  #
+  # @example
+  #   key = ["2b7e151628aed2a6abf7158809cf4f3c"].pack("H*")
+  #   message = ["6bc1bee22e409f96e93d7e117393172a"].pack("H*")
+  #   message2 = ["ae2d8a57"].pack("H*")
+  #
+  #   # One-shot computation
+  #   cmac = Krypt::Cmac.new(key)
+  #   tag = cmac.digest(message)
+  #
+  #   # Streaming computation
+  #   cmac = Krypt::Cmac.new(key)
+  #   cmac.update(message) # Or: cmac << message
+  #   cmac.update(message2)
+  #   tag = cmac.digest
+  #
+  #   # Streaming computation with chaining
+  #   tag = Krypt::Cmac.new(key).update(message).update(message2).digest
+  #
+  # @see Krypt::Cmac::Cmac96
+  # @see Krypt::Cmac::CmacPrf128
+  #
+  # References:
+  # - NIST SP 800-38B: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38b.pdf
+  # - CMAC RFC: https://tools.ietf.org/html/rfc4493
+  # - AES-CMAC-96 RFC: https://tools.ietf.org/html/rfc4494
+  # - AES-CMAC-PRF-128 RFC: https://tools.ietf.org/html/rfc4615
+  class Cmac
+    # The constant string for subkey generation for a cipher with block size 128.
+    # Note that this is the same for different key lengths, as AES block size is always 128 bits.
+    RB = 0x87
+    # AES block size in bytes, which is always 128 (i.e. 16 bytes) regardless of key length.
+    AES_BLOCK_SIZE = 16
+    # A block of zeros, used for padding and initialization vectors.
+    BLOCK_OF_ZEROS = "\0".b * AES_BLOCK_SIZE
+
+    attr_reader :key, :k1, :k2, :l, :mac_tag
+
+    # Creates a new CMAC instance with the given key. The key length determines
+    # the version of AES to use for the CMAC computation.
+    #
+    # @param key [String] The key to use for the CMAC computation.
+    #   The key must be 128, 192, or 256 bits long, selecting the AES version to use.
+    # @raise [ArgumentError] If the key length is not 128, 192, or 256 bits.
+    def initialize(key)
+      unless [16, 24, 32].include?(key.bytesize)
+        raise ArgumentError, "Key must be 128, 192, or 256 bits long"
+      end
+      @key = key.b
+      @k1, @k2, @l = generate_subkeys(@key)
+      @buffer = "".b
+      @aes_cbc = cipher_for_key(@key, :CBC)
+      @aes_cbc.iv = BLOCK_OF_ZEROS
+    end
+
+    # Updates the CMAC computation with the given data. The data can be any
+    # string, and the CMAC computation is updated with the data. The data can
+    # be given in multiple calls to update, and the CMAC computation is
+    # updated with each call.
+    #
+    # @param data [String] The data to update the CMAC computation with.
+    # @return [self] The CMAC instance itself, to allow chaining.
+    # @raise [InvalidStateError] If the CMAC has already been finalized.
+    def update(data)
+      return self if data.nil?
+      raise InvalidStateError.new("CMAC has already been finalized") if @mac_tag
+
+      @buffer << data
+      buffer_len = @buffer.bytesize
+
+      # Return early if the buffer does not contain enough data to form a block
+      return self if buffer_len <= AES_BLOCK_SIZE
+
+      # Ensure that we do not process the final block yet. The final block is
+      # processed in the digest method. This is to ensure that the final block
+      # is padded correctly. For now, just process the remaining full blocks.
+      remainder = buffer_len % AES_BLOCK_SIZE
+      remainder = AES_BLOCK_SIZE if remainder == 0
+      @aes_cbc.update(@buffer.slice!(0...-remainder))
+
+      self # Return self to allow chaining
+    end
+    # Allow the << operator to be used as an alias for update.
+    # This allows the CMAC computation to be updated with the << operator.
+    # (@see #update)
+    alias_method :<<, :update
+
+    # Finalizes the CMAC computation and returns the computed MAC tag. If data
+    # is given, the CMAC computation is updated with the data before finalizing.
+    # The CMAC computation is finalized after calling this method, and no further
+    # updates are allowed.
+    #
+    # @param data [String] The data to update the CMAC computation with before finalizing.
+    #   If nil, the CMAC computation is finalized without updating with any data.
+    # @return [String] The computed MAC tag.
+    # @raise [ArgumentError] If data is given after the CMAC has already been finalized.
+    def digest(data = nil)
+      raise ArgumentError.new("CMAC has already been finalized") if data && @mac_tag
+      return @mac_tag if @mac_tag
+
+      update(data) if data
+      @mac_tag = @aes_cbc.update(pad_last_block(@buffer)) # No need to call final because no padding is used
+    end
+
+    # Returns the computed MAC tag as a hex-encoded string.
+    #
+    # @param data [String] The data to update the CMAC computation with before finalizing.
+    #   If nil, the CMAC computation is finalized without updating with any data.
+    # @return [String] The computed MAC tag as a hex-encoded string.
+    def hexdigest(data = nil)
+      digest(data).unpack1("H*")
+    end
+
+    # Returns the computed MAC tag as a Base64-encoded string.
+    #
+    # @param data [String] The data to update the CMAC computation with before finalizing.
+    #   If nil, the CMAC computation is finalized without updating with any data.
+    # @return [String] The computed MAC tag as a Base64-encoded string.
+    def base64digest(data = nil)
+      [digest(data)].pack("m0")
+    end
+
+    # Verifies the given MAC tag against the computed MAC tag for the given data.
+    #
+    # @param tag [String] The MAC tag to verify.
+    # @param data [String] The data to verify the MAC tag against.
+    #   If nil, the MAC tag is verified against the current CMAC computation.
+    # @return [Boolean] True if the MAC tag is verified. Raises otherwise.
+    # @raise [TagMismatchError] If the MAC tag verification fails.
+    def verify(tag, data = nil)
+      if !secure_compare(tag, digest(data))
+        raise TagMismatchError.new("MAC tag verification failed, the tags do not match")
+      end
+      true # Needs not be checked because an error is raised if the tags do not match
+    end
+
+    # Compares the CMAC instance with another CMAC instance. The comparison is
+    # done by comparing the computed MAC tags. The comparison is done in constant
+    # time to prevent timing attacks.
+    #
+    # @param other [Krypt::Cmac] The other CMAC instance to compare with.
+    # @return [Boolean] True if the MAC tags are equal, false otherwise.
+    def ==(other)
+      return false unless Cmac === other
+      return false unless digest.bytesize == other.digest.bytesize
+      OpenSSL.fixed_length_secure_compare(digest, other.digest)
+    end
+
+    private
+
+    def cipher_for_key(key, mode)
+      algorithm = "AES-#{key.size * 8}-#{mode}"
+      OpenSSL::Cipher.new(algorithm).tap do |cipher|
+        cipher.encrypt
+        cipher.key = key
+        cipher.padding = 0  # Do not use padding
+      end
+    end
+
+    def generate_subkeys(key)
+      aes_ecb = cipher_for_key(key, :ECB)
+      l = aes_ecb.update(BLOCK_OF_ZEROS) # No need to call final because no padding is used
+      k1 = generate_subkey(l)
+      k2 = generate_subkey(k1)
+      [k1, k2, l]
+    end
+
+    def generate_subkey(bytes)
+      msb = most_significant_bit_set?(bytes)
+      k = shift_left(bytes)
+      k.setbyte(-1, k.getbyte(-1) ^ RB) if msb
+      k
+    end
+
+    def pad_last_block(buffer)
+      len = buffer.bytesize # 0 < len <= AES_BLOCK_SIZE
+
+      if len == AES_BLOCK_SIZE
+        xor_block(buffer, k1)
+      else
+        buffer << "\x80".b # Append 1 bit (0x80 in hex) with ASCII-8BIT encoding
+        buffer << "\x00".b * (AES_BLOCK_SIZE - (len + 1)) # Pad the rest with 0 bits
+        xor_block(buffer, k2)
+      end
+    end
+
+    def shift_left(byte_string)
+      bytes = byte_string.bytes
+      carry = 0
+
+      bytes.reverse_each.with_index do |byte, i|
+        new_carry = (byte & 0x80) >> 7
+        # Update bytes beginning from the end, so use negative index plus 1
+        # i=0 => bytes[-1], i=1 => bytes[-2], etc.
+        # Shift left, clear the LSB to ensure it is 0 with 0xFE (whose LSB is 0), and finally add carry
+        bytes[-(i + 1)] = ((byte << 1) & 0xFE) | carry
+        carry = new_carry
+      end
+
+      bytes.pack("C*") # Convert bytes back to a string
+    end
+
+    def most_significant_bit_set?(bytes)
+      most_significant_bit(bytes) != 0
+    end
+
+    def most_significant_bit(bytes)
+      bytes.unpack1("C") & 0x80
+    end
+
+    def xor_block(block, key)
+      block.bytes.each_with_index.map { |b, i| b ^ key.getbyte(i) }.pack("C*")
+    end
+
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+      OpenSSL.fixed_length_secure_compare(a, b)
+    end
+  end
+end

data/spec/krypt/cmac/aes-cmac-prf-128_spec.rb

@@ -0,0 +1,16 @@
+RSpec.describe Krypt::Cmac::CmacPrf128 do
+  include_context "String helpers"
+  include_context "reference samples"
+
+  let(:data) { hex_to_bin(ReferenceSamples::AES_PRF_128[:data]) }
+
+  (ReferenceSamples::AES_PRF_128.keys - %i[data]).each do |sample_key|
+    sample = ReferenceSamples::AES_PRF_128[sample_key]
+    context sample[:description] do
+      let(:key) { hex_to_bin(sample[:key]) }
+      let(:expected_mac) { hex_to_bin(sample[:tag]) }
+
+      it_behaves_like "correct AES-CMAC-PRF-128"
+    end
+  end
+end

data/spec/krypt/cmac/aes_128_spec.rb

@@ -0,0 +1,16 @@
+RSpec.describe "Krypt::Cmac with AES-128 key" do
+  include_context "String helpers"
+  include_context "reference samples"
+
+  let(:key) { hex_to_bin(ReferenceSamples::AES_128[:key]) }
+
+  ReferenceSamples.sample_keys.each do |sample_key|
+    sample = ReferenceSamples::AES_128[sample_key]
+    context sample[:description] do
+      let(:data) { hex_to_bin(sample[:data]) }
+      let(:expected_mac) { hex_to_bin(sample[:tag]) }
+
+      it_behaves_like "correct CMAC"
+    end
+  end
+end

data/spec/krypt/cmac/aes_192_spec.rb

@@ -0,0 +1,16 @@
+RSpec.describe "Krypt::Cmac with AES-192 key" do
+  include_context "String helpers"
+  include_context "reference samples"
+
+  let(:key) { hex_to_bin(ReferenceSamples::AES_192[:key]) }
+
+  ReferenceSamples.sample_keys.each do |sample_key|
+    sample = ReferenceSamples::AES_192[sample_key]
+    context sample[:description] do
+      let(:data) { hex_to_bin(sample[:data]) }
+      let(:expected_mac) { hex_to_bin(sample[:tag]) }
+
+      it_behaves_like "correct CMAC"
+    end
+  end
+end

data/spec/krypt/cmac/aes_256_spec.rb

@@ -0,0 +1,16 @@
+RSpec.describe "Krypt::Cmac with AES-256 key" do
+  include_context "String helpers"
+  include_context "reference samples"
+
+  let(:key) { hex_to_bin(ReferenceSamples::AES_256[:key]) }
+
+  ReferenceSamples.sample_keys.each do |sample_key|
+    sample = ReferenceSamples::AES_256[sample_key]
+    context sample[:description] do
+      let(:data) { hex_to_bin(sample[:data]) }
+      let(:expected_mac) { hex_to_bin(sample[:tag]) }
+
+      it_behaves_like "correct CMAC"
+    end
+  end
+end

data/spec/krypt/cmac/aes_cmac_96_spec.rb

@@ -0,0 +1,16 @@
+RSpec.describe Krypt::Cmac::Cmac96 do
+  include_context "String helpers"
+  include_context "reference samples"
+
+  let(:key) { hex_to_bin(ReferenceSamples::AES_CMAC_96[:key]) }
+
+  ReferenceSamples.sample_keys.each do |sample_key|
+    sample = ReferenceSamples::AES_CMAC_96[sample_key]
+    context sample[:description] do
+      let(:data) { hex_to_bin(sample[:data]) }
+      let(:expected_mac) { hex_to_bin(sample[:tag]) }
+
+      it_behaves_like "correct AES-CMAC-96"
+    end
+  end
+end

data/spec/krypt/cmac/cmac_spec.rb

@@ -0,0 +1,82 @@
+RSpec.describe Krypt::Cmac do
+  include_context "String helpers"
+
+  it "has a version number" do
+    expect(Krypt::Cmac::VERSION).not_to be nil
+  end
+
+  context "general usage" do
+    let(:sample) { ReferenceSamples::AES_128[:single_block] }
+    let(:key) { hex_to_bin(ReferenceSamples::AES_128[:key]) }
+    let(:data) { hex_to_bin(sample[:data]) }
+    let(:tag) { hex_to_bin(sample[:tag]) }
+
+    subject { Krypt::Cmac.new(key) }
+
+    it "initializes with a key" do
+      expect(subject.key).to eq(key)
+    end
+
+    it "updates with data and allows chaining" do
+      expect { subject.update(data).update(data) }.not_to raise_error
+    end
+
+    it "raises an error if update is called after digest" do
+      subject.digest(data)
+      expect { subject.update(data) }.to raise_error(Krypt::Cmac::InvalidStateError, "CMAC has already been finalized")
+    end
+
+    it "raises an error if digest is called with data after finalization" do
+      subject.digest(data)
+      expect { subject.digest(data) }.to raise_error(ArgumentError, "CMAC has already been finalized")
+    end
+
+    it "returns the computed MAC tag if digest is called multiple times" do
+      subject.update(data)
+      tag1 = subject.digest
+      tag2 = subject.digest
+      expect(tag1).to eq(tag2)
+      expect(tag1).to eq(tag)
+    end
+
+    it "returns the correct MAC tag when updating and calling digest without arguments" do
+      computed_tag = subject.update(data).digest
+      expect(computed_tag).to eq(tag)
+    end
+
+    it "returns the correct MAC tag when calling digest with the data as an argument" do
+      computed_tag = subject.digest(data)
+      expect(computed_tag).to eq(tag)
+    end
+  end
+
+  context "initialization with different key sizes" do
+    subject { Krypt::Cmac.new(key) }
+
+    shared_examples "correct key" do
+      it { expect(subject.key).to eq(key) }
+    end
+
+    context "128-bit key" do
+      let(:key) { hex_to_bin(ReferenceSamples::AES_128[:key]) }
+      it_behaves_like "correct key"
+    end
+
+    context "192-bit key" do
+      let(:key) { hex_to_bin(ReferenceSamples::AES_192[:key]) }
+      it_behaves_like "correct key"
+    end
+
+    context "256-bit key" do
+      let(:key) { hex_to_bin(ReferenceSamples::AES_256[:key]) }
+      it_behaves_like "correct key"
+    end
+
+    context "invalid key size" do
+      let(:key) { b64_to_bin("deadbeef") }
+      it "raises ArgumentError" do
+        expect { subject }.to raise_error(ArgumentError, "Key must be 128, 192, or 256 bits long")
+      end
+    end
+  end
+end

data/spec/shared_contexts/reference_samples.rb

@@ -0,0 +1,73 @@
+require "krypt/cmac"
+
+RSpec.shared_context "reference samples" do
+  include_context "String helpers"
+
+  shared_examples "correct computation" do
+    subject {
+      described_class.new(key)
+    }
+
+    it { expect(subject.digest(data)).to eq(expected_mac) }
+
+    it "computes the correct digest when using update" do
+      expect(subject.update(data).digest).to eq(expected_mac)
+    end
+
+    it "computes the correct digest when using <<" do
+      subject << data
+      expect(subject.digest).to eq(expected_mac)
+    end
+
+    it "computes the correct hexdigest" do
+      expect(subject.hexdigest(data)).to eq(bin_to_hex(expected_mac))
+    end
+
+    it "computes the correct base64digest" do
+      expect(subject.base64digest(data)).to eq(bin_to_b64(expected_mac))
+    end
+
+    it "returns true when verifying the correct MAC" do
+      expect(subject.verify(expected_mac, data)).to be true
+    end
+
+    it "returns true when verifying the correct MAC without supplying data to `verify`" do
+      expect(subject.update(data).verify(expected_mac)).to be true
+    end
+
+    it "returns true when comparing two equal CMAC instances" do
+      expect(subject.update(data)).to eq(described_class.new(key).update(data))
+    end
+
+    it "returns false when comparing two different CMAC instances" do
+      expect(subject.update("nope")).not_to eq(described_class.new(key).update(data))
+    end
+
+    it "raises an error when verifying an incorrect MAC" do
+      expect { subject.verify(Krypt::Cmac::BLOCK_OF_ZEROS, data) }.to raise_error(Krypt::Cmac::TagMismatchError, "MAC tag verification failed, the tags do not match")
+    end
+
+    it "computes the correct MAC when updating the data in chunks" do
+      (1..(data.size)).each do |i|
+        mac = described_class.new(key)
+        data.chars.each_slice(i) { |slice| mac.update(slice.join) }
+        expect(mac.digest).to eq(expected_mac)
+      end
+    end
+  end
+
+  shared_examples "correct CMAC" do
+    let(:described_class) { Krypt::Cmac }
+    include_examples "correct computation"
+  end
+
+  shared_examples "correct AES-CMAC-96" do
+    let(:described_class) { Krypt::Cmac::Cmac96 }
+    include_examples "correct computation"
+  end
+
+  shared_examples "correct AES-CMAC-PRF-128" do
+    let(:described_class) { Krypt::Cmac::CmacPrf128 }
+    include_examples "correct computation"
+  end
+end

data/spec/shared_contexts/string_helpers.rb

@@ -0,0 +1,17 @@
+RSpec.shared_context "String helpers" do
+  def hex_to_bin(hex)
+    [hex].pack("H*")
+  end
+
+  def bin_to_hex(bin)
+    bin.unpack1("H*")
+  end
+
+  def b64_to_bin(b64)
+    b64.unpack1("m")
+  end
+
+  def bin_to_b64(bin)
+    [bin].pack("m0")
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,21 @@
+require "simplecov"
+SimpleCov.start
+
+require "krypt/cmac"
+
+RSpec.configure do |config|
+  # Include shared contexts
+  Dir[File.join(__dir__, "shared_contexts", "**", "*.rb")].each { |f| require f }
+  # Include all support files
+  Dir[File.join(__dir__, "support", "**", "*.rb")].each { |f| require f }
+
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = ".rspec_status"
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

data/spec/support/reference_samples.rb

@@ -0,0 +1,129 @@
+require "krypt/cmac"
+
+module ReferenceSamples
+  module_function
+
+  def sample_keys
+    @_keys ||= (AES_128.keys - %i[key])
+  end
+
+  # Taken from /res/AES_CMAC.pdf
+  AES_128 = {
+    key: "2b7e151628aed2a6abf7158809cf4f3c",
+    empty: {
+      description: "empty message (len 0)",
+      data: "",
+      tag: "bb1d6929e95937287fa37d129b756746"
+    },
+    single_block: {
+      description: "single block message (i.e. len 16)",
+      data: "6bc1bee22e409f96e93d7e117393172a",
+      tag: "070a16b46b4d4144f79bdd9dd04a287c"
+    },
+    non_multiple_block: {
+      description: "with a message that is not a multiple of the block size, e.g. len 20",
+      data: "6bc1bee22e409f96e93d7e117393172aae2d8a57",
+      tag: "7d85449ea6ea19c823a7bf78837dfade"
+    },
+    multiple_block: {
+      description: "with a message that is a multiple of the block size, e.g. len 64",
+      data: "6bc1bee22e409f96e93d7e117393172aae2d8a571e03ac9c9eb76fac45af8e5130c81c46a35ce411e5fbc1191a0a52eff69f2445df4f9b17ad2b417be66c3710",
+      tag: "51f0bebf7e3b9d92fc49741779363cfe"
+    }
+  }
+
+  # Taken from /res/AES_CMAC.pdf
+  AES_192 = {
+    key: "8e73b0f7da0e6452c810f32b809079e562f8ead2522c6b7b",
+    empty: {
+      description: "empty message (len 0)",
+      data: "",
+      tag: "d17ddf46adaacde531cac483de7a9367"
+    },
+    single_block: {
+      description: "single block message (i.e. len 16)",
+      data: "6bc1bee22e409f96e93d7e117393172a",
+      tag: "9e99a7bf31e710900662f65e617c5184"
+    },
+    non_multiple_block: {
+      description: "with a message that is not a multiple of the block size, e.g. len 20",
+      data: "6bc1bee22e409f96e93d7e117393172aae2d8a57",
+      tag: "3d75c194ed96070444a9fa7ec740ecf8"
+    },
+    multiple_block: {
+      description: "with a message that is a multiple of the block size, e.g. len 64",
+      data: "6bc1bee22e409f96e93d7e117393172aae2d8a571e03ac9c9eb76fac45af8e5130c81c46a35ce411e5fbc1191a0a52eff69f2445df4f9b17ad2b417be66c3710",
+      tag: "a1d5df0eed790f794d77589659f39a11"
+    }
+  }
+
+  # Taken from /res/AES_CMAC.pdf
+  AES_256 = {
+    key: "603deb1015ca71be2b73aef0857d77811f352c073b6108d72d9810a30914dff4",
+    empty: {
+      description: "empty message (len 0)",
+      data: "",
+      tag: "028962f61b7bf89efc6b551f4667d983"
+    },
+    single_block: {
+      description: "single block message (i.e. len 16)",
+      data: "6bc1bee22e409f96e93d7e117393172a",
+      tag: "28a7023f452e8f82bd4bf28d8c37c35c"
+    },
+    non_multiple_block: {
+      description: "with a message that is not a multiple of the block size, e.g. len 20",
+      data: "6bc1bee22e409f96e93d7e117393172aae2d8a57",
+      tag: "156727dc0878944a023c1fe03bad6d93"
+    },
+    multiple_block: {
+      description: "with a message that is a multiple of the block size, e.g. len 64",
+      data: "6bc1bee22e409f96e93d7e117393172aae2d8a571e03ac9c9eb76fac45af8e5130c81c46a35ce411e5fbc1191a0a52eff69f2445df4f9b17ad2b417be66c3710",
+      tag: "e1992190549f6ed5696a2c056c315410"
+    }
+  }
+
+  # Taken from RFC 4494
+  AES_CMAC_96 = {
+    key: "2b7e151628aed2a6abf7158809cf4f3c",
+    empty: {
+      description: "empty message (len 0)",
+      data: "",
+      tag: "bb1d6929e95937287fa37d12"
+    },
+    single_block: {
+      description: "single block message (i.e. len 16)",
+      data: "6bc1bee22e409f96e93d7e117393172a",
+      tag: "070a16b46b4d4144f79bdd9d"
+    },
+    non_multiple_block: {
+      description: "with a message that is not a multiple of the block size, e.g. len 40",
+      data: "6bc1bee22e409f96e93d7e117393172aae2d8a571e03ac9c9eb76fac45af8e5130c81c46a35ce411",
+      tag: "dfa66747de9ae63030ca3261"
+    },
+    multiple_block: {
+      description: "with a message that is a multiple of the block size, e.g. len 64",
+      data: "6bc1bee22e409f96e93d7e117393172aae2d8a571e03ac9c9eb76fac45af8e5130c81c46a35ce411e5fbc1191a0a52eff69f2445df4f9b17ad2b417be66c3710",
+      tag: "51f0bebf7e3b9d92fc497417"
+    }
+  }
+
+  # Taken from RFC 4615
+  AES_PRF_128 = {
+    data: "000102030405060708090a0b0c0d0e0f10111213",
+    key_length_18: {
+      key: "000102030405060708090a0b0c0d0e0fedcb",
+      description: "key length 18",
+      tag: "84a348a4a45d235babfffc0d2b4da09a"
+    },
+    key_length_16: {
+      key: "000102030405060708090a0b0c0d0e0f",
+      description: "key length 16",
+      tag: "980ae87b5f4c9c5214f5b6a8455e4c2d"
+    },
+    key_length_10: {
+      key: "00010203040506070809",
+      description: "key length 10",
+      tag: "290d9e112edb09ee141fcf64c0b72f3d"
+    }
+  }
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: krypt-cmac
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- Martin Boßlet
+bindir: bin
+cert_chain: []
+date: 2025-03-06 00:00:00.000000000 Z
+dependencies: []
+description: |2
+    An implementation of AES-CMAC for 128, 192, and 256 bit keys as specified in NIST SP 800-38B and RFC 4493, capable of streaming processing.
+    Also included is an implementation of AES-CMAC-PRF-128 as specified in RFC 4615 and of CMAC-96 as specified in RFC 4494.
+email:
+- martin.bosslet@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/krypt/cmac.rb
+- lib/krypt/cmac/cmac_96.rb
+- lib/krypt/cmac/cmac_prf_128.rb
+- lib/krypt/cmac/errors.rb
+- lib/krypt/cmac/version.rb
+- spec/krypt/cmac/aes-cmac-prf-128_spec.rb
+- spec/krypt/cmac/aes_128_spec.rb
+- spec/krypt/cmac/aes_192_spec.rb
+- spec/krypt/cmac/aes_256_spec.rb
+- spec/krypt/cmac/aes_cmac_96_spec.rb
+- spec/krypt/cmac/cmac_spec.rb
+- spec/shared_contexts/reference_samples.rb
+- spec/shared_contexts/string_helpers.rb
+- spec/spec_helper.rb
+- spec/support/reference_samples.rb
+homepage: https://github.com/krypt/krypt-cmac
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/krypt/krypt-cmac
+  source_code_uri: https://github.com/krypt/krypt-cmac
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: AES-CMAC as specified in NIST SP 800-38B, RFC 4493, RFC 4494 and RFC 4615.
+test_files: []