TE_verify_reg Kernel Service

Purpose

Registers a callout handler for Trusted Execution (TE) file verification during the exec() functions, kernel extension loads, and library load operations.

Syntax

#include <sys/file.h>
typedef int (*TE_verify)(char *, int, struct file *);

int TE_verify_reg(TE_verify verify_fn, uint_64 options)

Parameters

verify_fn: Specifies the callout function to be called for the verification checks with the exec() functions for the AIX® kernel level, loading of kernel extensions, and library loading events instead of the default AIX Trusted Execution method.
For more information about the function definition of this callout handler, see the alt_verify_fn section.
options: Specifies a bit mask of registration options. The options parameter is not defined currently. The caller must set the options parameter to 0.

Description

The TE_verify_reg kernel service registers a callout handler for the AIX Trusted Execution framework.

After a callout handler is registered, the handler is invoked for the exec() functions, loading kernel extensions, and library load-time checks for Trusted Execution in the AIX kernel. The default AIX Trusted Execution logic is not invoked and any AIX-configured policies for Trusted Execution not applied. The registered alternative handler becomes the active Trusted Execution engine for AIX to provide security policy as implemented in the handler and its associated management components.

After a callout handler is registered with the TE_verify_reg kernel service, subsequent invocation of the TE_verify_reg service returns with an error code of EEXIST.

You must have root authority to call the TE_verify_reg kernel service.

Return values

On successful completion, the TE_verify_reg service kernel service returns a value of 0.

The following error codes are returned on failure:

EEXIST: The callout handler is already registered.
EPERM: The caller does not have permission to invoke this function.
EINVAL: The callout handler or the options parameters are invalid.

Execution environment

The TE_verify_reg kernel service can be called from the process environment only.

The registered alternative Trusted Execution handler must conform to the behaviors that are described in the following section.

alt_verify_fn callout function

Purpose

Verifies the integrity of a file.

Syntax

#include <sys/file.h>

#define VERIFY_EXECUTABLES 2
#define VERIFY_SHLIBS 3
#define VERIFY_SCRIPTS 4
#define VERIFY_KERNEXTS 5

int alt_TE_verify (char *path_name, int type, struct file *path_fp)

Description

The alt_TE_verify callout function is started from the loader and the program execution path to verify the integrity of a file that is specified under the path_name parameter. The path_fp parameter is a file pointer to the file object that is associated with the path_name parameter.

The type parameter can be one of the following values:

VERIFY_EXECUTABLES: This value is specified when the alt_TE_verify function is started from the kernel exec() function to verify executable programs.
VERIFY_SCRIPTS: This value is specified when the alt_TE_verify function is started from the exec() function and the path_name value is a shell file.
VERIFY_KERNEXTS: This value is specified when the alt_TE_verify function is started for loading a kernel extension.
VERIFY_SHLIBS: This value is specified when the alt_TE_verify function is started for loading a shared library.

Input parameters

path_name: Specifies the path to the file that must be verified.
type: Indicates the type of verification that must be performed.
path_fp: Indicates the file pointer to the path_name file.

Return values

0: Indicates that the verification completed successfully.
Nonzero: Indicates that the verification failed.

The nonzero return value blocks loading of the file. An error number is set by the AIX kernel functions that start the alt_verify_fn callout function.