From d82de27053ae8110b65e71480db8f8504ae53903 Mon Sep 17 00:00:00 2001 From: Greg Hudson Date: Fri, 13 Nov 2020 15:32:31 -0500 Subject: 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) --- doc/appdev/gssapi.rst | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) (limited to 'doc') diff --git a/doc/appdev/gssapi.rst b/doc/appdev/gssapi.rst index 452ead2..d26c9fe 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 ```` 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 ` 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 ` which will be used, if + necessary, to refresh the credentials in the cache. + +* **keytab**: For acquiring acceptor credentials, the name of the + :ref:`keytab ` 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 ` 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 ----------------------------------- -- cgit v1.1