Branch: Tag:

2017-11-13

2017-11-13 13:48:20 by Stephen R. van den Berg <srb@cuci.nl>

Crypto.SCRAM: Streamline API and update docs.

1:      //! SCRAM, defined by @rfc{5802@}.   //! - //! This implements both the client and the serverside. + //! This implements both the client- and the serverside.   //! You normally run either the server or the client, but if you would   //! run both (use a separate client and a separate server object!),   //! the sequence would be:
23:   //! Step 0 in the SCRAM handshake, prior to creating the object,   //! you need to have agreed with your peer on the hashfunction to be used.   //! + //! @param h + //! The hash object on which the SCRAM object should base its + //! operations. Typical input is @[Crypto.SHA256]. + //!   //! @note   //! If you are a client, you must use the @ref{client_*@} methods; if you are   //! a server, you must use the @ref{server_*@} methods.   //! You cannot mix both client and server methods in a single object.   //! - //! @param h - //! The hash object on which the SCRAM object should base its - //! operations. Typical input is @[Crypto.SHA256]. - //! +    //! @seealso   //! @[client_1], @[server_1]   protected void create(.Hash h) {
51:   //! should be omitted here.   //!   //! @returns - //! The first request to send to the server. + //! The client-first request to send to the server.   //!   //! @seealso   //! @[client_2]
64:      //! Server-side step 1 in the SCRAM handshake.   //! + //! @param line + //! The received client-first request from the client. + //!   //! @returns   //! The username specified by the client.   //!
72:   string server_1(Stdio.Buffer|string(8bit) line) {    constant format = "n,,n=%s,r=%s";    string username, r; -  first = [string(8bit)]line[3..]; +  first = line[3..];    [username, r] = stringp(line)    ? array_sscanf([string]line, format)    : [array(string)](line->sscanf(format));
90:   //! to compute the authentication hash.   //!   //! @returns - //! The first response to send to the client. + //! The server-first challenge to send to the client.   //!   //! @seealso   //! @[server_3]
105:      //! Client-side step 2 in the SCRAM handshake.   //! + //! @param line + //! The received server-first challenge from the server. + //!   //! @param pass   //! The password to feed to the server.   //! - //! @param line - //! The challenge received from the server to our @[client_first]. - //! +    //! @returns - //! The final response to send to the server. If the response is + //! The client-final response to send to the server. If the response is   //! null, the server messed up the handshake.   //!   //! @seealso   //! @[client_3] - string(7bit) client_2(string pass, Stdio.Buffer|string(8bit) line) { + string(7bit) client_2(Stdio.Buffer|string(8bit) line, string pass) {    constant format = "r=%s,s=%s,i=%d";    string r, salt;    int iters;
148:      //! Final server-side step in the SCRAM handshake.   //! + //! @param line + //! The received client-final challenge and response from the client. + //!   //! @param salted_password   //! The salted (using the salt provided earlier) password belonging   //! to the specified username.   //!   //! @returns - //! The final response to send to the client. If the response + //! The server-final response to send to the client. If the response   //! is null, the client did not supply the correct credentials. - string(7bit) server_3(string(8bit) salted_password, -  Stdio.Buffer|string(8bit) line) { + string(7bit) server_3(Stdio.Buffer|string(8bit) line, +  string(8bit) salted_password) {    constant format = "c=biws,r=%s,p=%s";    string r, p, response;    [r, p] = stringp(line)
180:   //! credentials at all and is an imposter.   //!   //! @param line - //! The verification received from the server to our @[client_final]. + //! The received server-final verification response.   //!   //! @returns   //! True if the server is valid, false if the server is invalid. - int(0..1) client_3(Stdio.Buffer|string line) { + int(0..1) client_3(Stdio.Buffer|string(8bit) line) {    constant format = "v=%s";    string(8bit) v;    [v] = stringp(line)    ? array_sscanf(line, format) : line->sscanf(format);    return MIME.decode_base64(v) == cnonce;   }