NAME

Mojolicious::Plugin::Util::RandomString - Generate Secure Random Strings for Mojolicious

SYNOPSIS

  # Mojolicious::Lite
  plugin 'Util::RandomString' => {
    entropy => 256,
    printable => {
      alphabet => '2345679bdfhmnprtFGHJLMNPRT',
      length   => 20
    }
  };

  # Generate string with default configuration
  <%= random_string %>

  # Generate string with 'printable' configuration
  <%= random_string 'printable' %>

  # Generate string with 'printable' configuration
  # and overwrite length
  <%= random_string 'printable', length => 16 %>

  # Generate string with default configuration
  # and overwrite character set in a Controller
  $c->random_string(alphabet => ['a' .. 'z']);

DESCRIPTION

Mojolicious::Plugin::Util::RandomString is a plugin to generate random strings for session tokens, encryption salt, temporary password generation etc. Internally it uses Session::Token (see this comparison for reasons for this decision).

This plugin will automatically reseed the random number generator in a forking environment like Hypnotoad (although it is untested in other forking environments that don't use Mojo::IOLoop).

METHODS

Mojolicious::Plugin::Util::RandomString inherits all methods from Mojolicious::Plugin and implements the following new one.

register

  # Mojolicious
  $app->plugin('Util::RandomString');

  # Mojolicious::Lite
  plugin 'Util::RandomString' => {
    entropy => 256,
    printable => {
      alphabet => '2345679bdfhmnprtFGHJLMNPRT',
      length   => 20
    }
  };

  # Or in your config file
  {
    'Util-RandomString' => {
      entropy => 256,
      printable => {
        alphabet => '2345679bdfhmnprtFGHJLMNPRT',
        length   => 20
      }
    }
  }

Called when registering the plugin. Expects a hash reference containing parameters as defined in Session::Token for the default generator. To specify named generators, use a name key (other than alphabet, length, and entropy) and specify the parameters as a hash reference. The name key 'default' can overwrite the default configuration.

All parameters can be set either on registration or as part of the configuration file with the key Util-RandomString.

The plugin can be registered multiple times with different, overwriting configurations.

The default alphabet is base62. This is good for a lot of use cases. If you want to generate human readable tokens, you can define another scheme (e.g. the above shown 'printable' base26 scheme with a character set with visually distinctive characters, that also makes it unlikely to generate insulting words due to missing vocals).

HELPERS

random_string

  # In Controller
  print $c->random_string;
  print $c->random_string('printable');
  print $c->random_string(length => 45)
  print $c->random_string('printable', length => 45)

  # In Template
  %= random_string;
  %= random_string('printable');
  %= random_string(length => 45)
  %= random_string('printable', length => 45)

Generate a random string. In case of no parameters, the default configuration is used. In case of one parameter, this is treated as the key of a chosen configuration. The following parameters can be used to modify a given configuration for one request (but please note: each modified request creates a new and seeded Session::Token generator, which is bad for performance).

DEPENDENCIES

Mojolicious (best with SSL support), Session::Token.

AVAILABILITY

  https://github.com/Akron/Mojolicious-Plugin-Util-RandomString

COPYRIGHT AND LICENSE

Copyright (C) 2013-2014, Nils Diewald.

This program is free software, you can redistribute it and/or modify it under the same terms as Perl.