kkey_assign_private Kernel Service

Purpose

Requests a private kernel-key assignment.

Syntax

#include <sys/types.h>
#include <sys/skeys.h>
#include <sys/kerrno.h>

kerrno_t kkey_assign_private (id, instance, flags, kkey) char *id; long instance; unsigned long flags; kkey_t *kkey;

Parameters

Item	Description
id	Specifies a null-terminated string. The kkey_assign_private kernel service uses the string value to assign a private key. This normally contains a load module name associated with the calling kernel subsystem, but you can specify any unique string.
instance	Specifies a unique number for each private key requested by a subsystem. This must be an integer value starting from 0 and increases with each kernel-key requested.
flags	You must specify this parameter to zero.
kkey	Contains the returned assigned kernel key. The valid pointer must be a 4-byte aligned address (kkey_t’s natural alignment).

Description

The kkey_assign_private kernel service assigns a private kernel key to the caller. Private kernel keys are used to limit data accessibility by external kernel code. The kkey_assign_private kernel service distributes requests for private kernel keys among a predetermined range (from KKEY_PRIVATE1 to KKEY_PRIVATE32). The intention is to perform a uniform distribution on behalf of requests by multiple kernel subsystems. The assignment is made based on the id and instance parameters and might return the same private key to multiple callers. It might also return the same private key when the instance number is different.

The kkey_assign_private kernel service does not perform a resource allocation. It only provides a recommended kernel key to use for data protection.

Execution Environment

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

Return Values

Item	Description
0	Indicates a successful completion.
EINVAL_KKEY_ASSIGN_PRIVATE	Indicates that the parameter or execution environment is not valid.