lib/Web/Authn.pm

filter: Statementstmt 92.3% 24 / 26 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 9 / 9 Podpod n/a totaltotal 94.2% 33 / 35 CC 1 SCAR 0.3
CC
1
Cov
92%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« blib/lib/Web/Authn/Cookbook.pm ↑ Summary
1 ##----------------------------------------------------------------------------
2 ## WebAuthn - ~/lib/Web/Authn.pm
3 ## Version v0.2.2
4 ## Copyright(c) 2026 DEGUEST Pte. Ltd.
5 ## Author: Jacques Deguest <jack@deguest.jp>
6 ## Created 2026/09/09
7 ## Modified 2026/09/12
8 ## All rights reserved
9 ##
10 ## This program is free software; you can redistribute it and/or modify it
11 ## under the same terms as Perl itself.
12 ##----------------------------------------------------------------------------
13 package Web::Authn;
14 BEGIN
15 {
16 1 ▶ use v5.16.0;
Subroutine BEGIN: called CC=1 SCAR=0.0
17 1 ▶ use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 1 ▶ use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
19 1 ▶ use warnings::register;
Subroutine BEGIN: called CC=1 SCAR=0.0
20 1 ▶ use parent qw( Exporter );
Subroutine BEGIN: called CC=1 SCAR=0.0
21 1 ▶ use vars qw( $VERSION $ERROR $DEBUG $FATAL_EXCEPTIONS $JSON_CLASS @EXPORT_OK );
Subroutine BEGIN: called CC=1 SCAR=0.0
22 1 ▶ use Digest::SHA qw( sha256 );
Subroutine BEGIN: called CC=1 SCAR=0.0
23 1 ▶ use Scalar::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
24 0 ▶ use Wanted;
Subroutine BEGIN: called CC=1 SCAR=2.6
25 use Web::Authn::Attestation;
26 use Web::Authn::COSE;
27 use Web::Authn::Crypto;
28 use Web::Authn::Exception;
29 use Web::Authn::NullObject;
30 use Web::Authn::Parse;
31 our @EXPORT_OK = qw(
32 generate_registration_options
33 verify_registration_response
34 generate_authentication_options
35 verify_authentication_response
36 options_to_json
37 base64url_to_bytes
38 bytes_to_base64url
39 generate_challenge
40 generate_user_handle
41 );
42 # JSON backend detection: prefer Cpanel::JSON::XS (fastest, most rigorous), fall back
43 # to JSON::XS, then JSON::PP (core since Perl 5.14).
44 our $JSON_CLASS;
45 local $@;
46 if( eval{ require Cpanel::JSON::XS; 1 } )
47 {
48 $JSON_CLASS = 'Cpanel::JSON::XS';
49 }
50 elsif( eval{ require JSON::XS; 1 } )
51 {
52 $JSON_CLASS = 'JSON::XS';
53 }
54 else
55 {
56 require JSON::PP;
57 $JSON_CLASS = 'JSON::PP';
58 }
59 our $VERSION = 'v0.2.2';
60 };
61  
62 use strict;
63 use warnings;
64  
65 sub new
66 {
67 my $this = shift( @_ );
68 my $class = ref( $this ) || $this;
69 my $args = $this->_get_args_as_hash( @_ );
70 $this->_check_known_args( $args, [qw(
71 attestation
72 debug
73 expected_origin
74 expected_origins
75 expected_rp_id
76 fatal
77 origin
78 origins
79 rp_id
80 rp_name
81 timeout
82 user_verification
83 )] ) || return( $this->pass_error );
84  
85 my $origin = $args->{expected_origin} // $args->{expected_origins} // $args->{origin} // $args->{origins};
86 if( ( Scalar::Util::reftype( $origin ) || '' ) eq 'ARRAY' )
87 {
88 $origin = [ map{ $this->_plain( $_ ) } @$origin ];
89 }
90 else
91 {
92 $origin = $this->_plain( $origin );
93 }
94 my $self = bless({
95 rp_id => $this->_plain( $args->{rp_id} ),
96 rp_name => $this->_plain( $args->{rp_name} ),
97 expected_origin => $origin,
98 expected_rp_id => $this->_plain( $args->{expected_rp_id} || $args->{rp_id} ),
99 attestation => $this->_plain( $args->{attestation} ) || 'none',
100 timeout => defined( $args->{timeout} ) ? 0 + $this->_plain( $args->{timeout} ) : 60_000,
101 user_verification => $this->_plain( $args->{user_verification} ) || 'preferred',
102 fatal => defined( $args->{fatal} ) ? ( $this->_plain( $args->{fatal} ) ? 1 : 0 ) : 0,
103 debug => defined( $args->{debug} ) ? ( $this->_plain( $args->{debug} ) ? 1 : 0 ) : 0,
104 error => undef,
105 } => $class );
106 return( $self );
107 }
108  
109 # For option generation
110 sub base64url_to_bytes
111 {
112 my $self = __PACKAGE__->_instance( \@_ );
113 my $str = Web::Authn::Parse::maybe_bytes( shift( @_ ) );
114 local $@;
115 my $out = eval { Web::Authn::Parse::b64u_decode( $str ) };
116 return( $self->pass_error( $@ ) ) if( $@ );
117 return( $out );
118 }
119  
120 # For option generation
121 sub bytes_to_base64url
122 {
123 my $self = __PACKAGE__->_instance( \@_ );
124 my $bin = Web::Authn::Parse::maybe_bytes( shift( @_ ) );
125 return( Web::Authn::Parse::b64u_encode( $bin ) );
126 }
127  
128 sub error
129 {
130 my $self = shift( @_ );
131 $self = __PACKAGE__ unless( defined( $self ) );
132 if( @_ )
133 {
134 require Web::Authn::Exception;
135 my $msg;
136 my $opts = {};
137 if( @_ == 1 && ref( $_[0] ) eq 'HASH' )
138 {
139 $opts = $_[0];
140 $msg = $opts->{message};
141 }
142 else
143 {
144 $msg = join( '', map{ ( ref( $_ ) eq 'CODE' ) ? $_->() : $_ } @_ );
145 }
146 my $class = $opts->{class} || 'Web::Authn::Exception';
147 my $e = $class->new({
148 skip_frames => 1,
149 message => ( defined( $msg ) ? $msg : '' ),
150 ( defined( $opts->{code} ) ? ( code => $opts->{code} ) : () ),
151 });
152 $ERROR = $e;
153 $self->{error} = $e if( ref( $self ) );
154 if( $self->fatal )
155 {
156 die( $e );
157 }
158 else
159 {
160 warn( $e->message ) if( warnings::enabled( 'Web::Authn' ) );
161 rreturn( Web::Authn::NullObject->new ) if( want( 'OBJECT' ) );
162 return;
163 }
164 }
165 return( ref( $self ) ? $self->{error} : $ERROR );
166 }
167  
168 sub fatal
169 {
170 my $this = shift( @_ );
171 if( @_ )
172 {
173 if( ref( $this ) )
174 {
175 return( $this->_set_get_prop( 'fatal', @_ ) );
176 }
177 else
178 {
179 warn( "Cannot call fatal in mutator mode as a class method." ) if( warnings::enabled() );
180 }
181 }
182 return( ref( $this ) ? $this->_set_get_prop( 'fatal' ) : $FATAL_EXCEPTIONS );
183 }
184  
185 # For option generation
186 sub generate_authentication_options
187 {
188 my $self = __PACKAGE__->_instance( \@_ );
189 my $args = $self->_get_args_as_hash( @_ );
190 $self->_check_known_args( $args, [qw(
191 allow_credentials
192 challenge
193 rp_id
194 timeout
195 user_verification
196 )] ) || return( $self->pass_error );
197 my $rp_id = $self->_plain( $args->{rp_id} || $self->{rp_id} );
198 unless( defined( $rp_id ) && length( $rp_id ) )
199 {
200 return( $self->error( 'rp_id cannot be an empty string' ) );
201 }
202 return({
203 rp_id => $rp_id,
204 challenge => defined( $args->{challenge} ) ? Web::Authn::Parse::maybe_bytes( $args->{challenge} ) : Web::Authn::Parse::generate_challenge(),
205 timeout => defined( $args->{timeout} ) ? 0 + $self->_plain( $args->{timeout} ) : ( $self->{timeout} || 60_000 ),
206 allow_credentials => $args->{allow_credentials} || [],
207 user_verification => $self->_plain( $args->{user_verification} || $self->{user_verification} ) || 'preferred',
208 });
209 }
210  
211 # For option generation
212 sub generate_challenge
213 {
214 my $self = __PACKAGE__->_instance( \@_ );
215 my $len = shift( @_ );
216 return( Web::Authn::Parse::generate_challenge( $len ) );
217 }
218  
219 # For option generation
220 sub generate_registration_options
221 {
222 my $self = __PACKAGE__->_instance( \@_ );
223 my $args = $self->_get_args_as_hash( @_ );
224 $self->_check_known_args( $args, [qw(
225 attestation
226 authenticator_selection
227 challenge
228 exclude_credentials
229 hints
230 rp_id
231 rp_name
232 supported_pub_key_algs
233 timeout
234 user_display_name
235 user_id
236 user_name
237 )] ) || return( $self->pass_error );
238 my $rp_id = $self->_plain( $args->{rp_id} || $self->{rp_id} );
239 my $rp_name = $self->_plain( $args->{rp_name} || $self->{rp_name} );
240 my $user_name = $self->_plain( $args->{user_name} );
241 unless( defined( $rp_id ) && length( $rp_id ) )
242 {
243 return( $self->error( 'rp_id cannot be an empty string' ) );
244 }
245 unless( defined( $rp_name ) && length( $rp_name ) )
246 {
247 return( $self->error( 'rp_name cannot be an empty string' ) );
248 }
249 unless( defined( $user_name ) && length( $user_name ) )
250 {
251 return( $self->error( 'user_name cannot be an empty string' ) );
252 }
253  
254 my $user_id = $args->{user_id};
255 if( defined( $user_id ) )
256 {
257 local $@;
258 $user_id = eval { Web::Authn::Parse::maybe_bytes( $user_id ) };
259 if( $@ )
260 {
261 return( $self->error( 'user_id must be bytes' ) );
262 }
263 }
264 else
265 {
266 $user_id = Web::Authn::Parse::generate_user_handle();
267 }
268  
269 my @algs = $args->{supported_pub_key_algs}
270 ? @{$args->{supported_pub_key_algs}}
271 : Web::Authn::COSE::default_supported_algs();
272  
273 my $sel = $args->{authenticator_selection};
274 if( $sel && ( ( $self->_plain( $sel->{resident_key} ) || '' ) eq 'required' ) )
275 {
276 $sel->{require_resident_key} = 1;
277 }
278  
279 return({
280 rp => { name => $rp_name, id => $rp_id },
281 user => {
282 id => $user_id,
283 name => $user_name,
284 display_name => $self->_plain( $args->{user_display_name} ) || $user_name,
285 },
286 challenge => defined( $args->{challenge} ) ? Web::Authn::Parse::maybe_bytes( $args->{challenge} ) : Web::Authn::Parse::generate_challenge(),
287 pub_key_cred_params => [ map{ { type => 'public-key', alg => $_ } } @algs ],
288 timeout => defined( $args->{timeout} ) ? 0 + $self->_plain( $args->{timeout} ) : ( $self->{timeout} || 60_000 ),
289 exclude_credentials => $args->{exclude_credentials} || [],
290 attestation => $self->_plain( $args->{attestation} || $self->{attestation} ) || 'none',
291 authenticator_selection => $sel,
292 hints => $args->{hints},
293 });
294 }
295  
296 # For option generation
297 sub generate_user_handle
298 {
299 my $self = __PACKAGE__->_instance( \@_ );
300 return( Web::Authn::Parse::generate_user_handle() );
301 }
302  
303 # For option generation
304 sub options_to_json
305 {
306 my $self = __PACKAGE__->_instance( \@_ );
307 my $opts = shift( @_ );
308 return( Web::Authn::Parse::options_to_json( $opts ) );
309 }
310  
311 # For option generation
312 sub options_to_json_dict
313 {
314 my $self = __PACKAGE__->_instance( \@_ );
315 my $opts = shift( @_ );
316 return( Web::Authn::Parse::options_to_json_dict( $opts ) );
317 }
318  
319 sub pass_error
320 {
321 my $self = shift( @_ );
322 $self = __PACKAGE__ unless( defined( $self ) );
323 my $pack = ref( $self ) || $self;
324 my $opts = {};
325 my( $err, $class, $code );
326 no strict 'refs';
327 if( scalar( @_ ) )
328 {
329 if( scalar( @_ ) == 1 && ref( $_[0] ) eq 'HASH' )
330 {
331 $opts = $_[0];
332 }
333 else
334 {
335 if( scalar( @_ ) > 1 && ref( $_[-1] ) eq 'HASH' )
336 {
337 $opts = pop( @_ );
338 }
339 $err = $_[0];
340 }
341 }
342 $err = $opts->{error} if( !defined( $err ) && CORE::exists( $opts->{error} ) && defined( $opts->{error} ) && CORE::length( $opts->{error} ) );
343 $class = $opts->{class} if( CORE::exists( $opts->{class} ) && defined( $opts->{class} ) && CORE::length( $opts->{class} ) );
344 $code = $opts->{code} if( CORE::exists( $opts->{code} ) && defined( $opts->{code} ) && CORE::length( $opts->{code} ) );
345  
346 if( !defined( $err ) && ( !scalar( @_ ) || defined( $class ) ) )
347 {
348 my $error = ref( $self ) ? $self->{error} : length( ${ $pack . '::ERROR' } ) ? ${ $pack . '::ERROR' } : undef;
349 unless( defined( $error ) )
350 {
351 warn( "No error object provided and no previous error set either! It seems the previous method call returned a simple undef" );
352 }
353 else
354 {
355 $err = ( defined( $class ) ? bless( $error => $class ) : $error );
356 $err->code( $code ) if( defined( $code ) && $err->can( 'code' ) );
357 }
358 }
359 elsif( defined( $err ) &&
360 Scalar::Util::blessed( $err ) &&
361 ( scalar( @_ ) == 1 || ( scalar( @_ ) == 2 && defined( $class ) ) ) )
362 {
363 $self->{error} = ${ $pack . '::ERROR' } = ( defined( $class ) ? bless( $err => $class ) : $err );
364 $self->{error}->code( $code ) if( defined( $code ) && $self->{error}->can( 'code' ) );
365 if( ( ref( $self ) && $self->{fatal} ) ||
366 ( defined( ${"${pack}::FATAL_EXCEPTIONS"} ) && ${"${pack}::FATAL_EXCEPTIONS"} ) )
367 {
368 die( $self->{error} );
369 }
370 }
371 else
372 {
373 return( $self->error( @_ ) );
374 }
375  
376 if( want( 'OBJECT' ) )
377 {
378 rreturn( Web::Authn::NullObject->new );
379 }
380 return;
381 }
382  
383 # NOTE: Authentication verification (WebAuthn §7.2)
384 sub verify_authentication_response
385 {
386 my $self = __PACKAGE__->_instance( \@_ );
387 my $args = $self->_get_args_as_hash( @_ );
388 $self->_check_known_args( $args, [qw(
389 credential
390 credential_current_sign_count
391 credential_public_key
392 expected_challenge
393 expected_origin
394 expected_origins
395 expected_rp_id
396 origin
397 origins
398 require_user_verification
399 )] ) || return( $self->pass_error );
400 my $credential = $args->{credential};
401 my $expected_challenge = Web::Authn::Parse::maybe_bytes( $args->{expected_challenge} );
402 my $expected_rp_id = $self->_plain( $args->{expected_rp_id} || $self->{expected_rp_id} || $self->{rp_id} );
403 my $expected_origin = $args->{expected_origin} // $args->{expected_origins} // $args->{origin} // $args->{origins} // $self->{expected_origin};
404 my $cred_pk = Web::Authn::Parse::maybe_bytes( $args->{credential_public_key} );
405 my $current_count = defined( $args->{credential_current_sign_count} ) ? 0 + $self->_plain( $args->{credential_current_sign_count} ) : undef;
406 unless( defined( $credential ) && defined( $expected_challenge ) &&
407 defined( $expected_rp_id ) && defined( $expected_origin ) &&
408 defined( $cred_pk ) && defined( $current_count ) )
409 {
410 return( $self->_fail( 'Web::Authn::Exception::InvalidAuthentication', 'missing required verification arguments' ) );
411 }
412  
413 unless( ref( $credential ) eq 'HASH'
414 && $credential->{raw_id}
415 && $credential->{response}
416 && $credential->{response}->{authenticator_data}
417 && $credential->{response}->{signature} )
418 {
419 local $@;
420 $credential = eval { Web::Authn::Parse::parse_authentication_credential_json( $credential ) };
421 return( $self->_caught( 'Web::Authn::Exception::InvalidAuthentication' ) ) if( $@ );
422 }
423  
424 if( Web::Authn::Parse::b64u_encode( $credential->{raw_id} ) ne $credential->{id} )
425 {
426 return( $self->_fail( 'Web::Authn::Exception::InvalidAuthentication', 'id and raw_id were not equivalent' ) );
427 }
428 if( ( $credential->{type} || '' ) ne 'public-key' )
429 {
430 return( $self->_fail( 'Web::Authn::Exception::InvalidAuthentication', qq{Unexpected credential type "$credential->{type}", expected "public-key"} ) );
431 }
432  
433 my $client_data_bytes = $credential->{response}->{client_data_json};
434 my $auth_data_bytes = $credential->{response}->{authenticator_data};
435 my $signature_bytes = $credential->{response}->{signature};
436  
437 local $@;
438 my $client_data = eval { Web::Authn::Parse::parse_client_data_json( $client_data_bytes ) };
439 unless( $client_data )
440 {
441 return( $self->_caught( 'Web::Authn::Exception::InvalidAuthentication', 'clientDataJSON was malformed' ) );
442 }
443 if( $client_data->{type} ne 'webauthn.get' )
444 {
445 return( $self->_fail( 'Web::Authn::Exception::InvalidAuthentication', qq{Unexpected client data type "$client_data->{type}", expected "webauthn.get"} ) );
446 }
447 if( $expected_challenge ne $client_data->{challenge} )
448 {
449 return( $self->_fail( 'Web::Authn::Exception::InvalidAuthentication', 'Client data challenge was not expected challenge' ) );
450 }
451 $self->_check_origin( $expected_origin, $client_data->{origin}, 'InvalidAuthentication' ) || return( $self->pass_error );
452  
453 if( my $tb = $client_data->{token_binding} )
454 {
455 my $st = $tb->{status} || '';
456 unless( $st eq 'supported' || $st eq 'present' )
457 {
458 return( $self->_fail( 'Web::Authn::Exception::InvalidAuthentication', qq{Unexpected token_binding status of "$st"} ) );
459 }
460 }
461  
462 my $auth = eval { Web::Authn::Parse::parse_authenticator_data( $auth_data_bytes ) };
463 unless( $auth )
464 {
465 return( $self->_caught( 'Web::Authn::Exception::InvalidAuthentication', 'authenticatorData was malformed' ) );
466 }
467 if( $auth->{rp_id_hash} ne sha256( $expected_rp_id ) )
468 {
469 return( $self->_fail( 'Web::Authn::Exception::InvalidAuthentication', 'Unexpected RP ID hash' ) );
470 }
471 unless( $auth->{flags}->{up} )
472 {
473 return( $self->_fail( 'Web::Authn::Exception::InvalidAuthentication', 'User was not present during authentication' ) );
474 }
475 if( $args->{require_user_verification} && !$auth->{flags}->{uv} )
476 {
477 return( $self->_fail( 'Web::Authn::Exception::InvalidAuthentication', 'User verification is required but user was not verified during authentication' ) );
478 }
479 if( ( $auth->{sign_count} > 0 || $current_count > 0 ) && $auth->{sign_count} <= $current_count )
480 {
481 return( $self->_fail( 'Web::Authn::Exception::InvalidAuthentication', "Response sign count of $auth->{sign_count} was not greater than current count of $current_count" ) );
482 }
483  
484 my $signature_base = $auth_data_bytes . sha256( $client_data_bytes );
485 my $decoded = eval { Web::Authn::Parse::decode_credential_public_key( $cred_pk ) };
486 unless( $decoded )
487 {
488 return( $self->_caught( 'Web::Authn::Exception::InvalidAuthentication', 'credential public key was malformed' ) );
489 }
490 if( ( $decoded->{kty} || 0 ) == Web::Authn::COSE::KTY_ML_DSA )
491 {
492 return( $self->_fail( 'Web::Authn::Exception::UnsupportedAlgorithm', 'ML-DSA verification is not implemented in this release' ) );
493 }
494 eval
495 {
496 my $pk = Web::Authn::Crypto::cose_to_public_key( $decoded );
497 Web::Authn::Crypto::verify_signature(
498 public_key => $pk,
499 alg => $decoded->{alg},
500 signature => $signature_bytes,
501 data => $signature_base,
502 );
503 1;
504 } or return( $self->_caught( 'Web::Authn::Exception::InvalidAuthentication', 'Could not verify authentication signature' ) );
505  
506 my $backup = eval { Web::Authn::Parse::parse_backup_flags( $auth->{flags} ) };
507 return( $self->_caught( 'Web::Authn::Exception::InvalidAuthentication' ) ) if( $@ );
508 return({
509 credential_id => $credential->{raw_id},
510 new_sign_count => $auth->{sign_count},
511 credential_device_type => $backup->{credential_device_type},
512 credential_backed_up => $backup->{credential_backed_up},
513 user_verified => $auth->{flags}->{uv} ? 1 : 0,
514 user_handle => $credential->{response}->{user_handle},
515 });
516 }
517  
518 # NOTE: Registration verification (WebAuthn §7.1)
519 sub verify_registration_response
520 {
521 my $self = __PACKAGE__->_instance( \@_ );
522 my $args = $self->_get_args_as_hash( @_ );
523 $self->_check_known_args( $args, [qw(
524 credential
525 expected_challenge
526 expected_origin
527 expected_origins
528 expected_rp_id
529 origin
530 origins
531 pem_root_certs_bytes_by_fmt
532 require_user_presence
533 require_user_verification
534 supported_pub_key_algs
535 )] ) || return( $self->pass_error );
536 my $credential = $args->{credential};
537 my $expected_challenge = Web::Authn::Parse::maybe_bytes( $args->{expected_challenge} );
538 my $expected_rp_id = $self->_plain( $args->{expected_rp_id} || $self->{expected_rp_id} || $self->{rp_id} );
539 my $expected_origin = $args->{expected_origin} // $args->{expected_origins} // $args->{origin} // $args->{origins} // $self->{expected_origin};
540 unless( defined( $credential ) && defined( $expected_challenge ) &&
541 defined( $expected_rp_id ) && defined( $expected_origin ) )
542 {
543 return( $self->_fail( 'Web::Authn::Exception::InvalidRegistration', 'missing required verification arguments' ) );
544 }
545  
546 unless( ref( $credential ) eq 'HASH' && $credential->{response} &&
547 $credential->{response}->{client_data_json} && $credential->{raw_id} )
548 {
549 local $@;
550 $credential = eval { Web::Authn::Parse::parse_registration_credential_json( $credential ) };
551 return( $self->_caught( 'Web::Authn::Exception::InvalidRegistration' ) ) if( $@ );
552 }
553  
554 if( Web::Authn::Parse::b64u_encode( $credential->{raw_id} ) ne $credential->{id} )
555 {
556 return( $self->_fail( 'Web::Authn::Exception::InvalidRegistration', 'id and raw_id were not equivalent' ) );
557 }
558 if( ( $credential->{type} || '' ) ne 'public-key' )
559 {
560 return( $self->_fail( 'Web::Authn::Exception::InvalidRegistration', qq{Unexpected credential type "$credential->{type}", expected "public-key"} ) );
561 }
562  
563 my $client_data_bytes = $credential->{response}->{client_data_json};
564 my $att_obj_bytes = $credential->{response}->{attestation_object};
565 local $@;
566 my $client_data = eval { Web::Authn::Parse::parse_client_data_json( $client_data_bytes ) };
567 unless( $client_data )
568 {
569 return( $self->_caught( 'Web::Authn::Exception::InvalidRegistration', 'clientDataJSON was malformed' ) );
570 }
571 if( $client_data->{type} ne 'webauthn.create' )
572 {
573 return( $self->_fail( 'Web::Authn::Exception::InvalidRegistration', qq{Unexpected client data type "$client_data->{type}", expected "webauthn.create"} ) );
574 }
575 if( $expected_challenge ne $client_data->{challenge} )
576 {
577 return( $self->_fail( 'Web::Authn::Exception::InvalidRegistration', 'Client data challenge was not expected challenge' ) );
578 }
579 $self->_check_origin( $expected_origin, $client_data->{origin}, 'InvalidRegistration' ) || return( $self->pass_error );
580  
581 if( my $tb = $client_data->{token_binding} )
582 {
583 my $st = $tb->{status} || '';
584 unless( $st eq 'supported' || $st eq 'present' )
585 {
586 return( $self->_fail( 'Web::Authn::Exception::InvalidRegistration', qq{Unexpected token_binding status of "$st"} ) );
587 }
588 }
589  
590 my $att = eval { Web::Authn::Parse::parse_attestation_object( $att_obj_bytes ) };
591 unless( $att )
592 {
593 return( $self->_caught( 'Web::Authn::Exception::InvalidRegistration', 'attestationObject was malformed' ) );
594 }
595 my $auth = $att->{auth_data};
596 if( $auth->{rp_id_hash} ne sha256( $expected_rp_id ) )
597 {
598 return( $self->_fail( 'Web::Authn::Exception::InvalidRegistration', 'Unexpected RP ID hash' ) );
599 }
600 my $require_up = exists( $args->{require_user_presence} ) ? $args->{require_user_presence} : 1;
601 if( $require_up && !$auth->{flags}->{up} )
602 {
603 return( $self->_fail( 'Web::Authn::Exception::InvalidRegistration', 'User presence was required, but was not present during attestation' ) );
604 }
605 if( $args->{require_user_verification} && !$auth->{flags}->{uv} )
606 {
607 return( $self->_fail( 'Web::Authn::Exception::InvalidRegistration', 'User verification is required but user was not verified during attestation' ) );
608 }
609 my $acd = $auth->{attested_credential_data};
610 unless( $acd )
611 {
612 return( $self->_fail( 'Web::Authn::Exception::InvalidRegistration', 'Authenticator did not provide attested credential data' ) );
613 }
614 unless( $acd->{credential_id} )
615 {
616 return( $self->_fail( 'Web::Authn::Exception::InvalidRegistration', 'Authenticator did not provide a credential ID' ) );
617 }
618 unless( $acd->{credential_public_key} )
619 {
620 return( $self->_fail( 'Web::Authn::Exception::InvalidRegistration', 'Authenticator did not provide a credential public key' ) );
621 }
622 unless( $acd->{aaguid} )
623 {
624 return( $self->_fail( 'Web::Authn::Exception::InvalidRegistration', 'Authenticator did not provide an AAGUID' ) );
625 }
626  
627 local $@;
628 my $decoded_pk = eval { Web::Authn::Parse::decode_credential_public_key( $acd->{credential_public_key} ) };
629 return( $self->_caught( 'Web::Authn::Exception::InvalidRegistration' ) ) if( $@ );
630  
631 my @supported = $args->{supported_pub_key_algs}
632 ? @{ $args->{supported_pub_key_algs} }
633 : ( Web::Authn::COSE::default_supported_algs(),
634 Web::Authn::COSE::ECDSA_SHA_384(), Web::Authn::COSE::ECDSA_SHA_512(),
635 Web::Authn::COSE::RSASSA_PKCS1_SHA_384(), Web::Authn::COSE::RSASSA_PKCS1_SHA_512(),
636 Web::Authn::COSE::RSASSA_PSS_SHA_256(), Web::Authn::COSE::RSASSA_PSS_SHA_384(),
637 Web::Authn::COSE::RSASSA_PSS_SHA_512() );
638 unless( grep{ $_ == $decoded_pk->{alg} } @supported )
639 {
640 return( $self->_fail( 'Web::Authn::Exception::InvalidRegistration', qq{Unsupported credential public key alg "$decoded_pk->{alg}"} ) );
641 }
642  
643 my $pem_roots = [];
644 if( $args->{pem_root_certs_bytes_by_fmt} && $args->{pem_root_certs_bytes_by_fmt}->{ $att->{fmt} } )
645 {
646 $pem_roots = $args->{pem_root_certs_bytes_by_fmt}->{ $att->{fmt} };
647 }
648 my $ok = eval
649 {
650 Web::Authn::Attestation::verify(
651 fmt => $att->{fmt}, att_stmt => $att->{att_stmt}, auth_raw => $att->{auth_raw},
652 attestation_object => $att_obj_bytes, client_data_json => $client_data_bytes,
653 credential_public_key => $acd->{credential_public_key}, credential_id => $acd->{credential_id},
654 aaguid => $acd->{aaguid}, rp_id_hash => $auth->{rp_id_hash}, pem_root_certs => $pem_roots,
655 );
656 };
657 unless( $ok )
658 {
659 return( $self->_caught( 'Web::Authn::Exception::InvalidRegistration', 'Attestation statement could not be verified' ) );
660 }
661 my $backup = eval { Web::Authn::Parse::parse_backup_flags( $auth->{flags} ) };
662 return( $self->_caught( 'Web::Authn::Exception::InvalidRegistration' ) ) if( $@ );
663 return({
664 credential_id => $acd->{credential_id},
665 credential_public_key => $acd->{credential_public_key},
666 sign_count => $auth->{sign_count},
667 aaguid => Web::Authn::Parse::aaguid_to_string( $acd->{aaguid} ),
668 fmt => $att->{fmt},
669 credential_type => 'public-key',
670 user_verified => $auth->{flags}->{uv} ? 1 : 0,
671 attestation_object => $att_obj_bytes,
672 credential_device_type => $backup->{credential_device_type},
673 credential_backed_up => $backup->{credential_backed_up},
674 });
675 }
676  
677 sub _caught
678 {
679 my $self = shift( @_ );
680 my $class = shift( @_ );
681 my $fallback = shift( @_ );
682 my $err = $@;
683 if( Scalar::Util::blessed( $err ) && $err->isa( 'Web::Authn::Exception' ) )
684 {
685 return( $self->pass_error( $err ) );
686 }
687 my $msg = defined( $fallback ) && length( $fallback ) ? $fallback : ( defined( $err ) ? "$err" : 'unknown error' );
688 $msg =~ s/\s+at\s+\S+\s+line\s+\d+\.?\s*\z//;
689 return( $self->_fail( $class || 'Web::Authn::Exception', $msg ) );
690 }
691  
692 sub _check_known_args
693 {
694 my $self = shift( @_ );
695 my $args = shift( @_ );
696 my $ok = shift( @_ );
697 unless( $args && ( ref( $args ) || '' ) eq 'HASH' && $ok && ( Scalar::Util::reftype( $ok ) || '' ) eq 'ARRAY' )
698 {
699 return( $self->error( 'Internal error: _check_known_args expects a hash of arguments and an array of valid names' ) );
700 }
701 my %valid = map{ $_ => 1 } @$ok;
702 my @unknown = sort( grep{ !exists( $valid{ $_ } ) } keys( %$args ) );
703 if( @unknown )
704 {
705 my $sub = ( caller(1) )[3];
706 $sub = 'new' unless( defined( $sub ) && length( $sub ) );
707 $sub =~ s/.*:://;
708 return( $self->error( sprintf( 'Unknown argument%s passed to %s: %s', ( @unknown > 1 ? 's' : '' ), $sub, join( ', ', map{ qq{'$_'} } @unknown ) ) ) );
709 }
710 return(1);
711 }
712  
713 sub _check_origin
714 {
715 my $self = shift( @_ );
716 my $expected = shift( @_ );
717 my $got = $self->_plain( shift( @_ ) );
718 my $kind = shift( @_ ) || 'InvalidRegistration';
719 my $class = "Web::Authn::Exception::${kind}";
720 if( ( Scalar::Util::reftype( $expected ) || '' ) eq 'ARRAY' )
721 {
722 return(1) if( grep{ $self->_plain( $_ ) eq $got } @$expected );
723 return( $self->_fail( $class, qq{Unexpected client data origin "$got"} ) );
724 }
725 $expected = $self->_plain( $expected );
726 if( !ref( $expected ) )
727 {
728 unless( $expected eq $got )
729 {
730 return( $self->_fail( $class, qq{Unexpected client data origin "$got", expected "$expected"} ) );
731 }
732 return(1);
733 }
734 return( $self->_fail( $class, 'expected_origin must be a string or array of strings' ) );
735 }
736  
737 sub _fail
738 {
739 my $self = shift( @_ );
740 my $class = shift( @_ ) || 'Web::Authn::Exception';
741 my $msg = shift( @_ );
742 my $e = $class->new({ skip_frames => 2, message => $msg });
743 return( $self->pass_error( $e ) );
744 }
745  
746 sub _get_args_as_hash
747 {
748 my $self = shift( @_ );
749 my $ref = {};
750 if( scalar( @_ ) == 1 &&
751 defined( $_[0] ) &&
752 ( ref( $_[0] ) || '' ) eq 'HASH' )
753 {
754 $ref = shift( @_ );
755 }
756 elsif( !( scalar( @_ ) % 2 ) )
757 {
758 $ref = { @_ };
759 }
760 else
761 {
762 Web::Authn::Exception->throw( 'Uneven number of parameters provided.' );
763 }
764 return( $ref );
765 }
766  
767 sub _instance
768 {
769 my $class = shift( @_ );
770 my $args = shift( @_ );
771 if( @$args && ref( $args->[0] ) && Scalar::Util::blessed( $args->[0] ) && $args->[0]->isa( 'Web::Authn' ) )
772 {
773 return( shift( @$args ) );
774 }
775 if( @$args && defined( $args->[0] ) && !ref( $args->[0] ) && $args->[0] eq 'Web::Authn' )
776 {
777 shift( @$args );
778 return( $class->new );
779 }
780 return( $class->new );
781 }
782  
783  
784 sub _plain
785 {
786 my $self = shift( @_ );
787 return( Web::Authn::Parse::_plain( shift( @_ ) ) );
788 }
789  
790 sub _set_get_prop
791 {
792 my $self = shift( @_ );
793 my $key = shift( @_ );
794 $self->{ $key } = shift( @_ ) if( @_ );
795 return( $self->{ $key } );
796 }
797  
798 1;
799 # NOTE: POD
800 __END__
« blib/lib/Web/Authn/Cookbook.pm ↑ Summary