NAME#

Digest::PSHA1 - Pseudorandom hashing algorithm as per RFC5246

SYNOPSIS#

use Digest::PSHA1;

DESCRIPTION#

Calculates Pseudorandom SHA1 as defined in http://tools.ietf.org/html/rfc5246 (5. HMAC and the Pseudorandom Function)

This algorithm is used for signing XML documents when the RequestedProofToken is either http://docs.oasis-open.org/ws-sx/ws-trust/200512/CK/PSHA1 or http://schemas.xmlsoap.org/ws/2005/02/trust/CK/PSHA1.

Thanks to Leandro Boffi (http://leandrob.com/) for the nodejs version and a great blog.

USAGE#

use Digest::PSHA1;
use MIME::Base64;

# Extract base64'd binary secret of a RequestSecurityToken request and a
# RequestSecurityTokenResponse, like from such a structure:
# <Entropy>
#     <BinarySecret Type="http://schemas.xmlsoap.org/ws/2005/02/trust/Nonce">
#         grrlUUfhuNwlvQzQ4bV6TT3wA8ieZPltIf4+H7nIvCE=
#     </BinarySecret>
# </Entropy>

# Obtain the decoded versions
my $client-secret = MIME::Base64.decode-str($client-binary-secret);
my $server-secret = MIME::Base64.decode-str($server-binary-secret);

# Build the key to sign an XML document
my $key     = psha1($client-secret, $server-secret);
my $key-b64 = MIME::Base64.encode($key, :oneline);
#  ^--- you usually do not need the Base64 version of the key

# To actually use this key to sign a document, do something like this
use Digest::HMAC;
use Digest;

my $canonicalized-data  = '<SignedInfo xmlns="...">...</SignedInfo>';
#  ^--- use the correct c14n version according to your XML document
my $signature-value     = hmac($key, $canonicalized-data, &sha1);
my $signature-value-b64 = MIME::Base64.encode($signature-value, :oneline);
#  ^--- this is what you would add to your XML document

FUNCTIONS#

psha1-hex#

sub psha1-hex($secret, $seed, $blocksize = 256 --> Str:D)

Returns the hex stringified output of psha1. $secret and $seed can either be Str or Blob objects; if they are Str they will be encoded as ascii.

psha1-hex#

sub psha1($secret, $seed, $blocksize = 256 --> Buf:D)

Computes the PSHA1 of the passed information. $secret and $seed can either be Str or Blob objects; if they are Str they will be encoded as ascii.

AUTHOR#

Tobias Leich (FROGGS)

Source can be located at: https://github.com/raku-community-modules/Digest-PSHA1 . Comments and Pull Requests are welcome.

COPYRIGHT AND LICENSE#

Copyright 2014-2017 Tobias Leich

Copyright 2023, 2024 Raku Community

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.