diff options
author | Greg Hudson <ghudson@mit.edu> | 2020-11-13 15:32:31 -0500 |
---|---|---|
committer | Greg Hudson <ghudson@mit.edu> | 2020-11-18 11:31:46 -0500 |
commit | d82de27053ae8110b65e71480db8f8504ae53903 (patch) | |
tree | db9e590bc31e496cdfc0bec91397e9b82fc9e34f /doc | |
parent | adbf73c507f383380c55d2ba9fa1ad6f30545bec (diff) | |
download | krb5-d82de27053ae8110b65e71480db8f8504ae53903.tar.gz |
Add GSS credential store documentation
Add documentation for gss_acquire_cred_from() and
gss_store_cred_into(), including descriptions of the currently
supported options for the krb5 mechanism.
ticket: 8964 (new)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/appdev/gssapi.rst | 80 |
1 files changed, 80 insertions, 0 deletions
diff --git a/doc/appdev/gssapi.rst b/doc/appdev/gssapi.rst index 452ead2a9..d26c9fe86 100644 --- a/doc/appdev/gssapi.rst +++ b/doc/appdev/gssapi.rst @@ -206,6 +206,86 @@ so multiple invocations may be necessary to retrieve all of the indicators from the ticket. (New in release 1.15.) +Credential store extensions +--------------------------- + +Beginning with release 1.11, the following GSSAPI extensions declared +in ``<gssapi/gssapi_ext.h>`` can be used to specify how credentials +are acquired or stored:: + + struct gss_key_value_element_struct { + const char *key; + const char *value; + }; + typedef struct gss_key_value_element_struct gss_key_value_element_desc; + + struct gss_key_value_set_struct { + OM_uint32 count; + gss_key_value_element_desc *elements; + }; + typedef const struct gss_key_value_set_struct gss_key_value_set_desc; + typedef const gss_key_value_set_desc *gss_const_key_value_set_t; + + OM_uint32 gss_acquire_cred_from(OM_uint32 *minor_status, + const gss_name_t desired_name, + OM_uint32 time_req, + const gss_OID_set desired_mechs, + gss_cred_usage_t cred_usage, + gss_const_key_value_set_t cred_store, + gss_cred_id_t *output_cred_handle, + gss_OID_set *actual_mechs, + OM_uint32 *time_rec); + + OM_uint32 gss_store_cred_into(OM_uint32 *minor_status, + gss_cred_id_t input_cred_handle, + gss_cred_usage_t cred_usage, + const gss_OID desired_mech, + OM_uint32 overwrite_cred, + OM_uint32 default_cred, + gss_const_key_value_set_t cred_store, + gss_OID_set *elements_stored, + gss_cred_usage_t *cred_usage_stored); + +The additional *cred_store* parameter allows the caller to specify +information about how the credentials should be obtained and stored. +The following options are supported by the krb5 mechanism: + +* **ccache**: For acquiring initiator credentials, the name of the + :ref:`credential cache <ccache_definition>` to which the handle will + refer. For storing credentials, the name of the cache where the + credentials should be stored. If a collection name is given, the + primary cache of the collection will be used; this behavior may + change in future releases to select a cache from the collection. + +* **client_keytab**: For acquiring initiator credentials, the name of + the :ref:`keytab <keytab_definition>` which will be used, if + necessary, to refresh the credentials in the cache. + +* **keytab**: For acquiring acceptor credentials, the name of the + :ref:`keytab <keytab_definition>` to which the handle will refer. + In release 1.19 and later, this option also determines the keytab to + be used for verification when initiator credentials are acquired + using a password and verified. + +* **password**: For acquiring initiator credentials, this option + instructs the mechanism to acquire fresh credentials into a unique + memory credential cache. This option may not be used with the + **ccache** or **client_keytab** options, and a *desired_name* must + be specified. (New in release 1.19.) + +* **rcache**: For acquiring acceptor credentials, the name of the + :ref:`replay cache <rcache_definition>` to be used when processing + the initiator tokens. (New in release 1.13.) + +* **verify**: For acquiring initiator credentials, this option + instructs the mechanism to verify the credentials by obtaining a + ticket to a service with a known key. The service key is obtained + from the keytab specified with the **keytab** option or the default + keytab. The value may be the name of a principal in the keytab, or + the empty string. If the empty string is given, any ``host`` + service principal in the keytab may be used. (New in release 1.19.) + + Importing and exporting credentials ----------------------------------- |