Chap_API_Security.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter: Security
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Security}
\label{chap:api_security}

\ac{PMIx} utilizes a multi-layered approach toward security that differs for client versus tool processes. By definition, \emph{client} processes must be preregistered with the \ac{PMIx} server library via the \refapi{PMIx_server_register_client} \ac{API} before they are spawned. This \ac{API} requires that the host pass the expected effective \ac{UID}/\ac{GID} of the client process.

When the client attempts to connect to the \ac{PMIx} server, the server shall use available standard \ac{OS} methods to determine the effective \ac{UID}/\ac{GID} of the process requesting the connection. \ac{PMIx} implementations shall not rely on any values reported by the client process itself. The effective \ac{UID}/\ac{GID} reported by the \ac{OS} is compared to the values provided by the host during registration - if the values fail to match, the \ac{PMIx} server is required to drop the connection request. This ensures that the \ac{PMIx} server does not allow connection from a client that doesn't at least meet some minimal security requirement.

Once the requesting client passes the initial test, the \ac{PMIx} server can, at the choice of the implementor, perform additional security checks. This may involve a variety of methods such as exchange of a system-provided key or credential. At the conclusion of that process, the \ac{PMIx} server reports the client connection request to the host via the \refapi{pmix_server_client_connected2_fn_t} interface, if provided. The host may perform any additional checks and operations before responding with either \refconst{PMIX_SUCCESS} to indicate that the connection is approved, or a \ac{PMIx} error constant indicating that the connection request is refused. In this latter case, the \ac{PMIx} server is required to drop the connection.

Tools started by the host environment are classed as a subgroup of client processes and follow the client process procedure. However, tools that are not started by the host environment must be handled differently as registration information is not available prior to the connection request. In these cases, the \ac{PMIx} server library is required to use available standard \ac{OS} methods to get the effective \ac{UID}/\ac{GID} of the tool and report them upwards as part of invoking the \refapi{pmix_server_tool_connection_fn_t} interface, deferring initial security screening to the host. Host environments willing to accept tool connections must therefore both explicitly enable them via the \refattr{PMIX_SERVER_TOOL_SUPPORT} attribute, thereby confirming acceptance of the authentication and authorization burden, and provide the \refapi{pmix_server_tool_connection_fn_t} server module function pointer.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Obtaining Credentials}
\label{chap:api_security:obtain}

Applications and tools often interact with the host environment in ways that require security beyond just verifying the user's identity - e.g., access to that user's relevant authorizations. This is particularly important when tools connect directly to a system-level \ac{PMIx} server that may be operating at a privileged level. A variety of system management software packages provide authorization services, but the lack of standardized interfaces makes portability problematic.

This section defines two \ac{PMIx} client-side \acp{API} for this purpose. These are most likely to be used by user-space applications/tools, but are not restricted to that realm.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\code{PMIx_Get_credential}}
\declareapi{PMIx_Get_credential}

%%%%
\summary

Request a credential from the \ac{PMIx} server library or the host environment.

%%%%
\format

\copySignature{PMIx_Get_credential}{3.0}{
pmix_status_t \\
PMIx_Get_credential(const pmix_info_t info[], size_t ninfo, \\
\hspace*{20\sigspace}pmix_byte_object_t *credential);
}

\begin{arglist}
\argin{info}{Array of \refstruct{pmix_info_t} structures (array of handles)}
\argin{ninfo}{Number of elements in the \refarg{info} array (\code{size_t})}
\argin{credential}{Address of a \refstruct{pmix_byte_object_t} within which to return credential (handle)}
\end{arglist}

Returns one of the following:

\begin{itemize}
    \item \refconst{PMIX_SUCCESS}, indicating that the credential has been returned in the provided \refstruct{pmix_byte_object_t}
    \item a \ac{PMIx} error constant indicating either an error in the input or that the request is unsupported
\end{itemize}

\reqattrstart
There are no required attributes for this \ac{API}. Note that implementations may choose to internally
execute integration for some security environments (e.g., directly
contacting a \textit{munge} server).

Implementations that support the operation but cannot directly process the client's request must pass any attributes that are provided by the client to the host environment for processing. In addition, the following attributes are required to be included in the \refarg{info} array passed from the \ac{PMIx} library to the host environment:

\pasteAttributeItem{PMIX_USERID}
\pasteAttributeItem{PMIX_GRPID}

\reqattrend

\optattrstart
The following attributes are optional for host environments that support this operation:

\pasteAttributeItem{PMIX_TIMEOUT}

\optattrend

%%%%
\descr

Request a credential from the \ac{PMIx} server library or the host environment. The credential is returned as a \refstruct{pmix_byte_object_t} to support potential binary formats - it is therefore opaque to the caller. No information as to the source of the credential is provided.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\code{PMIx_Get_credential_nb}}
\declareapi{PMIx_Get_credential_nb}

%%%%
\summary

Request a credential from the \ac{PMIx} server library or the host environment.

%%%%
\format

\copySignature{PMIx_Get_credential_nb}{3.0}{
pmix_status_t \\
PMIx_Get_credential_nb(const pmix_info_t info[], size_t ninfo, \\
\hspace*{23\sigspace}pmix_credential_cbfunc_t cbfunc, \\
\hspace*{23\sigspace}void *cbdata);
}

\begin{arglist}
\argin{info}{Array of \refstruct{pmix_info_t} structures (array of handles)}
\argin{ninfo}{Number of elements in the \refarg{info} array (\code{size_t})}
\argin{cbfunc}{Callback function to return credential (\refapi{pmix_credential_cbfunc_t} function reference)}
\argin{cbdata}{Data to be passed to the callback function (memory reference)}
\end{arglist}

Returns one of the following:

\begin{itemize}
    \item \refconst{PMIX_SUCCESS}, indicating that the request has been communicated to the local \ac{PMIx} server - result will be returned in the provided \refarg{cbfunc}
    \item a \ac{PMIx} error constant indicating either an error in the input or that the request is unsupported - the \refarg{cbfunc} will \textit{not} be called
\end{itemize}

\reqattrstart
There are no required attributes for this \ac{API}. Note that implementations may choose to internally
execute integration for some security environments (e.g., directly
contacting a \textit{munge} server).

Implementations that support the operation but cannot directly process the client's request must pass any attributes that are provided by the client to the host environment for processing. In addition, the following attributes are required to be included in the \refarg{info} array passed from the \ac{PMIx} library to the host environment:

\pasteAttributeItem{PMIX_USERID}
\pasteAttributeItem{PMIX_GRPID}

\reqattrend

\optattrstart
The following attributes are optional for host environments that support this operation:

\pasteAttributeItem{PMIX_TIMEOUT}

\optattrend

%%%%
\descr

Request a credential from the \ac{PMIx} server library or the host environment.  This version of the \ac{API} is generally preferred in scenarios where the host environment may have to contact a remote credential service. Thus, provision is made for the system to return additional information (e.g., the identity of the issuing agent) outside of the credential itself and visible to the application.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Credential Attributes}
\label{chap:api_security:attributes}

The following attributes are defined to support credential operations:

%
\declareAttribute{PMIX_CRED_TYPE}{"pmix.sec.ctype"}{char*}{
When passed in \refapi{PMIx_Get_credential}, a prioritized, comma-delimited list of desired credential types for use
in environments where multiple authentication mechanisms may be available. When returned in a callback function, a
string identifier of the credential type.
}
%
\declareAttribute{PMIX_CRYPTO_KEY}{"pmix.sec.key"}{pmix_byte_object_t}{
Blob containing crypto key.
}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Validating Credentials}
\label{chap:api_security:validate}

Given a credential, \ac{PMIx} provides two methods by which a caller can request that the system validate it, returning any additional information (e.g., authorizations) conveyed within the credential.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\code{PMIx_Validate_credential}}
\declareapi{PMIx_Validate_credential}

%%%%
\summary

Request validation of a credential by the \ac{PMIx} server library or the host environment.

%%%%
\format

\copySignature{PMIx_Validate_credential}{3.0}{
pmix_status_t \\
PMIx_Validate_credential(const pmix_byte_object_t *cred, \\
\hspace*{25\sigspace}const pmix_info_t info[], size_t ninfo, \\
\hspace*{25\sigspace}pmix_info_t **results, size_t *nresults);
}

\begin{arglist}
\argin{cred}{Pointer to \refstruct{pmix_byte_object_t} containing the credential (handle)}
\argin{info}{Array of \refstruct{pmix_info_t} structures (array of handles)}
\argin{ninfo}{Number of elements in the \refarg{info} array (\code{size_t})}
\arginout{results}{Address where a pointer to an array of \refstruct{pmix_info_t} containing the results of the request can be returned (memory reference)}
\arginout{nresults}{Address where the number of elements in \refarg{results} can be returned (handle)}
\end{arglist}

Returns one of the following:

\begin{itemize}
    \item \refconst{PMIX_SUCCESS}, indicating that the request was processed and returned \textit{success} (i.e., the credential was both valid and any information it contained was successfully processed). Details of the result will be returned in the \refarg{results} array
    \item a PMIx error constant indicating either an error in the parsing of the credential or that the request was refused
\end{itemize}

\reqattrstart
There are no required attributes for this \ac{API}. Note that implementations may choose to internally
execute integration for some security environments (e.g., directly
contacting a \textit{munge} server).

Implementations that support the operation but cannot directly process the client's request must pass any attributes that are provided by the client to the host environment for processing. In addition, the following attributes are required to be included in the \refarg{info} array passed from the \ac{PMIx} library to the host environment:

\pasteAttributeItem{PMIX_USERID}
\pasteAttributeItem{PMIX_GRPID}

\reqattrend

\optattrstart
The following attributes are optional for host environments that support this operation:

\pasteAttributeItem{PMIX_TIMEOUT}

\optattrend

%%%%
\descr

Request validation of a credential by the \ac{PMIx} server library or the host environment.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\code{PMIx_Validate_credential_nb}}
\declareapi{PMIx_Validate_credential_nb}

%%%%
\summary

Request validation of a credential by the \ac{PMIx} server library or the host environment. Provision is made for the system to return additional information regarding possible authorization limitations beyond simple authentication.

%%%%
\format

\copySignature{PMIx_Validate_credential_nb}{3.0}{
pmix_status_t \\
PMIx_Validate_credential_nb(const pmix_byte_object_t *cred, \\
\hspace*{28\sigspace}const pmix_info_t info[], size_t ninfo, \\
\hspace*{28\sigspace}pmix_validation_cbfunc_t cbfunc, \\
\hspace*{28\sigspace}void *cbdata);
}

\begin{arglist}
\argin{cred}{Pointer to \refstruct{pmix_byte_object_t} containing the credential (handle)}
\argin{info}{Array of \refstruct{pmix_info_t} structures (array of handles)}
\argin{ninfo}{Number of elements in the \refarg{info} array (\code{size_t})}
\argin{cbfunc}{Callback function to return result (\refapi{pmix_validation_cbfunc_t} function reference)}
\argin{cbdata}{Data to be passed to the callback function (memory reference)}
\end{arglist}

Returns one of the following:

\begin{itemize}
    \item \refconst{PMIX_SUCCESS}, indicating that the request has been communicated to the local \ac{PMIx} server - result will be returned in the provided \refarg{cbfunc}
    \item a \ac{PMIx} error constant indicating either an error in the input or that the request is unsupported - the \refarg{cbfunc} will \textit{not} be called
\end{itemize}

Upon completion of processing the callback function will be executed. Note that the callback function must not be executed prior to return from the \ac{API}.

\reqattrstart
There are no required attributes for this \ac{API}. Note that implementations may choose to internally
execute integration for some security environments (e.g., directly
contacting a \textit{munge} server).

Implementations that support the operation but cannot directly process the client's request must pass any attributes that are provided by the client to the host environment for processing. In addition, the following attributes are required to be included in the \refarg{info} array passed from the \ac{PMIx} library to the host environment:

\pasteAttributeItem{PMIX_USERID}
\pasteAttributeItem{PMIX_GRPID}

\reqattrend

\optattrstart
The following attributes are optional for host environments that support this operation:

\pasteAttributeItem{PMIX_TIMEOUT}

\optattrend

%%%%
\descr

Request validation of a credential by the \ac{PMIx} server library or the host environment. This version of the \ac{API} is generally preferred in scenarios where the host environment may have to contact a remote credential service. Provision is made for the system to return additional information (e.g., possible authorization limitations) beyond simple authentication.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%