Skip to content

Commit d75b5e2

Browse files
gtcooke94gtcooke94
authored
advancedtls: Rename custom verification function APIs (#7140)
* Rename custom verification function APIs
1 parent 34de5cf commit d75b5e2

File tree

5 files changed

+103
-60
lines changed

5 files changed

+103
-60
lines changed

‎security/advancedtls/advancedtls.go‎

Lines changed: 61 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -35,10 +35,10 @@ import (
3535
credinternal "google.golang.org/grpc/internal/credentials"
3636
)
3737

38-
// VerificationFuncParams contains parameters available to users when
39-
// implementing CustomVerificationFunc.
38+
// HandshakeVerificationInfo contains information about a handshake needed for
39+
// verification for use when implementing the `PostHandshakeVerificationFunc`
4040
// The fields in this struct are read-only.
41-
type VerificationFuncParams struct {
41+
type HandshakeVerificationInfo struct {
4242
// The target server name that the client connects to when establishing the
4343
// connection. This field is only meaningful for client side. On server side,
4444
// this field would be an empty string.
@@ -54,17 +54,36 @@ type VerificationFuncParams struct {
5454
Leaf *x509.Certificate
5555
}
5656

57-
// VerificationResults contains the information about results of
58-
// CustomVerificationFunc.
59-
// VerificationResults is an empty struct for now. It may be extended in the
57+
// VerificationFuncParams contains parameters available to users when
58+
// implementing CustomVerificationFunc.
59+
// The fields in this struct are read-only.
60+
//
61+
// Deprecated: use HandshakeVerificationInfo instead.
62+
type VerificationFuncParams = HandshakeVerificationInfo
63+
64+
// PostHandshakeVerificationResults contains the information about results of
65+
// PostHandshakeVerificationFunc.
66+
// PostHandshakeVerificationResults is an empty struct for now. It may be extended in the
6067
// future to include more information.
61-
type VerificationResults struct{}
68+
type PostHandshakeVerificationResults struct{}
69+
70+
// Deprecated: use PostHandshakeVerificationResults instead.
71+
type VerificationResults = PostHandshakeVerificationResults
72+
73+
// PostHandshakeVerificationFunc is the function defined by users to perform
74+
// custom verification checks after chain building and regular handshake
75+
// verification has been completed.
76+
// PostHandshakeVerificationFunc should return (nil, error) if the authorization
77+
// should fail, with the error containing information on why it failed.
78+
type PostHandshakeVerificationFunc func(params *HandshakeVerificationInfo) (*PostHandshakeVerificationResults, error)
6279

6380
// CustomVerificationFunc is the function defined by users to perform custom
6481
// verification check.
6582
// CustomVerificationFunc returns nil if the authorization fails; otherwise
6683
// returns an empty struct.
67-
type CustomVerificationFunc func(params *VerificationFuncParams) (*VerificationResults, error)
84+
//
85+
// Deprecated: use PostHandshakeVerificationFunc instead.
86+
type CustomVerificationFunc = PostHandshakeVerificationFunc
6887

6988
// GetRootCAsParams contains the parameters available to users when
7089
// implementing GetRootCAs.
@@ -167,11 +186,18 @@ type ClientOptions struct {
167186
// IdentityOptions is OPTIONAL on client side. This field only needs to be
168187
// set if mutual authentication is required on server side.
169188
IdentityOptions IdentityCertificateOptions
189+
// AdditionalPeerVerification is a custom verification check after certificate signature
190+
// check.
191+
// If this is set, we will perform this customized check after doing the
192+
// normal check(s) indicated by setting VerificationType.
193+
AdditionalPeerVerification PostHandshakeVerificationFunc
170194
// VerifyPeer is a custom verification check after certificate signature
171195
// check.
172196
// If this is set, we will perform this customized check after doing the
173-
// normal check(s) indicated by setting VType.
174-
VerifyPeer CustomVerificationFunc
197+
// normal check(s) indicated by setting VerificationType.
198+
//
199+
// Deprecated: use AdditionalPeerVerification instead.
200+
VerifyPeer PostHandshakeVerificationFunc
175201
// RootOptions is OPTIONAL on client side. If not set, we will try to use the
176202
// default trust certificates in users' OS system.
177203
RootOptions RootCertificateOptions
@@ -206,11 +232,18 @@ type ClientOptions struct {
206232
type ServerOptions struct {
207233
// IdentityOptions is REQUIRED on server side.
208234
IdentityOptions IdentityCertificateOptions
235+
// AdditionalPeerVerification is a custom verification check after certificate signature
236+
// check.
237+
// If this is set, we will perform this customized check after doing the
238+
// normal check(s) indicated by setting VerificationType.
239+
AdditionalPeerVerification PostHandshakeVerificationFunc
209240
// VerifyPeer is a custom verification check after certificate signature
210241
// check.
211242
// If this is set, we will perform this customized check after doing the
212-
// normal check(s) indicated by setting VType.
213-
VerifyPeer CustomVerificationFunc
243+
// normal check(s) indicated by setting VerificationType.
244+
//
245+
// Deprecated: use AdditionalPeerVerification instead.
246+
VerifyPeer PostHandshakeVerificationFunc
214247
// RootOptions is OPTIONAL on server side. This field only needs to be set if
215248
// mutual authentication is required(RequireClientCert is true).
216249
RootOptions RootCertificateOptions
@@ -239,13 +272,18 @@ type ServerOptions struct {
239272
}
240273

241274
func (o *ClientOptions) config() (*tls.Config, error) {
275+
// TODO(gtcooke94) Remove this block when o.VerifyPeer is remoed.
276+
// VerifyPeer is deprecated, but do this to aid the transitory migration time.
277+
if o.AdditionalPeerVerification == nil {
278+
o.AdditionalPeerVerification = o.VerifyPeer
279+
}
242280
// TODO(gtcooke94). VType is deprecated, eventually remove this block. This
243281
// will ensure that users still explicitly setting `VType` will get the
244282
// setting to the right place.
245283
if o.VType != CertAndHostVerification {
246284
o.VerificationType = o.VType
247285
}
248-
if o.VerificationType == SkipVerification && o.VerifyPeer == nil {
286+
if o.VerificationType == SkipVerification && o.AdditionalPeerVerification == nil {
249287
return nil, fmt.Errorf("client needs to provide custom verification mechanism if choose to skip default verification")
250288
}
251289
// Make sure users didn't specify more than one fields in
@@ -321,13 +359,18 @@ func (o *ClientOptions) config() (*tls.Config, error) {
321359
}
322360

323361
func (o *ServerOptions) config() (*tls.Config, error) {
362+
// TODO(gtcooke94) Remove this block when o.VerifyPeer is remoed.
363+
// VerifyPeer is deprecated, but do this to aid the transitory migration time.
364+
if o.AdditionalPeerVerification == nil {
365+
o.AdditionalPeerVerification = o.VerifyPeer
366+
}
324367
// TODO(gtcooke94). VType is deprecated, eventually remove this block. This
325368
// will ensure that users still explicitly setting `VType` will get the
326369
// setting to the right place.
327370
if o.VType != CertAndHostVerification {
328371
o.VerificationType = o.VType
329372
}
330-
if o.RequireClientCert && o.VerificationType == SkipVerification && o.VerifyPeer == nil {
373+
if o.RequireClientCert && o.VerificationType == SkipVerification && o.AdditionalPeerVerification == nil {
331374
return nil, fmt.Errorf("server needs to provide custom verification mechanism if choose to skip default verification, but require client certificate(s)")
332375
}
333376
// Make sure users didn't specify more than one fields in
@@ -416,7 +459,7 @@ func (o *ServerOptions) config() (*tls.Config, error) {
416459
// using TLS.
417460
type advancedTLSCreds struct {
418461
config *tls.Config
419-
verifyFunc CustomVerificationFunc
462+
verifyFunc PostHandshakeVerificationFunc
420463
getRootCAs func(params *GetRootCAsParams) (*GetRootCAsResults, error)
421464
isClient bool
422465
verificationType VerificationType
@@ -579,7 +622,7 @@ func buildVerifyFunc(c *advancedTLSCreds,
579622
}
580623
// Perform custom verification check if specified.
581624
if c.verifyFunc != nil {
582-
_, err := c.verifyFunc(&VerificationFuncParams{
625+
_, err := c.verifyFunc(&HandshakeVerificationInfo{
583626
ServerName: serverName,
584627
RawCerts: rawCerts,
585628
VerifiedChains: chains,
@@ -602,7 +645,7 @@ func NewClientCreds(o *ClientOptions) (credentials.TransportCredentials, error)
602645
config: conf,
603646
isClient: true,
604647
getRootCAs: o.RootOptions.GetRootCertificates,
605-
verifyFunc: o.VerifyPeer,
648+
verifyFunc: o.AdditionalPeerVerification,
606649
verificationType: o.VerificationType,
607650
revocationConfig: o.RevocationConfig,
608651
}
@@ -621,7 +664,7 @@ func NewServerCreds(o *ServerOptions) (credentials.TransportCredentials, error)
621664
config: conf,
622665
isClient: false,
623666
getRootCAs: o.RootOptions.GetRootCertificates,
624-
verifyFunc: o.VerifyPeer,
667+
verifyFunc: o.AdditionalPeerVerification,
625668
verificationType: o.VerificationType,
626669
revocationConfig: o.RevocationConfig,
627670
}

‎security/advancedtls/advancedtls_integration_test.go‎

Lines changed: 26 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -143,13 +143,13 @@ func (s) TestEnd2End(t *testing.T) {
143143
clientGetCert func(*tls.CertificateRequestInfo) (*tls.Certificate, error)
144144
clientRoot *x509.CertPool
145145
clientGetRoot func(params *GetRootCAsParams) (*GetRootCAsResults, error)
146-
clientVerifyFunc CustomVerificationFunc
146+
clientVerifyFunc PostHandshakeVerificationFunc
147147
clientVerificationType VerificationType
148148
serverCert []tls.Certificate
149149
serverGetCert func(*tls.ClientHelloInfo) ([]*tls.Certificate, error)
150150
serverRoot *x509.CertPool
151151
serverGetRoot func(params *GetRootCAsParams) (*GetRootCAsResults, error)
152-
serverVerifyFunc CustomVerificationFunc
152+
serverVerifyFunc PostHandshakeVerificationFunc
153153
serverVerificationType VerificationType
154154
}{
155155
// Test Scenarios:
@@ -175,8 +175,8 @@ func (s) TestEnd2End(t *testing.T) {
175175
}
176176
},
177177
clientRoot: cs.ClientTrust1,
178-
clientVerifyFunc: func(params *VerificationFuncParams) (*VerificationResults, error) {
179-
return &VerificationResults{}, nil
178+
clientVerifyFunc: func(params *HandshakeVerificationInfo) (*PostHandshakeVerificationResults, error) {
179+
return &PostHandshakeVerificationResults{}, nil
180180
},
181181
clientVerificationType: CertVerification,
182182
serverCert: []tls.Certificate{cs.ServerCert1},
@@ -188,8 +188,8 @@ func (s) TestEnd2End(t *testing.T) {
188188
return &GetRootCAsResults{TrustCerts: cs.ServerTrust2}, nil
189189
}
190190
},
191-
serverVerifyFunc: func(params *VerificationFuncParams) (*VerificationResults, error) {
192-
return &VerificationResults{}, nil
191+
serverVerifyFunc: func(params *HandshakeVerificationInfo) (*PostHandshakeVerificationResults, error) {
192+
return &PostHandshakeVerificationResults{}, nil
193193
},
194194
serverVerificationType: CertVerification,
195195
},
@@ -216,8 +216,8 @@ func (s) TestEnd2End(t *testing.T) {
216216
return &GetRootCAsResults{TrustCerts: cs.ClientTrust2}, nil
217217
}
218218
},
219-
clientVerifyFunc: func(params *VerificationFuncParams) (*VerificationResults, error) {
220-
return &VerificationResults{}, nil
219+
clientVerifyFunc: func(params *HandshakeVerificationInfo) (*PostHandshakeVerificationResults, error) {
220+
return &PostHandshakeVerificationResults{}, nil
221221
},
222222
clientVerificationType: CertVerification,
223223
serverGetCert: func(*tls.ClientHelloInfo) ([]*tls.Certificate, error) {
@@ -229,8 +229,8 @@ func (s) TestEnd2End(t *testing.T) {
229229
}
230230
},
231231
serverRoot: cs.ServerTrust1,
232-
serverVerifyFunc: func(params *VerificationFuncParams) (*VerificationResults, error) {
233-
return &VerificationResults{}, nil
232+
serverVerifyFunc: func(params *HandshakeVerificationInfo) (*PostHandshakeVerificationResults, error) {
233+
return &PostHandshakeVerificationResults{}, nil
234234
},
235235
serverVerificationType: CertVerification,
236236
},
@@ -258,7 +258,7 @@ func (s) TestEnd2End(t *testing.T) {
258258
return &GetRootCAsResults{TrustCerts: cs.ClientTrust2}, nil
259259
}
260260
},
261-
clientVerifyFunc: func(params *VerificationFuncParams) (*VerificationResults, error) {
261+
clientVerifyFunc: func(params *HandshakeVerificationInfo) (*PostHandshakeVerificationResults, error) {
262262
if len(params.RawCerts) == 0 {
263263
return nil, fmt.Errorf("no peer certs")
264264
}
@@ -280,7 +280,7 @@ func (s) TestEnd2End(t *testing.T) {
280280
}
281281
}
282282
if authzCheck {
283-
return &VerificationResults{}, nil
283+
return &PostHandshakeVerificationResults{}, nil
284284
}
285285
return nil, fmt.Errorf("custom authz check fails")
286286
},
@@ -294,8 +294,8 @@ func (s) TestEnd2End(t *testing.T) {
294294
}
295295
},
296296
serverRoot: cs.ServerTrust1,
297-
serverVerifyFunc: func(params *VerificationFuncParams) (*VerificationResults, error) {
298-
return &VerificationResults{}, nil
297+
serverVerifyFunc: func(params *HandshakeVerificationInfo) (*PostHandshakeVerificationResults, error) {
298+
return &PostHandshakeVerificationResults{}, nil
299299
},
300300
serverVerificationType: CertVerification,
301301
},
@@ -314,16 +314,16 @@ func (s) TestEnd2End(t *testing.T) {
314314
desc: "TestServerCustomVerification",
315315
clientCert: []tls.Certificate{cs.ClientCert1},
316316
clientRoot: cs.ClientTrust1,
317-
clientVerifyFunc: func(params *VerificationFuncParams) (*VerificationResults, error) {
318-
return &VerificationResults{}, nil
317+
clientVerifyFunc: func(params *HandshakeVerificationInfo) (*PostHandshakeVerificationResults, error) {
318+
return &PostHandshakeVerificationResults{}, nil
319319
},
320320
clientVerificationType: CertVerification,
321321
serverCert: []tls.Certificate{cs.ServerCert1},
322322
serverRoot: cs.ServerTrust1,
323-
serverVerifyFunc: func(params *VerificationFuncParams) (*VerificationResults, error) {
323+
serverVerifyFunc: func(params *HandshakeVerificationInfo) (*PostHandshakeVerificationResults, error) {
324324
switch stage.read() {
325325
case 0, 2:
326-
return &VerificationResults{}, nil
326+
return &PostHandshakeVerificationResults{}, nil
327327
case 1:
328328
return nil, fmt.Errorf("custom authz check fails")
329329
default:
@@ -345,9 +345,9 @@ func (s) TestEnd2End(t *testing.T) {
345345
RootCACerts: test.serverRoot,
346346
GetRootCertificates: test.serverGetRoot,
347347
},
348-
RequireClientCert: true,
349-
VerifyPeer: test.serverVerifyFunc,
350-
VerificationType: test.serverVerificationType,
348+
RequireClientCert: true,
349+
AdditionalPeerVerification: test.serverVerifyFunc,
350+
VerificationType: test.serverVerificationType,
351351
}
352352
serverTLSCreds, err := NewServerCreds(serverOptions)
353353
if err != nil {
@@ -368,7 +368,7 @@ func (s) TestEnd2End(t *testing.T) {
368368
Certificates: test.clientCert,
369369
GetIdentityCertificatesForClient: test.clientGetCert,
370370
},
371-
VerifyPeer: test.clientVerifyFunc,
371+
AdditionalPeerVerification: test.clientVerifyFunc,
372372
RootOptions: RootCertificateOptions{
373373
RootCACerts: test.clientRoot,
374374
GetRootCertificates: test.clientGetRoot,
@@ -635,8 +635,8 @@ func (s) TestPEMFileProviderEnd2End(t *testing.T) {
635635
RootProvider: serverRootProvider,
636636
},
637637
RequireClientCert: true,
638-
VerifyPeer: func(params *VerificationFuncParams) (*VerificationResults, error) {
639-
return &VerificationResults{}, nil
638+
AdditionalPeerVerification: func(params *HandshakeVerificationInfo) (*PostHandshakeVerificationResults, error) {
639+
return &PostHandshakeVerificationResults{}, nil
640640
},
641641
VerificationType: CertVerification,
642642
}
@@ -658,8 +658,8 @@ func (s) TestPEMFileProviderEnd2End(t *testing.T) {
658658
IdentityOptions: IdentityCertificateOptions{
659659
IdentityProvider: clientIdentityProvider,
660660
},
661-
VerifyPeer: func(params *VerificationFuncParams) (*VerificationResults, error) {
662-
return &VerificationResults{}, nil
661+
AdditionalPeerVerification: func(params *HandshakeVerificationInfo) (*PostHandshakeVerificationResults, error) {
662+
return &PostHandshakeVerificationResults{}, nil
663663
},
664664
RootOptions: RootCertificateOptions{
665665
RootProvider: clientRootProvider,

0 commit comments

Comments
 (0)