diff options
Diffstat (limited to 'doc/appdev')
| -rw-r--r-- | doc/appdev/gssapi.rst | 618 | ||||
| -rw-r--r-- | doc/appdev/h5l_mit_apidiff.rst | 31 | ||||
| -rw-r--r-- | doc/appdev/index.rst | 15 | ||||
| -rw-r--r-- | doc/appdev/init_creds.rst | 304 | ||||
| -rw-r--r-- | doc/appdev/princ_handle.rst | 79 | ||||
| -rw-r--r-- | doc/appdev/refs/api/index.rst | 411 | ||||
| -rw-r--r-- | doc/appdev/refs/index.rst | 9 | ||||
| -rw-r--r-- | doc/appdev/refs/macros/index.rst | 380 | ||||
| -rw-r--r-- | doc/appdev/refs/types/index.rst | 109 | ||||
| -rw-r--r-- | doc/appdev/refs/types/krb5_int32.rst | 12 | ||||
| -rw-r--r-- | doc/appdev/refs/types/krb5_ui_4.rst | 12 |
11 files changed, 1980 insertions, 0 deletions
diff --git a/doc/appdev/gssapi.rst b/doc/appdev/gssapi.rst new file mode 100644 index 000000000000..0258f793b99b --- /dev/null +++ b/doc/appdev/gssapi.rst @@ -0,0 +1,618 @@ +Developing with GSSAPI +====================== + +The GSSAPI (Generic Security Services API) allows applications to +communicate securely using Kerberos 5 or other security mechanisms. +We recommend using the GSSAPI (or a higher-level framework which +encompasses GSSAPI, such as SASL) for secure network communication +over using the libkrb5 API directly. + +GSSAPIv2 is specified in :rfc:`2743` and :rfc:`2744`. Also see +:rfc:`7546` for a description of how to use the GSSAPI in a client or +server program. + +This documentation will describe how various ways of using the +GSSAPI will behave with the krb5 mechanism as implemented in MIT krb5, +as well as krb5-specific extensions to the GSSAPI. + + +Name types +---------- + +A GSSAPI application can name a local or remote entity by calling +gss_import_name_, specifying a name type and a value. The following +name types are supported by the krb5 mechanism: + +* **GSS_C_NT_HOSTBASED_SERVICE**: The value should be a string of the + form ``service`` or ``service@hostname``. This is the most common + way to name target services when initiating a security context, and + is the most likely name type to work across multiple mechanisms. + +* **GSS_KRB5_NT_PRINCIPAL_NAME**: The value should be a principal name + string. This name type only works with the krb5 mechanism, and is + defined in the ``<gssapi/gssapi_krb5.h>`` header. + +* **GSS_C_NT_USER_NAME** or **GSS_C_NULL_OID**: The value is treated + as an unparsed principal name string, as above. These name types + may work with mechanisms other than krb5, but will have different + interpretations in those mechanisms. **GSS_C_NT_USER_NAME** is + intended to be used with a local username, which will parse into a + single-component principal in the default realm. + +* **GSS_C_NT_ANONYMOUS**: The value is ignored. The anonymous + principal is used, allowing a client to authenticate to a server + without asserting a particular identity (which may or may not be + allowed by a particular server or Kerberos realm). + +* **GSS_C_NT_MACHINE_UID_NAME**: The value is uid_t object. On + Unix-like systems, the username of the uid is looked up in the + system user database and the resulting username is parsed as a + principal name. + +* **GSS_C_NT_STRING_UID_NAME**: As above, but the value is a decimal + string representation of the uid. + +* **GSS_C_NT_EXPORT_NAME**: The value must be the result of a + gss_export_name_ call. + + +Initiator credentials +--------------------- + +A GSSAPI client application uses gss_init_sec_context_ to establish a +security context. The *initiator_cred_handle* parameter determines +what tickets are used to establish the connection. An application can +either pass **GSS_C_NO_CREDENTIAL** to use the default client +credential, or it can use gss_acquire_cred_ beforehand to acquire an +initiator credential. The call to gss_acquire_cred_ may include a +*desired_name* parameter, or it may pass **GSS_C_NO_NAME** if it does +not have a specific name preference. + +If the desired name for a krb5 initiator credential is a host-based +name, it is converted to a principal name of the form +``service/hostname`` in the local realm, where *hostname* is the local +hostname if not specified. The hostname will be canonicalized using +forward name resolution, and possibly also using reverse name +resolution depending on the value of the **rdns** variable in +:ref:`libdefaults`. + +If a desired name is specified in the call to gss_acquire_cred_, the +krb5 mechanism will attempt to find existing tickets for that client +principal name in the default credential cache or collection. If the +default cache type does not support a collection, and the default +cache contains credentials for a different principal than the desired +name, a **GSS_S_CRED_UNAVAIL** error will be returned with a minor +code indicating a mismatch. + +If no existing tickets are available for the desired name, but the +name has an entry in the default client :ref:`keytab_definition`, the +krb5 mechanism will acquire initial tickets for the name using the +default client keytab. + +If no desired name is specified, credential acquisition will be +deferred until the credential is used in a call to +gss_init_sec_context_ or gss_inquire_cred_. If the call is to +gss_init_sec_context_, the target name will be used to choose a client +principal name using the credential cache selection facility. (This +facility might, for instance, try to choose existing tickets for a +client principal in the same realm as the target service). If there +are no existing tickets for the chosen principal, but it is present in +the default client keytab, the krb5 mechanism will acquire initial +tickets using the keytab. + +If the target name cannot be used to select a client principal +(because the credentials are used in a call to gss_inquire_cred_), or +if the credential cache selection facility cannot choose a principal +for it, the default credential cache will be selected if it exists and +contains tickets. + +If the default credential cache does not exist, but the default client +keytab does, the krb5 mechanism will try to acquire initial tickets +for the first principal in the default client keytab. + +If the krb5 mechanism acquires initial tickets using the default +client keytab, the resulting tickets will be stored in the default +cache or collection, and will be refreshed by future calls to +gss_acquire_cred_ as they approach their expire time. + + +Acceptor names +-------------- + +A GSSAPI server application uses gss_accept_sec_context_ to establish +a security context based on tokens provided by the client. The +*acceptor_cred_handle* parameter determines what +:ref:`keytab_definition` entries may be authenticated to by the +client, if the krb5 mechanism is used. + +The simplest choice is to pass **GSS_C_NO_CREDENTIAL** as the acceptor +credential. In this case, clients may authenticate to any service +principal in the default keytab (typically |keytab|, or the value of +the **KRB5_KTNAME** environment variable). This is the recommended +approach if the server application has no specific requirements to the +contrary. + +A server may acquire an acceptor credential with gss_acquire_cred_ and +a *cred_usage* of **GSS_C_ACCEPT** or **GSS_C_BOTH**. If the +*desired_name* parameter is **GSS_C_NO_NAME**, then clients will be +allowed to authenticate to any service principal in the default +keytab, just as if no acceptor credential was supplied. + +If a server wishes to specify a *desired_name* to gss_acquire_cred_, +the most common choice is a host-based name. If the host-based +*desired_name* contains just a *service*, then clients will be allowed +to authenticate to any host-based service principal (that is, a +principal of the form ``service/hostname@REALM``) for the named +service, regardless of hostname or realm, as long as it is present in +the default keytab. If the input name contains both a *service* and a +*hostname*, clients will be allowed to authenticate to any host-based +principal for the named service and hostname, regardless of realm. + +.. note:: + + If a *hostname* is specified, it will be canonicalized + using forward name resolution, and possibly also using + reverse name resolution depending on the value of the + **rdns** variable in :ref:`libdefaults`. + +.. note:: + + If the **ignore_acceptor_hostname** variable in + :ref:`libdefaults` is enabled, then *hostname* will be + ignored even if one is specified in the input name. + +.. note:: + + In MIT krb5 versions prior to 1.10, and in Heimdal's + implementation of the krb5 mechanism, an input name with + just a *service* is treated like an input name of + ``service@localhostname``, where *localhostname* is the + string returned by gethostname(). + +If the *desired_name* is a krb5 principal name or a local system name +type which is mapped to a krb5 principal name, clients will only be +allowed to authenticate to that principal in the default keytab. + + +Name Attributes +--------------- + +In release 1.8 or later, the gss_inquire_name_ and +gss_get_name_attribute_ functions, specified in :rfc:`6680`, can be +used to retrieve name attributes from the *src_name* returned by +gss_accept_sec_context_. The following attributes are defined when +the krb5 mechanism is used: + +.. _gssapi_authind_attr: + +* "auth-indicators" attribute: + +This attribute will be included in the gss_inquire_name_ output if the +ticket contains :ref:`authentication indicators <auth_indicator>`. +One indicator is returned per invocation of gss_get_name_attribute_, +so multiple invocations may be necessary to retrieve all of the +indicators from the ticket. (New in release 1.15.) + + +Importing and exporting credentials +----------------------------------- + +The following GSSAPI extensions can be used to import and export +credentials (declared in ``<gssapi/gssapi_ext.h>``):: + + OM_uint32 gss_export_cred(OM_uint32 *minor_status, + gss_cred_id_t cred_handle, + gss_buffer_t token); + + OM_uint32 gss_import_cred(OM_uint32 *minor_status, + gss_buffer_t token, + gss_cred_id_t *cred_handle); + +The first function serializes a GSSAPI credential handle into a +buffer; the second unseralizes a buffer into a GSSAPI credential +handle. Serializing a credential does not destroy it. If any of the +mechanisms used in *cred_handle* do not support serialization, +gss_export_cred will return **GSS_S_UNAVAILABLE**. As with other +GSSAPI serialization functions, these extensions are only intended to +work with a matching implementation on the other side; they do not +serialize credentials in a standardized format. + +A serialized credential may contain secret information such as ticket +session keys. The serialization format does not protect this +information from eavesdropping or tampering. The calling application +must take care to protect the serialized credential when communicating +it over an insecure channel or to an untrusted party. + +A krb5 GSSAPI credential may contain references to a credential cache, +a client keytab, an acceptor keytab, and a replay cache. These +resources are normally serialized as references to their external +locations (such as the filename of the credential cache). Because of +this, a serialized krb5 credential can only be imported by a process +with similar privileges to the exporter. A serialized credential +should not be trusted if it originates from a source with lower +privileges than the importer, as it may contain references to external +credential cache, keytab, or replay cache resources not accessible to +the originator. + +An exception to the above rule applies when a krb5 GSSAPI credential +refers to a memory credential cache, as is normally the case for +delegated credentials received by gss_accept_sec_context_. In this +case, the contents of the credential cache are serialized, so that the +resulting token may be imported even if the original memory credential +cache no longer exists. + + +Constrained delegation (S4U) +---------------------------- + +The Microsoft S4U2Self and S4U2Proxy Kerberos protocol extensions +allow an intermediate service to acquire credentials from a client to +a target service without requiring the client to delegate a +ticket-granting ticket, if the KDC is configured to allow it. + +To perform a constrained delegation operation, the intermediate +service must submit to the KDC an "evidence ticket" from the client to +the intermediate service with the forwardable bit set. An evidence +ticket can be acquired when the client authenticates to the +intermediate service with Kerberos, or with an S4U2Self request if the +KDC allows it. The MIT krb5 GSSAPI library represents an evidence +ticket using a "proxy credential", which is a special kind of +gss_cred_id_t object whose underlying credential cache contains the +evidence ticket and a krbtgt ticket for the intermediate service. + +To acquire a proxy credential during client authentication, the +service should first create an acceptor credential using the +**GSS_C_BOTH** usage. The application should then pass this +credential as the *acceptor_cred_handle* to gss_accept_sec_context_, +and also pass a *delegated_cred_handle* output parameter to receive a +proxy credential containing the evidence ticket. The output value of +*delegated_cred_handle* may be a delegated ticket-granting ticket if +the client sent one, or a proxy credential if the client authenticated +with a forwardable service ticket, or **GSS_C_NO_CREDENTIAL** if +neither is the case. + +To acquire a proxy credential using an S4U2Self request, the service +can use the following GSSAPI extension:: + + OM_uint32 gss_acquire_cred_impersonate_name(OM_uint32 *minor_status, + gss_cred_id_t icred, + gss_name_t desired_name, + OM_uint32 time_req, + gss_OID_set desired_mechs, + gss_cred_usage_t cred_usage, + gss_cred_id_t *output_cred, + gss_OID_set *actual_mechs, + OM_uint32 *time_rec); + +The parameters to this function are similar to those of +gss_acquire_cred_, except that *icred* is used to make an S4U2Self +request to the KDC for a ticket from *desired_name* to the +intermediate service. Both *icred* and *desired_name* are required +for this function; passing **GSS_C_NO_CREDENTIAL** or +**GSS_C_NO_NAME** will cause the call to fail. *icred* must contain a +krbtgt ticket for the intermediate service. If the KDC returns a +forwardable ticket, the result of this operation is a proxy +credential; if it is not forwardable, the result is a regular +credential for *desired_name*. + +A recent KDC will usually allow any service to acquire a ticket from a +client to itself with an S4U2Self request, but the ticket will only be +forwardable if the service has a specific privilege. In the MIT krb5 +KDC, this privilege is determined by the **ok_to_auth_as_delegate** +bit on the intermediate service's principal entry, which can be +configured with :ref:`kadmin(1)`. + +Once the intermediate service has a proxy credential, it can simply +pass it to gss_init_sec_context_ as the *initiator_cred_handle* +parameter, and the desired service as the *target_name* parameter. +The GSSAPI library will present the krbtgt ticket and evidence ticket +in the proxy credential to the KDC in an S4U2Proxy request; if the +intermediate service has the appropriate permissions, the KDC will +issue a ticket from the client to the target service. The GSSAPI +library will then use this ticket to authenticate to the target +service. + + +AEAD message wrapping +--------------------- + +The following GSSAPI extensions (declared in +``<gssapi/gssapi_ext.h>``) can be used to wrap and unwrap messages +with additional "associated data" which is integrity-checked but is +not included in the output buffer:: + + OM_uint32 gss_wrap_aead(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + int conf_req_flag, gss_qop_t qop_req, + gss_buffer_t input_assoc_buffer, + gss_buffer_t input_payload_buffer, + int *conf_state, + gss_buffer_t output_message_buffer); + + OM_uint32 gss_unwrap_aead(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + gss_buffer_t input_message_buffer, + gss_buffer_t input_assoc_buffer, + gss_buffer_t output_payload_buffer, + int *conf_state, + gss_qop_t *qop_state); + +Wrap tokens created with gss_wrap_aead will successfully unwrap only +if the same *input_assoc_buffer* contents are presented to +gss_unwrap_aead. + + +IOV message wrapping +-------------------- + +The following extensions (declared in ``<gssapi/gssapi_ext.h>``) can +be used for in-place encryption, fine-grained control over wrap token +layout, and for constructing wrap tokens compatible with Microsoft DCE +RPC:: + + typedef struct gss_iov_buffer_desc_struct { + OM_uint32 type; + gss_buffer_desc buffer; + } gss_iov_buffer_desc, *gss_iov_buffer_t; + + OM_uint32 gss_wrap_iov(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + int conf_req_flag, gss_qop_t qop_req, + int *conf_state, + gss_iov_buffer_desc *iov, int iov_count); + + OM_uint32 gss_unwrap_iov(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + int *conf_state, gss_qop_t *qop_state, + gss_iov_buffer_desc *iov, int iov_count); + + OM_uint32 gss_wrap_iov_length(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + int conf_req_flag, + gss_qop_t qop_req, int *conf_state, + gss_iov_buffer_desc *iov, + int iov_count); + + OM_uint32 gss_release_iov_buffer(OM_uint32 *minor_status, + gss_iov_buffer_desc *iov, + int iov_count); + +The caller of gss_wrap_iov provides an array of gss_iov_buffer_desc +structures, each containing a type and a gss_buffer_desc structure. +Valid types include: + +* **GSS_C_BUFFER_TYPE_DATA**: A data buffer to be included in the + token, and to be encrypted or decrypted in-place if the token is + confidentiality-protected. + +* **GSS_C_BUFFER_TYPE_HEADER**: The GSSAPI wrap token header and + underlying cryptographic header. + +* **GSS_C_BUFFER_TYPE_TRAILER**: The cryptographic trailer, if one is + required. + +* **GSS_C_BUFFER_TYPE_PADDING**: Padding to be combined with the data + during encryption and decryption. (The implementation may choose to + place padding in the trailer buffer, in which case it will set the + padding buffer length to 0.) + +* **GSS_C_BUFFER_TYPE_STREAM**: For unwrapping only, a buffer + containing a complete wrap token in standard format to be unwrapped. + +* **GSS_C_BUFFER_TYPE_SIGN_ONLY**: A buffer to be included in the + token's integrity protection checksum, but not to be encrypted or + included in the token itself. + +For gss_wrap_iov, the IOV list should contain one HEADER buffer, +followed by zero or more SIGN_ONLY buffers, followed by one or more +DATA buffers, followed by a TRAILER buffer. The memory pointed to by +the buffers is not required to be contiguous or in any particular +order. If *conf_req_flag* is true, DATA buffers will be encrypted +in-place, while SIGN_ONLY buffers will not be modified. + +The type of an output buffer may be combined with +**GSS_C_BUFFER_FLAG_ALLOCATE** to request that gss_wrap_iov allocate +the buffer contents. If gss_wrap_iov allocates a buffer, it sets the +**GSS_C_BUFFER_FLAG_ALLOCATED** flag on the buffer type. +gss_release_iov_buffer can be used to release all allocated buffers +within an iov list and unset their allocated flags. Here is an +example of how gss_wrap_iov can be used with allocation requested +(*ctx* is assumed to be a previously established gss_ctx_id_t):: + + OM_uint32 major, minor; + gss_iov_buffer_desc iov[4]; + char str[] = "message"; + + iov[0].type = GSS_IOV_BUFFER_TYPE_HEADER | GSS_IOV_BUFFER_FLAG_ALLOCATE; + iov[1].type = GSS_IOV_BUFFER_TYPE_DATA; + iov[1].buffer.value = str; + iov[1].buffer.length = strlen(str); + iov[2].type = GSS_IOV_BUFFER_TYPE_PADDING | GSS_IOV_BUFFER_FLAG_ALLOCATE; + iov[3].type = GSS_IOV_BUFFER_TYPE_TRAILER | GSS_IOV_BUFFER_FLAG_ALLOCATE; + + major = gss_wrap_iov(&minor, ctx, 1, GSS_C_QOP_DEFAULT, NULL, + iov, 4); + if (GSS_ERROR(major)) + handle_error(major, minor); + + /* Transmit or otherwise use resulting buffers. */ + + (void)gss_release_iov_buffer(&minor, iov, 4); + +If the caller does not choose to request buffer allocation by +gss_wrap_iov, it should first call gss_wrap_iov_length to query the +lengths of the HEADER, PADDING, and TRAILER buffers. DATA buffers +must be provided in the iov list so that padding length can be +computed correctly, but the output buffers need not be initialized. +Here is an example of using gss_wrap_iov_length and gss_wrap_iov:: + + OM_uint32 major, minor; + gss_iov_buffer_desc iov[4]; + char str[1024] = "message", *ptr; + + iov[0].type = GSS_IOV_BUFFER_TYPE_HEADER; + iov[1].type = GSS_IOV_BUFFER_TYPE_DATA; + iov[1].buffer.value = str; + iov[1].buffer.length = strlen(str); + + iov[2].type = GSS_IOV_BUFFER_TYPE_PADDING; + iov[3].type = GSS_IOV_BUFFER_TYPE_TRAILER; + + major = gss_wrap_iov_length(&minor, ctx, 1, GSS_C_QOP_DEFAULT, + NULL, iov, 4); + if (GSS_ERROR(major)) + handle_error(major, minor); + if (strlen(str) + iov[0].buffer.length + iov[2].buffer.length + + iov[3].buffer.length > sizeof(str)) + handle_out_of_space_error(); + ptr = str + strlen(str); + iov[0].buffer.value = ptr; + ptr += iov[0].buffer.length; + iov[2].buffer.value = ptr; + ptr += iov[2].buffer.length; + iov[3].buffer.value = ptr; + + major = gss_wrap_iov(&minor, ctx, 1, GSS_C_QOP_DEFAULT, NULL, + iov, 4); + if (GSS_ERROR(major)) + handle_error(major, minor); + +If the context was established using the **GSS_C_DCE_STYLE** flag +(described in :rfc:`4757`), wrap tokens compatible with Microsoft DCE +RPC can be constructed. In this case, the IOV list must include a +SIGN_ONLY buffer, a DATA buffer, a second SIGN_ONLY buffer, and a +HEADER buffer in that order (the order of the buffer contents remains +arbitrary). The application must pad the DATA buffer to a multiple of +16 bytes as no padding or trailer buffer is used. + +gss_unwrap_iov may be called with an IOV list just like one which +would be provided to gss_wrap_iov. DATA buffers will be decrypted +in-place if they were encrypted, and SIGN_ONLY buffers will not be +modified. + +Alternatively, gss_unwrap_iov may be called with a single STREAM +buffer, zero or more SIGN_ONLY buffers, and a single DATA buffer. The +STREAM buffer is interpreted as a complete wrap token. The STREAM +buffer will be modified in-place to decrypt its contents. The DATA +buffer will be initialized to point to the decrypted data within the +STREAM buffer, unless it has the **GSS_C_BUFFER_FLAG_ALLOCATE** flag +set, in which case it will be initialized with a copy of the decrypted +data. Here is an example (*token* and *token_len* are assumed to be a +pre-existing pointer and length for a modifiable region of data):: + + OM_uint32 major, minor; + gss_iov_buffer_desc iov[2]; + + iov[0].type = GSS_IOV_BUFFER_TYPE_STREAM; + iov[0].buffer.value = token; + iov[0].buffer.length = token_len; + iov[1].type = GSS_IOV_BUFFER_TYPE_DATA; + major = gss_unwrap_iov(&minor, ctx, NULL, NULL, iov, 2); + if (GSS_ERROR(major)) + handle_error(major, minor); + + /* Decrypted data is in iov[1].buffer, pointing to a subregion of + * token. */ + +.. _gssapi_mic_token: + +IOV MIC tokens +-------------- + +The following extensions (declared in ``<gssapi/gssapi_ext.h>``) can +be used in release 1.12 or later to construct and verify MIC tokens +using an IOV list:: + + OM_uint32 gss_get_mic_iov(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + gss_qop_t qop_req, + gss_iov_buffer_desc *iov, + int iov_count); + + OM_uint32 gss_get_mic_iov_length(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + gss_qop_t qop_req, + gss_iov_buffer_desc *iov, + iov_count); + + OM_uint32 gss_verify_mic_iov(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + gss_qop_t *qop_state, + gss_iov_buffer_desc *iov, + int iov_count); + +The caller of gss_get_mic_iov provides an array of gss_iov_buffer_desc +structures, each containing a type and a gss_buffer_desc structure. +Valid types include: + +* **GSS_C_BUFFER_TYPE_DATA** and **GSS_C_BUFFER_TYPE_SIGN_ONLY**: The + corresponding buffer for each of these types will be signed for the + MIC token, in the order provided. + +* **GSS_C_BUFFER_TYPE_MIC_TOKEN**: The GSSAPI MIC token. + +The type of the MIC_TOKEN buffer may be combined with +**GSS_C_BUFFER_FLAG_ALLOCATE** to request that gss_get_mic_iov +allocate the buffer contents. If gss_get_mic_iov allocates the +buffer, it sets the **GSS_C_BUFFER_FLAG_ALLOCATED** flag on the buffer +type. gss_release_iov_buffer can be used to release all allocated +buffers within an iov list and unset their allocated flags. Here is +an example of how gss_get_mic_iov can be used with allocation +requested (*ctx* is assumed to be a previously established +gss_ctx_id_t):: + + OM_uint32 major, minor; + gss_iov_buffer_desc iov[3]; + + iov[0].type = GSS_IOV_BUFFER_TYPE_DATA; + iov[0].buffer.value = "sign1"; + iov[0].buffer.length = 5; + iov[1].type = GSS_IOV_BUFFER_TYPE_SIGN_ONLY; + iov[1].buffer.value = "sign2"; + iov[1].buffer.length = 5; + iov[2].type = GSS_IOV_BUFFER_TYPE_MIC_TOKEN | GSS_IOV_BUFFER_FLAG_ALLOCATE; + + major = gss_get_mic_iov(&minor, ctx, GSS_C_QOP_DEFAULT, iov, 3); + if (GSS_ERROR(major)) + handle_error(major, minor); + + /* Transmit or otherwise use iov[2].buffer. */ + + (void)gss_release_iov_buffer(&minor, iov, 3); + +If the caller does not choose to request buffer allocation by +gss_get_mic_iov, it should first call gss_get_mic_iov_length to query +the length of the MIC_TOKEN buffer. Here is an example of using +gss_get_mic_iov_length and gss_get_mic_iov:: + + OM_uint32 major, minor; + gss_iov_buffer_desc iov[2]; + char data[1024]; + + iov[0].type = GSS_IOV_BUFFER_TYPE_MIC_TOKEN; + iov[1].type = GSS_IOV_BUFFER_TYPE_DATA; + iov[1].buffer.value = "message"; + iov[1].buffer.length = 7; + + major = gss_wrap_iov_length(&minor, ctx, 1, GSS_C_QOP_DEFAULT, + NULL, iov, 2); + if (GSS_ERROR(major)) + handle_error(major, minor); + if (iov[0].buffer.length > sizeof(data)) + handle_out_of_space_error(); + iov[0].buffer.value = data; + + major = gss_wrap_iov(&minor, ctx, 1, GSS_C_QOP_DEFAULT, NULL, + iov, 2); + if (GSS_ERROR(major)) + handle_error(major, minor); + + +.. _gss_accept_sec_context: http://tools.ietf.org/html/rfc2744.html#section-5.1 +.. _gss_acquire_cred: http://tools.ietf.org/html/rfc2744.html#section-5.2 +.. _gss_export_name: http://tools.ietf.org/html/rfc2744.html#section-5.13 +.. _gss_get_name_attribute: http://tools.ietf.org/html/6680.html#section-7.5 +.. _gss_import_name: http://tools.ietf.org/html/rfc2744.html#section-5.16 +.. _gss_init_sec_context: http://tools.ietf.org/html/rfc2744.html#section-5.19 +.. _gss_inquire_name: http://tools.ietf.org/html/rfc6680.txt#section-7.4 +.. _gss_inquire_cred: http://tools.ietf.org/html/rfc2744.html#section-5.21 diff --git a/doc/appdev/h5l_mit_apidiff.rst b/doc/appdev/h5l_mit_apidiff.rst new file mode 100644 index 000000000000..0ea5e32efc28 --- /dev/null +++ b/doc/appdev/h5l_mit_apidiff.rst @@ -0,0 +1,31 @@ +Differences between Heimdal and MIT Kerberos API +================================================ + +.. tabularcolumns:: |l|l| + +.. table:: + + ======================================== ================================================= + :c:func:`krb5_auth_con_getaddrs()` H5l: If either of the pointers to local_addr + and remote_addr is not NULL, it is freed + first and then reallocated before being + populated with the content of corresponding + address from authentication context. + :c:func:`krb5_auth_con_setaddrs()` H5l: If either address is NULL, the previous + address remains in place + :c:func:`krb5_auth_con_setports()` H5l: Not implemented as of version 1.3.3 + :c:func:`krb5_auth_con_setrecvsubkey()` H5l: If either port is NULL, the previous + port remains in place + :c:func:`krb5_auth_con_setsendsubkey()` H5l: Not implemented as of version 1.3.3 + :c:func:`krb5_cc_set_config()` MIT: Before version 1.10 it was assumed that + the last argument *data* is ALWAYS non-zero. + :c:func:`krb5_cccol_last_change_time()` H5l takes 3 arguments: krb5_context context, + const char \*type, krb5_timestamp \*change_time + MIT takes two arguments: krb5_context context, + krb5_timestamp \*change_time + :c:func:`krb5_set_default_realm()` H5l: Caches the computed default realm context + field. If the second argument is NULL, + it tries to retrieve it from libdefaults or DNS. + MIT: Computes the default realm each time + if it wasn't explicitly set in the context + ======================================== ================================================= diff --git a/doc/appdev/index.rst b/doc/appdev/index.rst new file mode 100644 index 000000000000..3d62045ca870 --- /dev/null +++ b/doc/appdev/index.rst @@ -0,0 +1,15 @@ +For application developers +========================== + +.. toctree:: + :maxdepth: 1 + + gssapi.rst + h5l_mit_apidiff.rst + init_creds.rst + princ_handle.rst + +.. toctree:: + :maxdepth: 1 + + refs/index.rst diff --git a/doc/appdev/init_creds.rst b/doc/appdev/init_creds.rst new file mode 100644 index 000000000000..5c3c0a87c5da --- /dev/null +++ b/doc/appdev/init_creds.rst @@ -0,0 +1,304 @@ +Initial credentials +=================== + +Software that performs tasks such as logging users into a computer +when they type their Kerberos password needs to get initial +credentials (usually ticket granting tickets) from Kerberos. Such +software shares some behavior with the :ref:`kinit(1)` program. + +Whenever a program grants access to a resource (such as a local login +session on a desktop computer) based on a user successfully getting +initial Kerberos credentials, it must verify those credentials against +a secure shared secret (e.g., a host keytab) to ensure that the user +credentials actually originate from a legitimate KDC. Failure to +perform this verification is a critical vulnerability, because a +malicious user can execute the "Zanarotti attack": the user constructs +a fake response that appears to come from the legitimate KDC, but +whose contents come from an attacker-controlled KDC. + +Some applications read a Kerberos password over the network (ideally +over a secure channel), which they then verify against the KDC. While +this technique may be the only practical way to integrate Kerberos +into some existing legacy systems, its use is contrary to the original +design goals of Kerberos. + +The function :c:func:`krb5_get_init_creds_password` will get initial +credentials for a client using a password. An application that needs +to verify the credentials can call :c:func:`krb5_verify_init_creds`. +Here is an example of code to obtain and verify TGT credentials, given +strings *princname* and *password* for the client principal name and +password:: + + krb5_error_code ret; + krb5_creds creds; + krb5_principal client_princ = NULL; + + memset(&creds, 0, sizeof(creds)); + ret = krb5_parse_name(context, princname, &client_princ); + if (ret) + goto cleanup; + ret = krb5_get_init_creds_password(context, &creds, client_princ, + password, NULL, NULL, 0, NULL, NULL); + if (ret) + goto cleanup; + ret = krb5_verify_init_creds(context, &creds, NULL, NULL, NULL, NULL); + + cleanup: + krb5_free_principal(context, client_princ); + krb5_free_cred_contents(context, &creds); + return ret; + +Options for get_init_creds +-------------------------- + +The function :c:func:`krb5_get_init_creds_password` takes an options +parameter (which can be a null pointer). Use the function +:c:func:`krb5_get_init_creds_opt_alloc` to allocate an options +structure, and :c:func:`krb5_get_init_creds_opt_free` to free it. For +example:: + + krb5_error_code ret; + krb5_get_init_creds_opt *opt = NULL; + krb5_creds creds; + + memset(&creds, 0, sizeof(creds)); + ret = krb5_get_init_creds_opt_alloc(context, &opt); + if (ret) + goto cleanup; + krb5_get_init_creds_opt_set_tkt_life(opt, 24 * 60 * 60); + ret = krb5_get_init_creds_password(context, &creds, client_princ, + password, NULL, NULL, 0, NULL, opt); + if (ret) + goto cleanup; + + cleanup: + krb5_get_init_creds_opt_free(context, opt); + krb5_free_cred_contents(context, &creds); + return ret; + +Getting anonymous credentials +----------------------------- + +As of release 1.8, it is possible to obtain fully anonymous or +partially anonymous (realm-exposed) credentials, if the KDC supports +it. The MIT KDC supports issuing fully anonymous credentials as of +release 1.8 if configured appropriately (see :ref:`anonymous_pkinit`), +but does not support issuing realm-exposed anonymous credentials at +this time. + +To obtain fully anonymous credentials, call +:c:func:`krb5_get_init_creds_opt_set_anonymous` on the options +structure to set the anonymous flag, and specify a client principal +with the KDC's realm and a single empty data component (the principal +obtained by parsing ``@``\ *realmname*). Authentication will take +place using anonymous PKINIT; if successful, the client principal of +the resulting tickets will be +``WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS``. Here is an example:: + + krb5_get_init_creds_opt_set_anonymous(opt, 1); + ret = krb5_build_principal(context, &client_princ, strlen(myrealm), + myrealm, "", (char *)NULL); + if (ret) + goto cleanup; + ret = krb5_get_init_creds_password(context, &creds, client_princ, + password, NULL, NULL, 0, NULL, opt); + if (ret) + goto cleanup; + +To obtain realm-exposed anonymous credentials, set the anonymous flag +on the options structure as above, but specify a normal client +principal in order to prove membership in the realm. Authentication +will take place as it normally does; if successful, the client +principal of the resulting tickets will be ``WELLKNOWN/ANONYMOUS@``\ +*realmname*. + +User interaction +---------------- + +Authenticating a user usually requires the entry of secret +information, such as a password. A password can be supplied directly +to :c:func:`krb5_get_init_creds_password` via the *password* +parameter, or the application can supply prompter and/or responder +callbacks instead. If callbacks are used, the user can also be +queried for other secret information such as a PIN, informed of +impending password expiration, or prompted to change a password which +has expired. + +Prompter callback +~~~~~~~~~~~~~~~~~ + +A prompter callback can be specified via the *prompter* and *data* +parameters to :c:func:`krb5_get_init_creds_password`. The prompter +will be invoked each time the krb5 library has a question to ask or +information to present. When the prompter callback is invoked, the +*banner* argument (if not null) is intended to be displayed to the +user, and the questions to be answered are specified in the *prompts* +array. Each prompt contains a text question in the *prompt* field, a +*hidden* bit to indicate whether the answer should be hidden from +display, and a storage area for the answer in the *reply* field. The +callback should fill in each question's ``reply->data`` with the +answer, up to a maximum number of ``reply->length`` bytes, and then +reset ``reply->length`` to the length of the answer. + +A prompter callback can call :c:func:`krb5_get_prompt_types` to get an +array of type constants corresponding to the prompts, to get +programmatic information about the semantic meaning of the questions. +:c:func:`krb5_get_prompt_types` may return a null pointer if no prompt +type information is available. + +Text-based applications can use a built-in text prompter +implementation by supplying :c:func:`krb5_prompter_posix` as the +*prompter* parameter and a null pointer as the *data* parameter. For +example:: + + ret = krb5_get_init_creds_password(context, &creds, client_princ, + NULL, krb5_prompter_posix, NULL, 0, + NULL, NULL); + +Responder callback +~~~~~~~~~~~~~~~~~~ + +A responder callback can be specified through the init_creds options +using the :c:func:`krb5_get_init_creds_opt_set_responder` function. +Responder callbacks can present a more sophisticated user interface +for authentication secrets. The responder callback is usually invoked +only once per authentication, with a list of questions produced by all +of the allowed preauthentication mechanisms. + +When the responder callback is invoked, the *rctx* argument can be +accessed to obtain the list of questions and to answer them. The +:c:func:`krb5_responder_list_questions` function retrieves an array of +question types. For each question type, the +:c:func:`krb5_responder_get_challenge` function retrieves additional +information about the question, if applicable, and the +:c:func:`krb5_responder_set_answer` function sets the answer. + +Responder question types, challenges, and answers are UTF-8 strings. +The question type is a well-known string; the meaning of the challenge +and answer depend on the question type. If an application does not +understand a question type, it cannot interpret the challenge or +provide an answer. Failing to answer a question typically results in +the prompter callback being used as a fallback. + +Password question +################# + +The :c:macro:`KRB5_RESPONDER_QUESTION_PASSWORD` (or ``"password"``) +question type requests the user's password. This question does not +have a challenge, and the response is simply the password string. + +One-time password question +########################## + +The :c:macro:`KRB5_RESPONDER_QUESTION_OTP` (or ``"otp"``) question +type requests a choice among one-time password tokens and the PIN and +value for the chosen token. The challenge and answer are JSON-encoded +strings, but an application can use convenience functions to avoid +doing any JSON processing itself. + +The :c:func:`krb5_responder_otp_get_challenge` function decodes the +challenge into a krb5_responder_otp_challenge structure. The +:c:func:`krb5_responder_otp_set_answer` function selects one of the +token information elements from the challenge and supplies the value +and pin for that token. + +PKINIT password or PIN question +############################### + +The :c:macro:`KRB5_RESPONDER_QUESTION_PKINIT` (or ``"pkinit"``) question +type requests PINs for hardware devices and/or passwords for encrypted +credentials which are stored on disk, potentially also supplying +information about the state of the hardware devices. The challenge and +answer are JSON-encoded strings, but an application can use convenience +functions to avoid doing any JSON processing itself. + +The :c:func:`krb5_responder_pkinit_get_challenge` function decodes the +challenges into a krb5_responder_pkinit_challenge structure. The +:c:func:`krb5_responder_pkinit_set_answer` function can be used to +supply the PIN or password for a particular client credential, and can +be called multiple times. + +Example +####### + +Here is an example of using a responder callback:: + + static krb5_error_code + my_responder(krb5_context context, void *data, + krb5_responder_context rctx) + { + krb5_error_code ret; + krb5_responder_otp_challenge *chl; + + if (krb5_responder_get_challenge(context, rctx, + KRB5_RESPONDER_QUESTION_PASSWORD)) { + ret = krb5_responder_set_answer(context, rctx, + KRB5_RESPONDER_QUESTION_PASSWORD, + "open sesame"); + if (ret) + return ret; + } + ret = krb5_responder_otp_get_challenge(context, rctx, &chl); + if (ret == 0 && chl != NULL) { + ret = krb5_responder_otp_set_answer(context, rctx, 0, "1234", + NULL); + krb5_responder_otp_challenge_free(context, rctx, chl); + if (ret) + return ret; + } + return 0; + } + + static krb5_error_code + get_creds(krb5_context context, krb5_principal client_princ) + { + krb5_error_code ret; + krb5_get_init_creds_opt *opt = NULL; + krb5_creds creds; + + memset(&creds, 0, sizeof(creds)); + ret = krb5_get_init_creds_opt_alloc(context, &opt); + if (ret) + goto cleanup; + ret = krb5_get_init_creds_opt_set_responder(context, opt, my_responder, + NULL); + if (ret) + goto cleanup; + ret = krb5_get_init_creds_password(context, &creds, client_princ, + NULL, NULL, NULL, 0, NULL, opt); + + cleanup: + krb5_get_init_creds_opt_free(context, opt); + krb5_free_cred_contents(context, &creds); + return ret; + } + +Verifying initial credentials +----------------------------- + +Use the function :c:func:`krb5_verify_init_creds` to verify initial +credentials. It takes an options structure (which can be a null +pointer). Use :c:func:`krb5_verify_init_creds_opt_init` to initialize +the caller-allocated options structure, and +:c:func:`krb5_verify_init_creds_opt_set_ap_req_nofail` to set the +"nofail" option. For example:: + + krb5_verify_init_creds_opt vopt; + + krb5_verify_init_creds_opt_init(&vopt); + krb5_verify_init_creds_opt_set_ap_req_nofail(&vopt, 1); + ret = krb5_verify_init_creds(context, &creds, NULL, NULL, NULL, &vopt); + +The confusingly named "nofail" option, when set, means that the +verification must actually succeed in order for +:c:func:`krb5_verify_init_creds` to indicate success. The default +state of this option (cleared) means that if there is no key material +available to verify the user credentials, the verification will +succeed anyway. (The default can be changed by a configuration file +setting.) + +This accommodates a use case where a large number of unkeyed shared +desktop workstations need to allow users to log in using Kerberos. +The security risks from this practice are mitigated by the absence of +valuable state on the shared workstations---any valuable resources +that the users would access reside on networked servers. diff --git a/doc/appdev/princ_handle.rst b/doc/appdev/princ_handle.rst new file mode 100644 index 000000000000..455f00a4b6e7 --- /dev/null +++ b/doc/appdev/princ_handle.rst @@ -0,0 +1,79 @@ +Principal manipulation and parsing +================================== + +Kerberos principal structure + +.. + +:c:type:`krb5_principal_data` + +:c:type:`krb5_principal` + +.. + +Create and free principal + +.. + +:c:func:`krb5_build_principal()` + +:c:func:`krb5_build_principal_alloc_va()` + +:c:func:`krb5_build_principal_ext()` + +:c:func:`krb5_copy_principal()` + +:c:func:`krb5_free_principal()` + +:c:func:`krb5_cc_get_principal()` + +.. + +Comparing + +.. + +:c:func:`krb5_principal_compare()` + +:c:func:`krb5_principal_compare_flags()` + +:c:func:`krb5_principal_compare_any_realm()` + +:c:func:`krb5_sname_match()` + +:c:func:`krb5_sname_to_principal()` + +.. + + +Parsing: + +.. + +:c:func:`krb5_parse_name()` + +:c:func:`krb5_parse_name_flags()` + +:c:func:`krb5_unparse_name()` + +:c:func:`krb5_unparse_name_flags()` + +.. + +Utilities: + +.. + +:c:func:`krb5_is_config_principal()` + +:c:func:`krb5_kuserok()` + +:c:func:`krb5_set_password()` + +:c:func:`krb5_set_password_using_ccache()` + +:c:func:`krb5_set_principal_realm()` + +:c:func:`krb5_realm_compare()` + +.. diff --git a/doc/appdev/refs/api/index.rst b/doc/appdev/refs/api/index.rst new file mode 100644 index 000000000000..f2f27fe72ea2 --- /dev/null +++ b/doc/appdev/refs/api/index.rst @@ -0,0 +1,411 @@ +krb5 API +======== + + +Frequently used public interfaces +---------------------------------- + +.. toctree:: + :maxdepth: 1 + + krb5_build_principal.rst + krb5_build_principal_alloc_va.rst + krb5_build_principal_ext.rst + krb5_cc_close.rst + krb5_cc_default.rst + krb5_cc_default_name.rst + krb5_cc_destroy.rst + krb5_cc_dup.rst + krb5_cc_get_name.rst + krb5_cc_get_principal.rst + krb5_cc_get_type.rst + krb5_cc_initialize.rst + krb5_cc_new_unique.rst + krb5_cc_resolve.rst + krb5_change_password.rst + krb5_chpw_message.rst + krb5_expand_hostname.rst + krb5_free_context.rst + krb5_free_error_message.rst + krb5_free_principal.rst + krb5_fwd_tgt_creds.rst + krb5_get_default_realm.rst + krb5_get_error_message.rst + krb5_get_host_realm.rst + krb5_get_credentials.rst + krb5_get_fallback_host_realm.rst + krb5_get_init_creds_keytab.rst + krb5_get_init_creds_opt_alloc.rst + krb5_get_init_creds_opt_free.rst + krb5_get_init_creds_opt_get_fast_flags.rst + krb5_get_init_creds_opt_set_address_list.rst + krb5_get_init_creds_opt_set_anonymous.rst + krb5_get_init_creds_opt_set_canonicalize.rst + krb5_get_init_creds_opt_set_change_password_prompt.rst + krb5_get_init_creds_opt_set_etype_list.rst + krb5_get_init_creds_opt_set_expire_callback.rst + krb5_get_init_creds_opt_set_fast_ccache.rst + krb5_get_init_creds_opt_set_fast_ccache_name.rst + krb5_get_init_creds_opt_set_fast_flags.rst + krb5_get_init_creds_opt_set_forwardable.rst + krb5_get_init_creds_opt_set_in_ccache.rst + krb5_get_init_creds_opt_set_out_ccache.rst + krb5_get_init_creds_opt_set_pa.rst + krb5_get_init_creds_opt_set_pac_request.rst + krb5_get_init_creds_opt_set_preauth_list.rst + krb5_get_init_creds_opt_set_proxiable.rst + krb5_get_init_creds_opt_set_renew_life.rst + krb5_get_init_creds_opt_set_responder.rst + krb5_get_init_creds_opt_set_salt.rst + krb5_get_init_creds_opt_set_tkt_life.rst + krb5_get_init_creds_password.rst + krb5_get_profile.rst + krb5_get_prompt_types.rst + krb5_get_renewed_creds.rst + krb5_get_validated_creds.rst + krb5_init_context.rst + krb5_init_secure_context.rst + krb5_is_config_principal.rst + krb5_is_thread_safe.rst + krb5_kt_close.rst + krb5_kt_client_default.rst + krb5_kt_default.rst + krb5_kt_default_name.rst + krb5_kt_dup.rst + krb5_kt_get_name.rst + krb5_kt_get_type.rst + krb5_kt_resolve.rst + krb5_kuserok.rst + krb5_parse_name.rst + krb5_parse_name_flags.rst + krb5_principal_compare.rst + krb5_principal_compare_any_realm.rst + krb5_principal_compare_flags.rst + krb5_prompter_posix.rst + krb5_realm_compare.rst + krb5_responder_get_challenge.rst + krb5_responder_list_questions.rst + krb5_responder_set_answer.rst + krb5_responder_otp_get_challenge.rst + krb5_responder_otp_set_answer.rst + krb5_responder_otp_challenge_free.rst + krb5_responder_pkinit_get_challenge.rst + krb5_responder_pkinit_set_answer.rst + krb5_responder_pkinit_challenge_free.rst + krb5_set_default_realm.rst + krb5_set_password.rst + krb5_set_password_using_ccache.rst + krb5_set_principal_realm.rst + krb5_set_trace_callback.rst + krb5_set_trace_filename.rst + krb5_sname_match.rst + krb5_sname_to_principal.rst + krb5_unparse_name.rst + krb5_unparse_name_ext.rst + krb5_unparse_name_flags.rst + krb5_unparse_name_flags_ext.rst + krb5_us_timeofday.rst + krb5_verify_authdata_kdc_issued.rst + +Rarely used public interfaces +-------------------------------- + +.. toctree:: + :maxdepth: 1 + + krb5_425_conv_principal.rst + krb5_524_conv_principal.rst + krb5_address_compare.rst + krb5_address_order.rst + krb5_address_search.rst + krb5_allow_weak_crypto.rst + krb5_aname_to_localname.rst + krb5_anonymous_principal.rst + krb5_anonymous_realm.rst + krb5_appdefault_boolean.rst + krb5_appdefault_string.rst + krb5_auth_con_free.rst + krb5_auth_con_genaddrs.rst + krb5_auth_con_get_checksum_func.rst + krb5_auth_con_getaddrs.rst + krb5_auth_con_getauthenticator.rst + krb5_auth_con_getflags.rst + krb5_auth_con_getkey.rst + krb5_auth_con_getkey_k.rst + krb5_auth_con_getlocalseqnumber.rst + krb5_auth_con_getrcache.rst + krb5_auth_con_getrecvsubkey.rst + krb5_auth_con_getrecvsubkey_k.rst + krb5_auth_con_getremoteseqnumber.rst + krb5_auth_con_getsendsubkey.rst + krb5_auth_con_getsendsubkey_k.rst + krb5_auth_con_init.rst + krb5_auth_con_set_checksum_func.rst + krb5_auth_con_set_req_cksumtype.rst + krb5_auth_con_setaddrs.rst + krb5_auth_con_setflags.rst + krb5_auth_con_setports.rst + krb5_auth_con_setrcache.rst + krb5_auth_con_setrecvsubkey.rst + krb5_auth_con_setrecvsubkey_k.rst + krb5_auth_con_setsendsubkey.rst + krb5_auth_con_setsendsubkey_k.rst + krb5_auth_con_setuseruserkey.rst + krb5_cc_cache_match.rst + krb5_cc_copy_creds.rst + krb5_cc_end_seq_get.rst + krb5_cc_get_config.rst + krb5_cc_get_flags.rst + krb5_cc_get_full_name.rst + krb5_cc_last_change_time.rst + krb5_cc_lock.rst + krb5_cc_move.rst + krb5_cc_next_cred.rst + krb5_cc_remove_cred.rst + krb5_cc_retrieve_cred.rst + krb5_cc_select.rst + krb5_cc_set_config.rst + krb5_cc_set_default_name.rst + krb5_cc_set_flags.rst + krb5_cc_start_seq_get.rst + krb5_cc_store_cred.rst + krb5_cc_support_switch.rst + krb5_cc_switch.rst + krb5_cc_unlock.rst + krb5_cccol_cursor_free.rst + krb5_cccol_cursor_new.rst + krb5_cccol_cursor_next.rst + krb5_cccol_have_content.rst + krb5_cccol_last_change_time.rst + krb5_cccol_lock.rst + krb5_cccol_unlock.rst + krb5_clear_error_message.rst + krb5_check_clockskew.rst + krb5_copy_addresses.rst + krb5_copy_authdata.rst + krb5_copy_authenticator.rst + krb5_copy_checksum.rst + krb5_copy_context.rst + krb5_copy_creds.rst + krb5_copy_data.rst + krb5_copy_error_message.rst + krb5_copy_keyblock.rst + krb5_copy_keyblock_contents.rst + krb5_copy_principal.rst + krb5_copy_ticket.rst + krb5_find_authdata.rst + krb5_free_addresses.rst + krb5_free_ap_rep_enc_part.rst + krb5_free_authdata.rst + krb5_free_authenticator.rst + krb5_free_cred_contents.rst + krb5_free_creds.rst + krb5_free_data.rst + krb5_free_data_contents.rst + krb5_free_default_realm.rst + krb5_free_enctypes.rst + krb5_free_error.rst + krb5_free_host_realm.rst + krb5_free_keyblock.rst + krb5_free_keyblock_contents.rst + krb5_free_keytab_entry_contents.rst + krb5_free_string.rst + krb5_free_ticket.rst + krb5_free_unparsed_name.rst + krb5_get_permitted_enctypes.rst + krb5_get_server_rcache.rst + krb5_get_time_offsets.rst + krb5_init_context_profile.rst + krb5_init_creds_free.rst + krb5_init_creds_get.rst + krb5_init_creds_get_creds.rst + krb5_init_creds_get_error.rst + krb5_init_creds_get_times.rst + krb5_init_creds_init.rst + krb5_init_creds_set_keytab.rst + krb5_init_creds_set_password.rst + krb5_init_creds_set_service.rst + krb5_init_creds_step.rst + krb5_init_keyblock.rst + krb5_is_referral_realm.rst + krb5_kt_add_entry.rst + krb5_kt_end_seq_get.rst + krb5_kt_get_entry.rst + krb5_kt_have_content.rst + krb5_kt_next_entry.rst + krb5_kt_read_service_key.rst + krb5_kt_remove_entry.rst + krb5_kt_start_seq_get.rst + krb5_make_authdata_kdc_issued.rst + krb5_merge_authdata.rst + krb5_mk_1cred.rst + krb5_mk_error.rst + krb5_mk_ncred.rst + krb5_mk_priv.rst + krb5_mk_rep.rst + krb5_mk_rep_dce.rst + krb5_mk_req.rst + krb5_mk_req_extended.rst + krb5_mk_safe.rst + krb5_os_localaddr.rst + krb5_pac_add_buffer.rst + krb5_pac_free.rst + krb5_pac_get_buffer.rst + krb5_pac_get_types.rst + krb5_pac_init.rst + krb5_pac_parse.rst + krb5_pac_sign.rst + krb5_pac_verify.rst + krb5_prepend_error_message.rst + krb5_principal2salt.rst + krb5_rd_cred.rst + krb5_rd_error.rst + krb5_rd_priv.rst + krb5_rd_rep.rst + krb5_rd_rep_dce.rst + krb5_rd_req.rst + krb5_rd_safe.rst + krb5_read_password.rst + krb5_salttype_to_string.rst + krb5_server_decrypt_ticket_keytab.rst + krb5_set_default_tgs_enctypes.rst + krb5_set_error_message.rst + krb5_set_kdc_recv_hook.rst + krb5_set_kdc_send_hook.rst + krb5_set_real_time.rst + krb5_string_to_cksumtype.rst + krb5_string_to_deltat.rst + krb5_string_to_enctype.rst + krb5_string_to_salttype.rst + krb5_string_to_timestamp.rst + krb5_timeofday.rst + krb5_timestamp_to_sfstring.rst + krb5_timestamp_to_string.rst + krb5_tkt_creds_free.rst + krb5_tkt_creds_get.rst + krb5_tkt_creds_get_creds.rst + krb5_tkt_creds_get_times.rst + krb5_tkt_creds_init.rst + krb5_tkt_creds_step.rst + krb5_verify_init_creds.rst + krb5_verify_init_creds_opt_init.rst + krb5_verify_init_creds_opt_set_ap_req_nofail.rst + krb5_vprepend_error_message.rst + krb5_vset_error_message.rst + krb5_vwrap_error_message.rst + krb5_wrap_error_message.rst + + +Public interfaces that should not be called directly +------------------------------------------------------- + +.. toctree:: + :maxdepth: 1 + + krb5_c_block_size.rst + krb5_c_checksum_length.rst + krb5_c_crypto_length.rst + krb5_c_crypto_length_iov.rst + krb5_c_decrypt.rst + krb5_c_decrypt_iov.rst + krb5_c_derive_prfplus.rst + krb5_c_encrypt.rst + krb5_c_encrypt_iov.rst + krb5_c_encrypt_length.rst + krb5_c_enctype_compare.rst + krb5_c_free_state.rst + krb5_c_fx_cf2_simple.rst + krb5_c_init_state.rst + krb5_c_is_coll_proof_cksum.rst + krb5_c_is_keyed_cksum.rst + krb5_c_keyed_checksum_types.rst + krb5_c_keylengths.rst + krb5_c_make_checksum.rst + krb5_c_make_checksum_iov.rst + krb5_c_make_random_key.rst + krb5_c_padding_length.rst + krb5_c_prf.rst + krb5_c_prfplus.rst + krb5_c_prf_length.rst + krb5_c_random_add_entropy.rst + krb5_c_random_make_octets.rst + krb5_c_random_os_entropy.rst + krb5_c_random_to_key.rst + krb5_c_string_to_key.rst + krb5_c_string_to_key_with_params.rst + krb5_c_valid_cksumtype.rst + krb5_c_valid_enctype.rst + krb5_c_verify_checksum.rst + krb5_c_verify_checksum_iov.rst + krb5_cksumtype_to_string.rst + krb5_decode_authdata_container.rst + krb5_decode_ticket.rst + krb5_deltat_to_string.rst + krb5_encode_authdata_container.rst + krb5_enctype_to_name.rst + krb5_enctype_to_string.rst + krb5_free_checksum.rst + krb5_free_checksum_contents.rst + krb5_free_cksumtypes.rst + krb5_free_tgt_creds.rst + krb5_k_create_key.rst + krb5_k_decrypt.rst + krb5_k_decrypt_iov.rst + krb5_k_encrypt.rst + krb5_k_encrypt_iov.rst + krb5_k_free_key.rst + krb5_k_key_enctype.rst + krb5_k_key_keyblock.rst + krb5_k_make_checksum.rst + krb5_k_make_checksum_iov.rst + krb5_k_prf.rst + krb5_k_reference_key.rst + krb5_k_verify_checksum.rst + krb5_k_verify_checksum_iov.rst + + +Legacy convenience interfaces +------------------------------ + +.. toctree:: + :maxdepth: 1 + + krb5_recvauth.rst + krb5_recvauth_version.rst + krb5_sendauth.rst + + +Deprecated public interfaces +------------------------------ + +.. toctree:: + :maxdepth: 1 + + krb5_524_convert_creds.rst + krb5_auth_con_getlocalsubkey.rst + krb5_auth_con_getremotesubkey.rst + krb5_auth_con_initivector.rst + krb5_build_principal_va.rst + krb5_c_random_seed.rst + krb5_calculate_checksum.rst + krb5_checksum_size.rst + krb5_encrypt.rst + krb5_decrypt.rst + krb5_eblock_enctype.rst + krb5_encrypt_size.rst + krb5_finish_key.rst + krb5_finish_random_key.rst + krb5_cc_gen_new.rst + krb5_get_credentials_renew.rst + krb5_get_credentials_validate.rst + krb5_get_in_tkt_with_password.rst + krb5_get_in_tkt_with_skey.rst + krb5_get_in_tkt_with_keytab.rst + krb5_get_init_creds_opt_init.rst + krb5_init_random_key.rst + krb5_kt_free_entry.rst + krb5_random_key.rst + krb5_process_key.rst + krb5_string_to_key.rst + krb5_use_enctype.rst + krb5_verify_checksum.rst diff --git a/doc/appdev/refs/index.rst b/doc/appdev/refs/index.rst new file mode 100644 index 000000000000..37a895f3bee4 --- /dev/null +++ b/doc/appdev/refs/index.rst @@ -0,0 +1,9 @@ +Complete reference - API and datatypes +====================================== + +.. toctree:: + :maxdepth: 1 + + api/index.rst + types/index.rst + macros/index.rst diff --git a/doc/appdev/refs/macros/index.rst b/doc/appdev/refs/macros/index.rst new file mode 100644 index 000000000000..e76747102576 --- /dev/null +++ b/doc/appdev/refs/macros/index.rst @@ -0,0 +1,380 @@ +krb5 simple macros +========================= + +Public +------- + +.. toctree:: + :maxdepth: 1 + + ADDRTYPE_ADDRPORT.rst + ADDRTYPE_CHAOS.rst + ADDRTYPE_DDP.rst + ADDRTYPE_INET.rst + ADDRTYPE_INET6.rst + ADDRTYPE_IPPORT.rst + ADDRTYPE_ISO.rst + ADDRTYPE_IS_LOCAL.rst + ADDRTYPE_NETBIOS.rst + ADDRTYPE_XNS.rst + AD_TYPE_EXTERNAL.rst + AD_TYPE_FIELD_TYPE_MASK.rst + AD_TYPE_REGISTERED.rst + AD_TYPE_RESERVED.rst + AP_OPTS_ETYPE_NEGOTIATION.rst + AP_OPTS_MUTUAL_REQUIRED.rst + AP_OPTS_RESERVED.rst + AP_OPTS_USE_SESSION_KEY.rst + AP_OPTS_USE_SUBKEY.rst + AP_OPTS_WIRE_MASK.rst + CKSUMTYPE_CMAC_CAMELLIA128.rst + CKSUMTYPE_CMAC_CAMELLIA256.rst + CKSUMTYPE_CRC32.rst + CKSUMTYPE_DESCBC.rst + CKSUMTYPE_HMAC_MD5_ARCFOUR.rst + CKSUMTYPE_HMAC_SHA1_96_AES128.rst + CKSUMTYPE_HMAC_SHA1_96_AES256.rst + CKSUMTYPE_HMAC_SHA256_128_AES128.rst + CKSUMTYPE_HMAC_SHA384_192_AES256.rst + CKSUMTYPE_HMAC_SHA1_DES3.rst + CKSUMTYPE_MD5_HMAC_ARCFOUR.rst + CKSUMTYPE_NIST_SHA.rst + CKSUMTYPE_RSA_MD4.rst + CKSUMTYPE_RSA_MD4_DES.rst + CKSUMTYPE_RSA_MD5.rst + CKSUMTYPE_RSA_MD5_DES.rst + ENCTYPE_AES128_CTS_HMAC_SHA1_96.rst + ENCTYPE_AES128_CTS_HMAC_SHA256_128.rst + ENCTYPE_AES256_CTS_HMAC_SHA1_96.rst + ENCTYPE_AES256_CTS_HMAC_SHA384_192.rst + ENCTYPE_ARCFOUR_HMAC.rst + ENCTYPE_ARCFOUR_HMAC_EXP.rst + ENCTYPE_CAMELLIA128_CTS_CMAC.rst + ENCTYPE_CAMELLIA256_CTS_CMAC.rst + ENCTYPE_DES3_CBC_ENV.rst + ENCTYPE_DES3_CBC_RAW.rst + ENCTYPE_DES3_CBC_SHA.rst + ENCTYPE_DES3_CBC_SHA1.rst + ENCTYPE_DES_CBC_CRC.rst + ENCTYPE_DES_CBC_MD4.rst + ENCTYPE_DES_CBC_MD5.rst + ENCTYPE_DES_CBC_RAW.rst + ENCTYPE_DES_HMAC_SHA1.rst + ENCTYPE_DSA_SHA1_CMS.rst + ENCTYPE_MD5_RSA_CMS.rst + ENCTYPE_NULL.rst + ENCTYPE_RC2_CBC_ENV.rst + ENCTYPE_RSA_ENV.rst + ENCTYPE_RSA_ES_OAEP_ENV.rst + ENCTYPE_SHA1_RSA_CMS.rst + ENCTYPE_UNKNOWN.rst + KDC_OPT_ALLOW_POSTDATE.rst + KDC_OPT_CANONICALIZE.rst + KDC_OPT_CNAME_IN_ADDL_TKT.rst + KDC_OPT_DISABLE_TRANSITED_CHECK.rst + KDC_OPT_ENC_TKT_IN_SKEY.rst + KDC_OPT_FORWARDABLE.rst + KDC_OPT_FORWARDED.rst + KDC_OPT_POSTDATED.rst + KDC_OPT_PROXIABLE.rst + KDC_OPT_PROXY.rst + KDC_OPT_RENEW.rst + KDC_OPT_RENEWABLE.rst + KDC_OPT_RENEWABLE_OK.rst + KDC_OPT_REQUEST_ANONYMOUS.rst + KDC_OPT_VALIDATE.rst + KDC_TKT_COMMON_MASK.rst + KRB5_ALTAUTH_ATT_CHALLENGE_RESPONSE.rst + KRB5_ANONYMOUS_PRINCSTR.rst + KRB5_ANONYMOUS_REALMSTR.rst + KRB5_AP_REP.rst + KRB5_AP_REQ.rst + KRB5_AS_REP.rst + KRB5_AS_REQ.rst + KRB5_AUTHDATA_AND_OR.rst + KRB5_AUTHDATA_AUTH_INDICATOR.rst + KRB5_AUTHDATA_CAMMAC.rst + KRB5_AUTHDATA_ETYPE_NEGOTIATION.rst + KRB5_AUTHDATA_FX_ARMOR.rst + KRB5_AUTHDATA_IF_RELEVANT.rst + KRB5_AUTHDATA_INITIAL_VERIFIED_CAS.rst + KRB5_AUTHDATA_KDC_ISSUED.rst + KRB5_AUTHDATA_MANDATORY_FOR_KDC.rst + KRB5_AUTHDATA_OSF_DCE.rst + KRB5_AUTHDATA_SESAME.rst + KRB5_AUTHDATA_SIGNTICKET.rst + KRB5_AUTHDATA_WIN2K_PAC.rst + KRB5_AUTH_CONTEXT_DO_SEQUENCE.rst + KRB5_AUTH_CONTEXT_DO_TIME.rst + KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR.rst + KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR.rst + KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR.rst + KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR.rst + KRB5_AUTH_CONTEXT_PERMIT_ALL.rst + KRB5_AUTH_CONTEXT_RET_SEQUENCE.rst + KRB5_AUTH_CONTEXT_RET_TIME.rst + KRB5_AUTH_CONTEXT_USE_SUBKEY.rst + KRB5_CRED.rst + KRB5_CRYPTO_TYPE_CHECKSUM.rst + KRB5_CRYPTO_TYPE_DATA.rst + KRB5_CRYPTO_TYPE_EMPTY.rst + KRB5_CRYPTO_TYPE_HEADER.rst + KRB5_CRYPTO_TYPE_PADDING.rst + KRB5_CRYPTO_TYPE_SIGN_ONLY.rst + KRB5_CRYPTO_TYPE_STREAM.rst + KRB5_CRYPTO_TYPE_TRAILER.rst + KRB5_CYBERSAFE_SECUREID.rst + KRB5_DOMAIN_X500_COMPRESS.rst + KRB5_ENCPADATA_REQ_ENC_PA_REP.rst + KRB5_ERROR.rst + KRB5_FAST_REQUIRED.rst + KRB5_GC_CACHED.rst + KRB5_GC_CANONICALIZE.rst + KRB5_GC_CONSTRAINED_DELEGATION.rst + KRB5_GC_FORWARDABLE.rst + KRB5_GC_NO_STORE.rst + KRB5_GC_NO_TRANSIT_CHECK.rst + KRB5_GC_USER_USER.rst + KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST.rst + KRB5_GET_INIT_CREDS_OPT_ANONYMOUS.rst + KRB5_GET_INIT_CREDS_OPT_CANONICALIZE.rst + KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT.rst + KRB5_GET_INIT_CREDS_OPT_ETYPE_LIST.rst + KRB5_GET_INIT_CREDS_OPT_FORWARDABLE.rst + KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST.rst + KRB5_GET_INIT_CREDS_OPT_PROXIABLE.rst + KRB5_GET_INIT_CREDS_OPT_RENEW_LIFE.rst + KRB5_GET_INIT_CREDS_OPT_SALT.rst + KRB5_GET_INIT_CREDS_OPT_TKT_LIFE.rst + KRB5_INIT_CONTEXT_SECURE.rst + KRB5_INIT_CONTEXT_KDC.rst + KRB5_INIT_CREDS_STEP_FLAG_CONTINUE.rst + KRB5_INT16_MAX.rst + KRB5_INT16_MIN.rst + KRB5_INT32_MAX.rst + KRB5_INT32_MIN.rst + KRB5_KEYUSAGE_AD_ITE.rst + KRB5_KEYUSAGE_AD_KDCISSUED_CKSUM.rst + KRB5_KEYUSAGE_AD_MTE.rst + KRB5_KEYUSAGE_AD_SIGNEDPATH.rst + KRB5_KEYUSAGE_APP_DATA_CKSUM.rst + KRB5_KEYUSAGE_APP_DATA_ENCRYPT.rst + KRB5_KEYUSAGE_AP_REP_ENCPART.rst + KRB5_KEYUSAGE_AP_REQ_AUTH.rst + KRB5_KEYUSAGE_AP_REQ_AUTH_CKSUM.rst + KRB5_KEYUSAGE_AS_REP_ENCPART.rst + KRB5_KEYUSAGE_AS_REQ.rst + KRB5_KEYUSAGE_AS_REQ_PA_ENC_TS.rst + KRB5_KEYUSAGE_CAMMAC.rst + KRB5_KEYUSAGE_ENC_CHALLENGE_CLIENT.rst + KRB5_KEYUSAGE_ENC_CHALLENGE_KDC.rst + KRB5_KEYUSAGE_FAST_ENC.rst + KRB5_KEYUSAGE_FAST_FINISHED.rst + KRB5_KEYUSAGE_FAST_REP.rst + KRB5_KEYUSAGE_FAST_REQ_CHKSUM.rst + KRB5_KEYUSAGE_GSS_TOK_MIC.rst + KRB5_KEYUSAGE_GSS_TOK_WRAP_INTEG.rst + KRB5_KEYUSAGE_GSS_TOK_WRAP_PRIV.rst + KRB5_KEYUSAGE_IAKERB_FINISHED.rst + KRB5_KEYUSAGE_KDC_REP_TICKET.rst + KRB5_KEYUSAGE_KRB_CRED_ENCPART.rst + KRB5_KEYUSAGE_KRB_ERROR_CKSUM.rst + KRB5_KEYUSAGE_KRB_PRIV_ENCPART.rst + KRB5_KEYUSAGE_KRB_SAFE_CKSUM.rst + KRB5_KEYUSAGE_PA_FX_COOKIE.rst + KRB5_KEYUSAGE_PA_OTP_REQUEST.rst + KRB5_KEYUSAGE_PA_PKINIT_KX.rst + KRB5_KEYUSAGE_PA_S4U_X509_USER_REPLY.rst + KRB5_KEYUSAGE_PA_S4U_X509_USER_REQUEST.rst + KRB5_KEYUSAGE_PA_SAM_CHALLENGE_CKSUM.rst + KRB5_KEYUSAGE_PA_SAM_CHALLENGE_TRACKID.rst + KRB5_KEYUSAGE_PA_SAM_RESPONSE.rst + KRB5_KEYUSAGE_TGS_REP_ENCPART_SESSKEY.rst + KRB5_KEYUSAGE_TGS_REP_ENCPART_SUBKEY.rst + KRB5_KEYUSAGE_TGS_REQ_AD_SESSKEY.rst + KRB5_KEYUSAGE_TGS_REQ_AD_SUBKEY.rst + KRB5_KEYUSAGE_TGS_REQ_AUTH.rst + KRB5_KEYUSAGE_TGS_REQ_AUTH_CKSUM.rst + KRB5_KPASSWD_ACCESSDENIED.rst + KRB5_KPASSWD_AUTHERROR.rst + KRB5_KPASSWD_BAD_VERSION.rst + KRB5_KPASSWD_HARDERROR.rst + KRB5_KPASSWD_INITIAL_FLAG_NEEDED.rst + KRB5_KPASSWD_MALFORMED.rst + KRB5_KPASSWD_SOFTERROR.rst + KRB5_KPASSWD_SUCCESS.rst + KRB5_LRQ_ALL_ACCT_EXPTIME.rst + KRB5_LRQ_ALL_LAST_INITIAL.rst + KRB5_LRQ_ALL_LAST_RENEWAL.rst + KRB5_LRQ_ALL_LAST_REQ.rst + KRB5_LRQ_ALL_LAST_TGT.rst + KRB5_LRQ_ALL_LAST_TGT_ISSUED.rst + KRB5_LRQ_ALL_PW_EXPTIME.rst + KRB5_LRQ_NONE.rst + KRB5_LRQ_ONE_ACCT_EXPTIME.rst + KRB5_LRQ_ONE_LAST_INITIAL.rst + KRB5_LRQ_ONE_LAST_RENEWAL.rst + KRB5_LRQ_ONE_LAST_REQ.rst + KRB5_LRQ_ONE_LAST_TGT.rst + KRB5_LRQ_ONE_LAST_TGT_ISSUED.rst + KRB5_LRQ_ONE_PW_EXPTIME.rst + KRB5_NT_ENTERPRISE_PRINCIPAL.rst + KRB5_NT_ENT_PRINCIPAL_AND_ID.rst + KRB5_NT_MS_PRINCIPAL.rst + KRB5_NT_MS_PRINCIPAL_AND_ID.rst + KRB5_NT_PRINCIPAL.rst + KRB5_NT_SMTP_NAME.rst + KRB5_NT_SRV_HST.rst + KRB5_NT_SRV_INST.rst + KRB5_NT_SRV_XHST.rst + KRB5_NT_UID.rst + KRB5_NT_UNKNOWN.rst + KRB5_NT_WELLKNOWN.rst + KRB5_NT_X500_PRINCIPAL.rst + KRB5_PAC_CLIENT_INFO.rst + KRB5_PAC_CREDENTIALS_INFO.rst + KRB5_PAC_DELEGATION_INFO.rst + KRB5_PAC_LOGON_INFO.rst + KRB5_PAC_PRIVSVR_CHECKSUM.rst + KRB5_PAC_SERVER_CHECKSUM.rst + KRB5_PAC_UPN_DNS_INFO.rst + KRB5_PADATA_AFS3_SALT.rst + KRB5_PADATA_AP_REQ.rst + KRB5_PADATA_AS_CHECKSUM.rst + KRB5_PADATA_ENCRYPTED_CHALLENGE.rst + KRB5_PADATA_ENC_SANDIA_SECURID.rst + KRB5_PADATA_ENC_TIMESTAMP.rst + KRB5_PADATA_ENC_UNIX_TIME.rst + KRB5_PADATA_ETYPE_INFO.rst + KRB5_PADATA_ETYPE_INFO2.rst + KRB5_PADATA_FOR_USER.rst + KRB5_PADATA_FX_COOKIE.rst + KRB5_PADATA_FX_ERROR.rst + KRB5_PADATA_FX_FAST.rst + KRB5_PADATA_GET_FROM_TYPED_DATA.rst + KRB5_PADATA_NONE.rst + KRB5_PADATA_OSF_DCE.rst + KRB5_PADATA_OTP_CHALLENGE.rst + KRB5_PADATA_OTP_PIN_CHANGE.rst + KRB5_PADATA_OTP_REQUEST.rst + KRB5_PADATA_PAC_REQUEST.rst + KRB5_PADATA_PKINIT_KX.rst + KRB5_PADATA_PK_AS_REP.rst + KRB5_PADATA_PK_AS_REP_OLD.rst + KRB5_PADATA_PK_AS_REQ.rst + KRB5_PADATA_PK_AS_REQ_OLD.rst + KRB5_PADATA_PW_SALT.rst + KRB5_PADATA_REFERRAL.rst + KRB5_PADATA_S4U_X509_USER.rst + KRB5_PADATA_SAM_CHALLENGE.rst + KRB5_PADATA_SAM_CHALLENGE_2.rst + KRB5_PADATA_SAM_REDIRECT.rst + KRB5_PADATA_SAM_RESPONSE.rst + KRB5_PADATA_SAM_RESPONSE_2.rst + KRB5_PADATA_SESAME.rst + KRB5_PADATA_SVR_REFERRAL_INFO.rst + KRB5_PADATA_TGS_REQ.rst + KRB5_PADATA_USE_SPECIFIED_KVNO.rst + KRB5_PRINCIPAL_COMPARE_CASEFOLD.rst + KRB5_PRINCIPAL_COMPARE_ENTERPRISE.rst + KRB5_PRINCIPAL_COMPARE_IGNORE_REALM.rst + KRB5_PRINCIPAL_COMPARE_UTF8.rst + KRB5_PRINCIPAL_PARSE_ENTERPRISE.rst + KRB5_PRINCIPAL_PARSE_IGNORE_REALM.rst + KRB5_PRINCIPAL_PARSE_NO_REALM.rst + KRB5_PRINCIPAL_PARSE_REQUIRE_REALM.rst + KRB5_PRINCIPAL_UNPARSE_DISPLAY.rst + KRB5_PRINCIPAL_UNPARSE_NO_REALM.rst + KRB5_PRINCIPAL_UNPARSE_SHORT.rst + KRB5_PRIV.rst + KRB5_PROMPT_TYPE_NEW_PASSWORD.rst + KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN.rst + KRB5_PROMPT_TYPE_PASSWORD.rst + KRB5_PROMPT_TYPE_PREAUTH.rst + KRB5_PVNO.rst + KRB5_REALM_BRANCH_CHAR.rst + KRB5_RECVAUTH_BADAUTHVERS.rst + KRB5_RECVAUTH_SKIP_VERSION.rst + KRB5_REFERRAL_REALM.rst + KRB5_RESPONDER_PKINIT_FLAGS_TOKEN_USER_PIN_COUNT_LOW.rst + KRB5_RESPONDER_PKINIT_FLAGS_TOKEN_USER_PIN_FINAL_TRY.rst + KRB5_RESPONDER_PKINIT_FLAGS_TOKEN_USER_PIN_LOCKED.rst + KRB5_RESPONDER_QUESTION_PKINIT.rst + KRB5_RESPONDER_OTP_FLAGS_COLLECT_PIN.rst + KRB5_RESPONDER_OTP_FLAGS_COLLECT_TOKEN.rst + KRB5_RESPONDER_OTP_FLAGS_NEXTOTP.rst + KRB5_RESPONDER_OTP_FLAGS_SEPARATE_PIN.rst + KRB5_RESPONDER_OTP_FORMAT_ALPHANUMERIC.rst + KRB5_RESPONDER_OTP_FORMAT_DECIMAL.rst + KRB5_RESPONDER_OTP_FORMAT_HEXADECIMAL.rst + KRB5_RESPONDER_QUESTION_OTP.rst + KRB5_RESPONDER_QUESTION_PASSWORD.rst + KRB5_SAFE.rst + KRB5_SAM_MUST_PK_ENCRYPT_SAD.rst + KRB5_SAM_SEND_ENCRYPTED_SAD.rst + KRB5_SAM_USE_SAD_AS_KEY.rst + KRB5_TC_MATCH_2ND_TKT.rst + KRB5_TC_MATCH_AUTHDATA.rst + KRB5_TC_MATCH_FLAGS.rst + KRB5_TC_MATCH_FLAGS_EXACT.rst + KRB5_TC_MATCH_IS_SKEY.rst + KRB5_TC_MATCH_KTYPE.rst + KRB5_TC_MATCH_SRV_NAMEONLY.rst + KRB5_TC_MATCH_TIMES.rst + KRB5_TC_MATCH_TIMES_EXACT.rst + KRB5_TC_NOTICKET.rst + KRB5_TC_OPENCLOSE.rst + KRB5_TC_SUPPORTED_KTYPES.rst + KRB5_TGS_NAME.rst + KRB5_TGS_NAME_SIZE.rst + KRB5_TGS_REP.rst + KRB5_TGS_REQ.rst + KRB5_TKT_CREDS_STEP_FLAG_CONTINUE.rst + KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL.rst + KRB5_WELLKNOWN_NAMESTR.rst + LR_TYPE_INTERPRETATION_MASK.rst + LR_TYPE_THIS_SERVER_ONLY.rst + MAX_KEYTAB_NAME_LEN.rst + MSEC_DIRBIT.rst + MSEC_VAL_MASK.rst + SALT_TYPE_AFS_LENGTH.rst + SALT_TYPE_NO_LENGTH.rst + THREEPARAMOPEN.rst + TKT_FLG_ANONYMOUS.rst + TKT_FLG_ENC_PA_REP.rst + TKT_FLG_FORWARDABLE.rst + TKT_FLG_FORWARDED.rst + TKT_FLG_HW_AUTH.rst + TKT_FLG_INITIAL.rst + TKT_FLG_INVALID.rst + TKT_FLG_MAY_POSTDATE.rst + TKT_FLG_OK_AS_DELEGATE.rst + TKT_FLG_POSTDATED.rst + TKT_FLG_PRE_AUTH.rst + TKT_FLG_PROXIABLE.rst + TKT_FLG_PROXY.rst + TKT_FLG_RENEWABLE.rst + TKT_FLG_TRANSIT_POLICY_CHECKED.rst + VALID_INT_BITS.rst + VALID_UINT_BITS.rst + krb5_const.rst + krb5_princ_component.rst + krb5_princ_name.rst + krb5_princ_realm.rst + krb5_princ_set_realm.rst + krb5_princ_set_realm_data.rst + krb5_princ_set_realm_length.rst + krb5_princ_size.rst + krb5_princ_type.rst + krb5_roundup.rst + krb5_x.rst + krb5_xc.rst + +Deprecated macros +------------------------------ + +.. toctree:: + :maxdepth: 1 + + krb524_convert_creds_kdc.rst + krb524_init_ets.rst diff --git a/doc/appdev/refs/types/index.rst b/doc/appdev/refs/types/index.rst new file mode 100644 index 000000000000..dc414cfdebe1 --- /dev/null +++ b/doc/appdev/refs/types/index.rst @@ -0,0 +1,109 @@ +krb5 types and structures +========================= + +Public +------- + +.. toctree:: + :maxdepth: 1 + + krb5_address.rst + krb5_addrtype.rst + krb5_ap_req.rst + krb5_ap_rep.rst + krb5_ap_rep_enc_part.rst + krb5_authdata.rst + krb5_authdatatype.rst + krb5_authenticator.rst + krb5_boolean.rst + krb5_checksum.rst + krb5_const_pointer.rst + krb5_const_principal.rst + krb5_cred.rst + krb5_cred_enc_part.rst + krb5_cred_info.rst + krb5_creds.rst + krb5_crypto_iov.rst + krb5_cryptotype.rst + krb5_data.rst + krb5_deltat.rst + krb5_enc_data.rst + krb5_enc_kdc_rep_part.rst + krb5_enc_tkt_part.rst + krb5_encrypt_block.rst + krb5_enctype.rst + krb5_error.rst + krb5_error_code.rst + krb5_expire_callback_func.rst + krb5_flags.rst + krb5_get_init_creds_opt.rst + krb5_gic_opt_pa_data.rst + krb5_int16.rst + krb5_int32.rst + krb5_kdc_rep.rst + krb5_kdc_req.rst + krb5_keyblock.rst + krb5_keytab_entry.rst + krb5_keyusage.rst + krb5_kt_cursor.rst + krb5_kvno.rst + krb5_last_req_entry.rst + krb5_magic.rst + krb5_mk_req_checksum_func.rst + krb5_msgtype.rst + krb5_octet.rst + krb5_pa_pac_req.rst + krb5_pa_server_referral_data.rst + krb5_pa_svr_referral_data.rst + krb5_pa_data.rst + krb5_pointer.rst + krb5_post_recv_fn.rst + krb5_pre_send_fn.rst + krb5_preauthtype.rst + krb5_principal.rst + krb5_principal_data.rst + krb5_const_principal.rst + krb5_prompt.rst + krb5_prompt_type.rst + krb5_prompter_fct.rst + krb5_pwd_data.rst + krb5_responder_context.rst + krb5_responder_fn.rst + krb5_responder_otp_challenge.rst + krb5_responder_otp_tokeninfo.rst + krb5_responder_pkinit_challenge.rst + krb5_responder_pkinit_identity.rst + krb5_response.rst + krb5_replay_data.rst + krb5_ticket.rst + krb5_ticket_times.rst + krb5_timestamp.rst + krb5_tkt_authent.rst + krb5_trace_callback.rst + krb5_trace_info.rst + krb5_transited.rst + krb5_typed_data.rst + krb5_ui_2.rst + krb5_ui_4.rst + krb5_verify_init_creds_opt.rst + passwd_phrase_element.rst + + +Internal +--------- + +.. toctree:: + :maxdepth: 1 + + krb5_auth_context.rst + krb5_cksumtype + krb5_context.rst + krb5_cc_cursor.rst + krb5_ccache.rst + krb5_cccol_cursor.rst + krb5_init_creds_context.rst + krb5_key.rst + krb5_keytab.rst + krb5_pac.rst + krb5_rcache.rst + krb5_tkt_creds_context.rst diff --git a/doc/appdev/refs/types/krb5_int32.rst b/doc/appdev/refs/types/krb5_int32.rst new file mode 100644 index 000000000000..2bc914b3cd77 --- /dev/null +++ b/doc/appdev/refs/types/krb5_int32.rst @@ -0,0 +1,12 @@ +.. highlightlang:: c + +.. _krb5-int32-struct: + +krb5_int32 +========== + +.. +.. c:type:: krb5_int32 +.. + +krb5_int32 is a signed 32-bit integer type diff --git a/doc/appdev/refs/types/krb5_ui_4.rst b/doc/appdev/refs/types/krb5_ui_4.rst new file mode 100644 index 000000000000..de79bafe1944 --- /dev/null +++ b/doc/appdev/refs/types/krb5_ui_4.rst @@ -0,0 +1,12 @@ +.. highlightlang:: c + +.. _krb5-ui4-struct: + +krb5_ui_4 +========== + +.. +.. c:type:: krb5_ui_4 +.. + +krb5_ui_4 is an unsigned 32-bit integer type. |