diff options
author | Gregory Cooke <gregorycooke@google.com> | 2024-05-13 14:03:03 -0400 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-05-13 14:03:03 -0400 |
commit | 0020ccf9d9fc448fcfa099173df4ad330e96326c (patch) | |
tree | 45749a54e2b592b4c3dfaf094147f50d0f3c1163 | |
parent | 59954c80165855ecd478a79e75bcc7d64f629ded (diff) | |
download | grpc-grpc-go-upstream-master.tar.gz |
advancedTLS: Documentation (#7213)upstream-master
Add documentation for advancedTLS package
-rw-r--r-- | security/advancedtls/advancedtls.go | 25 |
1 files changed, 16 insertions, 9 deletions
diff --git a/security/advancedtls/advancedtls.go b/security/advancedtls/advancedtls.go index 444aab72..51ac7a47 100644 --- a/security/advancedtls/advancedtls.go +++ b/security/advancedtls/advancedtls.go @@ -16,9 +16,15 @@ * */ -// Package advancedtls is a utility library containing functions to construct -// credentials.TransportCredentials that can perform credential reloading and -// custom verification check. +// Package advancedtls provides gRPC transport credentials that allow easy +// configuration of advanced TLS features. The APIs here give the user more +// customizable control to fit their security landscape, thus the "advanced" +// moniker. This package provides both interfaces and generally useful +// implementations of those interfaces, for example periodic credential +// reloading, support for certificate revocation lists, and customizable +// certificate verification behaviors. If the provided implementations do not +// fit a given use case, a custom implementation of the interface can be +// injected. package advancedtls import ( @@ -119,8 +125,9 @@ type GetRootCAsResults = RootCertificates // RootCertificateOptions contains options to obtain root trust certificates // for both the client and the server. -// At most one option could be set. If none of them are set, we -// use the system default trust certificates. +// At most one field should be set. If none of them are set, we use the system +// default trust certificates. Setting more than one field will result in +// undefined behavior. type RootCertificateOptions struct { // If RootCertificates is set, it will be used every time when verifying // the peer certificates, without performing root certificate reloading. @@ -153,18 +160,18 @@ func (o RootCertificateOptions) nonNilFieldCount() int { // IdentityCertificateOptions contains options to obtain identity certificates // for both the client and the server. -// At most one option could be set. +// At most one field should be set. Setting more than one field will result in undefined behavior. type IdentityCertificateOptions struct { // If Certificates is set, it will be used every time when needed to present - //identity certificates, without performing identity certificate reloading. + // identity certificates, without performing identity certificate reloading. Certificates []tls.Certificate // If GetIdentityCertificatesForClient is set, it will be invoked to obtain // identity certs for every new connection. - // This field MUST be set on client side. + // This field is only relevant when set on the client side. GetIdentityCertificatesForClient func(*tls.CertificateRequestInfo) (*tls.Certificate, error) // If GetIdentityCertificatesForServer is set, it will be invoked to obtain // identity certs for every new connection. - // This field MUST be set on server side. + // This field is only relevant when set on the server side. GetIdentityCertificatesForServer func(*tls.ClientHelloInfo) ([]*tls.Certificate, error) // If IdentityProvider is set, we will use the identity certs from the // Provider's KeyMaterial() call in the new connections. The Provider must |