krb5_mk_priv()--Create Kerberos KRB_PRIV Message

 #include <krb5.h>

 krb5_error_code krb5_mk_priv(
     krb5_context       context,
     krb5_auth_context      auth_context,  
     krb5_const krb5_data *   userdata,
     krb5_data *      out_data,
     krb5_replay_data *     replay_data);  

The krb5_mk_priv() function creates a Kerberos KRB_PRIV message using data supplied by the application. The krb5_mk_priv() routine is similar to the krb5_mk_safe() routine, but the message is encrypted and integrity-protected rather than just integrity-protected. The krb5_rd_priv() routine decrypts and validates the message integrity.

Authorities

No authorities are required.

Parameters

context  (Input)

The Kerberos context.

auth_context  (Input)

The authentication context.

userdata  (Input)

The application data for the KRB_PRIV message.

out_data  (Output)

The KRB_PRIV message. The krb5_free_data_contents() routine should be called to release the storage pointed to by the data field of the krb5_data structure when it is no longer needed.

replay_data  (Output)

Replay information returned to the caller. This parameter is required if the KRB5_AUTH_CONTEXT_RET_TIME (x'00000002') or KRB5_AUTH_CONTEXT_RET_SEQUENCE (x'00000008') flag is set in the authentication context. Otherwise, NULL may be specified for this parameter.

Return Value

If no errors occur, the return value is 0. Otherwise, a Kerberos error code is returned.

Error Messages

Usage Notes

1. The authentication context specifies the checksum type, the data encryption type, the keyblock used to seed the checksum, the addresses of the sender and receiver, and the replay cache.
   
   
2. Use the krb5_auth_con_setrcache() routine to set the replay cache in the authentication context.
   
   
3. The local address in the authentication context is used to create the KRB_PRIV message and must be present. The remote address is optional. Use the krb5_auth_con_genaddrs() routine or a combination of the krb5_auth_con_setaddrs() and the krb5_auth_con_setports() routines to set the addresses in the authentication context. If the remote address is set, then the local address also must be set in the authentication context that is used for the krb5_rd_priv() routine. If port numbers are set, then they also must be set in the authentication context used for the krb5_rd_priv() routine.
   
   
4. The authentication context flags determine whether sequence numbers or timestamps should be used to identify the message. Use the krb5_auth_con_set_flags() routine to set the authentication context flags.
   
   
5. The encryption type is taken from the keyblock in the authentication context. If the initial vector has been set in the authentication context, it is used as the initialization vector for the encryption (if the encryption type supports initialization) and its contents are replaced with the last block of encrypted data upon return. Use the krb5_auth_con_setivector() routine or the krb5_auth_con_initvector() routine to modify the initial vector in the authentication context.
   
   
6. If timestamps are used (KRB5_AUTH_CONTEXT_DO_TIME (x'00000001') is set), an entry describing the message is entered in the replay cache so the caller can detect if this message is sent back by an attacker. An error is returned if the authentication context does not specify a replay cache.
   
   
7. If sequence numbers are used (KRB5_AUTH_CONTEXT_DO_SEQUENCE (x'00000004') or KRB5_AUTH_CONTEXT_RET_SEQUENCE (x'00000008') is set), the local sequence number in the authentication context is placed in the protected message as its sequence number.
   
   
8. The Kerberos protocol runtime provides no concurrency control for the authentication context. If the application wants to use the same authentication context in multiple threads, it is the responsibility of the application to serialize access to the authentication context so that only a single thread is accessing the authentication context at any time. Because message sequence numbers are contained in the authentication context, this serialization needs to be extended to encompass the message exchange between the two applications. Otherwise, message sequence errors are liable to occur if the messages are delivered out of sequence.

[ Back to top | Security APIs | UNIX-Type APIs | APIs by category ]