Skip to content

Commit 0020ccf

Browse files
authored
advancedTLS: Documentation (#7213)
Add documentation for advancedTLS package
1 parent 59954c8 commit 0020ccf

File tree

1 file changed

+16
-9
lines changed

1 file changed

+16
-9
lines changed

security/advancedtls/advancedtls.go

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,15 @@
1616
*
1717
*/
1818

19-
// Package advancedtls is a utility library containing functions to construct
20-
// credentials.TransportCredentials that can perform credential reloading and
21-
// custom verification check.
19+
// Package advancedtls provides gRPC transport credentials that allow easy
20+
// configuration of advanced TLS features. The APIs here give the user more
21+
// customizable control to fit their security landscape, thus the "advanced"
22+
// moniker. This package provides both interfaces and generally useful
23+
// implementations of those interfaces, for example periodic credential
24+
// reloading, support for certificate revocation lists, and customizable
25+
// certificate verification behaviors. If the provided implementations do not
26+
// fit a given use case, a custom implementation of the interface can be
27+
// injected.
2228
package advancedtls
2329

2430
import (
@@ -119,8 +125,9 @@ type GetRootCAsResults = RootCertificates
119125

120126
// RootCertificateOptions contains options to obtain root trust certificates
121127
// for both the client and the server.
122-
// At most one option could be set. If none of them are set, we
123-
// use the system default trust certificates.
128+
// At most one field should be set. If none of them are set, we use the system
129+
// default trust certificates. Setting more than one field will result in
130+
// undefined behavior.
124131
type RootCertificateOptions struct {
125132
// If RootCertificates is set, it will be used every time when verifying
126133
// the peer certificates, without performing root certificate reloading.
@@ -153,18 +160,18 @@ func (o RootCertificateOptions) nonNilFieldCount() int {
153160

154161
// IdentityCertificateOptions contains options to obtain identity certificates
155162
// for both the client and the server.
156-
// At most one option could be set.
163+
// At most one field should be set. Setting more than one field will result in undefined behavior.
157164
type IdentityCertificateOptions struct {
158165
// If Certificates is set, it will be used every time when needed to present
159-
//identity certificates, without performing identity certificate reloading.
166+
// identity certificates, without performing identity certificate reloading.
160167
Certificates []tls.Certificate
161168
// If GetIdentityCertificatesForClient is set, it will be invoked to obtain
162169
// identity certs for every new connection.
163-
// This field MUST be set on client side.
170+
// This field is only relevant when set on the client side.
164171
GetIdentityCertificatesForClient func(*tls.CertificateRequestInfo) (*tls.Certificate, error)
165172
// If GetIdentityCertificatesForServer is set, it will be invoked to obtain
166173
// identity certs for every new connection.
167-
// This field MUST be set on server side.
174+
// This field is only relevant when set on the server side.
168175
GetIdentityCertificatesForServer func(*tls.ClientHelloInfo) ([]*tls.Certificate, error)
169176
// If IdentityProvider is set, we will use the identity certs from the
170177
// Provider's KeyMaterial() call in the new connections. The Provider must

0 commit comments

Comments
 (0)