📄 rfc1509.txt
字号:
typedef struct gss_OID_set_desc_struct {
int count;
gss_OID elements;
} gss_OID_set_desc, *gss_OID_set;
The count field contains the number of OIDs within the set. The
elements field is a pointer to an array of gss_OID_desc objects, each
of which describes a single OID. gss_OID_set values are used to name
the available mechanisms supported by the GSSAPI, to request the use
of specific mechanisms, and to indicate which mechanisms a given
credential supports. Storage associated with gss_OID_set values
returned to the application by the GSSAPI may be deallocated by the
gss_release_oid_set routine.
2.1.6. Credentials
A credential handle is a caller-opaque atomic datum that identifies a
GSSAPI credential data structure. It is represented by the caller-
opaque type gss_cred_id_t, which may be implemented as either an
arithmetic or a pointer type. Credentials describe a principal, and
they give their holder the ability to act as that principal. The
GSSAPI does not make the actual credentials available to
applications; instead the credential handle is used to identify a
particular credential, held internally by GSSAPI or underlying
Wray [Page 6]
RFC 1509 GSSAPI - Overview and C bindings September 1993
mechanism. Thus the credential handle contains no security-relavent
information, and requires no special protection by the application.
Depending on the implementation, a given credential handle may refer
to different credentials when presented to the GSSAPI by different
callers. Individual GSSAPI implementations should define both the
scope of a credential handle and the scope of a credential itself
(which must be at least as wide as that of a handle). Possibilities
for credential handle scope include the process that acquired the
handle, the acquiring process and its children, or all processes
sharing some local identification information (e.g., UID). If no
handles exist by which a given credential may be reached, the GSSAPI
may delete the credential.
Certain routines allow credential handle parameters to be omitted to
indicate the use of a default credential. The mechanism by which a
default credential is established and its scope should be defined by
the individual GSSAPI implementation.
2.1.7. Contexts
The gss_ctx_id_t data type contains a caller-opaque atomic value that
identifies one end of a GSSAPI security context. It may be
implemented as either an arithmetic or a pointer type. Depending on
the implementation, a given gss_ctx_id_t value may refer to different
GSSAPI security contexts when presented to the GSSAPI by different
callers. The security context holds state information about each end
of a peer communication, including cryptographic state information.
Individual GSSAPI implementations should define the scope of a
context. Since no way is provided by which a new gss_ctx_id_t value
may be obtained for an existing context, the scope of a context
should be the same as the scope of a gss_ctx_id_t.
2.1.8. Authentication tokens
A token is a caller-opaque type that GSSAPI uses to maintain
synchronization between the context data structures at each end of a
GSSAPI security context. The token is a cryptographically protected
bit-string, generated by the underlying mechanism at one end of a
GSSAPI security context for use by the peer mechanism at the other
end. Encapsulation (if required) and transfer of the token are the
responsibility of the peer applications. A token is passed between
the GSSAPI and the application using the gss_buffer_t conventions.
2.1.9. Status values
One or more status codes are returned by each GSSAPI routine. Two
distinct sorts of status codes are returned. These are termed GSS
status codes and Mechanism status codes.
Wray [Page 7]
RFC 1509 GSSAPI - Overview and C bindings September 1993
2.1.9.1. GSS status codes
GSSAPI routines return GSS status codes as their OM_uint32 function
value. These codes indicate errors that are independent of the
underlying mechanism used to provide the security service. The
errors that can be indicated via a GSS status code are either generic
API routine errors (errors that are defined in the GSSAPI
specification) or calling errors (errors that are specific to these
bindings).
A GSS status code can indicate a single fatal generic API error from
the routine and a single calling error. In addition, supplementary
status information may be indicated via the setting of bits in the
supplementary info field of a GSS status code.
These errors are encoded into the 32-bit GSS status code as follows:
MSB LSB
|------------------------------------------------------------|
| Calling Error | Routine Error | Supplementary Info |
|------------------------------------------------------------|
Bit 31 24 23 16 15 0
Hence if a GSSAPI routine returns a GSS status code whose upper 16
bits contain a non-zero value, the call failed. If the calling error
field is non-zero, the invoking application's call of the routine was
erroneous. Calling errors are defined in table 5-1. If the routine
error field is non-zero, the routine failed for one of the routine-
specific reasons listed below in table 5-2. Whether or not the upper
16 bits indicate a failure or a success, the routine may indicate
additional information by setting bits in the supplementary info
field of the status code. The meaning of individual bits is listed
below in table 5-3.
Table 5-1 Calling Errors
Name Value in Meaning
Field
GSS_S_CALL_INACCESSIBLE_READ 1 A required input
parameter could
not be read.
GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output
parameter could
not be written.
GSS_S_CALL_BAD_STRUCTURE 3 A parameter was
malformed
Wray [Page 8]
RFC 1509 GSSAPI - Overview and C bindings September 1993
Table 5-2 Routine Errors
Name Value in Meaning
Field
GSS_S_BAD_MECH 1 An unsupported mechanism was
requested
GSS_S_BAD_NAME 2 An invalid name was supplied
GSS_S_BAD_NAMETYPE 3 A supplied name was of an
unsupported type
GSS_S_BAD_BINDINGS 4 Incorrect channel bindings
were supplied
GSS_S_BAD_STATUS 5 An invalid status code was
supplied
GSS_S_BAD_SIG 6 A token had an invalid
signature
GSS_S_NO_CRED 7 No credentials were supplied
GSS_S_NO_CONTEXT 8 No context has been
established
GSS_S_DEFECTIVE_TOKEN 9 A token was invalid
GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid
GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials
have expired
GSS_S_CONTEXT_EXPIRED 12 The context has expired
GSS_S_FAILURE 13 Miscellaneous failure
(see text)
Table 5-3 Supplementary Status Bits
Name Bit Number Meaning
GSS_S_CONTINUE_NEEDED 0 (LSB) The routine must be called
again to complete its
function.
See routine documentation for
detailed description.
GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of
an earlier token
GSS_S_OLD_TOKEN 2 The token's validity period
has expired
GSS_S_UNSEQ_TOKEN 3 A later token has already been
processed
The routine documentation also uses the name GSS_S_COMPLETE, which is
a zero value, to indicate an absence of any API errors or
supplementary information bits.
Wray [Page 9]
RFC 1509 GSSAPI - Overview and C bindings September 1993
All GSS_S_xxx symbols equate to complete OM_uint32 status codes,
rather than to bitfield values. For example, the actual value of the
symbol GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 3
<< 16.
The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and
GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS
status code and removes all but the relevant field. For example, the
value obtained by applying GSS_ROUTINE_ERROR to a status code removes
the calling errors and supplementary info fields, leaving only the
routine errors field. The values delivered by these macros may be
directly compared with a GSS_S_xxx symbol of the appropriate type.
The macro GSS_ERROR() is also provided, which when applied to a GSS
status code returns a non-zero value if the status code indicated a
calling or routine error, and a zero value otherwise.
A GSSAPI implementation may choose to signal calling errors in a
platform-specific manner instead of, or in addition to the routine
value; routine errors and supplementary info should be returned via
routine status values only.
2.1.9.2. Mechanism-specific status codes
GSSAPI routines return a minor_status parameter, which is used to
indicate specialized errors from the underlying security mechanism.
This parameter may contain a single mechanism-specific error,
indicated by a OM_uint32 value.
The minor_status parameter will always be set by a GSSAPI routine,
even if it returns a calling error or one of the generic API errors
indicated above as fatal, although other output parameters may remain
unset in such cases. However, output parameters that are expected to
return pointers to storage allocated by a routine must always set set
by the routine, even in the event of an error, although in such cases
the GSSAPI routine may elect to set the returned parameter value to
NULL to indicate that no storage was actually allocated. Any length
field associated with such pointers (as in a gss_buffer_desc
structure) should also be set to zero in such cases.
The GSS status code GSS_S_FAILURE is used to indicate that the
underlying mechanism detected an error for which no specific GSS
status code is defined. The mechanism status code will provide more
details about the error.
2.1.10. Names
A name is used to identify a person or entity. GSSAPI authenticates
the relationship between a name and the entity claiming the name.
Wray [Page 10]
RFC 1509 GSSAPI - Overview and C bindings September 1993
Two distinct representations are defined for names:
(a) A printable form, for presentation to a user
(b) An internal form, for presentation at the API
The syntax of a printable name is defined by the GSSAPI
implementation, and may be dependent on local system configuration,
or on individual user preference. The internal form provides a
canonical representation of the name that is independent of
configuration.
A given GSSAPI implementation may support names drawn from multiple
namespaces. In such an implementation, the internal form of the name
must include fields that identify the namespace from which the name
is drawn. The namespace from which a printable name is drawn is
specified by an accompanying object identifier.
Routines (gss_import_name and gss_display_name) are provided to
convert names between their printable representations and the
gss_name_t type. gss_import_name may support multiple syntaxes for
each supported namespace, allowing users the freedom to choose a
preferred name representation. gss_display_name should use an
implementation-chosen preferred syntax for each supported name-type.
Comparison of internal-form names is accomplished via the
gss_compare_names routine. This removes the need for the application
program to understand the syntaxes of the various printable names
that a given GSSAPI implementation may support.
Storage is allocated by routines that return gss_name_t values. A
procedure, gss_release_name, is provided to free storage associated
with a name.
2.1.11. Channel Bindings
GSSAPI supports the use of user-specified tags to identify a given
context to the peer application. These tags are used to identify the
particular communications channel that carries the context. Channel
bindings are communicated to the GSSAPI using the following
structure:
Wray [Page 11]
RFC 1509 GSSAPI - Overview and C bindings September 1993
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -