1 // 2 // Copyright 2020 gRPC authors. 3 // 4 // Licensed under the Apache License, Version 2.0 (the "License"); 5 // you may not use this file except in compliance with the License. 6 // You may obtain a copy of the License at 7 // 8 // http://www.apache.org/licenses/LICENSE-2.0 9 // 10 // Unless required by applicable law or agreed to in writing, software 11 // distributed under the License is distributed on an "AS IS" BASIS, 12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 // See the License for the specific language governing permissions and 14 // limitations under the License. 15 // 16 17 #ifndef GRPCPP_SECURITY_TLS_CERTIFICATE_PROVIDER_H 18 #define GRPCPP_SECURITY_TLS_CERTIFICATE_PROVIDER_H 19 20 #include <grpc/credentials.h> 21 #include <grpc/grpc_security.h> 22 #include <grpc/grpc_security_constants.h> 23 #include <grpc/status.h> 24 #include <grpc/support/port_platform.h> 25 #include <grpcpp/support/config.h> 26 27 #include <memory> 28 #include <string> 29 #include <vector> 30 31 #include "absl/status/statusor.h" 32 33 namespace grpc { 34 namespace experimental { 35 36 // Interface for a class that handles the process to fetch credential data. 37 // Implementations should be a wrapper class of an internal provider 38 // implementation. 39 class GRPCXX_DLL CertificateProviderInterface { 40 public: 41 virtual ~CertificateProviderInterface() = default; 42 virtual grpc_tls_certificate_provider* c_provider() = 0; 43 }; 44 45 // A struct that stores the credential data presented to the peer in handshake 46 // to show local identity. The private_key and certificate_chain should always 47 // match. 48 struct GRPCXX_DLL IdentityKeyCertPair { 49 std::string private_key; 50 std::string certificate_chain; 51 }; 52 53 // A basic CertificateProviderInterface implementation that will load credential 54 // data from static string during initialization. This provider will always 55 // return the same cert data for all cert names, and reloading is not supported. 56 class GRPCXX_DLL StaticDataCertificateProvider 57 : public CertificateProviderInterface { 58 public: 59 StaticDataCertificateProvider( 60 const std::string& root_certificate, 61 const std::vector<IdentityKeyCertPair>& identity_key_cert_pairs); 62 StaticDataCertificateProvider(const std::string & root_certificate)63 explicit StaticDataCertificateProvider(const std::string& root_certificate) 64 : StaticDataCertificateProvider(root_certificate, {}) {} 65 StaticDataCertificateProvider(const std::vector<IdentityKeyCertPair> & identity_key_cert_pairs)66 explicit StaticDataCertificateProvider( 67 const std::vector<IdentityKeyCertPair>& identity_key_cert_pairs) 68 : StaticDataCertificateProvider("", identity_key_cert_pairs) {} 69 70 ~StaticDataCertificateProvider() override; 71 c_provider()72 grpc_tls_certificate_provider* c_provider() override { return c_provider_; } 73 74 // Returns an OK status if the following conditions hold: 75 // - the root certificates consist of one or more valid PEM blocks, and 76 // - every identity key-cert pair has a certificate chain that consists of 77 // valid PEM blocks and has a private key is a valid PEM block. 78 absl::Status ValidateCredentials() const; 79 80 private: 81 grpc_tls_certificate_provider* c_provider_ = nullptr; 82 }; 83 84 // A CertificateProviderInterface implementation that will watch the credential 85 // changes on the file system. This provider will always return the up-to-date 86 // cert data for all the cert names callers set through |TlsCredentialsOptions|. 87 // Several things to note: 88 // 1. This API only supports one key-cert file and hence one set of identity 89 // key-cert pair, so SNI(Server Name Indication) is not supported. 90 // 2. The private key and identity certificate should always match. This API 91 // guarantees atomic read, and it is the callers' responsibility to do atomic 92 // updates. There are many ways to atomically update the key and certs in the 93 // file system. To name a few: 94 // 1) creating a new directory, renaming the old directory to a new name, and 95 // then renaming the new directory to the original name of the old directory. 96 // 2) using a symlink for the directory. When need to change, put new 97 // credential data in a new directory, and change symlink. 98 class GRPCXX_DLL FileWatcherCertificateProvider final 99 : public CertificateProviderInterface { 100 public: 101 // Constructor to get credential updates from root and identity file paths. 102 // 103 // @param private_key_path is the file path of the private key. 104 // @param identity_certificate_path is the file path of the identity 105 // certificate chain. 106 // @param root_cert_path is the file path to the root certificate bundle. 107 // @param refresh_interval_sec is the refreshing interval that we will check 108 // the files for updates. 109 FileWatcherCertificateProvider(const std::string& private_key_path, 110 const std::string& identity_certificate_path, 111 const std::string& root_cert_path, 112 unsigned int refresh_interval_sec); 113 // Constructor to get credential updates from identity file paths only. FileWatcherCertificateProvider(const std::string & private_key_path,const std::string & identity_certificate_path,unsigned int refresh_interval_sec)114 FileWatcherCertificateProvider(const std::string& private_key_path, 115 const std::string& identity_certificate_path, 116 unsigned int refresh_interval_sec) 117 : FileWatcherCertificateProvider(private_key_path, 118 identity_certificate_path, "", 119 refresh_interval_sec) {} 120 // Constructor to get credential updates from root file path only. FileWatcherCertificateProvider(const std::string & root_cert_path,unsigned int refresh_interval_sec)121 FileWatcherCertificateProvider(const std::string& root_cert_path, 122 unsigned int refresh_interval_sec) 123 : FileWatcherCertificateProvider("", "", root_cert_path, 124 refresh_interval_sec) {} 125 126 ~FileWatcherCertificateProvider() override; 127 c_provider()128 grpc_tls_certificate_provider* c_provider() override { return c_provider_; } 129 130 // Returns an OK status if the following conditions hold: 131 // - the currently-loaded root certificates, if any, consist of one or more 132 // valid PEM blocks, and 133 // - every currently-loaded identity key-cert pair, if any, has a certificate 134 // chain that consists of valid PEM blocks and has a private key is a valid 135 // PEM block. 136 absl::Status ValidateCredentials() const; 137 138 private: 139 grpc_tls_certificate_provider* c_provider_ = nullptr; 140 }; 141 142 } // namespace experimental 143 } // namespace grpc 144 145 #endif // GRPCPP_SECURITY_TLS_CERTIFICATE_PROVIDER_H 146