krb5_rd_req_verify (process a Kerberos AP_REQ message and verify checksum data)

z/OS Integrated Security Services Network Authentication Service Programming

krb5_rd_req_verify (process a Kerberos AP_REQ message and verify checksum data)

z/OS Integrated Security Services Network Authentication Service Programming
SC23-6787-00

Purpose

Processes a Kerberos AP_REQ message and verifies the application data checksum

Format

#include <skrb/krb5.h>
krb5_error_code krb5_rd_req_verify (
    krb5_context                                   context,
    krb5_auth_context *                            auth_context,
    const krb5_data *                              in_data,
    const krb5_data *                              appl_data,
    krb5_const_principal                           server,
    krb5_keytab                                    keytab,
    krb5_flags *                                   ap_req_options,
    krb5_ticket **                                 ticket)

Parameters

Input

context: Specifies the Kerberos context.
in_data: Specifies the buffer containing the AP_REQ message.
appl_data: Specifies the application data to be verified. The checksum is computed for the supplied data and compared to the checksum obtained from the authenticator. Specify NULL if the checksum is not to be verified.
server: Specifies the server name. The server principal in the AP_REQ must be the same as the principal specified by this parameter. Specify NULL if any server principal is acceptable.
keytab: Specifies the key table that contains the server key. The default key table is used if NULL is specified for this parameter.

Input/Output

auth_context: Specifies the authentication context. A new authentication context is created and returned in this parameter if the value is NULL.

Output

ap_req_options: Returns the options from the AP_REQ message. Specify NULL for this parameter if the options are not needed.
ticket: Returns the ticket from the AP_REQ message. Specify NULL for this parameter if the ticket is not needed. The krb5_free_ticket() routine should be called to release the ticket when it is no longer needed.

Usage

The krb5_rd_req_verify() routine processes an AP_REQ message generated by the partner application and verifies the application data checksum contained in the authenticator. The authenticator is extracted, validated, and stored in the authentication context. If the server parameter is not NULL and no replay cache is associated with the authentication context, the Kerberos runtime creates a replay cache and stores the cache handle in the authentication context..

If the authentication context contains a keyblock, it is used to decrypt the ticket in the AP_REQ message. This is useful for user-to-user authentication. If the authentication context does not contain a keyblock, the key table specified on the function call is used to obtain the decryption key.

The client in the authenticator must match the client in the ticket. If the remote address has been set in the authentication context, the request must have come from that address. If a replay cache handle is stored in the authentication context, the new authenticator is stored in the cache after checking for replay.

If no errors are detected, the authenticator, subsession key, and remote sequence number are stored in the authentication context. If AP_OPTS_MUTUAL_REQUIRED is specified in the AP_REQ message, the local sequence number is XORed with the remote sequence number.

The function return value is zero if no errors occurred. Otherwise, it is a Kerberos error code.

If the Kerberos security server is running on the same system as the application, it is not necessary to provide a key table. Instead, the krb5_rd_req_verify() routine uses the local instance of the Kerberos security server to decrypt the ticket. In order to activate this support, the KRB5_SERVER_KEYTAB environment variable needs to be set to one of the following values and, depending on the value set, the following requirements must also be met: krb5_recvauth

If the KRB5_SERVER_KEYTAB environment variable is set to 1:
1. NULL must be specified for the key table parameter on the call to the krb5_rd_req_verify() routine.
2. The application must be running with a user or group that has at least READ access to the IRR.RUSERMAP resource in the FACILITY class.
3. The Kerberos principal associated with the current system identity must match the server principal in the ticket.
If the KRB5_SERVER_KEYTAB environment variable is set to 2:
1. NULL must be specified for the key table parameter on the call to the krb5_rd_req_verify() routine.
2. The current system identity must have an associated Kerberos principal that matches the server principal in the ticket or have at least READ access in the KERBLINK class to the server principal in the ticket.

Note: If requirement 2a is satisfied but 2b is not, the krb5_rd_req_verify() routine will not fall back to using a keytab file but will fail.