An authentication path is the sequence of intermediate realms that are transited in communicating from one realm to another.

A realm is said to communicate with another realm if the two realms share an inter-realm key

These might be established to make communication between two realms more efficient

A single-string representation of a Kerberos name consists of one or more principal name components, separated by slashes, optionally followed by the "@" character and a realm name. If the realm name is not specified, the local realm is used. The slash and "@" characters may be quoted (i.e., included as part of a component rather than as a component separator or realm prefix) by preceding them with a backslash ("\") character. Similarly, newline, tab, backspace, and null characters may be included in a component by using \n, \t, \b or \0, respectively.

The realm in a Kerberos name may not contain the slash, colon or null characters.

*principal will point to allocated storage which should be freed by the caller (using krb5_free_principal()) after use.

*name points to allocated storage and should be freed by the caller when finished.

Takes KDC rep parts in *rep and *encpart, and formats it into *enc_rep, using message type type and encryption key client_key and encryption block eblock.

enc_rep->data will point to allocated storage upon non-error return; the caller should free it when finished.

Takes a KDC_REP message and decrypts encrypted part using etype and *key, putting result in *dec_rep. The pointers in dec_rep are all set to allocated storage which should be freed by the caller when finished with the response (by using krb5_free_kdc_rep()).

If the response isn't a KDC_REP (tgs or as), it returns an error from the decoding routines.

The result is in allocated storage pointed to by dec_rep->enc_part2, unless some error occurs.

This function is suitable for use as the decrypt_proc argument to krb5_get_in_tkt().

Encrypts the unecrypted part of the ticket found in dec_ticket->enc_part2 using srv_key, and places result in dec_ticket->enc_part. The dec_ticket->enc_part will be allocated by this function.

enc_part->data is allocated and filled in with encrypted stuff.

Takes encrypted dec_ticket->enc_part, decrypts with dec_ticket->etype using srv_key, and places result in dec_ticket->enc_part2. The storage of dec_ticket->enc_part2 will be allocated before return.

Sends a request to the TGS and waits for a response. kdcoptions is used for the options in the KRB_TGS_REQ. timestruct values are used for from, till, and rtime in the KRB_TGS_REQ. etypes is a list of etypes used in the KRB_TGS_REQ. sumtype is used for the checksum in the AP_REQ in the KRB_TGS_REQ. sname is used for sname in the KRB_TGS_REQ. addrs, if non-NULL, is used for addresses in the KRB_TGS_REQ. authorization_data, if non-NULL, is used for authorization_data in the KRB_TGS_REQ. padata, if non-NULL, is combined with any other supplied preauthentication data for the KRB_TGS_REQ. second_ticket, if required by options, is used for the 2nd ticket in the KRB_TGS_REQ. in_cred is used for the ticket and session key in the KRB_AP_REQ header in the KRB_TGS_REQ.

The KDC realm is extracted from in_cred->server's realm.

The response is placed into *rep. rep->response.data is set to point at allocated storage which should be freed by the caller when finished.

ccache is used to fetch initial TGT's to start the authentication path to the server.

Credentials are requested from the KDC for the server's realm. Any TGT credentials obtained in the process of contacting the KDC are returned in an array of credentials; tgts is filled in to point to an array of pointers to credential structures (if no TGT's were used, the pointer is zeroed). TGT's may be returned even if no useful end ticket was obtained.

The returned credentials are NOT cached.

If credentials are obtained, creds is filled in with the results; creds->ticket and creds->keyblock->key are set to allocated storage, which should be freed by the caller when finished.

kdcoptions refers to the options as listed in Table 2. The optional address is used for addressed in the KRB_TGS_REQ (see krb5_send_tgs()).

• The server identified by in_creds->server

• The options in options. Valid choices are KRB5_GC_USER_USER and KRB5_GC_GC_CACHED

• The expiration date specified in in_creds->times.endtime

• The session key type specified in in_creds->keyblock.keytype if it is non-zero.

If options specifies KRB5_GC_CACHED, then krb5_get_credentials() will only search the credentials cache for a ticket.

If options specifies KRB5_GC_USER_USER, then krb5_get_credentials() will get credentials for a user to user authentication. In a user to user authentication, the secret key for the server is the session key from the server's ticket-granting-ticket (TGT). The TGT is passed from the server to the client over the network _this is safe since the TGT is encrypted in a key known only by the Kerberos server and the client must pass this TGT to krb5_get_credentials() in in_creds->second_ticket. The Kerberos server will use this TGT to construct a user to user ticket which can be verified by the server by using the session key from its TGT.

The effective expiration date is the minimum of the following:

• The expiration date as specified in in_creds->times.endtime
• The requested start time plus the maximum lifetime of the server as specified by the server's entry in the Kerberos database.
• The requested start time plus the maximum lifetime of tickets allowed in the local site, as specified by the KDC. This is currently a compile-time option, KRB5_KDB_MAX_LIFE in config.h, and is by default 1 day.

If any special authorization data needs to be included in the ticket, for example, restrictions on how the ticket can be used _they should be specified in in_creds-> authdata. If there is no special authorization data to be passed, in_creds->authdata should be NULL.

Any returned ticket and intermediate ticket-granting tickets are stored in ccache.

Attempts to get an initial ticket for creds->client to use server creds->server, using the following: the realm from creds->client; the options in options (listed in Table 2); and ptypes, the preauthentication method (valid preauthentication methods are listed in Table 2). krb5_get_in_tkt() requests encryption type etypes (valid encryption types are ETYPE_DES_CBC_CRC and ETYPE_RAW_DES_CBC), using creds->times.starttime, creds->times.endtime, creds->times.renew_till as from, till, and rtime. creds->times.renew_till is ignored unless the RENEWABLE option is requested.

key_proc is called, with context, keytype, keyseed andpadata as arguments, to fill in key to be used for decryption. The valid key types for keytype are KEYTYPE_NULL and KEYTYPE_DES However, KEYTYPE_DES is the only key type supported by MIT kerberos. The content of keyseed depends on the key_proc being used. The padata passed to key_proc is the preauthentication data returned by the KDC as part of the reply to the initial ticket request. It may contain an element of type KRB5_PADATA_PW_SALT, which key_proc should use to determine what salt to use when generating the key. key_proc should fill in key with a key for the client, or return an error code.

decrypt_proc is called to perform the decryption of the response (the encrypted part is in dec_rep->enc_part; the decrypted part should be allocated and filled into dec_rep->enc_part2. decryptarg is passed on to decrypt_proc, and its content depends on the decrypt_proc being used.

If addrs is non-NULL, it is used for the addresses requested. If it is null, the system standard addresses are used.

If ret_as_reply is non-NULL, it is filled in with a pointer to a structure containing the reply packet from the KDC. Some programs may find it useful to have direct access to this information. For example, it can be used to obtain the pre-authentication data passed back from the KDC. The caller is responsible for freeing this structure by using krb5_free_kdc_rep().

If etypes is non-NULL, the it is used as for the list of valid encyrption types. Otherwise, the context default is used (as returned by krb5_get_default_in_tkt_etypes().

A succesful call will place the ticket in the credentials cache ccache and fill in creds with the ticket information used/returned.

The password is converted into a key using the appropriate string-to-key conversion function for the specified keytype, and using any salt data returned by the KDC in response to the authentication request.

See krb5_get_in_tkt() for documentation of the options, addrs, pre_auth_type, etype, keytype, ccache, creds and ret_as_reply arguments.

See krb5_get_in_tkt() for documentation of the options, addrs, pre_auth_type, etype, ccache, creds and ret_as_reply arguments.

See krb5_get_in_tkt() for documentation of the options, addrs, pre_auth_type, etype, ccache, creds and ret_as_reply arguments.

The server to receive the message is specified by hostname. The principal of the server to receive the message is specified by hostname and service. If credentials are not present in the credentials cache ccache for this server, the TGS request with default parameters is used in an attempt to obtain such credentials, and they are stored in ccache.

ap_req_options specifies the KRB_AP_REQ options desired. Valid options are:

AP_OPTS_USE_SESSION_KEY
AP_OPTS_MUTUAL_REQUIRED

The checksum method to be used is as specified in auth_context.

outbuf should point to an existing krb5_data structure. outbuf->length and outbuf->data will be filled in on success, and the latter should be freed by the caller when it is no longer needed; if an error is returned, however, no storage is allocated and outbuf->data does not need to be freed.

outbuf, ap_req_options, auth_context, and ccache are used in the same fashion as for krb5_mk_req().

in_creds is used to supply the credentials (ticket and session key) needed to form the request.

If in_creds->ticket has no data (length == 0), then an error is returned.

During this call, the structure elements in in_creds may be freed and reallocated. Hence all of the structure elements which are pointers should point to allocated memory, and there should be no other pointers aliased to the same memory, since it may be deallocated during this procedure call.

If ap_req_options specifies AP_OPTS_USE_SUBKEY, then a subkey will be generated if need be by krb5_generate_subkey().

A copy of the authenticator will be stored in the auth_context, with the principal and checksum fields nulled out, unless an error is returned. (This is to prevent pointer sharing problems; the caller shouldn't need these fields anyway, since the caller supplied them.)

subkey is filled in to point to the generated subkey, unless an error is returned. The returned key (i.e., *subkey) is allocated and should be freed by the caller with krb5_free_keyblock() when it is no longer needed.

inbuf should contain the KRB_AP_REQ message to be parsed.

If auth_context is NULL, one will be generated and freed internally by the function.

server specifies the expected server's name for the ticket. If server is NULL, then any server name will be accepted if the appropriate key can be found, and the caller should verify that the server principal matches some trust criterion.

If server is not NULL, and a replay detaction cache has not been established with the auth_context, one will be generated.

keytab specifies a keytab containing generate a decryption key. If NULL, krb5_kt_default will be used to find the default keytab and the key taken from there11 .

If a keyblock is present in the auth_context, it will be used to decrypt the ticket request and the keyblock freed with krb5_free_keyblock(). This is useful for user to user authentication. If no keyblock is specified, the keytab is consulted for an entry matching the requested keytype, server and version number and used instead.

The authenticator in the request is decrypted and stored in the auth_context. The client specified in the decrypted authenticator is compared to the client specified in the decoded ticket to ensure that the compare.

If the remote_addr portion of the auth_context is set, then this routine checks if the request came from the right client.

sender_addr specifies the address(es) expected to be present in the ticket.

The replay cache is checked to see if the ticket and authenticator have been seen and if so, returns an error. If not, the ticket and authenticator are entered into the cache.

Various other checks are made of the decoded data, including, cross-realm policy, clockskew and ticket validation times.

The keyblock, subkey, and sequence number of the request are all stored in the auth_context for future use.

If the request has the AP_OPTS_MUTUAL_REQUIRED bit set, the local sequence number, which is stored in the auth_context, is XORed with the remote sequence number in the request.

If ap_req_options is non-NULL, it will be set to contain the application request flags.

When successfull, outbuf->length and outbuf->data are filled in with the length of the AP_REQ message and allocated data holding it. outbuf->data should be freed by the caller when it is no longer needed.

If the flags in auth_context indicate that a sequence number should be used (either KRB5_AUTH_CONTEXT_DO_SEQUENCE or KRB5_AUTH_CONTEXT_RET_SEQUENCE) and the local sequqnce number in the auth_context is 0, a new number will be generated with krb5_generate_seq_number().

The keyblock stored in auth_context is used to decrypt the message after establishing any key pre-processing with krb5_process_key().

The error buffer storage (enc_err->data) is allocated, and should be freed by the caller when finished.

key parameterizes the choice of the random sequence number, which is filled into *seqno upon return.

The paramter appl_version is a string describing the application protocol version which the client is expecting to use for this exchange. If the server is using a different application protocol, an error will be returned.

The parameters client and server specify the kerberos principals for the client and the server. They are ignored if in_creds is non-null. Otherwise, server must be non-null, but client may be null, in which case the client principal used is the one in the credential cache's default principal.

The ap_req_options parameters specifies the options which should be passed to krb5_mk_req(). Valid options are listed in Table 4.1.4. If ap_req_options specifies MUTUAL_REQUIRED, then krb5_sendauth() will perform a mutual authentication exchange, and if rep_result is non-null, it will be filled in with the result of the mutual authentication exchange; the caller should free *rep_result with krb5_free_ap_rep_enc_part() when done with it.

If in_creds is non-null, then in_creds->client and in_creds->server must be filled in, and either the other structure fields should be filled in with valid credentials, or in_creds->ticket.length should be zero.

If in_creds->ticket.length is non-zero, then in_creds will be used as-is as the credentials to send to the server, and ccache is ignored; otherwise, ccache is used as described below, and out_creds , if not NULL, is filled in with the retrieved credentials. ccache() specifies the credential cache to use when one is needed (i.e., when in_creds() is null or in_creds->ticket.length is zero). When a credential cache is not needed, ccache() is ignored. When a credential cache is needed and ccache() is null, the default credential cache is used. Note that if the credential cache is needed and does not contain the needed credentials, they will be retrieved from the KDC and stored in the credential cache.

If mutual authentication is used and rep_result is non-null, the sequence number for the server is available to the caller in *rep_result->seq_number. (If mutual authentication is not used, there is no way to negotiate a sequence number for the server.)

If an error occurs during the authenticated ticket exchange and error is non-null, the error packet (if any) that was sent from the server will be placed in it. This error should be freed with krb5_free_error().

fd is a pointer to the network connection. As in krb5_sendauth(), in the MIT Unix implementation fd is a pointer to a file descriptor.

The parameter appl_version is a string describing the application protocol version which the server is expecting to use for this exchange. If the client is using a different application protocol, an error will be returned and the authentication exchange will be aborted.

If server is non-null, then krb5_recvauth() verifies that the server principal requested by the client matches server. If not, an error will be returned and the authentication exchange will be aborted.

The parameters server, auth_context, and keytab are used by krb5_rd_req() to obtain the server's private key.

If server is non-null, the princicpal component of it is used to determine the replay cache to use. Otherwise, krb5_recvauth() will use a default replay cache.

The flags argument allows the caller to modify the behavior of krb5_recvauth(). For non-library callers, flags should be 0.

ticket is optional and is only filled in if non-null. It is filled with the data from the ticket sent by the client, and should be freed with krb5_free_ticket() when it is no longer needed.

userdata is formatted as the user data in the message. Portions of auth_context specify the checksum type; the keyblockm which might be used to seed the checksum; full addresses (host and port) for the sender and receiver. The local_addr portion of *auth_context is used to form the addresses usedin the KRB_SAFE message. The remote_addr is optional; if the receiver's address is not known, it may be replaced by NULL. local_addr, however, is mandatory.

The auth_context flags select whether sequence numbers or timestamps should be used to identify the message. Valid flags are listed below.

If timestamps are to be used (i.e., if KRB5_AUTH_CONTEXT_DO_TIME is set), an entry describing the message will be entered in the replay cache so that the caller may detect if this message is sent back to him by an attacker. If KRB5_AUTH_CONTEXT_DO_TIME_NOTIME is not set, the auth_context replay cache is not used. If sequence numbers are to be used (i.e., if either KRB5_AUTH_CONTEXT_DO_SEQUENCE or KRB5_AUTH_CONTEXT_RET_SEQUENEC is set), then auth_context local sequence number will be placed in the protected message as its sequence number.

The outbuf buffer storage (i.e., outbuf->data) is allocated, and should be freed by the caller when finished.

The keyblock used for verifying the integrity of the message is taken from the auth_context local_subkey, remote_subkey, or keyblock. The keyblock is chosen in the above order by the first one which is not NULL.

The remote_addr and localaddr portions of the *auth_context specify the full addresses (host and port) of the sender and receiver, and must be of type ADDRTYPE_ADDRPORT.

The remote_addr parameter is mandatory; it specifies the address of the sender.

If the address of the sender in the message does not match remote_addr, the error KRB5KRB_AP_ERR_BADADDR will be returned.

If local_addr is non-NULL, then the address of the receiver in the message much match it. If it is null, the receiver address in the message will be checked against the list of local addresses as returned by krb5_os_localaddr(). If the check fails, KRB5KRB_AP_ERR_BADARRD is returned.

The outbuf buffer storage (i.e., outbuf->data is allocated storage which the caller should free when it is no longer needed.

If auth_context_flags portion of auth_context indicates that sequence numbers are to be used (i.e., if KRB5_AUTH_CONTEXT_DOSEQUENCE is set in it), The remote_seq_number portion of auth_context is compared to the sequence number for the message, and KRB5_KRB_AP_ERR_BADORDER is returned if it does not match. Otherwise, the sequence number is not used.

If timestamps are to be used (i.e., if KRB5_AUTH_CONTEXT_DO_TIME is set in the auth_context), then two additional checks are performed:

• The timestamp in the message must be within the permitted clock skew (which is usually five minutes), or KRB5KRB_AP_ERR_SKEW is returned.
• message must not be a replayed message, according to rcache.

inbuf, auth_context, outdata and outbuf function as in krb5_mk_safe().

As in krb5_mk_safe(), the remote_addr and remote_port part of the auth_context is optional; if the receiver's address is not known, it may be replaced by NULL. The local_addr, however, is mandatory.

The encryption type is taken from the auth_context keyblock portion. If i_vector portion of the auth_context is non-null, it is used as an initialization vector for the encryption (if the chosen encryption type supports initialization vectors) and its contents are replaced with the last block of encrypted data upon return.

The flags from the auth_context selects whether sequence numbers or timestamps should be used to identify the message. Valid flags are listed below.

inbuf, auth_context, outdata and outbuf function as in krb5_rd_safe().

The remote_addr part of the auth_context as set by krb5_auth_con_setaddrs() is mandatory; it specifies the address of the sender. If the address of the sender in the message does not match the remote_addr, the error KRB5KRB_AP_ERR_BADADDR will be returned.

If local_addr portion of the auth_context is non-NULL, then the address of the receiver in the message much match it. If it is null, the receiver address in the message will be checked against the list of local addresses as returned by krb5_os_localaddr().

The keyblock portion of auth_context specifies the key to be used for decryption of the message. If the i_vector element, is non-null, it is used as an initialization vector for the decryption (if the encryption type of the message supports initialization vectors) and its contents are replaced with the last block of encrypted data in the message.

The auth_context flags specify whether timestamps (KRB5_AUTH_CONTEXT_DO_TIME) and sequence numbers (KRB5_AUTH_CONTEXT_DO_SEQUENCE) are to be used.

Upon successful return, ret_rcache is filled in to contain a handle to an open rcache, which should be closed with krb5_rc_close().

If at least one match is found, one of the matching credentials is returned in *creds. The credentials should be freed using krb5_free_credentials().

Before the cache can be used krb5_rc_initialize() or krb5_rc_recover() must be called.

If type is not found, krb5_rc_type_notfound is returned.

NOTE: This is an internal function, which is not necessarily intended for use by application programs. Its interface may change at any time.