.. _man3-PMIx_Validate_credential: PMIx_Validate_credential ======================== .. include_body ``PMIx_Validate_credential``, ``PMIx_Validate_credential_nb`` |mdash| Request validation of a security credential by the PMIx server library or the host environment. SYNOPSIS -------- .. code-block:: c #include 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); Python Syntax ^^^^^^^^^^^^^ .. code-block:: python3 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 INPUT PARAMETERS ---------------- * ``cred``: Pointer to a :ref:`pmix_byte_object_t(5) ` containing the credential to be validated. * ``info``: Pointer to an array of :ref:`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. OUTPUT PARAMETERS ----------------- * ``results`` (blocking form): Address where a pointer to an array of :ref:`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 :ref:`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``. 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. 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) |mdash| the expected effective user id of the credential to be validated. * ``PMIX_GRPID`` (uint32_t) |mdash| the expected effective group id of the credential to be validated. * ``PMIX_TIMEOUT`` (int) |mdash| 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. 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`` |mdash| the credential was valid (or, for the non-blocking form, the request was accepted; validity is reported to ``cbfunc``). * ``PMIX_ERR_NOT_AVAILABLE`` |mdash| the operation cannot be serviced because the library's progress engine has been stopped. * ``PMIX_ERR_INIT`` |mdash| 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 |mdash| in particular, an error status reports that the credential was rejected. PMIx error constants are defined in ``pmix_common.h``. 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. .. seealso:: :ref:`PMIx_Init(3) `, :ref:`PMIx_Get_credential(3) `, :ref:`pmix_info_t(5) `, :ref:`pmix_byte_object_t(5) `, :ref:`pmix_status_t(5) `