Security Lib Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ircmaxell/security-lib
   

   Add to composer.json under require if not using Composer globally.

2. First Use Case: Use the BinarySafeString class for secure string length comparisons (e.g., password validation, input sanitization):

   use Ircmaxell\SecurityLib\BinarySafeString;
   
   $str = "test";
   $length = BinarySafeString::length($str); // Returns binary-safe length
   

3. Key Classes:

   • BinarySafeString: For accurate string length calculations (critical for multibyte characters).
   • RandomLib: For cryptographically secure random number generation (if extended in future projects).

4. Where to Look First:

   • Source Code (minimal but clear).
   • Focus on BinarySafeString for immediate utility.

Implementation Patterns

Core Workflows

1. Binary-Safe String Handling:

   • Replace strlen() with BinarySafeString::length() for:
     • Password length validation (e.g., if (BinarySafeString::length($password) < 8)).
     • Input sanitization (e.g., trimming multibyte strings safely).
   • Example:

     use Ircmaxell\SecurityLib\BinarySafeString;
     
     $input = "café";
     $safeLength = BinarySafeString::length($input); // Returns 4 (not 5)
     

2. Integration with Laravel:

   • Form Request Validation:

     use Illuminate\Validation\Rule;
     use Ircmaxell\SecurityLib\BinarySafeString;
     
     public function rules()
     {
         return [
             'username' => [
                 'string',
                 Rule::function(function ($attribute, $value) {
                     return BinarySafeString::length($value) <= 32;
                 }),
             ],
         ];
     }
     

   • Middleware for Input Sanitization:

     namespace App\Http\Middleware;
     
     use Closure;
     use Ircmaxell\SecurityLib\BinarySafeString;
     
     class SanitizeInput
     {
         public function handle($request, Closure $next)
         {
             $request->merge([
                 'trimmed_input' => trim($request->input('user_input'), "\x00..\x1F")
             ]);
             return $next($request);
         }
     }
     

3. Testing:

   • Mock BinarySafeString in unit tests to verify length calculations:

     $this->assertEquals(4, BinarySafeString::length("café"));
     

Advanced Patterns

• Custom Validation Rules: Create a reusable rule for binary-safe constraints:

  namespace App\Rules;
  
  use Ircmaxell\SecurityLib\BinarySafeString;
  use Illuminate\Contracts\Validation\Rule;
  
  class BinaryLength extends Rule
  {
      protected $max;
  
      public function __construct($max)
      {
          $this->max = $max;
      }
  
      public function passes($attribute, $value)
      {
          return BinarySafeString::length($value) <= $this->max;
      }
  }
  

  Usage:

  'username' => ['app:binary-length', 32],
  

Gotchas and Tips

Pitfalls

1. Deprecation Risk:

   • Last release in 2015; no active maintenance. Use cautiously in production.
   • Mitigation: Fork the repo or wrap usage in a service layer for easier migration if needed.

2. Limited Features:

   • Only BinarySafeString is fully functional. RandomLib is a placeholder (no implementation).
   • Workaround: Use Laravel’s built-in Str::random() or random_bytes() instead.

3. Edge Cases in BinarySafeString:

   • Non-string inputs may cause errors. Validate inputs first:

     if (!is_string($input)) {
         throw new \InvalidArgumentException('Input must be a string');
     }
     

Debugging Tips

1. Verify Length Calculations:

   • Compare BinarySafeString::length() with mb_strlen() for multibyte strings:

     $str = "café";
     var_dump(BinarySafeString::length($str)); // int(4)
     var_dump(mb_strlen($str, 'UTF-8'));       // int(4)
     

   • Discrepancies may indicate encoding issues (e.g., UTF-8 vs. ISO-8859-1).

2. Performance:

   • BinarySafeString::length() is slower than strlen() for ASCII strings. Benchmark in critical paths.

Extension Points

1. Add to Laravel Service Provider:

   • Register a facade for easier access:

     // app/Providers/AppServiceProvider.php
     use Illuminate\Support\Facades\Facade;
     
     Facade::register('BinarySafeString', function () {
         return new \Ircmaxell\SecurityLib\BinarySafeString();
     });
     

   • Usage:

     $length = \BinarySafeString::length($str);
     

2. Custom Binary-Safe Functions:

   • Extend the class for project-specific needs (e.g., binary-safe substring):

     namespace App\Extensions;
     
     use Ircmaxell\SecurityLib\BinarySafeString as Base;
     
     class BinarySafeString extends Base
     {
         public static function substring($string, $start, $length)
         {
             return substr($string, $start, $length);
             // Note: Substring may still be unsafe for multibyte. Use with caution.
         }
     }
     

3. Fallback for Missing Features:

   • Implement RandomLib if needed (e.g., for CSRF tokens):

     use RandomLib\Factory;
     
     $factory = new Factory();
     $generator = $factory->getMediumStrengthGenerator();
     $token = $generator->generateString(32);