Bricks Scrypt Password Encoder Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require usu/scrypt-password-encoder-bundle
   

   Add the bundle to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 2/3):

   // config/bundles.php
   return [
       // ...
       Usu\ScryptPasswordEncoderBundle\UsuScryptPasswordEncoderBundle::class => ['all' => true],
   ];
   

2. Configure in config/packages/security.yaml

   security:
       encoders:
           App\Entity\User: 'scrypt'
   

3. First Use Case Register a user via Symfony’s UserPasswordHasherInterface (or EncoderFactory in older versions):

   use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;
   
   $hasher = $this->get('security.user_password_hasher');
   $hashedPassword = $hasher->hashPassword($user, 'plainPassword');
   

Implementation Patterns

Core Workflow

1. Password Hashing Use the built-in UserPasswordHasherInterface (Symfony 5+) or EncoderFactory (Symfony 2/3) to hash passwords:

   // Symfony 5+
   $hasher = $this->get('security.user_password_hasher');
   $hashed = $hasher->hashPassword($user, $plainPassword);
   
   // Symfony 2/3 (legacy)
   $encoder = $this->get('security.encoder_factory')->getEncoder($user);
   $hashed = $encoder->encodePassword($plainPassword, $user->getSalt());
   

2. Verification

   if ($hasher->isPasswordValid($user, $plainPassword)) {
       // Password matches
   }
   

3. Custom User Entity Ensure your User entity implements PasswordAwareInterface (Symfony 5+) or has getPassword()/setPassword() methods:

   use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
   
   class User implements PasswordAuthenticatedUserInterface {
       private $password;
   
       public function getPassword(): ?string { ... }
       public function setPassword(string $password): void { ... }
   }
   

Integration Tips

• Migrations: If upgrading from another encoder (e.g., bcrypt), re-hash all passwords during migration:

  $users = $entityManager->getRepository(User::class)->findAll();
  foreach ($users as $user) {
      $user->setPassword($hasher->hashPassword($user, $user->getPassword()));
  }
  $entityManager->flush();
  

• Custom Parameters: Override scrypt parameters in config/packages/security.yaml:

  security:
      encoders:
          App\Entity\User:
              algorithm: scrypt
              cost: 15          # CPU/memory cost (default: 15)
              time: 2          # CPU cost (default: 2)
              block_size: 8    # Block size (default: 8)
  

Gotchas and Tips

Pitfalls

1. Performance Impact

   • Scrypt is CPU-intensive. Test on production-like hardware before deployment.
   • Default parameters (cost: 15, time: 2) are secure but may slow down registration/login. Adjust based on your server’s capabilities.

2. Legacy Symfony Versions

   • Symfony 2/3 users must manually configure the encoder in security.yml (not security.yaml).
   • Ensure Usu\ScryptPasswordEncoderBundle\Encoder\ScryptEncoder is properly registered as a service.

3. Password Reset Tokens

   • If using password reset tokens, hash the token separately (e.g., with hash_hmac). Scrypt is overkill for short-lived tokens.

4. Database Schema

   • Ensure your password column is TEXT or VARCHAR(255) (scrypt hashes are long).

Debugging

• Invalid Hashes: If isPasswordValid() fails, verify:

  • The plain password matches the stored hash’s original input.
  • The salt (if manually managed) is correct. Scrypt auto-generates salts in Symfony 5+.
  • No hidden characters (e.g., BOM) in the plain password.

• Logs: Enable Symfony’s debug mode to inspect the encoder:

  APP_DEBUG=1 php bin/console debug:container usu_scrypt_password_encoder
  

Extension Points

1. Custom Encoder Extend Usu\ScryptPasswordEncoderBundle\Encoder\ScryptEncoder to modify behavior (e.g., dynamic cost based on user role):

   class CustomScryptEncoder extends ScryptEncoder {
       protected function getParameters(UserInterface $user) {
           $params = parent::getParameters($user);
           $params['cost'] = $user->isAdmin() ? 18 : 15;
           return $params;
       }
   }
   

   Register it as a service, replacing the default encoder.

2. Event Listeners Use Symfony’s PasswordReset events to log or validate scrypt hashes:

   // config/services.yaml
   services:
       App\EventListener\ScryptListener:
           tags:
               - { name: 'kernel.event_listener', event: 'security.password_reset.start', method: 'onPasswordReset' }
   

3. Fallback Encoder Combine with Symfony’s chain_encoders for backward compatibility:

   security:
       encoders:
           App\Entity\User:
               - 'scrypt'
               - 'bcrypt'  # Fallback for legacy hashes