Skip to content

Commit 79c7ebc

Browse files
jake-descojake-desco
committed
Doc improvements; make GssNameType an interface
1 parent 2f4a3f2 commit 79c7ebc

File tree

5 files changed

+52
-33
lines changed

5 files changed

+52
-33
lines changed

‎build-tools/gen-gss-name-oids.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ package gssapi
4343
// GENERATED CODE: DO NOT EDIT
4444
4545
var nameTypes = []struct {
46-
id GssNameType
46+
id gssNameTypeImpl
4747
name string
4848
oidString string
4949
oid Oid

‎v3/cred.go‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ type Credential interface {
3939
// This method corresponds to GSS_Release_cred from RFC 2743 § 2.1.2.
4040
//
4141
// Returns:
42-
// - err: error if one occurred, otherwise nil
42+
// - error if one occurred, otherwise nil
4343
Release() error // RFC 2743 § 2.1.2
4444

4545
// Inquire returns information about the credential, implementing the GSS_Inquire_cred call
@@ -56,7 +56,7 @@ type Credential interface {
5656
// Returns:
5757
// - info: information about the credential
5858
// - err: error if one occurred, otherwise nil
59-
Inquire() (*CredInfo, error) // RFC 2743 § 2.1.3
59+
Inquire() (info *CredInfo, err error) // RFC 2743 § 2.1.3
6060

6161
// Add adds a credential element to the Credential. This method implements the GSS_Add_cred call
6262
// described in RFC 2743 § 2.1.4.
@@ -78,7 +78,7 @@ type Credential interface {
7878
// CredUsageAcceptOnly or CredUsageInitiateAndAccept, or the zero value for a default value
7979
//
8080
// Returns:
81-
// - err: error if one occurred, otherwise nil
81+
// - error if one occurred, otherwise nil
8282
Add(name GssName, mech GssMech, usage CredUsage, initiatorLifetime time.Duration, acceptorLifetime time.Duration) error // RFC 2743 § 2.1.4
8383

8484
// InquireByMech returns information about the credential element related to mech, implementing the
@@ -98,5 +98,5 @@ type Credential interface {
9898
// Returns:
9999
// - info: information about the credential element
100100
// - err: error if one occurred, otherwise nil
101-
InquireByMech(mech GssMech) (*CredInfo, error) // RFC 2743 § 2.1.5
101+
InquireByMech(mech GssMech) (info *CredInfo, err error) // RFC 2743 § 2.1.5
102102
}

‎v3/names.go‎

Lines changed: 38 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,20 @@ import (
88

99
//go:generate go run ../build-tools/gen-gss-name-oids.go -o names_gen.go
1010

11-
// GssNameType defines the name types in a mech-independent fashion,
12-
// as described in RFC 2743 § 4
13-
type GssNameType int
11+
// GssNameType describes an available GSSAPI Name Type (NT) as described in
12+
// RFC 2743 § 4.
13+
type GssNameType interface {
14+
// Oid returns the object identifier corresponding to the name type.
15+
Oid() Oid
16+
// OidString returns a printable version of the object identifier associated with the mechanism.
17+
OidString() string
18+
// String returns a printable version of the mechanism name.
19+
String() string
20+
}
21+
22+
// gssNameTypeImpl is an internal type that implements the GssNameType interface for the
23+
// well-known name types. It supports well known name types.
24+
type gssNameTypeImpl int
1425

1526
// GssName represents GSSAPI names (types INTERNAL NAME and MN) as described in RFC 2743 § 4.
1627
// This interface includes support for name-related calls: GSS_Compare_name, GSS_Display_name,
@@ -29,7 +40,7 @@ type GssName interface {
2940
// Returns:
3041
// - equal: boolean value indicating whether the two names are equal
3142
// - err: error if one occurred, otherwise nil
32-
Compare(other GssName) (bool, error) // RFC 2743 § 2.4.3
43+
Compare(other GssName) (equal bool, err error) // RFC 2743 § 2.4.3
3344

3445
// Display implements GSS_Display_Name from RFC 2743 § 2.4.4.
3546
// It returns a string representation of the name and its type.
@@ -38,13 +49,13 @@ type GssName interface {
3849
// - disp: string representation of the name
3950
// - nt: type of the name
4051
// - err: error if one occurred, otherwise nil
41-
Display() (string, GssNameType, error) // RFC 2743 § 2.4.4
52+
Display() (disp string, nt GssNameType, err error) // RFC 2743 § 2.4.4
4253

4354
// Release implements GSS_Release_Name from RFC 2743 § 2.4.6.
4455
// It releases the name when it is no longer required.
4556
//
4657
// Returns:
47-
// - err: error if one occurred, otherwise nil
58+
// - error if one occurred, otherwise nil
4859
Release() error // RFC 2743 § 2.4.6
4960

5061
// InquireMechs implements GSS_Inquire_mechs_for_name from RFC 2743 § 2.4.13.
@@ -53,7 +64,7 @@ type GssName interface {
5364
// Returns:
5465
// - mechs: set of mechanisms that support the name
5566
// - err: error if one occurred, otherwise nil
56-
InquireMechs() ([]GssMech, error) // RFC 2743 § 2.4.13
67+
InquireMechs() (mechs []GssMech, err error) // RFC 2743 § 2.4.13
5768

5869
// Canonicalize implements GSS_Canonicalize_name from RFC 2743 § 2.4.14.
5970
// It converts the name to a mechanism-specific form (MN).
@@ -64,7 +75,7 @@ type GssName interface {
6475
// Returns:
6576
// - name: the canonical GssName. This must be released using GssName.Release()
6677
// - err: error if one occurred, otherwise nil
67-
Canonicalize(GssMech) (GssName, error) // RFC 2743 § 2.4.14
78+
Canonicalize(mech GssMech) (name GssName, err error) // RFC 2743 § 2.4.14
6879

6980
// Export creates an exported byte representation of a mechanism name (MN) that is the result of
7081
// a call to CanonicalizeName() or Provider.AcceptSecContext().
@@ -76,23 +87,23 @@ type GssName interface {
7687
// Returns:
7788
// - exp: the exported name representation
7889
// - err: error if one occurred, otherwise nil
79-
Export() ([]byte, error) // RFC 2743 § 2.4.15
90+
Export() (exp []byte, err error) // RFC 2743 § 2.4.15
8091

8192
// Duplicate implements GSS_Duplicate_name from RFC 2743 § 2.4.16.
8293
// It creates a copy of the name that remains valid even if the source name is released.
8394
//
8495
// Returns:
8596
// - name: the duplicated name. This must be released using GssName.Release()
8697
// - err: error if one occurred, otherwise nil
87-
Duplicate() (GssName, error) // RFC 2743 § 2.4.16
98+
Duplicate() (name GssName, err error) // RFC 2743 § 2.4.16
8899
}
89100

90101
// NOTE: if the order here changes also change
91102
// gen-gss-name-oids.go!
92103

93104
const (
94105
// Host-based name form (RFC 2743 § 4.1), "service@host" or just "service"
95-
GSS_NT_HOSTBASED_SERVICE GssNameType = iota
106+
GSS_NT_HOSTBASED_SERVICE gssNameTypeImpl = iota
96107

97108
// User name form (RFC 2743 § 4.2), "username" : named local user
98109
GSS_NT_USER_NAME
@@ -136,48 +147,56 @@ const (
136147
_GSS_NAME_TYPE_LAST
137148
)
138149

139-
func (nt GssNameType) Oid() Oid {
150+
func (nt gssNameTypeImpl) Oid() Oid {
140151
if nt >= _GSS_NAME_TYPE_LAST {
141152
panic(ErrBadNameType)
142153
}
143154

144155
return nameTypes[nt].oid
145156
}
146157

147-
func (nt GssNameType) OidString() string {
158+
func (nt gssNameTypeImpl) OidString() string {
148159
if nt >= _GSS_NAME_TYPE_LAST {
149160
panic(ErrBadNameType)
150161
}
151162

152163
return nameTypes[nt].oidString
153164
}
154165

155-
func (nt GssNameType) String() string {
166+
func (nt gssNameTypeImpl) String() string {
156167
if nt >= _GSS_NAME_TYPE_LAST {
157168
panic(ErrBadNameType)
158169
}
159170

160171
return nameTypes[nt].name
161172
}
162173

163-
// NameFromOid returns the name type associated with an OID, or an error if the OID is unknown.
174+
// NameTypeFromOid returns the name type associated with an OID.
175+
//
176+
// The standard implementation offers this function for use with the gssNameTypeImpl
177+
// internal type for a standard set of well known name types.
178+
//
179+
// If a provider needs to support a different name type, it can be added to gssNameTypeImpl via a pull
180+
// request to the go-gssapi repository. Alternatively, a new implementation of GssNameType can be
181+
// created for use by that GSSAPI implementation. Depending on the requirements, a replacement for
182+
// NameTypeFromOid may also need to be provided by the provider.
164183
// This function is provided to map a name OID to a name type.
165184
//
166185
// Parameters:
167186
// - oid: the object identifier to look up
168187
//
169188
// Returns:
170-
// - GssNameType: the corresponding name type
189+
// - gssNameTypeImpl: the corresponding name type
171190
// - error: ErrBadNameType if the OID is not recognized
172-
func NameFromOid(oid Oid) (GssNameType, error) {
191+
func NameTypeFromOid(oid Oid) (gssNameTypeImpl, error) {
173192
for i, nt := range nameTypes {
174193
if slices.Equal(nt.oid, oid) {
175-
return GssNameType(i), nil
194+
return gssNameTypeImpl(i), nil
176195
}
177196

178197
for _, alt := range nt.altOids {
179198
if slices.Equal(alt, oid) {
180-
return GssNameType(i), nil
199+
return gssNameTypeImpl(i), nil
181200
}
182201
}
183202
}

‎v3/names_gen.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ package gssapi
55
// GENERATED CODE: DO NOT EDIT
66

77
var nameTypes = []struct {
8-
id GssNameType
8+
id gssNameTypeImpl
99
name string
1010
oidString string
1111
oid Oid

‎v3/names_test.go‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ func TestNtOid(t *testing.T) {
2020
oid = GSS_NT_USER_NAME.Oid()
2121
assert.Equal(Oid{0x2a, 0x86, 0x48, 0x86, 0xf7, 0x12, 0x01, 0x02, 0x01, 0x01}, oid)
2222

23-
badNt := GssNameType(100)
23+
badNt := gssNameTypeImpl(100)
2424
assert.PanicsWithValue(ErrBadNameType, func() { _ = badNt.Oid() })
2525
}
2626

@@ -36,7 +36,7 @@ func TestNtOidString(t *testing.T) {
3636
oid = GSS_NT_USER_NAME.OidString()
3737
assert.Equal("1.2.840.113554.1.2.1.1", oid)
3838

39-
badNt := GssNameType(100)
39+
badNt := gssNameTypeImpl(100)
4040
assert.PanicsWithValue(ErrBadNameType, func() { _ = badNt.OidString() })
4141
}
4242

@@ -52,33 +52,33 @@ func TestNtString(t *testing.T) {
5252
oid = GSS_NT_USER_NAME.String()
5353
assert.Equal("GSS_NT_USER_NAME", oid)
5454

55-
badNt := GssNameType(100)
55+
badNt := gssNameTypeImpl(100)
5656
assert.PanicsWithValue(ErrBadNameType, func() { _ = badNt.String() })
5757
}
5858

5959
func TestNameFromOid(t *testing.T) {
6060
assert := assert.New(t)
6161

6262
// from a good primary OID
63-
nt, err := NameFromOid(Oid{0x2a, 0x86, 0x48, 0x86, 0xf7, 0x12, 0x01, 0x02, 0x01, 0x01})
63+
nt, err := NameTypeFromOid(Oid{0x2a, 0x86, 0x48, 0x86, 0xf7, 0x12, 0x01, 0x02, 0x01, 0x01})
6464
assert.NoError(err)
6565
assert.Equal(GSS_NT_USER_NAME, nt)
6666

6767
// from a secondary OID
68-
nt, err = NameFromOid(Oid{0x2B, 0x06, 0x01, 0x05, 0x06, 0x02})
68+
nt, err = NameTypeFromOid(Oid{0x2B, 0x06, 0x01, 0x05, 0x06, 0x02})
6969
assert.NoError(err)
7070
assert.Equal(GSS_NT_HOSTBASED_SERVICE, nt)
7171

72-
nt, err = NameFromOid(Oid{0x2a, 0x86, 0x48, 0x82, 0xf7, 0x12, 0x01, 0x02, 0x02})
72+
nt, err = NameTypeFromOid(Oid{0x2a, 0x86, 0x48, 0x82, 0xf7, 0x12, 0x01, 0x02, 0x02})
7373
assert.NoError(err)
7474
assert.Equal(GSS_KRB5_NT_PRINCIPAL_NAME, nt)
7575

7676
// from a bad oid
77-
_, err = NameFromOid(Oid{0x00})
77+
_, err = NameTypeFromOid(Oid{0x00})
7878
assert.ErrorIs(err, ErrBadNameType)
7979

8080
// from a nil oid
81-
nt, err = NameFromOid(nil)
81+
nt, err = NameTypeFromOid(nil)
8282
assert.NoError(err)
8383
assert.Equal(GSS_NO_OID, nt)
8484
}

0 commit comments

Comments
 (0)