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

NAME

6       Authen::SCRAM::Server - RFC 5802 SCRAM Server
7

VERSION

9       version 0.011
10

SYNOPSIS

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

DESCRIPTION

37       This module implements the server-side SCRAM algorithm.
38

NAME

40       Authen::SCRAM::Server - RFC 5802 SCRAM Server
41

VERSION

43       version 0.011
44

ATTRIBUTES

46   credential_cb (required)
47       This attribute must contain a code reference that takes a username (as
48       a character string normalized by SASLprep) and returns the four user-
49       credential parameters required by SCRAM: "salt", "StoredKey",
50       "ServerKey", and "iteration count".  The "salt", "StoredKey" and
51       "ServerKey" must be provided as octets (i.e. NOT base64 encoded).
52
53       If the username is unknown, it should return an empty list.
54
55           ($salt, $stored_key, $server_key, $iterations) =
56               $server->credential_cb->( $username );
57
58       See RFC 5802: SCRAM Algorithm Overview
59       <http://tools.ietf.org/html/rfc5802#section-3> for details.
60
61   auth_proxy_cb
62       If provided, this attribute must contain a code reference that takes an
63       authentication username and a authorization username (both as character
64       strings), and return a true value if the authentication username is
65       permitted to act as the authorization username:
66
67           $bool = $server->auth_proxy_cb->(
68               $authentication_user, $authorization_user
69           );
70
71       It will only be all called if the authentication username has
72       successfully authenticated.  Both usernames will have been normalized
73       via "SASLprep" with any transport encoding removed before being passed
74       to this function.
75
76   digest
77       Name of a digest function available via PBKDF2::Tiny.  Valid values are
78       SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512.  Defaults to SHA-1.
79
80   nonce_size
81       Size of the client-generated nonce, in bits.  Defaults to 192.  The
82       server-nonce will be appended, so the final nonce size will be
83       substantially larger.
84
85   skip_saslprep
86       A boolean that defaults to false.  If set to true, usernames and
87       passwords will not be normalized through SASLprep.  This is a deviation
88       from the RFC5802 spec and is not recommended.
89

METHODS

91   first_msg
92           $server_first_msg = $server->first_msg( $client_first_msg );
93
94       This takes the "client-first-message" received from the client and
95       returns the "server-first-message" string to be sent to the client to
96       continue a SCRAM session.  Calling this again will reset the internal
97       state and initiate a new session.  This will throw an exception should
98       an error occur.
99
100   final_msg
101           $server_final_msg = $server->final_msg( $client_final_msg );
102
103       This takes the "client-final-message" received from the client and
104       returns the "server-final-message" string containing the verification
105       signature to be sent to the client.
106
107       If an authorization identity was provided by the client, it will
108       confirm that the authenticating username is authorized to act as the
109       authorization id using the "auth_proxy_cb" attribute.
110
111       If the client credentials do not match or the authentication name is
112       not authorized to act as the authorization name, then an exception will
113       be thrown.
114
115   authorization_id
116           $username = $client->authorization_id();
117
118       This takes no arguments and returns the authorization identity
119       resulting from the SCRAM exchange.  This is the client-supplied
120       authorization identity (if one was provided and validated) or else the
121       successfully authenticated identity.
122

CHARACTER ENCODING CAVEAT

124       The SCRAM protocol mandates UTF-8 interchange.  However, all methods in
125       this module take and return character strings.  You must encode to
126       UTF-8 before sending and decode from UTF-8 on receiving according to
127       whatever transport mechanism you are using.
128
129       This is done to avoid double encoding/decoding problems if your
130       transport is already doing UTF-8 encoding or decoding as it constructs
131       outgoing messages or parses incoming messages.
132

AUTHOR

134       David Golden <dagolden@cpan.org>
135

137       This software is Copyright (c) 2014 by David Golden.
138
139       This is free software, licensed under:
140
141         The Apache License, Version 2.0, January 2004
142

AUTHOR

144       David Golden <dagolden@cpan.org>
145

147       This software is Copyright (c) 2014 by David Golden.
148
149       This is free software, licensed under:
150
151         The Apache License, Version 2.0, January 2004
152
153
154
155perl v5.34.0                      2022-01-20          Authen::SCRAM::Server(3)
Impressum