<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation"> <title>krb5_rd_safe()--Process Kerberos KRB_SAFE Message</title> <!-- Begin Header Records --> <!-- All rights reserved. Licensed Materials Property of IBM --> <!-- US Government Users Restricted Rights --> <!-- Use, duplication or disclosure restricted by --> <!-- GSA ADP Schedule Contract with IBM Corp. --> <!-- Change History: --> <!-- YYMMDD USERID Change description --> <!-- Created by Kent Hofer for V5R1 --> <!-- Edited by Kersten Jan 02 --> <link rel="stylesheet" type="text/css" href="../rzahg/ic.css"> </head> <body> <!-- End Header Records --> <!--Java sync-link--> <script type="text/javascript" language="Javascript" src="../rzahg/synch.js"> </script> <a name="Top_Of_Page"></a> <h2>krb5_rd_safe()--Process Kerberos KRB_SAFE Message</h2> <div class="box" style="width: 70%;"> <br> Syntax <pre> #include <krb5.h> krb5_error_code krb5_rd_safe( krb5_context <em>context</em>, krb5_auth_context <em>auth_context</em>, krb5_const krb5_data * <em>in_data</em>, krb5_data * <em>out_data</em>, krb5_replay_data * <em>replay_data</em>); </pre> Service Program Name: QSYS/QKRBGSS<br> <!-- iddvc RMBR --> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Threadsafe: Conditional. See <a href="#usage_notes">Usage notes</a>.<br> <!-- iddvc RMBR --> <br> </div> <p>The <strong>krb5_rd_safe()</strong> function processes a Kerberos KRB_SAFE message and extracts the application data after verifying its integrity. If timestamps are being used, the message is stored in the replay cache associated with the authentication context.</p> <br> <h3>Authorities</h3> <p>No authorities are required.</p> <br> <h3>Parameters</h3> <dl> <dt><strong>context</strong> (Input)</dt> <dd>The Kerberos context.<br> <br> </dd> <dt><strong>auth_context</strong> (Input)</dt> <dd>The authentication context.<br> <br> </dd> <dt><strong>in_data</strong> (Input)</dt> <dd>The buffer containing the KRB_SAFE message.<br> <br> </dd> <dt><strong>out_data</strong> (Output)</dt> <dd>The application data. The <strong>krb5_free_data_contents()</strong> routine should be called to release the storage pointed to by the <em>data</em> field of the krb5_data structure when it is no longer needed.<br> <br> </dd> <dt><strong>replay_data</strong> (Output)</dt> <dd>Replay information returned to the caller. This parameter is required if the <strong>KRB5_AUTH_CONTEXT_RET_TIME</strong> (x'00000002') or <strong>KRB5_AUTH_CONTEXT_RET_SEQUENCE</strong> (x'00000008') flag is set in the authentication context. Otherwise, <strong>NULL</strong> may be specified for this parameter.</dd> </dl> <br> <h3>Return Value</h3> <p>If no errors occur, the return value is 0. Otherwise, a Kerberos error code is returned.</p> <br> <h3>Error Messages</h3> <table width="100%" cellpadding="5"> <tr> <th align="left" valign="top">Message ID</th> <th align="left" valign="top">Error Message Text</th> </tr> <tr> <td width="15%" valign="top">CPE3418 E</td> <td width="85%" valign="top">Possible APAR condition or hardware failure.</td> </tr> </table> <br> <br> <h3><a name="usage_notes">Usage Notes</a></h3> <ol> <li>The keyblock that is used for verifying message integrity is obtained from the authentication context. The first non-NULL keyblock is used by checking the local_subkey, remote_subkey, or keyblock, in that order.<br> <br> </li> <li>The remote address in the authentication context must be present. It specifies the address of the sender. Use the <strong>krb5_auth_con_genaddrs()</strong> routine or the <strong>krb5_auth_con_setaddrs()</strong> routine to set the remote address. If the port number was set in the authentication context used for the <strong>krb5_mk_safe()</strong> routine, then the port number also must be set in the authentication context used for the <strong>krb5_rd_safe()</strong> routine. An error is returned if the address in the message does not match the remote address in the authentication context.<br> <br> </li> <li>The local address in the authentication context is optional. If it is present, then it must match the receiver address in the message. Otherwise, the receiver message in the message must match one of the local addresses returned by the <strong>krb5_os_localaddr()</strong> routine. If the port number was set in the authentication context used for the <strong>krb5_mk_safe()</strong> routine, then both the local address and the local port must be set in the authentication context used for the <strong>krb5_rd_priv()</strong> routine. Use the <strong>krb5_auth_con_genaddrs()</strong> routine or a combination of the <strong>krb5_auth_con_setaddrs()</strong> and <strong>krb5_auth_con_setports()</strong> routines to set the local address and local port in the authentication context.<br> <br> </li> <li>Use the <strong>krb5_auth_con_setrcache()</strong> routine to set the replay cache in the authentication context.<br> <br> </li> <li>If message sequence numbers are being used (<strong>KRB5_AUTH_CONTEXT_DO_SEQUENCE</strong> (x'00000004') is set in the authentication context), the remote sequence number in the authentication context must match the sequence number in the message. Use the <strong>krb5_auth_con_setflags()</strong> routine to set the <strong>KRB5_AUTH_CONTEXT_DO_SEQUENCE</strong> flag.<br> <br> </li> <li>If timestamps are being used (<strong>KRB5_AUTH_CONTEXT_DO_TIME</strong> (x'00000001') is set in the authentication context), the timestamp in the message must be within the Kerberos clock skew for the current time. In addition, the message must not be found in the replay cache obtained from the authentication context. Use the <strong>krb5_auth_con_setflags()</strong> routine to set the <strong>KRB5_AUTH_CONTEXT_DO_TIME</strong> flag.<br> <br> </li> <li>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.</li> </ol> <br> <hr> API introduced: V5R1 <hr> <center> <table cellpadding="2" cellspacing="2"> <tr align="center"> <td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href= "sec.htm">Security APIs</a> <br> <a href="unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a> </td> </tr> </table> </center> </body> </html>