18.2.26. PMIx_Validate_credential

PMIx_Validate_credential, PMIx_Validate_credential_nb — Request validation of a security credential by the PMIx server library or the host environment.

18.2.26.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Validate_credential(const pmix_byte_object_t *cred,
                                       const pmix_info_t info[], size_t ninfo,
                                       pmix_info_t **results, size_t *nresults);

pmix_status_t PMIx_Validate_credential_nb(const pmix_byte_object_t *cred,
                                          const pmix_info_t info[], size_t ninfo,
                                          pmix_validation_cbfunc_t cbfunc,
                                          void *cbdata);

18.2.26.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# ... after a successful foo.init() ...
# the credential is a Python ``pmix_byte_object_t`` dictionary
pycred = {'bytes': "mycredential", 'size': 12}
# the directives is a list of Python ``pmix_info_t`` dictionaries
pydirs = [{'key': PMIX_TIMEOUT,
           'value': {'value': 10, 'val_type': PMIX_INT}}]
rc, results = foo.validate_credential(pycred, pydirs)
# on success, results is a list of Python ``pmix_info_t`` dictionaries

18.2.26.2. INPUT PARAMETERS

cred: Pointer to a pmix_byte_object_t(5) containing the credential to be validated.
info: Pointer to an array of pmix_info_t(5) structures conveying directives that qualify the operation (see DIRECTIVES). A NULL value is supported when no directives are desired.
ninfo: Number of elements in the info array.

18.2.26.3. OUTPUT PARAMETERS

results (blocking form): Address where a pointer to an array of pmix_info_t(5) structures containing any information conveyed within the credential (for example, authorizations) is returned. The array is allocated by the library and must be released by the caller with PMIX_INFO_FREE when done.
nresults (blocking form): Address where the number of elements in results is returned.

The non-blocking form replaces results and nresults with a callback:

cbfunc: Callback function of type pmix_validation_cbfunc_t invoked with the final status and any accompanying information once the request completes.
cbdata: Opaque pointer that is passed, unmodified, to cbfunc.

18.2.26.4. DESCRIPTION

Request validation of a credential by the PMIx server library or the host environment, returning any additional information (for example, authorizations) conveyed within the credential.

PMIx_Validate_credential is the blocking form: it does not return until the credential has been validated (or the operation fails or times out). A successful return indicates that the credential was valid and any information it contained was successfully processed; the details are returned in the results array.

PMIx_Validate_credential_nb is the non-blocking form: it returns immediately, and the provided cbfunc is invoked with the final status once the request completes. This version is generally preferred in scenarios where the host environment may have to contact a remote credential service, and makes provision for the system to return additional information regarding possible authorization limitations beyond simple authentication. The information delivered to cbfunc is owned by the PMIx library and must not be released or altered by the receiving party; it is unrelated to the info array passed into the call.

As with all non-blocking PMIx APIs, callers of PMIx_Validate_credential_nb must keep the cred and info arrays valid until cbfunc is invoked.

The request is serviced by the host environment if it supports the operation; otherwise, the PMIx library attempts to validate the credential itself using an internal security (psec) plugin. A client or tool that is not connected to a local server, and a server whose host provides no credential support, are both handled by the internal plugins.

18.2.26.5. DIRECTIVES

The following attributes are relevant to this operation. There are no required attributes; implementations may internally integrate with a security environment (for example, contacting a munge server).

PMIX_USERID (uint32_t) — the expected effective user id of the credential to be validated.
PMIX_GRPID (uint32_t) — the expected effective group id of the credential to be validated.
PMIX_TIMEOUT (int) — maximum time, in seconds, to wait for validation before timing out and returning an error. Optional for host environments that support the operation.

Implementations that support the operation but cannot directly process the request pass the caller’s attributes to the host environment; in that case the PMIX_USERID and PMIX_GRPID attributes are required to be included in the array passed from the PMIx library to the host.

18.2.26.6. RETURN VALUE

For the blocking form, PMIX_SUCCESS indicates that the credential was valid and its contents were processed; any details are returned in results. For the non-blocking form, a return of PMIX_SUCCESS indicates only that the request was accepted for processing; the final status and any information are delivered to cbfunc. If the non-blocking form returns any value other than PMIX_SUCCESS, cbfunc will not be called.

PMIX_SUCCESS — the credential was valid (or, for the non-blocking form, the request was accepted; validity is reported to cbfunc).
PMIX_ERR_NOT_AVAILABLE — the operation cannot be serviced because the library’s progress engine has been stopped.
PMIX_ERR_INIT — the PMIx library has not been initialized.

If the connection to the local server is lost while a non-blocking request is outstanding, cbfunc is invoked with a status of PMIX_ERR_COMM_FAILURE.

Any other negative value indicates an appropriate error condition — in particular, an error status reports that the credential was rejected. PMIx error constants are defined in pmix_common.h.

18.2.26.7. NOTES

The credential is opaque and is understandable only by a service compatible with its issuer. The information array returned by validation typically contains, at a minimum, entries for the PMIX_USERID and PMIX_GRPID of the client described in the credential, though the precise contents depend on the host environment and its associated security system.