3 # Created as wrapper for CSRF and JWT tokens, but designed for more general use
5 # Copyright 2016 Rijksmuseum
7 # This file is part of Koha.
9 # Koha is free software; you can redistribute it and/or modify it
10 # under the terms of the GNU General Public License as published by
11 # the Free Software Foundation; either version 3 of the License, or
12 # (at your option) any later version.
14 # Koha is distributed in the hope that it will be useful, but
15 # WITHOUT ANY WARRANTY; without even the implied warranty of
16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 # GNU General Public License for more details.
19 # You should have received a copy of the GNU General Public License
20 # along with Koha; if not, see <http://www.gnu.org/licenses>.
24 Koha::Token - Tokenizer
29 my $tokenizer = Koha::Token->new;
30 my $token = $tokenizer->generate({ length => 20 });
32 # safely generate a CSRF token (nonblocking)
33 my $csrf_token = $tokenizer->generate({
34 type => 'CSRF', id => $id, secret => $secret,
37 # generate/check CSRF token with defaults and session id
38 my $csrf_token = $tokenizer->generate_csrf({ session_id => $x });
39 my $result = $tokenizer->check_csrf({
40 session_id => $x, token => $token,
45 Designed for providing general tokens.
46 Created due to the need for a nonblocking call to Bytes::Random::Secure
47 when generating a CSRF token.
52 use Bytes::Random::Secure;
56 use Digest::MD5 qw( md5_base64 );
59 use Koha::Exceptions::Token;
62 use base qw(Class::Accessor);
63 use constant HMAC_SHA1_LENGTH => 20;
64 use constant CSRF_EXPIRY_HOURS => 8; # 8 hours instead of 7 days..
65 use constant DEFA_SESSION_ID => 0;
66 use constant DEFA_SESSION_USERID => 'anonymous';
72 Create object (via Class::Accessor).
78 return $class->SUPER::new();
83 my $token = $tokenizer->generate({ length => 20 });
84 my $csrf_token = $tokenizer->generate({
85 type => 'CSRF', id => $id, secret => $secret,
87 my $jwt = $tokenizer->generate({
88 type => 'JWT, id => $id, secret => $secret,
91 Generate several types of tokens. Now includes CSRF.
92 For non-CSRF tokens an optional pattern parameter overrides length.
93 Room for future extension.
95 Pattern parameter could be write down using this subset of regular expressions:
96 \w Alphanumeric + "_".
98 \W Printable characters other than those in \w.
99 \D Printable characters other than those in \d.
100 . Printable characters.
101 [] Character classes.
110 my ( $self, $params ) = @_;
111 if( $params->{type} && $params->{type} eq 'CSRF' ) {
112 $self->{lasttoken} = _gen_csrf( $params );
113 } elsif( $params->{type} && $params->{type} eq 'JWT' ) {
114 $self->{lasttoken} = _gen_jwt( $params );
116 $self->{lasttoken} = _gen_rand( $params );
118 return $self->{lasttoken};
123 Like: generate({ type => 'CSRF', ... })
124 Note: id defaults to userid from context, secret to database password.
125 session_id is mandatory; it is combined with id.
130 my ( $self, $params ) = @_;
131 return if !$params->{session_id};
132 $params = _add_default_csrf_params( $params );
133 return $self->generate({ %$params, type => 'CSRF' });
138 Like: generate({ type => 'JWT', ... })
139 Note that JWT is designed to encode a structure but here we are actually only allowing a value
140 that will be store in the key 'id'.
145 my ( $self, $params ) = @_;
146 return if !$params->{id};
147 $params = _add_default_jwt_params( $params );
148 return $self->generate({ %$params, type => 'JWT' });
153 my $result = $tokenizer->check({
154 type => 'CSRF', id => $id, token => $token,
157 Check several types of tokens. Now includes CSRF.
158 Room for future extension.
163 my ( $self, $params ) = @_;
164 if( $params->{type} && $params->{type} eq 'CSRF' ) {
165 return _chk_csrf( $params );
167 elsif( $params->{type} && $params->{type} eq 'JWT' ) {
168 return _chk_jwt( $params );
175 Like: check({ type => 'CSRF', ... })
176 Note: id defaults to userid from context, secret to database password.
177 session_id is mandatory; it is combined with id.
182 my ( $self, $params ) = @_;
183 return if !$params->{session_id};
184 $params = _add_default_csrf_params( $params );
185 my $c = $self->check({ %$params, type => 'CSRF' });
188 # If the check failed we need to test with the "anonymous" in case the token was generating without the user being logged in yet.
189 $params->{id} = DEFA_SESSION_USERID . '_' . $params->{session_id};
190 $c = $self->check({ %$params, type => 'CSRF' });
198 Like: check({ type => 'JWT', id => $id, token => $token })
200 Will return true if the token contains the passed id
205 my ( $self, $params ) = @_;
206 $params = _add_default_jwt_params( $params );
207 return $self->check({ %$params, type => 'JWT' });
212 $tokenizer->decode_jwt({ type => 'JWT', token => $token })
214 Will return the value of the id stored in the token.
218 my ( $self, $params ) = @_;
219 $params = _add_default_jwt_params( $params );
220 return _decode_jwt( $params );
223 # --- Internal routines ---
225 sub _add_default_csrf_params {
227 $params->{session_id} //= DEFA_SESSION_ID;
230 my $session = Koha::Session->get_session( { sessionID => $params->{session_id} } );
232 $id = $session->param('id');
235 $id = DEFA_SESSION_USERID;
238 $params->{id} //= Encode::encode( 'UTF-8', $id );
239 $params->{id} .= '_' . $params->{session_id};
241 my $pw = C4::Context->config('pass');
242 $params->{secret} //= md5_base64( Encode::encode( 'UTF-8', $pw ) ),
248 # Since WWW::CSRF::generate_csrf_token does not use the NonBlocking
249 # parameter of Bytes::Random::Secure, we are passing random bytes from
250 # a non blocking source to WWW::CSRF via its Random parameter.
253 return if !$params->{id} || !$params->{secret};
256 my $randomizer = Bytes::Random::Secure->new( NonBlocking => 1 );
257 # this is most fundamental: do not use /dev/random since it is
258 # blocking, but use /dev/urandom !
259 my $random = $randomizer->bytes( HMAC_SHA1_LENGTH );
260 my $token = WWW::CSRF::generate_csrf_token(
261 $params->{id}, $params->{secret}, { Random => $random },
269 return if !$params->{id} || !$params->{secret} || !$params->{token};
271 my $csrf_status = WWW::CSRF::check_csrf_token(
275 { MaxAge => $params->{MaxAge} // ( CSRF_EXPIRY_HOURS * 3600 ) },
277 return $csrf_status == WWW::CSRF::CSRF_OK();
282 my $length = $params->{length} || 1;
283 $length = 1 unless $length > 0;
284 my $pattern = $params->{pattern} // '.{'.$length.'}'; # pattern overrides length parameter
288 $token = String::Random::random_regex( $pattern );
290 Koha::Exceptions::Token::BadPattern->throw($@) if $@;
294 sub _add_default_jwt_params {
296 my $pw = C4::Context->config('pass');
297 $params->{secret} //= md5_base64( Encode::encode( 'UTF-8', $pw ) ),
303 return if !$params->{id} || !$params->{secret};
305 return Mojo::JWT->new(
306 claims => { id => $params->{id} },
307 secret => $params->{secret}
313 return if !$params->{id} || !$params->{secret} || !$params->{token};
315 my $claims = Mojo::JWT->new(secret => $params->{secret})->decode($params->{token});
317 return 1 if exists $claims->{id} && $claims->{id} eq $params->{id};
322 return if !$params->{token} || !$params->{secret};
324 my $claims = Mojo::JWT->new(secret => $params->{secret})->decode($params->{token});
326 return $claims->{id};
331 Marcel de Rooy, Rijksmuseum Amsterdam, The Netherlands