ios_app_attest 0.1.0

data/lib/ios_app_attest/validators/base_validator.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module IosAppAttest
+  module Validators
+    # Base class for all validators in the iOS App Attest validation process
+    #
+    # This class provides common functionality used by all validator classes,
+    # including logging, cryptographic utilities, and base64 encoding/decoding.
+    # All specific validators inherit from this class.
+    #
+    # @abstract Subclass and override validation methods to implement specific validation logic
+    class BaseValidator
+      attr_reader :config, :logger
+      
+      # Initialize the validator
+      # @param config [IosAppAttest::Configuration] Configuration object
+      # @param logger [Object] Logger instance (optional)
+      def initialize(config, logger: nil)
+        @config = config
+        @logger = logger
+      end
+      
+      private
+      
+      # Log error if logger is available
+      # @param message [String] The error message to log
+      def log_error(message)
+        logger&.error(message)
+      end
+      
+      # Get SHA256 digest
+      # @return [OpenSSL::Digest] SHA256 digest instance
+      def sha256
+        @sha256 ||= OpenSSL::Digest.new('SHA256')
+      end
+      
+      # Decode base64 string
+      # @param base64_string [String] The base64 encoded string
+      # @return [String] The decoded string
+      def decode_base64(base64_string)
+        Base64.decode64(base64_string)
+      end
+      
+      # Encode base64 string
+      # @param string [String] The string to encode
+      # @return [String] The base64 encoded string
+      def encode_base64(string)
+        Base64.strict_encode64(string)
+      end
+    end
+  end
+end

data/lib/ios_app_attest/validators/certificate_validator.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module IosAppAttest
+  module Validators
+    # Validates certificate chain and related aspects
+    #
+    # This validator is responsible for verifying the certificate chain,
+    # validating sequence structures, and ensuring the App Attest OID
+    # is present in the certificate.
+    #
+    # @example
+    #   validator = IosAppAttest::Validators::CertificateValidator.new(config)
+    #   cred_cert = validator.validate(attestation)
+    class CertificateValidator < BaseValidator
+      # Validate the certificate chain
+      #
+      # This method performs the following validations:
+      # 1. Extracts certificates from the attestation statement
+      # 2. Verifies the certificate chain against the Apple root CA
+      # 3. Validates that the certificate contains the App Attest OID
+      #
+      # @param attestation [Hash] The decoded attestation object containing x5c certificates
+      # @return [OpenSSL::X509::Certificate] The credential certificate if validation succeeds
+      # @raise [IosAppAttest::CertificateError] If certificate chain validation fails or App Attest OID is missing
+      def validate(attestation)
+        att_stmt = attestation['attStmt']
+        certificates = att_stmt['x5c'].map { |c| OpenSSL::X509::Certificate.new(c) }
+        cred_cert, *chain = certificates
+        
+        context = OpenSSL::X509::StoreContext.new(certificates_store, cred_cert, chain)
+        unless context.verify
+          raise IosAppAttest::CertificateError, 
+                "Certificate chain verification failed: #{context.error_string}"
+        end
+        
+        verify_app_attest_oid(cred_cert)
+        cred_cert
+      end
+      
+      # Validate the sequence structure in the certificate
+      #
+      # This method validates that the certificate extension with the App Attest OID
+      # contains a properly structured ASN.1 sequence. This is required for the
+      # challenge validation process.
+      #
+      # @param cred_cert [OpenSSL::X509::Certificate] The credential certificate to validate
+      # @raise [IosAppAttest::CertificateError] If sequence structure validation fails
+      def validate_sequence(cred_cert)
+        extension = cred_cert.extensions.find { |e| e.oid == app_attest_oid }
+        sequence = OpenSSL::ASN1.decode(OpenSSL::ASN1.decode(extension.to_der).value[1].value)
+        
+        unless sequence.tag == OpenSSL::ASN1::SEQUENCE && sequence.value.size == 1
+          raise IosAppAttest::CertificateError, 'Failed sequence structure validation'
+        end
+      end
+      
+      # Extract the public key from the certificate
+      #
+      # This method extracts the public key from the credential certificate
+      # in DER (Distinguished Encoding Rules) format for further validation.
+      #
+      # @param cred_cert [OpenSSL::X509::Certificate] The credential certificate
+      # @return [String] The public key in DER format
+      def extract_public_key(cred_cert)
+        cred_cert.public_key.to_der
+      end
+      
+      private
+      
+      # Validate the app attest OID in the certificate
+      #
+      # This method checks that the certificate contains the Apple App Attest OID
+      # extension, which is required for valid App Attestation certificates.
+      #
+      # @param certificate [OpenSSL::X509::Certificate] The certificate to validate
+      # @raise [IosAppAttest::CertificateError] If App Attest OID is missing
+      def verify_app_attest_oid(certificate)
+        has_oid = certificate.extensions.any? { |ext| ext.oid == app_attest_oid }
+        unless has_oid
+          raise IosAppAttest::CertificateError, "Missing App Attest OID in certificate"
+        end
+      end
+      
+      # Create certificates store with hardcoded root CA
+      #
+      # This method creates an OpenSSL certificate store and adds the hardcoded Apple
+      # root CA certificate to it for certificate chain validation.
+      #
+      # @return [OpenSSL::X509::Store] The certificate store with Apple root CA
+      def certificates_store
+        root_cert = OpenSSL::X509::Certificate.new(root_ca)
+        @certificates_store ||= OpenSSL::X509::Store.new.add_cert(root_cert)
+      end
+      
+      # Get hardcoded root CA 
+      #
+      # This method returns the hardcoded Apple App Attestation root CA certificate content.
+      # The certificate is stored as a constant to avoid recreating the string on each call.
+      #
+      # @return [String] The Apple root CA certificate content
+      # @raise [IosAppAttest::CertificateError] If the certificate format is invalid
+      def root_ca
+        APPLE_APP_ATTEST_ROOT_CA
+      rescue StandardError => e
+        raise IosAppAttest::CertificateError, "Invalid root CA certificate format: #{e.message}"
+      end
+      
+      # Apple App Attestation Root CA Certificate
+      # This is the official Apple App Attestation root CA certificate
+      APPLE_APP_ATTEST_ROOT_CA = <<~CERT
+      -----BEGIN CERTIFICATE-----
+      MIICITCCAaegAwIBAgIQC/O+DvHN0uD7jG5yH2IXmDAKBggqhkjOPQQDAzBSMSYw
+      JAYDVQQDDB1BcHBsZSBBcHAgQXR0ZXN0YXRpb24gUm9vdCBDQTETMBEGA1UECgwK
+      QXBwbGUgSW5jLjETMBEGA1UECAwKQ2FsaWZvcm5pYTAeFw0yMDAzMTgxODMyNTNa
+      Fw00NTAzMTUwMDAwMDBaMFIxJjAkBgNVBAMMHUFwcGxlIEFwcCBBdHRlc3RhdGlv
+      biBSb290IENBMRMwEQYDVQQKDApBcHBsZSBJbmMuMRMwEQYDVQQIDApDYWxpZm9y
+      bmlhMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAERTHhmLW07ATaFQIEVwTtT4dyctdh
+      NbJhFs/Ii2FdCgAHGbpphY3+d8qjuDngIN3WVhQUBHAoMeQ/cLiP1sOUtgjqK9au
+      Yen1mMEvRq9Sk3Jm5X8U62H+xTD3FE9TgS41o0IwQDAPBgNVHRMBAf8EBTADAQH/
+      MB0GA1UdDgQWBBSskRBTM72+aEH/pwyp5frq5eWKoTAOBgNVHQ8BAf8EBAMCAQYw
+      CgYIKoZIzj0EAwMDaAAwZQIwQgFGnByvsiVbpTKwSga0kP0e8EeDS4+sQmTvb7vn
+      53O5+FRXgeLhpJ06ysC5PrOyAjEAp5U4xDgEgllF7En3VcE3iexZZtKeYnpqtijV
+      oyFraWVIyd/dganmrduC1bmTBGwD
+      -----END CERTIFICATE-----
+      CERT
+      
+      # Apple App Attestation OID constant
+      # This OID identifies the App Attest extension in certificates
+      APP_ATTEST_OID = "1.2.840.113635.100.8.2"
+      
+      # Get app attest OID
+      #
+      # This method returns the hardcoded Apple App Attest OID.
+      # The OID is used to identify the App Attest extension in certificates.
+      #
+      # @return [String] The Apple App Attest OID ("1.2.840.113635.100.8.2")
+      def app_attest_oid
+        APP_ATTEST_OID
+      end
+    end
+  end
+end

data/lib/ios_app_attest/validators/challenge_validator.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module IosAppAttest
+  module Validators
+    # Validates challenge nonce and related aspects of the attestation
+    #
+    # This validator is responsible for verifying the challenge nonce used in the
+    # attestation process. It validates that the nonce is valid, not expired, and
+    # matches the expected value. It also verifies the key ID against the certificate's
+    # public key and provides methods for decrypting challenges.
+    #
+    # @example
+    #   validator = IosAppAttest::Validators::ChallengeValidator.new(config, redis_client: redis)
+    #   validator.validate_nonce(challenge_id, challenge_decrypted)
+    #   validator.validate_challenge(cred_cert, challenge_decrypted, auth_data)
+    #   validator.validate_key_id(cred_cert, key_id)
+    class ChallengeValidator < BaseValidator
+      attr_reader :redis_client
+      
+      # Initialize the challenge validator
+      #
+      # This initializes the validator with configuration and optional Redis client.
+      # The Redis client is used to store and retrieve nonces for verification.
+      # If no Redis client is provided, nonce verification will be skipped.
+      #
+      # @param config [IosAppAttest::Configuration] Configuration object with encryption keys and OIDs
+      # @param redis_client [Object] Redis client for nonce verification (optional)
+      # @param logger [Object] Logger instance for logging validation events (optional)
+      def initialize(config, redis_client: nil, logger: nil)
+        super(config, logger: logger)
+        @redis_client = redis_client
+      end
+      
+      # Validate the challenge nonce against stored value
+      #
+      # This method verifies that the provided challenge nonce matches the one
+      # previously stored in Redis. After successful validation, the nonce is
+      # deleted from Redis to prevent replay attacks.
+      #
+      # @note This method requires a Redis client to be provided during initialization.
+      #       If no Redis client is available, this validation is skipped.
+      #
+      # @param challenge_id [String] The challenge nonce ID used as Redis key
+      # @param challenge_decrypted [String] The decrypted challenge nonce to validate
+      # @raise [IosAppAttest::ChallengeError] If nonce is invalid, expired, or missing
+      def validate_nonce(challenge_id, challenge_decrypted)
+        return unless redis_client
+        
+        nonce = redis_client.get("nonce:#{challenge_id}")
+        unless nonce && nonce == encode_base64(challenge_decrypted)
+          raise IosAppAttest::ChallengeError, "Invalid or expired challenge nonce"
+        end
+        
+        # Delete the nonce after successful validation to prevent replay attacks
+        redis_client.del("nonce:#{challenge_id}")
+      end
+      
+      # Verify challenge nonce from certificate
+      #
+      # This method verifies that the challenge nonce was correctly incorporated into
+      # the attestation by checking that the certificate contains a hash derived from
+      # the authentication data and challenge nonce. This ensures the attestation was
+      # created specifically for this challenge.
+      #
+      # @param cred_cert [OpenSSL::X509::Certificate] The credential certificate containing the App Attest extension
+      # @param challenge_decrypted [String] The decrypted challenge nonce to verify
+      # @param auth_data [String] The authentication data from the attestation
+      # @raise [IosAppAttest::ChallengeError] If challenge verification fails
+      def validate_challenge(cred_cert, challenge_decrypted, auth_data)
+        challenge_hash = sha256.digest(challenge_decrypted)
+
+        extension = cred_cert.extensions.find { |e| e.oid == app_attest_oid }
+        sequence = OpenSSL::ASN1.decode(OpenSSL::ASN1.decode(extension.to_der).value[1].value)
+        to_verify = sequence.value[0].value[0].value
+
+        expected_hash = sha256.digest(auth_data + challenge_hash)
+        unless to_verify == expected_hash
+          raise IosAppAttest::ChallengeError, 'Challenge verification failed'
+        end
+      end
+      
+      # Validate the key ID matches the certificate's public key
+      #
+      # This method verifies that the key ID provided in the attestation parameters
+      # matches the hash of the public key from the credential certificate. This ensures
+      # the attestation is using the correct key pair.
+      #
+      # @param cred_cert [OpenSSL::X509::Certificate] The credential certificate containing the public key
+      # @param key_id [String] The key ID from attestation parameters to verify
+      # @raise [IosAppAttest::ChallengeError] If key ID verification fails
+      def validate_key_id(cred_cert, key_id)
+        uncompressed_point_key = cred_cert.public_key.public_key.to_octet_string(:uncompressed)
+        expected_key_id = Base64.strict_encode64(sha256.digest(uncompressed_point_key))
+        
+        unless key_id == expected_key_id
+          raise IosAppAttest::ChallengeError, 'Key ID verification failed'
+        end
+      end
+      
+      # Decrypt challenge using AES-256-CBC
+      #
+      # This method decrypts the challenge nonce using AES-256-CBC encryption with
+      # the provided initialization vector and the encryption key from configuration.
+      #
+      # @param challenge [String] The encrypted challenge nonce
+      # @param iv [String] The initialization vector used for encryption
+      # @return [String] The decrypted challenge nonce
+      def decrypt_challenge(challenge, iv)
+        cipher = OpenSSL::Cipher::AES256.new(:CBC)
+        cipher.decrypt
+        cipher.key = encryption_key
+        cipher.iv = iv
+        cipher.update(challenge) + cipher.final
+      end
+      
+      private
+      
+      # Apple App Attest OID constant
+      # This OID identifies the App Attest extension in certificates
+      APP_ATTEST_OID = "1.2.840.113635.100.8.2"
+      
+      # Get app attest OID
+      #
+      # This method returns the hardcoded Apple App Attest OID.
+      # The OID is used to identify the App Attest extension in certificates.
+      #
+      # @return [String] The Apple App Attest OID ("1.2.840.113635.100.8.2")
+      def app_attest_oid
+        APP_ATTEST_OID
+      end
+      
+      # Get encryption key from configuration
+      #
+      # This method retrieves the encryption key from the configuration object.
+      # The key is used for decrypting challenge nonces.
+      #
+      # @return [String] The encryption key used for AES-256-CBC decryption
+      def encryption_key
+        config.encryption_key
+      end
+    end
+  end
+end

data/lib/ios_app_attest/validators/utils.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module IosAppAttest
+  module Validators
+    # Utility methods for iOS App Attest validators
+    #
+    # This module provides common cryptographic and encoding utilities
+    # used throughout the iOS App Attest validation process.
+    # It includes methods for base64 encoding/decoding, SHA256 hashing,
+    # and AES cipher creation.
+    module Utils
+      # Decode base64 string
+      # @param base64_string [String] The base64 encoded string
+      # @return [String] The decoded string
+      def self.decode_base64(base64_string)
+        Base64.strict_decode64(base64_string)
+      end
+      
+      # Encode base64 string
+      # @param string [String] The string to encode
+      # @return [String] The base64 encoded string
+      def self.encode_base64(string)
+        Base64.strict_encode64(string)
+      end
+      
+      # Get SHA256 digest
+      # @return [OpenSSL::Digest] SHA256 digest instance
+      def self.sha256
+        OpenSSL::Digest.new('SHA256')
+      end
+      
+      # Create AES cipher
+      # @return [OpenSSL::Cipher] AES256-CBC cipher instance
+      def self.cipher
+        OpenSSL::Cipher::AES256.new(:CBC)
+      end
+    end
+  end
+end

data/lib/ios_app_attest/validators.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'validators/utils'
+require_relative 'validators/base_validator'
+require_relative 'validators/attestation_validator'
+require_relative 'validators/certificate_validator'
+require_relative 'validators/challenge_validator'
+require_relative 'validators/app_identity_validator'
+
+module IosAppAttest
+  # Namespace for validators
+  module Validators
+  end
+end

data/lib/ios_app_attest/verifier.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require 'pry'
+require_relative 'validators'
+
+module IosAppAttest
+  # Verifies iOS App Attestation tokens
+  # 
+  # The Verifier class is responsible for validating iOS App Attestation tokens
+  # received from iOS clients. It performs a series of validation steps to ensure
+  # the attestation is genuine and comes from a valid Apple device.
+  #
+  # @example Basic usage
+  #   verifier = IosAppAttest::Verifier.new(attestation_params)
+  #   public_key, receipt = verifier.verify
+  #
+  # @example With Redis for nonce validation
+  #   verifier = IosAppAttest::Verifier.new(
+  #     attestation_params,
+  #     redis_client: redis
+  #   )
+  #   public_key, receipt = verifier.verify
+  class Verifier
+
+    attr_reader :attestation_params, :redis_client, :logger
+
+    # Initialize the verifier with attestation parameters
+    # @param attestation_params [Hash] The attestation parameters from the client
+    # @param redis_client [Object] Redis client for nonce verification (optional)
+    # @param logger [Object] Logger instance (optional)
+    def initialize(attestation_params, redis_client: nil, logger: nil)
+      @attestation_params = attestation_params
+      @redis_client = redis_client
+      @logger = logger
+      initialize_validators
+    end
+
+    # Verify the app attestation
+    # 
+    # This method performs a complete verification of the iOS App Attestation token.
+    # It validates the attestation structure, certificate chain, challenge nonce,
+    # and app identity. If all validations pass, it returns the public key and receipt.
+    #
+    # @return [Array<String>] An array containing [public_key, receipt] if verification succeeds
+    # @raise [VerificationError] If verification fails for any reason
+    # @raise [NonceError] If nonce validation fails
+    # @raise [CertificateError] If certificate validation fails
+    # @raise [ChallengeError] If challenge validation fails
+    # @raise [AppIdentityError] If app identity validation fails
+    # @raise [AttestationError] If attestation format is invalid
+    def verify
+      begin
+        # Step 1: Decode the attestation object
+        attestation = decode_attestation
+        
+        # Step 2: Validate the challenge nonce if Redis client is provided
+        if redis_client
+          challenge_validator.validate_nonce(challenge_id, challenge_decrypted)
+        end
+        
+        # Step 3: Validate the attestation structure and format
+        attestation_validator.validate(attestation)
+        
+        # Step 4: Extract auth_data and receipt
+        auth_data = attestation_validator.extract_auth_data(attestation)
+        @receipt = attestation_validator.extract_receipt(attestation)
+        
+        # Step 5: Validate the certificate chain and get the credential certificate
+        cred_cert = certificate_validator.validate(attestation)
+        
+        # Step 6: Validate the challenge
+        challenge_validator.validate_challenge(cred_cert, challenge_decrypted, auth_data)
+        
+        # Step 7: Validate the key ID
+        challenge_validator.validate_key_id(cred_cert, key_id)
+        
+        # Step 8: Validate the certificate sequence structure
+        certificate_validator.validate_sequence(cred_cert)
+        
+        # Step 9: Verify the app identity
+        app_identity_validator.validate(auth_data, key_id)
+        
+        # Step 10: Extract the public key
+        @public_key = certificate_validator.extract_public_key(cred_cert)
+      rescue IosAppAttest::Error => error
+        # Re-raise IosAppAttest errors directly
+        log_error("IosAppAttest verification failed: #{error}")
+        raise error
+      rescue StandardError => error
+        # Wrap other errors in VerificationError
+        log_error("IosAppAttest verification failed: #{error}")
+        raise VerificationError, "Attestation verification failed: #{error.message}"
+      end
+      
+      [public_key, receipt]
+    end
+    
+    private
+    
+    attr_reader :attestation_validator, :certificate_validator, :challenge_validator, 
+                :app_identity_validator, :public_key, :receipt
+    
+    # Initialize all validators
+    def initialize_validators
+      @attestation_validator = Validators::AttestationValidator.new(config, logger: logger)
+      @certificate_validator = Validators::CertificateValidator.new(config, logger: logger)
+      @challenge_validator = Validators::ChallengeValidator.new(
+        config, 
+        redis_client: redis_client, 
+        logger: logger
+      )
+      @app_identity_validator = Validators::AppIdentityValidator.new(config, logger: logger)
+    end
+    
+    # Get IosAppAttest configuration
+    # @return [IosAppAttest::Configuration] The configuration object
+    def config
+      IosAppAttest.configuration
+    end
+    
+    # Decrypt challenge using AES
+    # @return [String] The decrypted challenge
+    def challenge_decrypted
+      challenge_validator.decrypt_challenge(challenge, iv)
+    end
+    
+    #---------------------------
+    # Parameter Accessors
+    #---------------------------
+
+    # Get key ID from attestation parameters
+    # @return [String] The key ID
+    def key_id
+      @key_id ||= attestation_params[:key_id] || attestation_params["key_id"]
+    end
+    
+    # Get attestation object from attestation parameters
+    # @return [String] The decoded attestation object
+    def attestation_object
+      @attestation_object ||= Validators::Utils.decode_base64(attestation_params[:attestation_object] || attestation_params["attestation_object"])
+    end
+
+    # Get challenge ID from attestation parameters
+    # @return [String] The challenge nonce ID
+    def challenge_id
+      @challenge_id ||= attestation_params[:challenge_nonce_id] || attestation_params["challenge_nonce_id"]
+    end
+    
+    # Get challenge from attestation parameters
+    # @return [String] The decoded challenge nonce
+    def challenge
+      @challenge ||= Validators::Utils.decode_base64(attestation_params[:challenge_nonce] || attestation_params["challenge_nonce"])
+    end
+
+    # Get IV from attestation parameters
+    # @return [String] The decoded initialization vector
+    def iv
+      @iv ||= Validators::Utils.decode_base64(attestation_params[:initialization_vector] || attestation_params["initialization_vector"])
+    end
+    
+    # Log error if logger is available
+    # @param message [String] The error message to log
+    def log_error(message)
+      logger&.error(message)
+    end
+    
+    # Decode the attestation object from base64
+    # @return [Hash] The decoded attestation object
+    def decode_attestation
+      CBOR.decode(attestation_object)
+    end
+  end
+end

data/lib/ios_app_attest/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module IosAppAttest
+  VERSION = "0.1.0"
+end

data/lib/ios_app_attest.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "cbor"
+require "openssl"
+require "base64"
+require "securerandom"
+require_relative "ios_app_attest/version"
+require_relative "ios_app_attest/configuration"
+require_relative "ios_app_attest/errors"
+require_relative "ios_app_attest/validators"
+require_relative "ios_app_attest/verifier"
+require_relative "ios_app_attest/nonce_generator"
+
+# Main module for iOS App Attest verification
+#
+# This module provides functionality for verifying iOS App Attest attestations.
+# It includes classes for configuration, verification, nonce generation, and
+# various validators for different aspects of the attestation process.
+#
+# @example Basic usage
+#   IosAppAttest.configure do |config|
+#     config.app_id = "TEAM123.com.example.app"
+#     config.encryption_key = SecureRandom.random_bytes(32)
+#   end
+#   # Note: App Attest OID ("1.2.840.113635.100.8.2") is hardcoded in the gem
+#
+#   verifier = IosAppAttest::Verifier.new
+#   verifier.verify(attestation_object, challenge_id, key_id)
+#
+module IosAppAttest
+  # Configuration options for the IosAppAttest module
+  class << self
+    attr_accessor :configuration
+    
+    # Configure the IosAppAttest module
+    #
+    # This method allows configuration of the IosAppAttest module using a block.
+    # It yields the configuration object to the block, allowing for setting
+    # various configuration parameters.
+    #
+    # @example
+    #   IosAppAttest.configure do |config|
+    #     config.app_id = "TEAM123.com.example.app"
+    #     config.encryption_key = SecureRandom.random_bytes(32)
+    #   end
+    #   # Note: App Attest OID is hardcoded in the gem
+    #
+    # @yield [configuration] The configuration object to be modified
+    # @return [Configuration] The current configuration object
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+      configuration
+    end
+  end
+  
+  # Initialize with default configuration
+  configure
+end