NAME
Web::Authn::Parse - Parsing helpers for WebAuthn structures
SYNOPSIS
my $cd = Web::Authn::Parse::parse_client_data_json( $bytes );
my $ad = Web::Authn::Parse::parse_authenticator_data( $bytes );
my $ao = Web::Authn::Parse::parse_attestation_object( $bytes );
my $pk = Web::Authn::Parse::decode_credential_public_key( $cose );DESCRIPTION
Turns the binary and JSON blobs defined by WebAuthn into Perl hashes. Web::Authn calls these for you; they are public if you need to inspect a response yourself.
FUNCTIONS
aaguid_to_string
my $uuid = Web::Authn::Parse::aaguid_to_string( $acd->{aaguid} );
# "00000000-0000-0000-0000-000000000000"Formats a 16-byte AAGUID as a UUID string. Pass the raw 16 bytes, or an object that overloads stringification such as Module::Generic::Scalar.
The function throws Web::Authn::Exception::InvalidStructure if the value is not exactly 16 bytes long.
b64u_decode
my $raw = Web::Authn::Parse::b64u_decode( $credential->{id} );Decodes unpadded base64url to raw bytes. Pass the string to decode (characters A-Za-z0-9_-), or an object that overloads stringification.
b64u_encode
my $id = Web::Authn::Parse::b64u_encode( $acd->{credential_id} );Encodes raw bytes as unpadded base64url. Pass the byte string to encode, or an object that overloads stringification.
decode_credential_public_key
my $pk = Web::Authn::Parse::decode_credential_public_key( $cose );
# { kty => 2, alg => -7, crv => 1, x => $x, y => $y }Decodes a COSE_Key CBOR map, or uncompressed U2F 0x04 || X || Y (65 bytes), into a Perl hash with kty, alg, and the type-specific fields (crv/x/y, n/e, or pub). Pass the raw key bytes, or an object that overloads stringification.
generate_challenge
my $chal = Web::Authn::Parse::generate_challenge; # 64
my $chal = Web::Authn::Parse::generate_challenge(16);Returns raw CSPRNG bytes from Bytes::Random::Secure. You may pass an optional integer length; it defaults to 64.
generate_user_handle
my $handle = Web::Authn::Parse::generate_user_handle;Returns 64 raw random bytes suitable as a WebAuthn user.id. This function takes no arguments.
maybe_bytes
my $raw = Web::Authn::Parse::maybe_bytes( $maybe_sv );Normalises a value to raw bytes. Pass a plain Perl string, an unblessed scalar reference, or a blessed object that overloads stringification (overload::Method( $obj, '""' )), such as Module::Generic::Scalar. In the last case the value is taken as $obj . ''.
Anything else throws expected bytes.
options_to_json
my $json = Web::Authn::Parse::options_to_json( $opts );Serialises registration or authentication options to a JSON string. Byte fields become unpadded base64url; keys are camelCase. Pass the hash returned by "generate_registration_options" in Web::Authn or "generate_authentication_options" in Web::Authn.
options_to_json_dict
my $href = Web::Authn::Parse::options_to_json_dict( $opts );Same conversion as "options_to_json", but returns a hash instead of a JSON string. Pass the same options hash.
parse_attestation_object
my $att = Web::Authn::Parse::parse_attestation_object( $att_obj_bytes );
# { fmt => 'none', auth_data => {...}, att_stmt => {}, auth_raw => $bytes }Decodes the CBOR map fmt / authData / attStmt. Pass the raw attestationObject bytes, or an object that overloads stringification.
parse_attestation_statement
my $stmt = Web::Authn::Parse::parse_attestation_statement( $att->{attStmt} );Copies known attestation-statement fields (sig, alg, x5c, ver, certInfo, pubArea, response) into a Perl hash. Pass the decoded attStmt CBOR map. If the argument is undefined or is not a hash, the function returns {}.
parse_authenticator_data
my $ad = Web::Authn::Parse::parse_authenticator_data( $bytes );Splits rpIdHash, flags (UP/UV/BE/BS/AT/ED), signCount, optional attested credential data and extensions. It also applies the known EdDSA 0xA3-should-be-0xA4 workaround used by py_webauthn. Pass the raw authenticator data (at least 37 bytes), or an object that overloads stringification.
parse_backup_flags
my $info = Web::Authn::Parse::parse_backup_flags( $ad->{flags} );Maps the BE and BS flags to credential_device_type (singleDevice or multiDevice) and credential_backed_up. Pass the flags hash from "parse_authenticator_data". The function throws if BS is set without BE.
Maps BE/BS to credential_device_type and credential_backed_up.
Dies if BS is set without BE.
parse_client_data_json
my $cd = Web::Authn::Parse::parse_client_data_json( $bytes );Decodes clientDataJSON. The JSON object must contain type, challenge and origin; crossOrigin and tokenBinding are optional. The challenge is decoded from base64url to raw bytes. Pass the raw UTF-8 JSON bytes, or an object that overloads stringification.
parse_authentication_credential_json
my $cred = Web::Authn::Parse::parse_authentication_credential_json( $browser_json );Turns browser JSON (SimpleWebAuthn shape) into the internal hash used by "verify_authentication_response" in Web::Authn. Pass a JSON string, or a hash with id, rawId, type, and response (clientDataJSON, authenticatorData, signature, and optionally userHandle as unpadded base64url).
parse_registration_credential_json
my $cred = Web::Authn::Parse::parse_registration_credential_json( $browser_json );Turns browser JSON into the internal hash used by "verify_registration_response" in Web::Authn. Pass a JSON string, or a hash with id, rawId, type, and response (clientDataJSON and attestationObject as unpadded base64url). See Web::Authn for the JSON shape used on the wire.
THREAD & PROCESS SAFETY
This module is designed to be fully thread-safe and process-safe, ensuring data integrity across Perl ithreads and mod_perl’s threaded Multi-Processing Modules (MPMs) such as Worker or Event.
"_random" builds a new Bytes::Random::Secure object on every call so a generator created in one ithread is never reused in another. See "THREAD & PROCESS SAFETY" in Web::Authn.
AUTHOR
Jacques Deguest <jack@deguest.jp>
SEE ALSO
Web::Authn, Web::Authn::CBOR, Bytes::Random::Secure
COPYRIGHT & LICENSE
Copyright(c) 2026 DEGUEST Pte. Ltd.
All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.