1 /* 2 * 3 * Copyright 2020 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 // Package certprovider defines APIs for Certificate Providers in gRPC. 20 // 21 // # Experimental 22 // 23 // Notice: All APIs in this package are experimental and may be removed in a 24 // later release. 25 package certprovider 26 27 import ( 28 "context" 29 "crypto/tls" 30 "crypto/x509" 31 "errors" 32 33 "google.golang.org/grpc/internal" 34 ) 35 36 func init() { 37 internal.GetCertificateProviderBuilder = getBuilder 38 } 39 40 var ( 41 // errProviderClosed is returned by Distributor.KeyMaterial when it is 42 // closed. 43 errProviderClosed = errors.New("provider instance is closed") 44 45 // m is a map from name to Provider builder. 46 m = make(map[string]Builder) 47 ) 48 49 // Register registers the Provider builder, whose name as returned by its Name() 50 // method will be used as the name registered with this builder. Registered 51 // Builders are used by the Store to create Providers. 52 func Register(b Builder) { 53 m[b.Name()] = b 54 } 55 56 // getBuilder returns the Provider builder registered with the given name. 57 // If no builder is registered with the provided name, nil will be returned. 58 func getBuilder(name string) Builder { 59 if b, ok := m[name]; ok { 60 return b 61 } 62 return nil 63 } 64 65 // Builder creates a Provider. 66 type Builder interface { 67 // ParseConfig parses the given config, which is in a format specific to individual 68 // implementations, and returns a BuildableConfig on success. 69 ParseConfig(any) (*BuildableConfig, error) 70 71 // Name returns the name of providers built by this builder. 72 Name() string 73 } 74 75 // Provider makes it possible to keep channel credential implementations up to 76 // date with secrets that they rely on to secure communications on the 77 // underlying channel. 78 // 79 // Provider implementations are free to rely on local or remote sources to fetch 80 // the latest secrets, and free to share any state between different 81 // instantiations as they deem fit. 82 type Provider interface { 83 // KeyMaterial returns the key material sourced by the Provider. 84 // Callers are expected to use the returned value as read-only. 85 KeyMaterial(ctx context.Context) (*KeyMaterial, error) 86 87 // Close cleans up resources allocated by the Provider. 88 Close() 89 } 90 91 // KeyMaterial wraps the certificates and keys returned by a Provider instance. 92 type KeyMaterial struct { 93 // Certs contains a slice of cert/key pairs used to prove local identity. 94 Certs []tls.Certificate 95 // Roots contains the set of trusted roots to validate the peer's identity. 96 Roots *x509.CertPool 97 } 98 99 // BuildOptions contains parameters passed to a Provider at build time. 100 type BuildOptions struct { 101 // CertName holds the certificate name, whose key material is of interest to 102 // the caller. 103 CertName string 104 // WantRoot indicates if the caller is interested in the root certificate. 105 WantRoot bool 106 // WantIdentity indicates if the caller is interested in the identity 107 // certificate. 108 WantIdentity bool 109 } 110