E-MailRelay

gcram.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2024 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 "gstringarray.h"
26#include "gstringview.h"
27#include "gsecret.h"
28#include "gexception.h"
29#include <string>
30
31 namespace GAuth
32{
33 class Cram ;
34}
35
36//| \class GAuth::Cram
37/// Implements the standard challenge-response authentication
38/// mechanism of RFC-2195.
39///
40/// The response can be built from a simple digest or a hmac.
41/// It comprises the userid, followed by a space, followed by the
42/// printable digest or hmac. This is normally base64 encoded
43/// at higher protocol levels.
44///
45/// A hmac is (roughly) the hash of (1) the single-block shared
46/// key and (2) the hash of (2a) the single-block shared key and
47/// (2b) the challenge. The two intermediate hash states of
48/// stages (1) and (2a) can be stored instead of the the plaintext
49/// key (see GAuth::Secret::masked()).
50///
51 class GAuth::Cram
52{
53 public:
54 G_EXCEPTION( BadType , tx("invalid secret type") )
55 G_EXCEPTION( Mismatch , tx("mismatched hash types") )
56 G_EXCEPTION( NoState , tx("no intermediate-state hash function available") )
57 G_EXCEPTION( InvalidState , tx("invalid hash function intermediate state") )
58 G_EXCEPTION( NoTls , tx("no tls library") )
59
60 static std::string response( std::string_view hash_type , bool hmac ,
61 const Secret & secret , std::string_view challenge ,
62 std::string_view response_prefix ) ;
63 ///< Constructs a response to a challenge comprising the
64 ///< response-prefix, space, and digest-or-hmac of
65 ///< secretkey-plus-challenge. Returns an empty string on
66 ///< error; does not throw.
67
68 static std::string id( std::string_view response ) ;
69 ///< Returns the leading id part of the response. Returns
70 ///< the empty string on error.
71
72 static bool validate( std::string_view hash_type , bool hmac ,
73 const Secret & secret , std::string_view challenge ,
74 std::string_view response ) ;
75 ///< Validates the response with respect to the original
76 ///< challenge. Returns false on error; does not throw.
77
78 static G::StringArray hashTypes( std::string_view prefix = {} , bool require_state = false ) ;
79 ///< Returns a list of supported hash types, such as "MD5"
80 ///< and "SHA1", ordered with the strongest first. Optionally
81 ///< adds a prefix to each type, and optionally limits the
82 ///< list to those hash functions that support initialisation
83 ///< with intermediate state.
84
85 static std::string challenge( unsigned int random , const std::string & challenge_domain ) ;
86 ///< Returns a challenge string that incorporates the given
87 ///< random number and the current time.
88
89 public:
90 Cram() = delete ;
91
92 private:
93 static std::string responseImp( std::string_view , bool , const Secret & , std::string_view ) ;
94} ;
95
96#endif
GAuth::Cram
Implements the standard challenge-response authentication mechanism of RFC-2195.
Definition: gcram.h:52
GAuth::Cram::id
static std::string id(std::string_view response)
Returns the leading id part of the response.
Definition: gcram.cpp:143
GAuth::Cram::hashTypes
static G::StringArray hashTypes(std::string_view prefix={}, bool require_state=false)
Returns a list of supported hash types, such as "MD5" and "SHA1", ordered with the strongest first.
Definition: gcram.cpp:201
GAuth::Cram::challenge
static std::string challenge(unsigned int random, const std::string &challenge_domain)
Returns a challenge string that incorporates the given random number and the current time.
Definition: gcram.cpp:227
GAuth::Cram::validate
static bool validate(std::string_view hash_type, bool hmac, const Secret &secret, std::string_view challenge, std::string_view response)
Validates the response with respect to the original challenge.
Definition: gcram.cpp:119
GAuth::Cram::response
static std::string response(std::string_view hash_type, bool hmac, const Secret &secret, std::string_view challenge, std::string_view response_prefix)
Constructs a response to a challenge comprising the response-prefix, space, and digest-or-hmac of sec...
Definition: gcram.cpp:98
GAuth::Secret
Encapsulates a userid/shared-secret/hash-function tuple from the secrets file.
Definition: gsecret.h:44
gexception.h
gsecret.h
gstringarray.h
gstringview.h
GAuth
SASL authentication classes.
Definition: gcram.cpp:38
G::StringArray
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstringarray.h:30
G::tx
constexpr const char * tx(const char *p) noexcept
A briefer alternative to G::gettext_noop().
Definition: ggettext.h:84