SecureApi Gem

Version: 1.0.2
Authors: DentsplySirona
License: For DentsplySirona use only

Description

SecureApi is a Ruby gem that creates and validates time-sensitive, URL-safe tokens for authorizing API access. It uses AES-256-GCM encryption to generate secure tokens with configurable expiration times, providing a robust authentication mechanism for API controllers in Rails applications.

Key Features

• Time-sensitive tokens: Automatically expire after a configured duration
• AES-256-GCM encryption: Military-grade encryption with authentication tags
• Legacy compatibility mode: Optional AES-256-CBC token creation for backward compatibility
• URL-safe encoding: Tokens are Base64 URL-safe encoded for use in URLs and parameters
• Rails integration: Simple before_action filter for API authentication
• Configurable security parameters: Customizable cipher, key derivation, and token structure

Configuration Parameters

The gem is configured through SecureApi.configure block, typically in a Rails initializer:

# config/initializers/secure_api.rb
SecureApi.configure do |config|
  config.secure_api_pass_phrase = 'your-secret-passphrase'
  config.secure_api_salt = 'your-16-byte-salt'
  config.secure_api_cipher_name = 'AES-256-GCM'
  config.secure_api_key_iterations = 300_000
  config.secure_api_key_length = 32
  config.secure_api_auth_tag_length = 16
  config.secure_api_enable_legacy_encryption = false
  config.secure_api_legacy_cipher_name = 'AES-256-CBC'
  config.secure_api_legacy_key_iterations = 20_000
  config.secure_api_prefix = 'ssprefix-'
  config.secure_api_suffix = '-sssuffix'
end

Required Parameters

• secure_api_pass_phrase (String)
  The secret passphrase used for encryption key derivation. Keep this secure and unique per environment.

• secure_api_salt (String)
  Must be exactly 16 bytes long. Used in key derivation function along with the passphrase.

Optional Parameters (with defaults)

• secure_api_cipher_name (String)
  Default: 'AES-256-GCM'
  The cipher algorithm used for encryption. AES-256-GCM provides both encryption and authentication.

• secure_api_key_iterations (Integer)
  Default: 300_000
  Number of iterations for PBKDF2 key derivation. Higher values increase security but reduce performance.

• secure_api_key_length (Integer)
  Default: 32
  Length of the derived encryption key in bytes (32 bytes = 256 bits for AES-256).

• secure_api_auth_tag_length (Integer)
  Default: 16
  Length of the authentication tag in bytes for GCM mode (16 bytes recommended).

• secure_api_enable_legacy_encryption (Boolean)
  Default: false
  When true, new tokens are created with the legacy format (AES-256-CBC + PBKDF2-HMAC-SHA1).

• secure_api_legacy_cipher_name (String)
  Default: 'AES-256-CBC'
  Cipher used for legacy token encryption/decryption.

• secure_api_legacy_key_iterations (Integer)
  Default: 20_000
  PBKDF2 iteration count used for legacy SHA1 key derivation.

• secure_api_prefix (String)
  Default: 'ssprefix-'
  Prefix added to generated tokens for easy identification.

• secure_api_suffix (String)
  Default: '-sssuffix'
  Suffix added to generated tokens for easy identification.

Legacy Mode Configuration

Use legacy mode only when you must generate tokens compatible with older services.

SecureApi.configure do |config|
  config.secure_api_pass_phrase = ENV.fetch('SECURE_API_PASSPHRASE')
  config.secure_api_salt = ENV.fetch('SECURE_API_SALT')

  # Enables legacy token creation (AES-256-CBC + static IV from salt)
  config.secure_api_enable_legacy_encryption = true

  # Keep defaults unless your legacy system requires different values
  config.secure_api_legacy_cipher_name = 'AES-256-CBC'
  config.secure_api_legacy_key_iterations = 20_000
end

Notes:

• Token validation attempts the current format first, then falls back to legacy format automatically.
• Disabling secure_api_enable_legacy_encryption affects token creation only; existing legacy tokens can still be validated.
• Prefer leaving legacy mode disabled after migration so newly issued tokens use AES-256-GCM.

Usage

Protecting API Controllers

class ApiController < ApplicationController
  include SecureApi::AccessToken
end

Generating Tokens

token = ApiToken.create

Validating Tokens

ApiToken.valid?(token) # returns true/false

Sending Tokens with API Requests

data = JSON.generate({
  method: method, 
  args: args, 
  access_token: ApiToken.create
})
response = RestClient.post(url, data,
  content_type: 'application/json',
  cookies: request.cookies)

Security Considerations

• Keep secure_api_pass_phrase secret and unique per environment
• Ensure secure_api_salt is exactly 16 bytes and stored securely
• Use environment variables or encrypted credentials for sensitive configuration
• Tokens are time-sensitive and will expire after the configured duration
• The gem now generates a unique random initialization vector (IV) per encryption for enhanced security

Dependencies

• Rails >= 7.2
• OpenSSL for cryptographic operations
• Base64 for URL-safe encoding