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 <memory>
23#include <vector>
24
25#include <grpc/grpc_security.h>
26#include <grpc/grpc_security_constants.h>
27#include <grpc/status.h>
28#include <grpc/support/log.h>
29#include <grpcpp/security/tls_certificate_provider.h>
30#include <grpcpp/security/tls_certificate_verifier.h>
31#include <grpcpp/support/config.h>
32
33namespace grpc {
34namespace experimental {
35
36// Base class of configurable options specified by users to configure their
37// certain security features supported in TLS. It is used for experimental
38// purposes for now and it is subject to change.
39class TlsCredentialsOptions {
40 public:
41 // Constructor for base class TlsCredentialsOptions.
42 //
43 // @param certificate_provider the provider which fetches TLS credentials that
44 // will be used in the TLS handshake
45 TlsCredentialsOptions();
46 // ---- Setters for member fields ----
47 // Sets the certificate provider used to store root certs and identity certs.
48 void set_certificate_provider(
49 std::shared_ptr<CertificateProviderInterface> certificate_provider);
50 // Watches the updates of root certificates with name |root_cert_name|.
51 // If used in TLS credentials, setting this field is optional for both the
52 // client side and the server side.
53 // If this is not set on the client side, we will use the root certificates
54 // stored in the default system location, since client side must provide root
55 // certificates in TLS(no matter single-side TLS or mutual TLS).
56 // If this is not set on the server side, we will not watch any root
57 // certificate updates, and assume no root certificates needed for the server
58 // (in the one-side TLS scenario, the server is not required to provide root
59 // certs). We don't support default root certs on server side.
60 void watch_root_certs();
61 // Sets the name of root certificates being watched, if |watch_root_certs| is
62 // called. If not set, an empty string will be used as the name.
63 //
64 // @param root_cert_name the name of root certs being set.
65 void set_root_cert_name(const std::string& root_cert_name);
66 // Watches the updates of identity key-cert pairs with name
67 // |identity_cert_name|. If used in TLS credentials, it is required to be set
68 // on the server side, and optional for the client side(in the one-side
69 // TLS scenario, the client is not required to provide identity certs).
70 void watch_identity_key_cert_pairs();
71 // Sets the name of identity key-cert pairs being watched, if
72 // |watch_identity_key_cert_pairs| is called. If not set, an empty string will
73 // be used as the name.
74 //
75 // @param identity_cert_name the name of identity key-cert pairs being set.
76 void set_identity_cert_name(const std::string& identity_cert_name);
77 // Sets the Tls session key logging configuration. If not set, tls
78 // session key logging is disabled. Note that this should be used only for
79 // debugging purposes. It should never be used in a production environment
80 // due to security concerns.
81 //
82 // @param tls_session_key_log_file_path: Path where tls session keys would
83 // be logged.
84 void set_tls_session_key_log_file_path(
85 const std::string& tls_session_key_log_file_path);
86 // Sets the certificate verifier used to perform post-handshake peer identity
87 // checks.
88 void set_certificate_verifier(
89 std::shared_ptr<CertificateVerifier> certificate_verifier);
90 // Sets the options of whether to check the hostname of the peer on a per-call
91 // basis. This is usually used in a combination with virtual hosting at the
92 // client side, where each individual call on a channel can have a different
93 // host associated with it.
94 // This check is intended to verify that the host specified for the individual
95 // call is covered by the cert that the peer presented.
96 // We will perform such checks by default. This should be disabled if
97 // verifiers other than the host name verifier is used.
98 void set_check_call_host(bool check_call_host);
99
100 // TODO(zhenlian): This is an experimental API is likely to change in the
101 // future. Before de-experiementalizing, verify the API is up to date.
102 // If set, gRPC will read all hashed x.509 CRL files in the directory and
103 // enforce the CRL files on all TLS handshakes. Only supported for OpenSSL
104 // version > 1.1.
105 void set_crl_directory(const std::string& path);
106
107 // ----- Getters for member fields ----
108 // Get the internal c options. This function shall be used only internally.
109 grpc_tls_credentials_options* c_credentials_options() const {
110 return c_credentials_options_;
111 }
112
113 private:
114 std::shared_ptr<CertificateProviderInterface> certificate_provider_;
115 std::shared_ptr<CertificateVerifier> certificate_verifier_;
116 grpc_tls_credentials_options* c_credentials_options_ = nullptr;
117};
118
119// Contains configurable options on the client side.
120// Client side doesn't need to always use certificate provider. When the
121// certificate provider is not set, we will use the root certificates stored
122// in the system default locations, and assume client won't provide any
123// identity certificates(single side TLS).
124// It is used for experimental purposes for now and it is subject to change.
125class TlsChannelCredentialsOptions final : public TlsCredentialsOptions {
126 public:
127 // Sets the decision of whether to do a crypto check on the server certs.
128 // The default is true.
129 void set_verify_server_certs(bool verify_server_certs);
130
131 private:
132};
133
134// Contains configurable options on the server side.
135// It is used for experimental purposes for now and it is subject to change.
136class TlsServerCredentialsOptions final : public TlsCredentialsOptions {
137 public:
138 // Server side is required to use a provider, because server always needs to
139 // use identity certs.
140 explicit TlsServerCredentialsOptions(
141 std::shared_ptr<CertificateProviderInterface> certificate_provider)
142 : TlsCredentialsOptions() {
143 set_certificate_provider(certificate_provider);
144 }
145
146 // Sets option to request the certificates from the client.
147 // The default is GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE.
148 void set_cert_request_type(
149 grpc_ssl_client_certificate_request_type cert_request_type);
150
151 private:
152};
153
154} // namespace experimental
155} // namespace grpc
156
157#endif // GRPCPP_SECURITY_TLS_CREDENTIALS_OPTIONS_H
158

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