[an error occurred while processing this directive]

HP OpenVMS Systems Documentation
Content starts here
HP Open Source Security for OpenVMS Volume 3: Kerberos > Chapter 6 KRB5 (Kerberos V5) Application Programming Interface

krb5_sendauth — Send authenticated message

 » Table of Contents

 » Glossary

 » Index

spacerspacerspacer
spacer
spacer
  		 
 

C Prototype

krb5_error_code krb5_sendauth(
         krb5_context           context,
         krb5_auth_context      *auth_context,
         krb5_pointer           fd,
         char                   *appl_version,
         krb5_principal         client,
         krb5_principal         server,
         krb5_flags             ap_req_options,
         krb5_data              *in_data,
         krb5_creds             *in_creds,
         krb5_ccache            ccache,
         krb5_error             **error,
         krb5_ap_rep_enc_part   **rep_result,
         krb5_creds             **out_creds );

Arguments

context (input/output) 

The context structure.

auth_context (input/output) 

Authentication context.

fd (input) 

A pointer to a file descriptor describing the network socket.

appl_version (input) 

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

client (input) 

The Kerberos principal for the client. Ignored if in_creds is nonNULL.

server (input) 

The Kerberos principal for the server. Ignored if in_creds is nonNULL.

ap_req_options (input) 

Specifies the KRB_AP_REQ flags that should be passed to krb5_mk_req. Valid flags are:

AP_OPTS_USE_SESSION_KEY

AP_OPTS_MUTUAL_REQUIRED

AP_OPTS_USE_SUBKEY

in_data (input 

The data to be sent to the server.

in_creds (input) 

Input credentials, or NULL.

ccache (input/output)  

The credentials cache.

error (output) 

If nonNULL, contains the error packet returned from the server. This error should be freed with krb5_free_error.

rep_result (output) 

If nonNULL, contains the result of the mutual authentication exchange. The *rep_result argument should be freed with krb5_free_ap_rep_enc_part when the caller is done with it.

out_creds (output) 

If nonNULL, the retrieved credentials.

Description

This routine provides a convenient means for client and server programs to send authenticated messages to one another through network connections. The krb5_sendauth routine sends an authenticated ticket from the client program to the server program using the network connection specified by fd. In the MIT UNIX and OpenVMS implementations, fd should be a pointer to a file descriptor describing the network socket.

The arguments client and server specify the Kerberos principals for the client and the server. They are ignored if in_creds is nonNULL. Otherwise, server must be nonNULL, 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 argument specifies the options that should be passed to krb5_mk_req. If ap_req_options specifies MUTUAL_REQUIRED, then krb5_sendauth will perform a mutual authentication exchange, and if rep_result is nonNULLl, 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 nonNULL, 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 nonzero, 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 later, and out_creds, if not NULL, is filled in with the retrieved credentials.

The ccache argument specifies the credential cache to use when one is needed (that is, 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 nonNULL, 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 nonNULL, 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.

Return Values

This routine returns the following KRB5 status code:

0

Successful completion.



krb5_salttype_to_string — Convert a salttype (krb5_int32) to a string
  		 


krb5_set_default_realm — Sets the default realm