E-MailRelay
gcram.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file gcram.h
19///
20
21#ifndef G_AUTH_CRAM_H
22#define G_AUTH_CRAM_H
23
24#include "gdef.h"
25#include "gstrings.h"
26#include "gsecret.h"
27#include "gexception.h"
28#include <string>
29
30namespace GAuth
31{
32 class Cram ;
33}
34
35//| \class GAuth::Cram
36/// Implements the standard challenge-response authentication
37/// mechanism of RFC-2195.
38///
39/// The response can be built from a simple digest or a hmac.
40/// It comprises the userid, followed by a space, followed by the
41/// printable digest or hmac. This is normally base64 encoded
42/// at higher protocol levels.
43///
44/// A hmac is (roughly) the hash of (1) the single-block shared
45/// key and (2) the hash of (2a) the single-block shared key and
46/// (2b) the challenge. The two intermediate hash states of
47/// stages (1) and (2a) can be stored instead of the the plaintext
48/// key (see GAuth::Secret::masked()).
49///
51{
52public:
53 G_EXCEPTION( BadType , "invalid secret type" ) ;
54 G_EXCEPTION( Mismatch , "mismatched hash types" ) ;
55 G_EXCEPTION( NoState , "no intermediate-state hash function available" ) ;
56 G_EXCEPTION( InvalidState , "invalid hash function intermediate state" ) ;
57
58 static std::string response( const std::string & hash_type , bool hmac ,
59 const Secret & secret , const std::string & challenge ,
60 const std::string & response_prefix ) ;
61 ///< Constructs a response to a challenge comprising the
62 ///< response-prefix, space, and digest-or-hmac of
63 ///< secretkey-plus-challenge. Returns an empty string on
64 ///< error; does not throw.
65
66 static std::string id( const std::string & response ) ;
67 ///< Returns the leading id part of the response. Returns
68 ///< the empty string on error.
69
70 static bool validate( const std::string & hash_type , bool hmac ,
71 const Secret & secret , const std::string & challenge ,
72 const std::string & response ) ;
73 ///< Validates the response with respect to the original
74 ///< challenge. Returns false on error; does not throw.
75
76 static G::StringArray hashTypes( const std::string & prefix = std::string() , bool require_state = false ) ;
77 ///< Returns a list of supported hash types, such as "MD5"
78 ///< and "SHA1", ordered with the strongest first. Optionally
79 ///< adds a prefix to each type, and optionally limits the
80 ///< list to those hash functions that support initialisation
81 ///< with intermediate state.
82
83 static std::string challenge( unsigned int random ) ;
84 ///< Returns a challenge string that incorporates the given
85 ///< random number and the current time.
86
87public:
88 Cram() = delete ;
89
90private:
91 static std::string responseImp( const std::string & , bool , const Secret & , const std::string & ) ;
92} ;
93
94#endif
Implements the standard challenge-response authentication mechanism of RFC-2195.
Definition: gcram.h:51
static std::string challenge(unsigned int random)
Returns a challenge string that incorporates the given random number and the current time.
Definition: gcram.cpp:225
static std::string id(const std::string &response)
Returns the leading id part of the response.
Definition: gcram.cpp:142
static std::string response(const std::string &hash_type, bool hmac, const Secret &secret, const std::string &challenge, const std::string &response_prefix)
Constructs a response to a challenge comprising the response-prefix, space, and digest-or-hmac of sec...
Definition: gcram.cpp:96
static bool validate(const std::string &hash_type, bool hmac, const Secret &secret, const std::string &challenge, const std::string &response)
Validates the response with respect to the original challenge.
Definition: gcram.cpp:118
static G::StringArray hashTypes(const std::string &prefix=std::string(), bool require_state=false)
Returns a list of supported hash types, such as "MD5" and "SHA1", ordered with the strongest first.
Definition: gcram.cpp:199
Encapsulates a shared secret from the secrets file plus the associated userid.
Definition: gsecret.h:42
SASL authentication classes.
Definition: gcram.cpp:36
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstrings.h:31