1/*
2 *
3 * Copyright 2019 gRPC authors.
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 */
18
19#ifndef GRPCPP_SECURITY_TLS_CREDENTIALS_OPTIONS_H
20#define GRPCPP_SECURITY_TLS_CREDENTIALS_OPTIONS_H
21
22#include <grpc/grpc_security_constants.h>
23#include <grpc/status.h>
24#include <grpc/support/log.h>
25#include <grpcpp/support/config.h>
26
27#include <memory>
28#include <vector>
29
30typedef struct grpc_tls_credential_reload_arg grpc_tls_credential_reload_arg;
31typedef struct grpc_tls_credential_reload_config
32 grpc_tls_credential_reload_config;
33typedef struct grpc_tls_server_authorization_check_arg
34 grpc_tls_server_authorization_check_arg;
35typedef struct grpc_tls_server_authorization_check_config
36 grpc_tls_server_authorization_check_config;
37typedef struct grpc_tls_credentials_options grpc_tls_credentials_options;
38
39namespace grpc_impl {
40namespace experimental {
41
42/** TLS key materials config, wrapper for grpc_tls_key_materials_config. It is
43 * used for experimental purposes for now and subject to change. **/
44class TlsKeyMaterialsConfig {
45 public:
46 struct PemKeyCertPair {
47 grpc::string private_key;
48 grpc::string cert_chain;
49 };
50
51 /** Getters for member fields. **/
52 const grpc::string pem_root_certs() const { return pem_root_certs_; }
53 const std::vector<PemKeyCertPair>& pem_key_cert_pair_list() const {
54 return pem_key_cert_pair_list_;
55 }
56 int version() const { return version_; }
57
58 /** Setter for key materials that will be called by the user. Ownership of the
59 * arguments will not be transferred. **/
60 void set_pem_root_certs(const grpc::string& pem_root_certs);
61 void add_pem_key_cert_pair(const PemKeyCertPair& pem_key_cert_pair);
62 void set_key_materials(
63 const grpc::string& pem_root_certs,
64 const std::vector<PemKeyCertPair>& pem_key_cert_pair_list);
65 void set_version(int version) { version_ = version; };
66
67 private:
68 int version_ = 0;
69 std::vector<PemKeyCertPair> pem_key_cert_pair_list_;
70 grpc::string pem_root_certs_;
71};
72
73/** TLS credential reload arguments, wraps grpc_tls_credential_reload_arg. It is
74 * used for experimental purposes for now and it is subject to change.
75 *
76 * The credential reload arg contains all the info necessary to schedule/cancel
77 * a credential reload request. The callback function must be called after
78 * finishing the schedule operation. See the description of the
79 * grpc_tls_credential_reload_arg struct in grpc_security.h for more details.
80 * **/
81class TlsCredentialReloadArg {
82 public:
83 /** TlsCredentialReloadArg does not take ownership of the C arg that is passed
84 * to the constructor. One must remember to free any memory allocated to the
85 * C arg after using the setter functions below. **/
86 TlsCredentialReloadArg(grpc_tls_credential_reload_arg* arg);
87 ~TlsCredentialReloadArg();
88
89 /** Getters for member fields. **/
90 void* cb_user_data() const;
91 bool is_pem_key_cert_pair_list_empty() const;
92 grpc_ssl_certificate_config_reload_status status() const;
93 grpc::string error_details() const;
94
95 /** Setters for member fields. Ownership of the arguments will not be
96 * transferred. **/
97 void set_cb_user_data(void* cb_user_data);
98 void set_pem_root_certs(const grpc::string& pem_root_certs);
99 void add_pem_key_cert_pair(
100 const TlsKeyMaterialsConfig::PemKeyCertPair& pem_key_cert_pair);
101 void set_key_materials(const grpc::string& pem_root_certs,
102 std::vector<TlsKeyMaterialsConfig::PemKeyCertPair>
103 pem_key_cert_pair_list);
104 void set_key_materials_config(
105 const std::shared_ptr<TlsKeyMaterialsConfig>& key_materials_config);
106 void set_status(grpc_ssl_certificate_config_reload_status status);
107 void set_error_details(const grpc::string& error_details);
108
109 /** Calls the C arg's callback function. **/
110 void OnCredentialReloadDoneCallback();
111
112 private:
113 grpc_tls_credential_reload_arg* c_arg_;
114};
115
116/** An interface that the application derives and uses to instantiate a
117 * TlsCredentialReloadConfig instance. Refer to the definition of the
118 * grpc_tls_credential_reload_config in grpc_tls_credentials_options.h for more
119 * details on the expectations of the member functions of the interface. **/
120struct TlsCredentialReloadInterface {
121 virtual ~TlsCredentialReloadInterface() = default;
122 /** A callback that invokes the credential reload. **/
123 virtual int Schedule(TlsCredentialReloadArg* arg) = 0;
124 /** A callback that cancels a credential reload request. **/
125 virtual void Cancel(TlsCredentialReloadArg* /* arg */) {}
126};
127
128/** TLS credential reloag config, wraps grpc_tls_credential_reload_config. It is
129 * used for experimental purposes for now and it is subject to change. **/
130class TlsCredentialReloadConfig {
131 public:
132 TlsCredentialReloadConfig(std::shared_ptr<TlsCredentialReloadInterface>
133 credential_reload_interface);
134 ~TlsCredentialReloadConfig();
135
136 int Schedule(TlsCredentialReloadArg* arg) const {
137 if (credential_reload_interface_ == nullptr) {
138 gpr_log(GPR_ERROR, format: "credential reload interface is nullptr");
139 if (arg != nullptr) {
140 arg->set_status(GRPC_SSL_CERTIFICATE_CONFIG_RELOAD_FAIL);
141 arg->set_error_details(
142 "the interface of the credential reload config is nullptr");
143 }
144 return 1;
145 }
146 return credential_reload_interface_->Schedule(arg);
147 }
148
149 void Cancel(TlsCredentialReloadArg* arg) const {
150 if (credential_reload_interface_ == nullptr) {
151 gpr_log(GPR_ERROR, format: "credential reload interface is nullptr");
152 if (arg != nullptr) {
153 arg->set_status(GRPC_SSL_CERTIFICATE_CONFIG_RELOAD_FAIL);
154 arg->set_error_details(
155 "the interface of the credential reload config is nullptr");
156 }
157 return;
158 }
159 credential_reload_interface_->Cancel(arg);
160 }
161
162 /** Returns a C struct for the credential reload config. **/
163 grpc_tls_credential_reload_config* c_config() const { return c_config_; }
164
165 private:
166 grpc_tls_credential_reload_config* c_config_;
167 std::shared_ptr<TlsCredentialReloadInterface> credential_reload_interface_;
168};
169
170/** TLS server authorization check arguments, wraps
171 * grpc_tls_server_authorization_check_arg. It is used for experimental
172 * purposes for now and it is subject to change.
173 *
174 * The server authorization check arg contains all the info necessary to
175 * schedule/cancel a server authorization check request. The callback function
176 * must be called after finishing the schedule operation. See the description
177 * of the grpc_tls_server_authorization_check_arg struct in grpc_security.h for
178 * more details. **/
179class TlsServerAuthorizationCheckArg {
180 public:
181 /** TlsServerAuthorizationCheckArg does not take ownership of the C arg passed
182 * to the constructor. One must remember to free any memory allocated to the
183 * C arg after using the setter functions below. **/
184 TlsServerAuthorizationCheckArg(grpc_tls_server_authorization_check_arg* arg);
185 ~TlsServerAuthorizationCheckArg();
186
187 /** Getters for member fields. **/
188 void* cb_user_data() const;
189 int success() const;
190 grpc::string target_name() const;
191 grpc::string peer_cert() const;
192 grpc::string peer_cert_full_chain() const;
193 grpc_status_code status() const;
194 grpc::string error_details() const;
195
196 /** Setters for member fields. **/
197 void set_cb_user_data(void* cb_user_data);
198 void set_success(int success);
199 void set_target_name(const grpc::string& target_name);
200 void set_peer_cert(const grpc::string& peer_cert);
201 void set_peer_cert_full_chain(const grpc::string& peer_cert_full_chain);
202 void set_status(grpc_status_code status);
203 void set_error_details(const grpc::string& error_details);
204
205 /** Calls the C arg's callback function. **/
206 void OnServerAuthorizationCheckDoneCallback();
207
208 private:
209 grpc_tls_server_authorization_check_arg* c_arg_;
210};
211
212/** An interface that the application derives and uses to instantiate a
213 * TlsServerAuthorizationCheckConfig instance. Refer to the definition of the
214 * grpc_tls_server_authorization_check_config in grpc_tls_credentials_options.h
215 * for more details on the expectations of the member functions of the
216 * interface.
217 * **/
218struct TlsServerAuthorizationCheckInterface {
219 virtual ~TlsServerAuthorizationCheckInterface() = default;
220 /** A callback that invokes the server authorization check. **/
221 virtual int Schedule(TlsServerAuthorizationCheckArg* arg) = 0;
222 /** A callback that cancels a server authorization check request. **/
223 virtual void Cancel(TlsServerAuthorizationCheckArg* /* arg */) {}
224};
225
226/** TLS server authorization check config, wraps
227 * grps_tls_server_authorization_check_config. It is used for experimental
228 * purposes for now and it is subject to change. **/
229class TlsServerAuthorizationCheckConfig {
230 public:
231 TlsServerAuthorizationCheckConfig(
232 std::shared_ptr<TlsServerAuthorizationCheckInterface>
233 server_authorization_check_interface);
234 ~TlsServerAuthorizationCheckConfig();
235
236 int Schedule(TlsServerAuthorizationCheckArg* arg) const {
237 if (server_authorization_check_interface_ == nullptr) {
238 gpr_log(GPR_ERROR, format: "server authorization check interface is nullptr");
239 if (arg != nullptr) {
240 arg->set_status(GRPC_STATUS_NOT_FOUND);
241 arg->set_error_details(
242 "the interface of the server authorization check config is "
243 "nullptr");
244 }
245 return 1;
246 }
247 return server_authorization_check_interface_->Schedule(arg);
248 }
249
250 void Cancel(TlsServerAuthorizationCheckArg* arg) const {
251 if (server_authorization_check_interface_ == nullptr) {
252 gpr_log(GPR_ERROR, format: "server authorization check interface is nullptr");
253 if (arg != nullptr) {
254 arg->set_status(GRPC_STATUS_NOT_FOUND);
255 arg->set_error_details(
256 "the interface of the server authorization check config is "
257 "nullptr");
258 }
259 return;
260 }
261 server_authorization_check_interface_->Cancel(arg);
262 }
263
264 /** Returns C struct for the server authorization check config. **/
265 grpc_tls_server_authorization_check_config* c_config() const {
266 return c_config_;
267 }
268
269 private:
270 grpc_tls_server_authorization_check_config* c_config_;
271 std::shared_ptr<TlsServerAuthorizationCheckInterface>
272 server_authorization_check_interface_;
273};
274
275/** TLS credentials options, wrapper for grpc_tls_credentials_options. It is
276 * used for experimental purposes for now and it is subject to change. See the
277 * description of the grpc_tls_credentials_options struct in grpc_security.h for
278 * more details. **/
279class TlsCredentialsOptions {
280 public:
281 // Constructor for client.
282 explicit TlsCredentialsOptions(
283 grpc_tls_server_verification_option server_verification_option,
284 std::shared_ptr<TlsKeyMaterialsConfig> key_materials_config,
285 std::shared_ptr<TlsCredentialReloadConfig> credential_reload_config,
286 std::shared_ptr<TlsServerAuthorizationCheckConfig>
287 server_authorization_check_config);
288
289 // Constructor for server.
290 explicit TlsCredentialsOptions(
291 grpc_ssl_client_certificate_request_type cert_request_type,
292 std::shared_ptr<TlsKeyMaterialsConfig> key_materials_config,
293 std::shared_ptr<TlsCredentialReloadConfig> credential_reload_config);
294
295 // This constructor will be deprecated.
296 TlsCredentialsOptions(
297 grpc_ssl_client_certificate_request_type cert_request_type,
298 grpc_tls_server_verification_option server_verification_option,
299 std::shared_ptr<TlsKeyMaterialsConfig> key_materials_config,
300 std::shared_ptr<TlsCredentialReloadConfig> credential_reload_config,
301 std::shared_ptr<TlsServerAuthorizationCheckConfig>
302 server_authorization_check_config);
303 ~TlsCredentialsOptions();
304
305 /** Getters for member fields. **/
306 grpc_ssl_client_certificate_request_type cert_request_type() const {
307 return cert_request_type_;
308 }
309 grpc_tls_server_verification_option server_verification_option() const {
310 return server_verification_option_;
311 }
312 std::shared_ptr<TlsKeyMaterialsConfig> key_materials_config() const {
313 return key_materials_config_;
314 }
315 std::shared_ptr<TlsCredentialReloadConfig> credential_reload_config() const {
316 return credential_reload_config_;
317 }
318 std::shared_ptr<TlsServerAuthorizationCheckConfig>
319 server_authorization_check_config() const {
320 return server_authorization_check_config_;
321 }
322 grpc_tls_credentials_options* c_credentials_options() const {
323 return c_credentials_options_;
324 }
325
326 private:
327 /** The cert_request_type_ flag is only relevant when the
328 * TlsCredentialsOptions are used to instantiate server credentials; the flag
329 * goes unused when creating channel credentials, and the user can set it to
330 * GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE. **/
331 grpc_ssl_client_certificate_request_type cert_request_type_;
332 /** The server_verification_option_ flag is only relevant when the
333 * TlsCredentialsOptions are used to instantiate client credentials; **/
334 grpc_tls_server_verification_option server_verification_option_;
335 std::shared_ptr<TlsKeyMaterialsConfig> key_materials_config_;
336 std::shared_ptr<TlsCredentialReloadConfig> credential_reload_config_;
337 std::shared_ptr<TlsServerAuthorizationCheckConfig>
338 server_authorization_check_config_;
339 grpc_tls_credentials_options* c_credentials_options_;
340};
341
342} // namespace experimental
343} // namespace grpc_impl
344
345#endif // GRPCPP_SECURITY_TLS_CREDENTIALS_OPTIONS_H
346

source code of include/grpcpp/security/tls_credentials_options.h