Appendix D

Sun-Specific Features

This appendix covers features unique to Sun's implementation of the GSS-API.

Implementation-Specifc Features

A few aspects of the GSS-API may differ from one implementation of the API to another. In most cases differences in implementations have only minimal effect on programs; in all cases developers can maximize portability by not relying on any behavior specific to a given implementation, including Sun's.

Sun-Specific Functions

There are no GSS-API functions that are unique to Sun's implementation.

Human-Readable Name Syntax

Implementations of the GSS-API may differ in the printable syntax that corresponds to names. Applications that aim for portability should refrain from comparing names based on human--readable (that is, printable) forms and should instead use gss_compare_name() to determine whether or not one internal-format name matches another.

Sun's implementation of gss_display_name() displays names as follows: if the input_nameargument denotes a user principal, the gss_display_name() returns user_principal@realm as the output_name_buffer, and the gss_OID value as the output_name_type. If Kerberos v5 is the underlying mechanism, gss_OID is 1.2.840.11354.1.2.2.

If the name given to gss_display_name() was created by a call to gss_import_name(), specifying GSS_C_NO_OID as the name type, gss_display_name() returns GSS_C_NO_OID via the output_name_type parameter.

Format of Anonymous Names

The gss_display_name() function outputs the string '<anonymous>' to indicate an anonymous GSS-API principal. The name type OID associated with this name is GSS_C_NT_ANONYMOUS. No other valid printable names supported by Sun's implementation can begin with '<' and end with '>'.

Implementations of Selected Data Types

The following data types have been implemented as pointers (some implementations may specify them as arithmetic types): gss_cred_t, gss_ctx_id_t, gss_name_t.

Deletion of Contexts and Stored Data

In the case where context establishment fails, Sun's implementation does not automatically delete "half-built" contexts. Applications should therefore handle this event by deleting the contexts themselves with gss_delete_sec_context().

Sun's implementation automatically releases stored data, such as internal names, through memory management. However, for good measure, applications should still call appropriate functions, such as gss_release_name(), when data elements are no longer needed.

Protection of Channel-Binding Information

Sun does not encrypt information contained in channel bindings. Programmers must therefore not assume that this information is unassailable.

Context Exportation and Interprocess Tokens

Sun's implementation supports context exportation; other implementations of the GSS-API may not. The interprocess token used in exporting a context may contain sensitive data from the original security context, including cryptographic keys. Sun's implementation of the GSS-API does not encrypt interprocess tokens. Therefore, applications that export security contexts must take appropriate steps to protect these tokens in transit (that is, wrap them themselves).

Sun's implementation detects and rejects attempted multiple imports of the same context.

Types of Credentials Supported

Sun's implementation of the GSS-API supports the acquisition of GSS_C_INITIATE, GSS_C_ACCEPT, and GSS_C_BOTH credentials via gss_acquire_cred().

Credential Expiration

The Sun implementation of the GSS-API supports credential expiration. Therefore, programmers can use parameters relating to credential lifetime in functions such as gss_acquire_cred() and gss_add_cred().

Context Expiration

Sun's implementation of the GSS-API supports context expiration. Therefore, programmers can use parameters relating to context lifetime in functions such as gss_init_sec_context() and gss_inquire_context().

Wrap Size Limits and QOP Values

Sun's implementation of the GSS-API (as opposed to any underlying mechanism) does not impose a maximum size on the size of messages to be processed by gss_wrap(). Applications can determine the maximum message size with gss_wrap_size_limit().

Sun's implementation of the GSS-API detects invalid QOP values when gss_wrap_size_limit() is called.

Use of minor_status Parameter

In Sun's implementation of the GSS-API, functions return only mechanism-specific information in the minor_status parameter. (Other implementations may include implementation-specific return values as part of the returned minor-status code.)


	Appendix D Sun-Specific Features This appendix covers features unique to Sun's implementation of the GSS-API. Implementation-Specifc Features A few aspects of the GSS-API may differ from one implementation of the API to another. In most cases differences in implementations have only minimal effect on programs; in all cases developers can maximize portability by not relying on any behavior specific to a given implementation, including Sun's. Sun-Specific Functions There are no GSS-API functions that are unique to Sun's implementation. Human-Readable Name Syntax Implementations of the GSS-API may differ in the printable syntax that corresponds to names. Applications that aim for portability should refrain from comparing names based on human--readable (that is, printable) forms and should instead use `gss_compare_name()` to determine whether or not one internal-format name matches another. Sun's implementation of `gss_display_name()` displays names as follows: if the input_nameargument denotes a user principal, the `gss_display_name()` returns `user_principal@realm` as the output_name_buffer, and the `gss_OID` value as the output_name_type. If Kerberos v5 is the underlying mechanism, `gss_OID` is 1.2.840.11354.1.2.2. If the name given to `gss_display_name()` was created by a call to `gss_import_name()`, specifying `GSS_C_NO_OID` as the name type, `gss_display_name()` returns `GSS_C_NO_OID` via the output_name_type parameter. Format of Anonymous Names The `gss_display_name()` function outputs the string '`<anonymous>`' to indicate an anonymous GSS-API principal. The name type OID associated with this name is GSS_C_NT_ANONYMOUS. No other valid printable names supported by Sun's implementation can begin with '<' and end with '>'. Implementations of Selected Data Types The following data types have been implemented as pointers (some implementations may specify them as arithmetic types): gss_cred_t, gss_ctx_id_t, gss_name_t. Deletion of Contexts and Stored Data In the case where context establishment fails, Sun's implementation does not automatically delete "half-built" contexts. Applications should therefore handle this event by deleting the contexts themselves with `gss_delete_sec_context()`. Sun's implementation automatically releases stored data, such as internal names, through memory management. However, for good measure, applications should still call appropriate functions, such as `gss_release_name()`, when data elements are no longer needed. Protection of Channel-Binding Information Sun does not encrypt information contained in channel bindings. Programmers must therefore not assume that this information is unassailable. Context Exportation and Interprocess Tokens Sun's implementation supports context exportation; other implementations of the GSS-API may not. The interprocess token used in exporting a context may contain sensitive data from the original security context, including cryptographic keys. Sun's implementation of the GSS-API does not encrypt interprocess tokens. Therefore, applications that export security contexts must take appropriate steps to protect these tokens in transit (that is, wrap them themselves). Sun's implementation detects and rejects attempted multiple imports of the same context. Types of Credentials Supported Sun's implementation of the GSS-API supports the acquisition of `GSS_C_INITIATE`, `GSS_C_ACCEPT`, and `GSS_C_BOTH` credentials via `gss_acquire_cred()`. Credential Expiration The Sun implementation of the GSS-API supports credential expiration. Therefore, programmers can use parameters relating to credential lifetime in functions such as `gss_acquire_cred()` and `gss_add_cred()`. Context Expiration Sun's implementation of the GSS-API supports context expiration. Therefore, programmers can use parameters relating to context lifetime in functions such as `gss_init_sec_context()` and `gss_inquire_context()`. Wrap Size Limits and QOP Values Sun's implementation of the GSS-API (as opposed to any underlying mechanism) does not impose a maximum size on the size of messages to be processed by `gss_wrap()`. Applications can determine the maximum message size with `gss_wrap_size_limit()`. Sun's implementation of the GSS-API detects invalid QOP values when `gss_wrap_size_limit()` is called. Use of minor_status Parameter In Sun's implementation of the GSS-API, functions return only mechanism-specific information in the minor_status parameter. (Other implementations may include implementation-specific return values as part of the returned minor-status code.)