next up previous contents index
Next: Miscellaneous main functions Up: Main functions Previous: Principal access functions   Contents   Index

The application functions


\begin{funcdecl}{krb5_encode_kdc_rep}{krb5_error_code}{\funcin}
\funcarg{const k...
...krb5_kdc_rep *}{dec_rep}
\funcout
\funcarg{krb5_data **}{enc_rep}
\end{funcdecl}

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

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_repdata will point to allocated storage upon non-error return; the caller should free it when finished.

Returns system errors.


\begin{funcdecl}{krb5_decode_kdc_rep}{krb5_error_code}{\funcinout}
\funcarg{krb5...
... krb5_enctype}{etype}
\funcout
\funcarg{krb5_kdc_rep **}{dec_rep}
\end{funcdecl}

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

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.

Returns errors from encryption routines, system errors.


\begin{funcdecl}{krb5_kdc_rep_decrypt_proc}{krb5_error_code}{\funcinout}
\funcar...
...pointer}{decryptarg}
\funcinout
\funcarg{krb5_kdc_rep *}{dec_rep}
\end{funcdecl}

Decrypt the encrypted portion of dec_rep, using the encryption key key. The parameter decryptarg is ignored.

The result is in allocated storage pointed to by dec_repenc_part2, unless some error occurs.

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


\begin{funcdecl}{krb5_encrypt_tkt_part}{krb5_error_code}{\funcinout}
\funcarg{kr...
...yblock *}{srv_key}
\funcinout
\funcarg{krb5_ticket *}{dec_ticket}
\end{funcdecl}

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

Encrypts the unecrypted part of the ticket found in dec_ticketenc_part2 using srv_key, and places result in dec_ticketenc_part. The dec_ticketenc_part will be allocated by this function.

Returns errors from encryption routines, system errors

enc_partdata is allocated and filled in with encrypted stuff.


\begin{funcdecl}{krb5_decrypt_tkt_part}{krb5_error_code}{\funcinout}
\funcarg{kr...
...yblock *}{srv_key}
\funcinout
\funcarg{krb5_ticket *}{dec_ticket}
\end{funcdecl}

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

Takes encrypted dec_ticketenc_part, decrypts with dec_ticketetype using srv_key, and places result in dec_ticketenc_part2. The storage of dec_ticketenc_part2 will be allocated before return.

Returns errors from encryption routines, system errors


\begin{funcdecl}{krb5_send_tgs}{krb5_error_code}{\funcinout}
\funcarg{krb5_conte...
...rg{krb5_creds *}{in_cred}
\funcout
\funcarg{krb5_response *}{rep}
\end{funcdecl}

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

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 pre-authentication 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_credserver's realm.

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

Returns system errors.


\begin{funcdecl}{krb5_get_cred_from_kdc}{krb5_error_code}{\funcinout}
\funcarg{k...
...
\funcarg{krb5_cred **}{out_cred}
\funcarg{krb5_creds ***}{tgts}
\end{funcdecl}

Retrieve credentials for principal in_credclient, server credsserver, possibly credssecond_ticket if needed by the ticket flags.

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; credsticket and credskeyblockkey are set to allocated storage, which should be freed by the caller when finished.

Returns errors, system errors.


\begin{funcdecl}{krb5_get_cred_via_tkt}{krb5_error_code}{\funcinout}
\funcarg{kr...
...krb5_creds *}{in_cred}
\funcout
\funcarg{krb5_creds **}{out_cred}
\end{funcdecl}

Takes a ticket tkt and a target credential in_cred, attempts to fetch a TGS from the KDC. Upon success the resulting is stored in out_cred. The memory allocated in out_cred should be freed by the called when finished by using krb5_free_creds.

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).

Returns errors, system errors.


\begin{funcdecl}{krb5_get_credentials}{krb5_error_code}{\funcinout}
\funcarg{krb...
...rb5_creds *}{in_creds}
\funcout
\funcarg{krb5_creds *}{out_creds}
\end{funcdecl}

This routine attempts to use the credentials cache ccache or a TGS exchange to get an additional ticket for the client identified by in_credsclient, with following information:

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_credssecond_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:

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_credsauthdata. If there is no special authorization data to be passed, in_credsauthdata should be NULL.

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

Returns errors from encryption routines, system errors.


\begin{funcdecl}{krb5_get_in_tkt}{krb5_error_code}{\funcinout}
\funcarg{krb5_con...
...carg{krb5_ccache}{ccache}
\funcarg{krb5_kdc_rep **}{ret_as_reply}
\end{funcdecl}

This all-purpose initial ticket routine, usually called via krb5_get_in_tkt_with_skey or krb5_get_in_tkt_with_password or krb5_get_in_tkt_with_keytab.

Attempts to get an initial ticket for credsclient to use server credsserver, using the following: the realm from credsclient; 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 credstimes.starttime, credstimes.endtime, credstimes.renew_till as from, till, and rtime. credstimes.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,9 and KEYTYPE_DES.10 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_repenc_part; the decrypted part should be allocated and filled into dec_repenc_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.

Returns system errors, preauthentication errors, encryption errors.


\begin{funcdecl}{krb5_get_in_tkt_with_password}{krb5_error_code}{\funcinout}
\fu...
...carg{krb5_creds *}{creds}
\funcarg{krb5_kdc_rep **}{ret_as_reply}
\end{funcdecl}

Attempts to get an initial ticket using the null-terminated string password. If password is NULL, the password is read from the terminal using as a prompt the globalname krb5_default_pwd_prompt1.

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.

Returns system errors, preauthentication errors, encryption errors.


\begin{funcdecl}{krb5_get_in_tkt_with_keytab}{krb5_error_code}{\funcinout}
\func...
...carg{krb5_creds *}{creds}
\funcarg{krb5_kdc_rep **}{ret_as_reply}
\end{funcdecl}

Attempts to get an initial ticket using keytab. If keytab is NULL, the default keytab is used (e.g., /etc/v5srvtab).

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

Returns system errors, preauthentication errors, encryption errors.


\begin{funcdecl}{krb5_get_in_tkt_with_skey}{krb5_error_code}{\funcinout}
\funcar...
...carg{krb5_creds *}{creds}
\funcarg{krb5_kdc_rep **}{ret_as_reply}
\end{funcdecl}

Attempts to get an initial ticket using key. If key is NULL, an appropriate key is retrieved from the system key store (e.g., /etc/v5srvtab).

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

Returns system errors, preauthentication errors, encryption errors.


\begin{funcdecl}{krb5_mk_req}{krb5_error_code}{\funcinout}
\funcarg{krb5_context...
...ncarg{krb5_ccache}{ccache}
\funcout
\funcarg{krb5_data *}{outbuf}
\end{funcdecl}

Formats a KRB_AP_REQ message into outbuf.

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. outbuflength and outbufdata 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 outbufdata does not need to be freed.

Returns system errors, error getting credentials for server.


\begin{funcdecl}{krb5_mk_req_extended}{krb5_error_code}{\funcinout}
\funcarg{krb...
...rg{krb5_creds *}{in_creds}
\funcout
\funcarg{krb5_data *}{outbuf}
\end{funcdecl}

Formats a KRB_AP_REQ message into outbuf, with more complete options than krb5_mk_req.

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_credsticket 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.)

Returns system errors, errors contacting the KDC, KDC errors getting a new ticket for the authenticator.


\begin{funcdecl}{krb5_generate_subkey}{krb5_error_code}{\funcinout}
\funcarg{krb...
...krb5_keyblock *}{key}
\funcout
\funcarg{krb5_keyblock **}{subkey}
\end{funcdecl}

Generates a pseudo-random sub-session key using the encryption system's random key functions, based on the input key.

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.


\begin{funcdecl}{krb5_rd_req}{krb5_error_code}{\funcinout}
\funcarg{krb5_context...
...lags *}{ap_req_options}
\funcout
\funcarg{krb5_ticket **}{ticket}
\end{funcdecl}

Parses a KRB_AP_REQ message, returning its contents. Upon successful return, if ticket is non-NULL, *ticket will be modified to point to allocated storage containing the ticket information. The caller is responsible for deallocating this space by using krb5_free_ticket.

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 authentcator 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.

Returns system errors, encryption errors, replay errors.


\begin{funcdecl}{krb5_rd_req_decoded}{krb5_error_code}{\funcinout}
\funcarg{krb5...
...rg{krb5_keytab}{keytab}
\funcout
\funcarg{krb5_ticket **}{ticket}
\end{funcdecl}

Essentially the same as krb5_rd_req, but uses a decoded AP_REQ as the input rather than an encoded input.


\begin{funcdecl}{krb5_mk_rep}{krb5_error_code}{\funcinout}
\funcarg{krb5_context...
...uth_context}{auth_context}
\funcout
\funcarg{krb5_data *}{outbuf}
\end{funcdecl}

Formats and encrypts an AP_REP message, including in it the data in the authentp portion of auth_context, encrypted using the keyblock portion of auth_context.

When successful, outbuflength and outbufdata are filled in with the length of the AP_REQ message and allocated data holding it. outbufdata 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.

Returns system errors.


\begin{funcdecl}{krb5_rd_rep}{krb5_error_code}{\funcinout}
\funcarg{krb5_context...
...5_data *}{inbuf}
\funcout
\funcarg{krb5_ap_rep_enc_part **}{repl}
\end{funcdecl}

Parses and decrypts an AP_REP message from *inbuf, filling in *repl with a pointer to allocated storage containing the values from the message. The caller is responsible for freeing this structure with krb5_free_ap_rep_enc_part.

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

Returns system errors, encryption errors, replay errors.


\begin{funcdecl}{krb5_mk_error}{krb5_error_code}{\funcinout}
\funcarg{krb5_conte...
...st krb5_error *}{dec_err}
\funcout
\funcarg{krb5_data *}{enc_err}
\end{funcdecl}

Formats the error structure *dec_err into an error buffer *enc_err.

The error buffer storage (enc_errdata) is allocated, and should be freed by the caller when finished.

Returns system errors.


\begin{funcdecl}{krb5_rd_error}{krb5_error_code}{\funcinout}
\funcarg{krb5_conte...
...5_data *}{enc_errbuf}
\funcout
\funcarg{krb5_error **}{dec_error}
\end{funcdecl}

Parses an error protocol message from enc_errbuf and fills in *dec_error with a pointer to allocated storage containing the error message. The caller is reponsible for freeing this structure by using krb5_free_error.

Returns system errors.


\begin{funcdecl}{krb5_generate_seq_number}{krb5_error_code}{\funcinout}
\funcarg...
...onst krb5_keyblock *}{key}
\funcout
\funcarg{krb5_int32 *}{seqno}
\end{funcdecl}

Generates a pseudo-random sequence number suitable for use as an initial sequence number for the KRB_SAFE and KRB_PRIV message processing routines.

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


\begin{funcdecl}{krb5_sendauth}{krb5_error_code}
\funcinout
\funcarg{krb5_contex...
...p_rep_enc_part **}{rep_result}
\funcarg{krb5_creds **}{out_creds}
\end{funcdecl}

krb5_sendauth provides a convenient means for client and server programs to send authenticated messages to one another through network connections. krb5_sendauth sends an authenticated ticket from the client program to the server program using the network connection specified by fd. In the MIT Unix implementation, fd should be a pointer to a file descriptor describing the network socket. This can be changed in other implementations, however, if the routines krb5_read_message, krb5_write_message, krb5_net_read, and krb5_net_write are changed.

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_credsclient and in_credsserver must be filled in, and either the other structure fields should be filled in with valid credentials, or in_credsticket.length should be zero. If in_credsticket.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_credsticket.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.


\begin{funcdecl}{krb5_recvauth}{krb5_error_code}{\funcinout}
\funcarg{krb5_conte...
...rg{krb5_keytab}{keytab}
\funcout
\funcarg{krb5_ticket **}{ticket}
\end{funcdecl}

krb5_recvauth provides a convenient means for client and server programs to send authenticated messages to one another through network connections. krb5_sendauth is the matching routine to krb5_recvauth for the server. krb5_recvauth will engage in an authentication dialogue with the client program running krb5_sendauth to authenticate the client to the server. In addition, if requested by the client, krb5_recvauth will provide mutual authentication to prove to the client that the server represented by krb5_recvauth is legitimate.

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 ysed 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.


\begin{funcdecl}{krb5_mk_safe}{krb5_error_code}{\funcinout}
\funcarg{krb5_contex...
..._data *}{outbuf}
\funcinout
\funcarg{krb5_replay_data *}{outdata}
\end{funcdecl}

Formats a KRB_SAFE message into outbuf.

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.

Symbol Meaning
KRB5_AUTH_CONTEXT_DO_TIME Use timestamps
  and replay cache
KRB5_AUTH_CONTEXT_RET_TIME Copy timestamp
  to *outdata
KRB5_AUTH_CONTEXT_DO_SEQUENCE Use sequence numbers
KRB5_AUTH_CONTEXT_RET_SEQUENCE Copy sequence numbers
  to *outdata

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 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., outbufdata) is allocated, and should be freed by the caller when finished.

Returns system errors, encryption errors.


\begin{funcdecl}{krb5_rd_safe}{krb5_error_code}{\funcinout}
\funcarg{krb5_contex...
..._data *}{outbuf}
\funcinout
\funcarg{krb5_replay_data *}{outdata}
\end{funcdecl}

Parses a KRB_SAFE message from inbuf, placing the data in *outbuf after verifying its integrity.

The keyblock used for verifying the integrity of the message is taken from the auth_context recv_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., outbufdata 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:

Returns system errors, integrity errors.


\begin{funcdecl}{krb5_mk_priv}{krb5_error_code}{\funcinout}
\funcarg{krb5_contex...
...uncarg{krb5_data *}{outbuf}
\funcarg{krb5_replay_data *}{outdata}
\end{funcdecl}

Formats a KRB_PRIV message into outbuf. Behaves similarly to krb5_mk_safe, but the message is encrypted and integrity-protected rather than just integrity-protected.

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.

Symbol Meaning
KRB5_AUTH_CONTEXT_DO_TIME Use timestamps in replay cache
KRB5_AUTH_CONTEXT_RET_TIME Use timestamps in output data
KRB5_AUTH_CONTEXT_DO_SEQUENCE Use sequence numbers
  in replay cache
KRB5_AUTH_CONTEXT_RET_SEQUENCE Use sequence numbers
  in replay cache and output data

Returns system errors, encryption errors.


\begin{funcdecl}{krb5_rd_priv}{krb5_error_code}{\funcinout}
\funcarg{krb5_contex...
...cout
\funcarg{krb5_data *}{outbuf}
\funcarg{krb5_data *}{outdata}
\end{funcdecl}

Parses a KRB_PRIV message from inbuf, placing the data in *outbuf after decrypting it. Behaves similarly to krb5_rd_safe, but the message is decrypted rather than integrity-checked.

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.

Returns system errors, integrity errors.


next up previous contents index
Next: Miscellaneous main functions Up: Main functions Previous: Principal access functions   Contents   Index
Autobuild 2009-09-05