Chapter 5 GSS-API Client Example
This chapter presents a walk-through of a typical GSS-API client application.
The following topics are covered:
GSSAPI Client Example Overview
The sample client-side program gss-client creates a security context with a server, establishes security parameters, and sends the message string to the server. The program uses a simple TCP-based sockets connection to make the connection.
The following sections provide a step-by-step description of how gss-client works. Because gss-client is a sample program that has been designed to show off GSSAPI functionality, only relevant parts of the program are discussed in detail. The complete source code for the two applications appears in the appendix and can be downloaded from:
http://developers.sun.com/prodtech/solaris/downloads/index.html
GSSAPI Client Example Structure
-
Parses the command line.
-
Creates an object ID (OID) for a mechanism, if a mechanism is specified. Otherwise, the default mechanism is used, which is most commonly the case.
-
Creates a connection to the server.
-
Establishes a security context.
-
Wraps and sends the message.
-
Verifies that the message has been “signed” correctly by the server.
-
Deletes the security context.
The gss-client application performs the following steps:
Running the GSSAPI Client Example
The gss-client example takes this form on the command line:
gss-client [-port port] [-d] [-mech mech] host service-name [-f] msg |
-
port – The port number for making the connection to the remote machine that is specified by host.
-
-d flag – Causes security credentials to be delegated to the server. Specifically, the deleg-flag variable is set to the GSS-API value GSS_C_DELEG_FLAG. Otherwise, deleg-flag is set to zero.
-
mech – The name of the security mechanism, such as Kerberos v5 to be used. If no mechanism is specified, the GSS-API uses a default mechanism.
-
host – The name of the server.
-
service-name – The name of the network service requested by the client. Some typical examples are the telnet, ftp, and login services.
-
msg – The string to send to the server as protected data. If the -f option is specified, then msg is the name of a file from which to read the string.
A typical command line for client application program might look like the following example:
% gss-client -port 8080 -d -mech kerberos_v5 erebos.eng nfs "ls" |
The following example does not specify a mechanism, port, or delegation:
% gss-client erebos.eng nfs "ls" |
GSSAPI Client Example: main() Function
As with all C programs, the outer shell of the program is contained in the entry-point function, main(). main() performs four functions:
-
Parses command-line arguments and assigns the arguments to variables.
-
Calls parse_oid() to create a GSS-API OID, object identifier, if a mechanism other than the default is to be used. The object identifier comes from the name of the security mechanism, provided that a mechanism name has been supplied.
-
Calls call_server(), which does the actual work of creating a context and sending data.
-
Releases the storage space for the OID if necessary, after the data is sent.
The source code for the main() routine is shown in the following example.
Note –
The source code for this example is also available through the Sun download center. See http://www.sun.com/download/products.xml?id=41912db5.
Example 5–1 gss-client Example: main()
int main(argc, argv)
int argc;
char **argv;
{
char *msg;
char service_name[128];
char hostname[128];
char *mechanism = 0;
u_short port = 4444;
int use_file = 0;
OM_uint32 deleg_flag = 0, min_stat;
display_file = stdout;
/* Parse command-line arguments. */
argc--; argv++;
while (argc) {
if (strcmp(*argv, "-port") == 0) {
argc--; argv++;
if (!argc) usage();
port = atoi(*argv);
} else if (strcmp(*argv, "-mech") == 0) {
argc--; argv++;
if (!argc) usage();
mechanism = *argv;
} else if (strcmp(*argv, "-d") == 0) {
deleg_flag = GSS_C_DELEG_FLAG;
} else if (strcmp(*argv, "-f") == 0) {
use_file = 1;
} else
break;
argc--; argv++;
}
if (argc != 3)
usage();
if (argc > 1) {
strcpy(hostname, argv[0]);
} else if (gethostname(hostname, sizeof(hostname)) == -1) {
perror("gethostname");
exit(1);
}
if (argc > 2) {
strcpy(service_name, argv[1]);
strcat(service_name, "@");
strcat(service_name, hostname);
}
msg = argv[2];
/* Create GSSAPI object ID. */
if (mechanism)
parse_oid(mechanism, &g_mechOid);
/* Call server to create context and send data. */
if (call_server(hostname, port, g_mechOid, service_name,
deleg_flag, msg, use_file) < 0)
exit(1);
/* Release storage space for OID, if still allocated */
if (g_mechOid != GSS_C_NULL_OID)
(void) gss_release_oid(&min_stat, &gmechOid);
return 0;
}
Opening a Connection With the Server
The call_server() function uses the following code to make the connection with the server:
if ((s = connect_to_server(host, port)) < 0)
return -1;
s is a file descriptor, the int that is initially returned by a call to socket().
connect_to_server() is a simple function outside GSS-API that uses sockets to create a connection. The source code for connect_to_server() is shown in the following example.
Note –
The source code for this example is also available through the Sun download center. See http://www.sun.com/download/products.xml?id=41912db5.
Example 5–2 connect_to_server() Function
int connect_to_server(host, port)
char *host;
u_short port;
{
struct sockaddr_in saddr;
struct hostent *hp;
int s;
if ((hp = gethostbyname(host)) == NULL) {
fprintf(stderr, "Unknown host: %s\n", host);
return -1;
}
saddr.sin_family = hp->h_addrtype;
memcpy((char *)&saddr.sin_addr, hp->h_addr, sizeof(saddr.sin_addr));
saddr.sin_port = htons(port);
if ((s = socket(AF_INET, SOCK_STREAM, 0)) < 0) {
perror("creating socket");
return -1;
}
if (connect(s, (struct sockaddr *)&saddr, sizeof(saddr)) < 0) {
perror("connecting to server");
(void) close(s);
return -1;
}
return s;
}
Establishing a Security Context With the Server
After the connection is made, call_server() uses the function client_establish_context() to create the security context, as follows:
if (client_establish_context(s, service-name, deleg-flag, oid, &context,
&ret-flags) < 0) {
(void) close(s);
return -1;
}
-
s is a file descriptor that represents the connection that is established by connect_to_server().
-
service-name is the requested network service.
-
deleg-flag specifies whether the server can act as a proxy for the client.
-
oid is the mechanism.
-
context is the context to be created.
-
ret-flags is an int that specifies any flags to be returned by the GSS-API function gss_init_sec_context().
The client_establish_context() performs the following tasks:
-
Translates the service name into internal GSSAPI format
-
Performs a loop of token exchanges between the client and the server until the security context is complete
Translating a Service Name into GSS-API Format
The first task that client_establish_context() performs is to translate the service name string to internal GSS-API format by using gss_import_name().
Example 5–3 client_establish_context() – Translate Service Name
/*
* Import the name into target_name. Use send_tok to save
* local variable space.
*/
send_tok.value = service_name;
send_tok.length = strlen(service_name) + 1;
maj_stat = gss_import_name(&min_stat, &send_tok,
(gss_OID) GSS_C_NT_HOSTBASED_SERVICE, &target_name);
if (maj_stat != GSS_S_COMPLETE) {
display_status("parsing name", maj_stat, min_stat);
return -1;
}
gss_import_name() takes the name of the service, which is stored in an opaque GSS_API buffer send_tok, and converts the string to the GSS_API internal name target_name. send_tok is used to save space instead of declaring a new gss_buffer_desc. The third argument is a gss_OID type that indicates the send_tok name format. This example uses GSS_C_NT_HOSTBASED_SERVICE, which means a service of the format service@host. See Name Types for other possible values for this argument.
Establishing a Security Context for GSS-API
Once the service has been translated to GSS-API internal format, the context can be established. To maximize portability, establishing context should always be performed as a loop.
Before entering the loop, client_establish_context() initializes the context and the token_ptr parameter. There is a choice in the use of token_ptr. token_ptr can point either to send_tok, the token to be sent to the server, or to recv_tok, the token that is sent back by the server.
Inside the loop, two items are checked:
-
The status that is returned by gss_init_sec_context()
The return status catches any errors that might require the loop to be aborted. gss_init_sec_context() returns GSS_S_CONTINUE_NEEDED if and only if the server has another token to send.
-
The size of token to be sent to the server, which is generated by gss_init_sec_context()
A token size of zero indicates that no more information exists that can be sent to the server and that the loop can be exited. The token size is determined from token_ptr.
The following pseudocode describes the loop:
do
gss_init_sec_context()
if no context was created
exit with error;
if the status is neither "complete" nor "in process"
release the service namespace and exit with error;
if there is a token to send to the server, that is, the size is nonzero
send the token;
if sending the token fails,
release the token and service namespaces. Exit with error;
release the namespace for the token that was just sent;
if the context is not completely set up
receive a token from the server;
while the context is not completeThe loop starts with a call to gss_init_sec_context(), which takes the following arguments:
-
The status code to be set by the underlying mechanism.
-
The credential handle. The example uses GSS_C_NO_CREDENTIAL to act as a default principal.
-
gss-context, which represents the context handle to be created.
-
target-name of the service, as a GSS_API internal name.
-
oid, the ID for the mechanism.
-
Request flags. In this case, the client requests that the server authenticate itself, that message-duplication be turned on, and that the server act as a proxy if requested.
-
No time limit for the context.
-
No request for channel bindings.
-
token_ptr, which points to the token to be received from the server.
-
The mechanism actually used by the server. The mechanism is set to NULL here because the application does not use this value.
-
&send_tok, which is the token that gss_init_sec_context() creates to send to the server.
-
Return flags. Set to NULL because they are ignored in this example.
Note –
The client does not need to acquire credentials before initiating a context. On the client side, credential management is handled transparently by the GSS-API. That is, the GSS-API knows how to get credentials that are created by this mechanism for this principal. As a result, the application can pass gss_init_sec_context() a default credential. On the server side, however, a server application must explicitly acquire credentials for a service before accepting a context. See Acquiring Credentials.
After checking that a context or part of one exists and that gss_init_sec_context() is returning valid status, connect_to_server() checks that gss_init_sec_context() has provided a token to send to the server. If no token is present, the server has signalled that no other tokens are needed. If a token has been provided, then that token must be sent to the server. If sending the token fails, the namespaces for the token and service cannot be determined, and connect_to_server() exits. The following algorithm checks for the presence of a token by looking at the length:
if (send_tok_length != 0) {
if (send_token(s, &send_tok) < 0) {
(void) gss_release_buffer(&min_stat, &send_tok);
(void) gss_release_name(&min_stat, &target_name);
return -1;
}
}
send_token() is not a GSS-API function and needs to be written by the user. The send_token() function writes a token to the file descriptor. send_token() returns 0 on success and –1 on failure. GSS-API does not send or receive tokens itself. The calling applications are responsible for sending and receiving any tokens that have been created by GSS-API.
The source code for the context establishment loop is provided below.
Note –
The source code for this example is also available through the Sun download center. See http://www.sun.com/download/products.xml?id=41912db5.
Example 5–4 Loop for Establishing Contexts
/*
* Perform the context establishment loop.
*
* On each pass through the loop, token_ptr points to the token
* to send to the server (or GSS_C_NO_BUFFER on the first pass).
* Every generated token is stored in send_tok which is then
* transmitted to the server; every received token is stored in
* recv_tok, which token_ptr is then set to, to be processed by
* the next call to gss_init_sec_context.
*
* GSS-API guarantees that send_tok's length will be non-zero
* if and only if the server is expecting another token from us,
* and that gss_init_sec_context returns GSS_S_CONTINUE_NEEDED if
* and only if the server has another token to send us.
*/
token_ptr = GSS_C_NO_BUFFER;
*gss_context = GSS_C_NO_CONTEXT;
1234567890123456789012345678901234567890123456789012345678901234567890123456
do {
maj_stat =
gss_init_sec_context(&min_stat, GSS_C_NO_CREDENTIAL,
gss_context, target_name, oid,
GSS_C_MUTUAL_FLAG | GSS_C_REPLAY_FLAG | deleg_flag,
0, NULL, /* no channel bindings */
token_ptr, NULL, /* ignore mech type */
&send_tok, ret_flags, NULL); /* ignore time_rec */
if (gss_context == NULL){
printf("Cannot create context\n");
return GSS_S_NO_CONTEXT;
}
if (token_ptr != GSS_C_NO_BUFFER)
(void) gss_release_buffer(&min_stat, &recv_tok);
if (maj_stat!=GSS_S_COMPLETE && maj_stat!=GSS_S_CONTINUE_NEEDED) {
display_status("initializing context", maj_stat, min_stat);
(void) gss_release_name(&min_stat, &target_name);
return -1;
}
if (send_tok.length != 0){
fprintf(stdout, "Sending init_sec_context token (size=%ld)...",
send_tok.length);
if (send_token(s, &send_tok) < 0) {
(void) gss_release_buffer(&min_stat, &send_tok);
(void) gss_release_name(&min_stat, &target_name);
return -1;
}
}
(void) gss_release_buffer(&min_stat, &send_tok);
if (maj_stat == GSS_S_CONTINUE_NEEDED) {
fprintf(stdout, "continue needed...");
if (recv_token(s, &recv_tok) < 0) {
(void) gss_release_name(&min_stat, &target_name);
return -1;
}
token_ptr = &recv_tok;
}
printf("\n");
} while (maj_stat == GSS_S_CONTINUE_NEEDED);
For more information on how send_token() and recv_token() work, see Miscellaneous GSS-API Sample Functions.
Miscellaneous GSSAPI Context Operations on the Client Side
As a sample program, gss-client performs some functions for demonstration purposes. The following source code is not essential for the basic task, but is provided to demonstrate these other operations:
-
Saving and restoring the context
-
Displaying context flags
-
Obtaining the context status
The source code for these operations is shown in the following example.
Note –
The source code for this example is also available through the Sun download center. See http://www.sun.com/download/products.xml?id=41912db5.
Example 5–5 gss-client: call_server() Establish Context
/* Save and then restore the context */
maj_stat = gss_export_sec_context(&min_stat,
&context,
&context_token);
if (maj_stat != GSS_S_COMPLETE) {
display_status("exporting context", maj_stat, min_stat);
return -1;
}
maj_stat = gss_import_sec_context(&min_stat,
&context_token,
&context);
if (maj_stat != GSS_S_COMPLETE) {
display_status("importing context", maj_stat, min_stat);
return -1;
}
(void) gss_release_buffer(&min_stat, &context_token);
/* display the flags */
display_ctx_flags(ret_flags);
/* Get context information */
maj_stat = gss_inquire_context(&min_stat, context,
&src_name, &targ_name, &lifetime,
&mechanism, &context_flags,
&is_local,
&is_open);
if (maj_stat != GSS_S_COMPLETE) {
display_status("inquiring context", maj_stat, min_stat);
return -1;
}
if (maj_stat == GSS_S_CONTEXT_EXPIRED) {
printf(" context expired\n");
display_status("Context is expired", maj_stat, min_stat);
return -1;
}
Wrapping and Sending a Message
The gss-client application needs to wrap, that is, encrypt the data before the data can be sent. The application goes through the following steps to wrap the message:
-
Determines the wrap size limit. This process ensures that the wrapped message can be accommodated by the protocol.
-
Obtains the source and destination names. Translates the names from object identifiers to strings.
-
Gets the list of mechanism names. Translates the names from object identifiers to strings.
-
Inserts the message into a buffer and wraps the message.
-
Sends the message to the server.
The following source code wraps a message.
Note –
The source code for this example is also available through the Sun download center. See http://www.sun.com/download/products.xml?id=41912db5.
Example 5–6 gss-client Example: call_server() – Wrap Message
/* Test gss_wrap_size_limit */
maj_stat = gss_wrap_size_limit(&min_stat, context, conf_req_flag,
GSS_C_QOP_DEFAULT, req_output_size, &max_input_size);
if (maj_stat != GSS_S_COMPLETE) {
display_status("wrap_size_limit call", maj_stat, min_stat);
} else
fprintf (stderr, "gss_wrap_size_limit returned "
"max input size = %d \n"
"for req_output_size = %d with Integrity only\n",
max_input_size , req_output_size , conf_req_flag);
conf_req_flag = 1;
maj_stat = gss_wrap_size_limit(&min_stat, context, conf_req_flag,
GSS_C_QOP_DEFAULT, req_output_size, &max_input_size);
if (maj_stat != GSS_S_COMPLETE) {
display_status("wrap_size_limit call", maj_stat, min_stat);
} else
fprintf (stderr, "gss_wrap_size_limit returned "
" max input size = %d \n" "for req_output_size = %d with "
"Integrity & Privacy \n", max_input_size , req_output_size );
maj_stat = gss_display_name(&min_stat, src_name, &sname, &name_type);
if (maj_stat != GSS_S_COMPLETE) {
display_status("displaying source name", maj_stat, min_stat);
return -1;
}
maj_stat = gss_display_name(&min_stat, targ_name, &tname,
(gss_OID *) NULL);
if (maj_stat != GSS_S_COMPLETE) {
display_status("displaying target name", maj_stat, min_stat);
return -1;
}
fprintf(stderr, "\"%.*s\" to \"%.*s\", lifetime %u, flags %x, %s, %s\n",
(int) sname.length, (char *) sname.value, (int) tname.length,
(char *) tname.value, lifetime, context_flags,
(is_local) ? "locally initiated" : "remotely initiated",
(is_open) ? "open" : "closed");
(void) gss_release_name(&min_stat, &src_name);
(void) gss_release_name(&min_stat, &targ_name);
(void) gss_release_buffer(&min_stat, &sname);
(void) gss_release_buffer(&min_stat, &tname);
maj_stat = gss_oid_to_str(&min_stat, name_type, &oid_name);
if (maj_stat != GSS_S_COMPLETE) {
display_status("converting oid->string", maj_stat, min_stat);
return -1;
}
fprintf(stderr, "Name type of source name is %.*s.\n", (int) oid_name.length,
(char *) oid_name.value);
(void) gss_release_buffer(&min_stat, &oid_name);
/* Now get the names supported by the mechanism */
maj_stat = gss_inquire_names_for_mech(&min_stat, mechanism, &mech_names);
if (maj_stat != GSS_S_COMPLETE) {
display_status("inquiring mech names", maj_stat, min_stat);
return -1;
}
maj_stat = gss_oid_to_str(&min_stat, mechanism, &oid_name);
if (maj_stat != GSS_S_COMPLETE) {
display_status("converting oid->string", maj_stat, min_stat);
return -1;
}
mechStr = (char *)__gss_oid_to_mech(mechanism);
fprintf(stderr, "Mechanism %.*s (%s) supports %d names\n", (int) oid_name.length,
(char *) oid_name.value, (mechStr == NULL ? "NULL" : mechStr),
mech_names->count);
(void) gss_release_buffer(&min_stat, &oid_name);
for (i=0; i < mech_names->count; i++) {
maj_stat = gss_oid_to_str(&min_stat, &mech_names->elements[i], &oid_name);
if (maj_stat != GSS_S_COMPLETE) {
display_status("converting oid->string", maj_stat, min_stat);
return -1;
}
fprintf(stderr, " %d: %.*s\n", i, (int) oid_name.length, (
char *) oid_name.value);
(void) gss_release_buffer(&min_stat, &oid_name);
}
(void) gss_release_oid_set(&min_stat, &mech_names);
if (use_file) {
read_file(msg, &in_buf);
} else {
/* Wrap the message */
in_buf.value = msg;
in_buf.length = strlen(msg) + 1;
}
if (ret_flag & GSS_C_CONF_FLAG) {
state = 1;
else
state = 0;
}
maj_stat = gss_wrap(&min_stat, context, 1, GSS_C_QOP_DEFAULT, &in_buf,
&state, &out_buf);
if (maj_stat != GSS_S_COMPLETE) {
display_status("wrapping message", maj_stat, min_stat);
(void) close(s);
(void) gss_delete_sec_context(&min_stat, &context, GSS_C_NO_BUFFER);
return -1;
} else if (! state) {
fprintf(stderr, "Warning! Message not encrypted.\n");
}
/* Send to server */
if (send_token(s, &out_buf) < 0) {
(void) close(s);
(void) gss_delete_sec_context(&min_stat, &context, GSS_C_NO_BUFFER);
return -1;
}
(void) gss_release_buffer(&min_stat, &out_buf);
Reading and Verifying a Signature Block From a GSS-API Client
The gss-client program can now test the validity of the message that was sent. The server returns the MIC for the message that was sent. The message can be retrieved with the recv_token().
The gss_verify_mic() function is then used to verify the message's signature, that is, the MIC. gss_verify_mic() compares the MIC that was received with the original, unwrapped message. The received MIC comes from the server's token, which is stored in out_buf. The MIC from the unwrapped version of the message is held in in_buf. If the two MICs match, the message is verified. The client then releases the buffer for the received token, out_buf.
The process of reading and verifying a signature block is demonstrated in the following source code.
Note –
The source code for this example is also available through the Sun download center. See http://www.sun.com/download/products.xml?id=41912db5.
Example 5–7 gss-client Example – Read and Verify Signature Block
/* Read signature block into out_buf */
if (recv_token(s, &out_buf) < 0) {
(void) close(s);
(void) gss_delete_sec_context(&min_stat, &context, GSS_C_NO_BUFFER);
return -1;
}
/* Verify signature block */
maj_stat = gss_(&min_stat, context, &in_buf,
&out_buf, &qop_state);
if (maj_stat != GSS_S_COMPLETE) {
display_status("verifying signature", maj_stat, min_stat);
(void) close(s);
(void) gss_delete_sec_context(&min_stat, &context, GSS_C_NO_BUFFER);
return -1;
}
(void) gss_release_buffer(&min_stat, &out_buf);
if (use_file)
free(in_buf.value);
printf("Signature verified.\n");
Deleting the Security Context
The call_server() function finishes by deleting the context and returning to the main() function.
Note –
The source code for this example is also available through the Sun download center. See http://www.sun.com/download/products.xml?id=41912db5.
Example 5–8 gss-client Example: call_server() – Delete Context
/* Delete context */
maj_stat = gss_delete_sec_context(&min_stat, &context, &out_buf);
if (maj_stat != GSS_S_COMPLETE) {
display_status("deleting context", maj_stat, min_stat);
(void) close(s);
(void) gss_delete_sec_context(&min_stat, &context, GSS_C_NO_BUFFER);
return -1;
}
(void) gss_release_buffer(&min_stat, &out_buf);
(void) close(s);
return 0;
- © 2010, Oracle Corporation and/or its affiliates