1Authen::SCRAM::Server(3U)ser Contributed Perl DocumentatiAounthen::SCRAM::Server(3)
2
3
4
6 Authen::SCRAM::Server - RFC 5802 SCRAM Server
7
9 version 0.011
10
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
37 This module implements the server-side SCRAM algorithm.
38
40 Authen::SCRAM::Server - RFC 5802 SCRAM Server
41
43 version 0.011
44
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
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
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
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
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.30.0 2019-07-26 Authen::SCRAM::Server(3)