__certificate() — Register, deregister, or authenticate a digital certificate

Standards

Standards / Extensions	C or C++	Dependencies
z/OS® UNIX	both	OS/390 V2R7

Format

#define _OPEN_SYS
#include <unistd.h>

int __certificate(int function_code,
                  int certificate_length,
                  char *certificate,…);

General description

The __certificate() function allows the user to register or deregister a digital certificate with or from the userid that is associated with the current security environment, or to authenticate a security environment using a digital certificate in lieu of a userid/password combination.

The function takes at least the following arguments:

function_code

Specifies one of the following functions:

__CERTIFICATE_REGISTER: Register the passed certificate to the user. No new security environment is created, and no authentication of the user is done.
__CERTIFICATE_DEREGISTER: Deregister the passed certificate from the user. Certificate must have been previously registered to the user.
__CERTIFICATE_AUTHENTICATE: As of z/OS V1R4, authenticate the passed certificate for this caller. The certificate must have already been registered.

certificate_length

The length of the digital certificate. A zero length will cause -1 return value with errno set to EINVAL.

certificate

The certificate must be a single BER encoded X.509 certificate. PKCS7, PEM, or Base64 encoded certificates are allowed.

Note: Only a single BER encoded X.509 certificate is supported for the authenticate function.

As of z/OS V1R4, the __CERTIFICATE_AUTHENTICATE function code requires the following additional parameters to be specified o nthe function call:

buflen (size_t): Specifies the size of the buffer pointed to by buf. Up to buflen bytes of userid (including the NULL terminator) will be copied into the buffer. Note that truncation may occur if the buffer is too small. The buffer size should be large enough for any userid on the system. A value less than 1 will cause -1 return value with errno set to EINVAL.
buf (char *): Pointer to character buffer where _certificate() will place the userid associated with the digital certificate. A value of NULL will cause -1 return value with errno set to EINVAL.

Usage notes

The _certificate function is intended for servers that support the automatic registration of certificates for clients they are supporting (on the World Wide Web for example).
The __CERTIFICATE_REGISTER function code will associate the passed certificate with whatever user identity is present. If the task level identity is present the certificate is associated with the task. Task level security can be created by pthread_security_np(), __login() or by any other means of creating a task level ACEE. If no task level identity (ACEE) is present, the certificate will be associated with the address space identity.
The __certificate() function calls the z/OS z/OS UNIX System Services BPX1SEC service. For a more detailed description of the BPX1SEC service, see z/OS UNIX System Services Programming: Assembler Callable Services Reference.

Restrictions

A security manager supporting digital certificate registration and deregistration must be installed and operational.

Returned value

If successful, __certificate() returns 0.

If unsuccessful, __certificate() returns -1 and sets errno to one of the following values:

Error Code: Description
EACCES: Permission is denied.
EINVAL: A parameter is not valid.
EMVSERR: An MVS™ environmental error or internal error occurred.
EMVSSAF2ERR: An error occurred in the security product. Certificate is already defined for another process or certificate is not valid or certificate does not meet required format. Also, realized when an internal error has occurred.
ENOSYS: The function is not implemented or installed.
EPERM: The operation was not permitted. Calling process may not be authorized in BPX.DAEMON facility class.

Use __errno2() to obtain a more detailed reason code (in most cases) when __certificate() fails.