E-MailRelay
gsecret.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2023 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 gsecret.h
19///
20
21#ifndef G_AUTH_SECRET_H
22#define G_AUTH_SECRET_H
23
24#include "gdef.h"
25#include "gexception.h"
26#include <utility>
27#include <string>
28
29namespace GAuth
30{
31 class Secret ;
32}
33
34//| \class GAuth::Secret
35/// Encapsulates a userid/shared-secret/hash-function tuple from the secrets file.
36/// The shared secret can be a plaintext password or it can be a masked password
37/// using the given hash function. A masked secret can only be verified by an hmac
38/// operation using that hash function. However, the implementation of the hash
39/// function must be capable of accepting an intermediate hash state, and this
40/// might only be the case for md5.
41///
43{
44public:
45 G_EXCEPTION( Error , tx("invalid authorisation secret") ) ;
46 G_EXCEPTION( BadId , tx("invalid authorisation id") ) ;
47 using Value = std::pair<G::string_view,G::string_view> ; // encoded value and encoding
48
49 Secret( Value id , Value secret , G::string_view masking_hash_function = {} ,
50 G::string_view context = {} ) ;
51 ///< Constructor used by the SecretsFile class. Throws on error,
52 ///< including if the encodings are invalid. Encodings should be
53 ///< empty (raw) or "xtext" or "base64" or "dotted".
54
55 static std::string check( Value id , Value secret ,
56 G::string_view masking_hash_function ) ;
57 ///< Does a non-throwing check of the constructor parameters,
58 ///< returning an error message or the empty string.
59
60 bool valid() const ;
61 ///< Returns true if the secret is valid.
62
63 std::string id() const ;
64 ///< Returns the associated identity. Throws if not valid().
65
66 std::string secret() const ;
67 ///< Returns the secret shared key. Throws if not valid().
68
69 bool masked() const ;
70 ///< Returns true if a non-empty hash function was passed
71 ///< to the ctor.
72
73 std::string maskHashFunction() const ;
74 ///< Returns the masking function name as passed to the ctor,
75 ///< such as "md5", or the empty string if not masked().
76 ///< Throws if not valid().
77
78 static Secret none() ;
79 ///< Factory function that returns a secret that is not valid().
80
81 std::string info( const std::string & id = {} ) const ;
82 ///< Returns information for logging, excluding anything
83 ///< sensitive. The secret may be in-valid().
84
85 static bool isDotted( G::string_view ) ;
86 ///< Returns true if the given secret string looks like it is in
87 ///< the old dotted format rather than base64.
88
89 static std::string decode( Value ) ;
90 ///< Decodes a value.
91
92private:
93 enum class Encoding { xtext , base64 , raw , dotted } ;
94 Secret() ; // Secret::none()
95 static std::string undotted( G::string_view ) ;
96 static bool validEncodingType( Value ) ;
97 static bool validEncoding( Value ) ;
98 static Encoding encoding( Value ) ;
99
100private:
101 std::string m_id ;
102 std::string m_secret ;
103 std::string m_hash_function ;
104 std::string m_context ;
105} ;
106
107#endif
Encapsulates a userid/shared-secret/hash-function tuple from the secrets file.
Definition: gsecret.h:43
std::string secret() const
Returns the secret shared key. Throws if not valid().
Definition: gsecret.cpp:85
bool masked() const
Returns true if a non-empty hash function was passed to the ctor.
Definition: gsecret.cpp:91
static Secret none()
Factory function that returns a secret that is not valid().
Definition: gsecret.cpp:75
std::string maskHashFunction() const
Returns the masking function name as passed to the ctor, such as "md5", or the empty string if not ma...
Definition: gsecret.cpp:102
bool valid() const
Returns true if the secret is valid.
Definition: gsecret.cpp:80
std::string info(const std::string &id={}) const
Returns information for logging, excluding anything sensitive.
Definition: gsecret.cpp:108
static std::string check(Value id, Value secret, G::string_view masking_hash_function)
Does a non-throwing check of the constructor parameters, returning an error message or the empty stri...
Definition: gsecret.cpp:49
static bool isDotted(G::string_view)
Returns true if the given secret string looks like it is in the old dotted format rather than base64.
Definition: gsecret.cpp:124
static std::string decode(Value)
Decodes a value.
Definition: gsecret.cpp:187
std::string id() const
Returns the associated identity. Throws if not valid().
Definition: gsecret.cpp:96
A class like c++17's std::string_view.
Definition: gstringview.h:51
SASL authentication classes.
Definition: gcram.cpp:37
constexpr const char * tx(const char *p)
A briefer alternative to G::gettext_noop().
Definition: ggettext.h:84