MySQL 8.3.0
Source Code Documentation
auth_ldap_kerberos.h
Go to the documentation of this file.
1/* Copyright (c) 2020, 2023, Oracle and/or its affiliates.
2
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6
7 This program is also distributed with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have included with MySQL.
13
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License, version 2.0, for more details.
18
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22
23#ifndef AUTH_LDAP_KERBEROS_H_
24#define AUTH_LDAP_KERBEROS_H_
25
26#include <assert.h>
27#include <krb5/krb5.h>
28
29#include <string>
30
31#include "krb5_interface.h"
32
33namespace auth_ldap_sasl_client {
34
35/**
36 Kerberos class is built around kerberos library.
37 This class should/can be used for different part of code as standalone
38 class.
39 This class performs following operations:
40 1. Authentication with kerberos server and store the credentials in cache.
41 2. Get the default configured kerberos user in the OS, from default principal.
42
43 Credentials:
44 A ticket plus the secret session key necessary to use that ticket successfully
45 in an authentication exchange.
46
47 Principal:
48 A named client or server entity that participates in a network communication,
49 with one name that is considered canonical
50
51 Credential cache:
52 A credential cache (or ccache) holds Kerberos credentials while they
53 remain valid and, generally, while the user's session lasts, so that
54 authenticating to a service multiple times (e.g., connecting to a web or mail
55 server more than once) doesn't require contacting the KDC every time.
56*/
57class Kerberos {
58 public:
59 /**
60 Constructor.
61 */
62 Kerberos();
63 /**
64 Destructor.
65 */
66 ~Kerberos();
67 /**
68 Set user and password member variables.
69
70 @param user [in] user name
71 @param password [in] password
72 */
73 void set_user_and_password(const char *user, const char *password) {
74 assert(user);
75 assert(password);
76 m_user = user;
78 }
79 /**
80 1. This function authenticates with kerberos server.
81 2. If TGT destroy is false, this function stores the TGT in Kerberos cache
82 for subsequent usage.
83 3. If user credentials already exist in the cache, it doesn't attempt to get
84 it again.
85
86 @retval true Successfully able to obtain and store credentials.
87 @retval false Failed to obtain and store credentials.
88 */
90 /**
91 This function retrieves default principle from kerberos configuration and
92 parses the user name from it. If user name has not been provided in the
93 MySQL client, This method can be used to get the user name and use for
94 authentication.
95 @retval true Successfully able to get user name.
96 @retval false Failed to get user name.
97 */
98 bool get_default_principal_name(std::string &name);
99 /**
100 Check if the cache contains valid credentials
101
102 @retval true valid credentials exist
103 @retval false valid credentials not exist or an error ocurred
104 */
105 bool credentials_valid();
106 /**
107 Destroys existing credentials (remove them from the cache).
108 */
109 void destroy_credentials();
110 /**
111 This function gets LDAP host from krb5.conf file.
112 */
113 void get_ldap_host(std::string &host);
114
115 private:
116 /**
117 This function creates kerberos context, initializes credentials cache and
118 user principal.
119 @retval true All the required kerberos objects like context,
120 credentials cache and user principal are initialized correctly.
121 @retval false Required kerberos objects failed to initialized.
122 */
123 bool initialize();
124 /**
125 This function frees kerberos context, credentials, credentials cache and
126 user principal.
127 */
128 void cleanup();
129
130 /** is the object initialized */
132 /** user name */
133 std::string m_user;
134 /** user password */
135 std::string m_password;
136 /** LDAP host */
138 /** shall be the credentials destroyed on cleanup */
140 /** Kerberos context */
141 krb5_context m_context;
142 /** Kerberos cache */
144 /** Kerberos credentials */
145 krb5_creds m_credentials;
146 /** were the credentials created by the object */
148 /** interface to kerberos functions */
150
151 /**
152 Log a Kerberos error, the message is taken from the Kerberos based on the
153 error code.
154
155 @param error_code [in] Kerberos error code
156 */
157 void log(int error_code);
158 /**
159 This method gets kerberos profile settings from krb5.conf file.
160
161 @retval true success
162 @retval false failure
163
164 @details
165 Sample krb5.conf file format may be like this:
166
167 [realms]
168 MEM.LOCAL = {
169 kdc = VIKING67.MEM.LOCAL
170 admin_server = VIKING67.MEM.LOCAL
171 default_domain = MEM.LOCAL
172 }
173
174 # This portion is optional
175 [appdefaults]
176 mysql = {
177 ldap_server_host = ldap_host.oracle.com
178 ldap_destroy_tgt = true
179 }
180
181 kdc:
182 The name or address of a host running a KDC for that realm.
183 An optional port number, separated from the hostname by a colon, may
184 be included. If the name or address contains colons (for example, if it is
185 an IPv6 address), enclose it in square brackets to distinguish the colon
186 from a port separator.
187
188 For example:
189 kdchost.example.com:88
190 [2001:db8:3333:4444:5555:6666:7777:8888]:88
191
192 Details from:
193 https://web.mit.edu/kerberos/krb5-latest/doc/admin/conf_files/krb5_conf.html
194
195 Host information is used by LDAP SASL client API while initialization.
196 LDAP SASL API doesn't need port information and port is not used any where.
197 */
198 bool get_kerberos_config();
199 /**
200 Opens default Kerberos cache.
201
202 @retval true success
203 @retval false failure
204 */
205 bool open_default_cache();
206
207 /**
208 Closes default Kerberos cache.
209 */
210 void close_default_cache();
211};
212} // namespace auth_ldap_sasl_client
213#endif // AUTH_LDAP_KERBEROS_H_
Kerberos class is built around kerberos library.
Definition: auth_ldap_kerberos.h:57
krb5_context m_context
Kerberos context.
Definition: auth_ldap_kerberos.h:141
void get_ldap_host(std::string &host)
This function gets LDAP host from krb5.conf file.
Definition: auth_ldap_kerberos.cc:42
~Kerberos()
Destructor.
Definition: auth_ldap_kerberos.cc:40
void set_user_and_password(const char *user, const char *password)
Set user and password member variables.
Definition: auth_ldap_kerberos.h:73
void cleanup()
This function frees kerberos context, credentials, credentials cache and user principal.
Definition: auth_ldap_kerberos.cc:75
Krb5_interface krb5
interface to kerberos functions
Definition: auth_ldap_kerberos.h:149
bool get_kerberos_config()
This method gets kerberos profile settings from krb5.conf file.
Definition: auth_ldap_kerberos.cc:252
bool open_default_cache()
Opens default Kerberos cache.
Definition: auth_ldap_kerberos.cc:91
bool obtain_store_credentials()
Definition: auth_ldap_kerberos.cc:116
krb5_ccache m_krb_credentials_cache
Kerberos cache.
Definition: auth_ldap_kerberos.h:143
void destroy_credentials()
Destroys existing credentials (remove them from the cache).
Definition: auth_ldap_kerberos.cc:454
std::string m_user
user name
Definition: auth_ldap_kerberos.h:133
std::string m_ldap_server_host
LDAP host.
Definition: auth_ldap_kerberos.h:137
std::string m_password
user password
Definition: auth_ldap_kerberos.h:135
bool m_destroy_tgt
shall be the credentials destroyed on cleanup
Definition: auth_ldap_kerberos.h:139
Kerberos()
Constructor.
Definition: auth_ldap_kerberos.cc:31
void close_default_cache()
Closes default Kerberos cache.
Definition: auth_ldap_kerberos.cc:105
bool credentials_valid()
Check if the cache contains valid credentials.
Definition: auth_ldap_kerberos.cc:365
bool get_default_principal_name(std::string &name)
This function retrieves default principle from kerberos configuration and parses the user name from i...
Definition: auth_ldap_kerberos.cc:467
bool m_initialized
is the object initialized
Definition: auth_ldap_kerberos.h:131
void log(int error_code)
Log a Kerberos error, the message is taken from the Kerberos based on the error code.
Definition: auth_ldap_kerberos.cc:516
bool initialize()
This function creates kerberos context, initializes credentials cache and user principal.
Definition: auth_ldap_kerberos.cc:46
bool m_credentials_created
were the credentials created by the object
Definition: auth_ldap_kerberos.h:147
krb5_creds m_credentials
Kerberos credentials.
Definition: auth_ldap_kerberos.h:145
Class representing interface to KRB5 functions.
Definition: krb5_interface.h:137
static char * password
Definition: mysql_secure_installation.cc:57
char * user
Definition: mysqladmin.cc:64
const char * host
Definition: mysqladmin.cc:63
Definition: auth_ldap_kerberos.cc:29
case opt name
Definition: sslopt-case.h:32