Koha/AuthUtils.pm

   1 package Koha::AuthUtils;
   2
   3 # Copyright 2013 Catalyst IT
   4 #
   5 # This file is part of Koha.
   6 #
   7 # Koha is free software; you can redistribute it and/or modify it
   8 # under the terms of the GNU General Public License as published by
   9 # the Free Software Foundation; either version 3 of the License, or
  10 # (at your option) any later version.
  11 #
  12 # Koha is distributed in the hope that it will be useful, but
  13 # WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15 # GNU General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU General Public License
  18 # along with Koha; if not, see <http://www.gnu.org/licenses>.
  19
  20 use Modern::Perl;
  21 use Crypt::Eksblowfish::Bcrypt qw(bcrypt en_base64);
  22 use Encode qw( encode is_utf8 );
  23 use Fcntl qw/O_RDONLY/; # O_RDONLY is used in generate_salt
  24
  25 use base 'Exporter';
  26
  27 our @EXPORT_OK   = qw(hash_password);
  28
  29 =head1 NAME
  30
  31 Koha::AuthUtils - utility routines for authentication
  32
  33 =head1 SYNOPSIS
  34
  35     use Koha::AuthUtils qw/hash_password/;
  36     my $hash = hash_password($password);
  37
  38 =head1 DESCRIPTION
  39
  40 This module provides utility functions related to managing
  41 user passwords.
  42
  43 =head1 FUNCTIONS
  44
  45 =head2 hash_password
  46
  47     my $hash = Koha::AuthUtils::hash_password($password, $settings);
  48
  49 =cut
  50
  51 # Using Bcrypt method for hashing. This can be changed to something else in future, if needed.
  52 sub hash_password {
  53     my $password = shift;
  54     $password = Encode::encode( 'UTF-8', $password )
  55       if Encode::is_utf8($password);
  56
  57     # Generate a salt if one is not passed
  58     my $settings = shift;
  59     unless( defined $settings ){ # if there are no settings, we need to create a salt and append settings
  60     # Set the cost to 8 and append a NULL
  61         $settings = '$2a$08$'.en_base64(generate_salt('weak', 16));
  62     }
  63     # Encrypt it
  64     return bcrypt($password, $settings);
  65 }
  66
  67 =head2 generate_salt
  68
  69     my $salt = Koha::Auth::generate_salt($strength, $length);
  70
  71 =over
  72
  73 =item strength
  74
  75 For general password salting a C<$strength> of C<weak> is recommend,
  76 For generating a server-salt a C<$strength> of C<strong> is recommended
  77
  78 'strong' uses /dev/random which may block until sufficient entropy is acheived.
  79 'weak' uses /dev/urandom and is non-blocking.
  80
  81 =item length
  82
  83 C<$length> is a positive integer which specifies the desired length of the returned string
  84
  85 =back
  86
  87 =cut
  88
  89
  90 # the implementation of generate_salt is loosely based on Crypt::Random::Provider::File
  91 sub generate_salt {
  92     # strength is 'strong' or 'weak'
  93     # length is number of bytes to read, positive integer
  94     my ($strength, $length) = @_;
  95
  96     my $source;
  97
  98     if( $length < 1 ){
  99         die "non-positive strength of '$strength' passed to Koha::AuthUtils::generate_salt\n";
 100     }
 101
 102     if( $strength eq "strong" ){
 103         $source = '/dev/random'; # blocking
 104     } else {
 105         unless( $strength eq 'weak' ){
 106             warn "unsuppored strength of '$strength' passed to Koha::AuthUtils::generate_salt, defaulting to 'weak'\n";
 107         }
 108         $source = '/dev/urandom'; # non-blocking
 109     }
 110
 111     sysopen SOURCE, $source, O_RDONLY
 112         or die "failed to open source '$source' in Koha::AuthUtils::generate_salt\n";
 113
 114     # $bytes is the bytes just read
 115     # $string is the concatenation of all the bytes read so far
 116     my( $bytes, $string ) = ("", "");
 117
 118     # keep reading until we have $length bytes in $strength
 119     while( length($string) < $length ){
 120         # return the number of bytes read, 0 (EOF), or -1 (ERROR)
 121         my $return = sysread SOURCE, $bytes, $length - length($string);
 122
 123         # if no bytes were read, keep reading (if using /dev/random it is possible there was insufficient entropy so this may block)
 124         next unless $return;
 125         if( $return == -1 ){
 126             die "error while reading from $source in Koha::AuthUtils::generate_salt\n";
 127         }
 128
 129         $string .= $bytes;
 130     }
 131
 132     close SOURCE;
 133     return $string;
 134 }
 135 1;
 136
 137 __END__
 138
 139 =head1 SEE ALSO
 140
 141 Crypt::Eksblowfish::Bcrypt(3)
 142
 143 =cut