3 * Copyright 2019 gRPC authors.
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
9 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 #ifndef GRPCPP_SECURITY_TLS_CREDENTIALS_OPTIONS_H
20 #define GRPCPP_SECURITY_TLS_CREDENTIALS_OPTIONS_H
22 #include <grpc/grpc_security_constants.h>
23 #include <grpc/status.h>
24 #include <grpc/support/log.h>
25 #include <grpcpp/security/tls_certificate_provider.h>
26 #include <grpcpp/support/config.h>
31 // TODO(yihuazhang): remove the forward declaration here and include
32 // <grpc/grpc_security.h> directly once the insecure builds are cleaned up.
33 typedef struct grpc_tls_server_authorization_check_arg
34 grpc_tls_server_authorization_check_arg;
35 typedef struct grpc_tls_server_authorization_check_config
36 grpc_tls_server_authorization_check_config;
37 typedef struct grpc_tls_credentials_options grpc_tls_credentials_options;
38 typedef struct grpc_tls_certificate_provider grpc_tls_certificate_provider;
41 namespace experimental {
43 /** TLS server authorization check arguments, wraps
44 * grpc_tls_server_authorization_check_arg. It is used for experimental
45 * purposes for now and it is subject to change.
47 * The server authorization check arg contains all the info necessary to
48 * schedule/cancel a server authorization check request. The callback function
49 * must be called after finishing the schedule operation. See the description
50 * of the grpc_tls_server_authorization_check_arg struct in grpc_security.h for
52 class TlsServerAuthorizationCheckArg {
54 /** TlsServerAuthorizationCheckArg does not take ownership of the C arg passed
55 * to the constructor. One must remember to free any memory allocated to the
56 * C arg after using the setter functions below. **/
57 TlsServerAuthorizationCheckArg(grpc_tls_server_authorization_check_arg* arg);
58 ~TlsServerAuthorizationCheckArg();
60 /** Getters for member fields. **/
61 void* cb_user_data() const;
63 std::string target_name() const;
64 std::string peer_cert() const;
65 std::string peer_cert_full_chain() const;
66 grpc_status_code status() const;
67 std::string error_details() const;
69 /** Setters for member fields. **/
70 void set_cb_user_data(void* cb_user_data);
71 void set_success(int success);
72 void set_target_name(const std::string& target_name);
73 void set_peer_cert(const std::string& peer_cert);
74 void set_peer_cert_full_chain(const std::string& peer_cert_full_chain);
75 void set_status(grpc_status_code status);
76 void set_error_details(const std::string& error_details);
78 /** Calls the C arg's callback function. **/
79 void OnServerAuthorizationCheckDoneCallback();
82 grpc_tls_server_authorization_check_arg* c_arg_;
85 /** An interface that the application derives and uses to instantiate a
86 * TlsServerAuthorizationCheckConfig instance. Refer to the definition of the
87 * grpc_tls_server_authorization_check_config in grpc_tls_credentials_options.h
88 * for more details on the expectations of the member functions of the
91 struct TlsServerAuthorizationCheckInterface {
92 virtual ~TlsServerAuthorizationCheckInterface() = default;
93 /** A callback that invokes the server authorization check. **/
94 virtual int Schedule(TlsServerAuthorizationCheckArg* arg) = 0;
95 /** A callback that cancels a server authorization check request. **/
96 virtual void Cancel(TlsServerAuthorizationCheckArg* /* arg */) {}
99 /** TLS server authorization check config, wraps
100 * grps_tls_server_authorization_check_config. It is used for experimental
101 * purposes for now and it is subject to change. **/
102 class TlsServerAuthorizationCheckConfig {
104 TlsServerAuthorizationCheckConfig(
105 std::shared_ptr<TlsServerAuthorizationCheckInterface>
106 server_authorization_check_interface);
107 ~TlsServerAuthorizationCheckConfig();
109 int Schedule(TlsServerAuthorizationCheckArg* arg) const {
110 if (server_authorization_check_interface_ == nullptr) {
111 gpr_log(GPR_ERROR, "server authorization check interface is nullptr");
112 if (arg != nullptr) {
113 arg->set_status(GRPC_STATUS_NOT_FOUND);
114 arg->set_error_details(
115 "the interface of the server authorization check config is "
120 return server_authorization_check_interface_->Schedule(arg);
123 void Cancel(TlsServerAuthorizationCheckArg* arg) const {
124 if (server_authorization_check_interface_ == nullptr) {
125 gpr_log(GPR_ERROR, "server authorization check interface is nullptr");
126 if (arg != nullptr) {
127 arg->set_status(GRPC_STATUS_NOT_FOUND);
128 arg->set_error_details(
129 "the interface of the server authorization check config is "
134 server_authorization_check_interface_->Cancel(arg);
137 /** Returns C struct for the server authorization check config. **/
138 grpc_tls_server_authorization_check_config* c_config() const {
143 grpc_tls_server_authorization_check_config* c_config_;
144 std::shared_ptr<TlsServerAuthorizationCheckInterface>
145 server_authorization_check_interface_;
148 // Base class of configurable options specified by users to configure their
149 // certain security features supported in TLS. It is used for experimental
150 // purposes for now and it is subject to change.
151 class TlsCredentialsOptions {
153 // Constructor for base class TlsCredentialsOptions.
155 // @param certificate_provider the provider which fetches TLS credentials that
156 // will be used in the TLS handshake
157 explicit TlsCredentialsOptions(
158 std::shared_ptr<CertificateProviderInterface> certificate_provider);
159 // ---- Setters for member fields ----
160 // Watches the updates of root certificates with name |root_cert_name|.
161 // If used in TLS credentials, it should always be set unless the root
162 // certificates are not needed(e.g. in the one-side TLS scenario, the server
163 // is not required to verify the client).
164 void watch_root_certs();
165 // Sets the name of root certificates being watched, if |watch_root_certs| is
166 // called. If not set, an empty string will be used as the name.
168 // @param root_cert_name the name of root certs being set.
169 void set_root_cert_name(const std::string& root_cert_name);
170 // Watches the updates of identity key-cert pairs with name
171 // |identity_cert_name|. If used in TLS credentials, it should always be set
172 // unless the identity certificates are not needed(e.g. in the one-side TLS
173 // scenario, the client is not required to provide certs).
174 void watch_identity_key_cert_pairs();
175 // Sets the name of identity key-cert pairs being watched, if
176 // |watch_identity_key_cert_pairs| is called. If not set, an empty string will
177 // be used as the name.
179 // @param identity_cert_name the name of identity key-cert pairs being set.
180 void set_identity_cert_name(const std::string& identity_cert_name);
182 // ----- Getters for member fields ----
183 // Get the internal c options. This function shall be used only internally.
184 grpc_tls_credentials_options* c_credentials_options() const {
185 return c_credentials_options_;
189 std::shared_ptr<CertificateProviderInterface> certificate_provider_;
190 grpc_tls_credentials_options* c_credentials_options_ = nullptr;
193 // Contains configurable options on the client side.
194 // It is used for experimental purposes for now and it is subject to change.
195 class TlsChannelCredentialsOptions final : public TlsCredentialsOptions {
197 explicit TlsChannelCredentialsOptions(
198 std::shared_ptr<CertificateProviderInterface> certificate_provider)
199 : TlsCredentialsOptions(std::move(certificate_provider)) {}
201 // Sets the option to verify the server.
202 // The default is GRPC_TLS_SERVER_VERIFICATION.
203 void set_server_verification_option(
204 grpc_tls_server_verification_option server_verification_option);
205 // Sets the custom authorization config.
206 void set_server_authorization_check_config(
207 std::shared_ptr<TlsServerAuthorizationCheckConfig>
208 authorization_check_config);
213 // Contains configurable options on the server side.
214 // It is used for experimental purposes for now and it is subject to change.
215 class TlsServerCredentialsOptions final : public TlsCredentialsOptions {
217 explicit TlsServerCredentialsOptions(
218 std::shared_ptr<CertificateProviderInterface> certificate_provider)
219 : TlsCredentialsOptions(std::move(certificate_provider)) {}
221 // Sets option to request the certificates from the client.
222 // The default is GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE.
223 void set_cert_request_type(
224 grpc_ssl_client_certificate_request_type cert_request_type);
229 } // namespace experimental
232 #endif // GRPCPP_SECURITY_TLS_CREDENTIALS_OPTIONS_H