1Authen::SCRAM::Client(3U)ser Contributed Perl DocumentatiAounthen::SCRAM::Client(3)
2
3
4

NAME

6       Authen::SCRAM::Client - RFC 5802 SCRAM client
7

VERSION

9       version 0.011
10

SYNOPSIS

12           use Authen::SCRAM::Client;
13           use Try::Tiny;
14
15           $client = Authen::SCRAM::Client->new(
16               username => 'johndoe',
17               password => 'trustno1',
18           );
19
20           try {
21               $client_first = $client->first_msg();
22
23               # send to server and get server-first-message
24
25               $client_final = $client->final_msg( $server_first );
26
27               # send to server and get server-final-message
28
29               $client->validate( $server_final );
30           }
31           catch {
32               die "Authentication failed!"
33           };
34

DESCRIPTION

36       This module implements the client-side SCRAM algorithm.
37

NAME

39       Authen::SCRAM::Client - RFC 5802 SCRAM client
40

VERSION

42       version 0.011
43

ATTRIBUTES

45   username (required)
46       Authentication identity.  This will be normalized with the SASLprep
47       algorithm before being transmitted to the server.
48
49   password (required)
50       Authentication password.  This will be normalized with the SASLprep
51       algorithm before being transmitted to the server.
52
53   authorization_id
54       If the authentication identity ("username") will act as a different,
55       authorization identity, this attribute provides the authorization
56       identity.  It is optional.  If not provided, the authentication
57       identity is considered by the server to be the same as the
58       authorization identity.
59
60   minimum_iteration_count
61       If the server requests an iteration count less than this value, the
62       client throws an error.  This protects against downgrade attacks.  The
63       default is 4096, consistent with recommendations in the RFC.
64
65   digest
66       Name of a digest function available via PBKDF2::Tiny.  Valid values are
67       SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512.  Defaults to SHA-1.
68
69   nonce_size
70       Size of the client-generated nonce, in bits.  Defaults to 192.  The
71       server-nonce will be appended, so the final nonce size will be
72       substantially larger.
73
74   skip_saslprep
75       A boolean that defaults to false.  If set to true, usernames and
76       passwords will not be normalized through SASLprep.  This is a deviation
77       from the RFC5802 spec and is not recommended.
78

METHODS

80   first_msg
81           $client_first_msg = $client->first_msg();
82
83       This takes no arguments and returns the "client-first-message"
84       character string to be sent to the server to initiate a SCRAM session.
85       Calling this again will reset the internal state and initiate a new
86       session.  This will throw an exception should an error occur.
87
88   final_msg
89           $client_final_msg = $client->final_msg( $server_first_msg );
90
91       This takes the "server-first-message" character string received from
92       the server and returns the "client-final-message" character string
93       containing the authentication proof to be sent to the server.  This
94       will throw an exception should an error occur.
95
96   validate
97           $client->validate( $server_final_msg );
98
99       This takes the "server-final-message" character string received from
100       the server and verifies that the server actually has a copy of the
101       client credentials.  It will return true if valid and throw an
102       exception, otherwise.
103
104   computed_keys
105       This method returns the opaque keys used in the SCRAM protocol.  It
106       returns the 'stored key', the 'client key' and the 'server key'.  The
107       server must have a copy of the stored key and server key for a given
108       user in order to authenticate.
109
110       This method caches the computed values -- it generates them fresh only
111       if the supplied salt and iteration count don't match the cached salt
112       and iteration count.
113

CHARACTER ENCODING CAVEAT

115       The SCRAM protocol mandates UTF-8 interchange.  However, all methods in
116       this module take and return character strings.  You must encode to
117       UTF-8 before sending and decode from UTF-8 on receiving according to
118       whatever transport mechanism you are using.
119
120       This is done to avoid double encoding/decoding problems if your
121       transport is already doing UTF-8 encoding or decoding as it constructs
122       outgoing messages or parses incoming messages.
123

AUTHOR

125       David Golden <dagolden@cpan.org>
126

128       This software is Copyright (c) 2014 by David Golden.
129
130       This is free software, licensed under:
131
132         The Apache License, Version 2.0, January 2004
133

AUTHOR

135       David Golden <dagolden@cpan.org>
136

138       This software is Copyright (c) 2014 by David Golden.
139
140       This is free software, licensed under:
141
142         The Apache License, Version 2.0, January 2004
143
144
145
146perl v5.36.0                      2023-01-20          Authen::SCRAM::Client(3)
Impressum