| <!--#include virtual="header.txt"--> |
| |
| <h1><a name="top">SLURM Authentication Plugin API</a></h1> |
| |
| <h2> Overview</h2> |
| <p> This document describes SLURM authentication plugins and the API that defines |
| them. It is intended as a resource to programmers wishing to write their own SLURM |
| authentication plugins. This is version 0 of the API.</p> |
| <p>SLURM authentication plugins are SLURM plugins that implement the SLURM authentication |
| API described herein. They must conform to the SLURM Plugin API with the following |
| specifications:</p> |
| <p><span class="commandline">const char plugin_type[]</span><br> |
| The major type must be "auth." The minor type can be any recognizable |
| abbreviation for the type of authentication. We recommend, for example:</p> |
| <ul> |
| <li><b>none</b>—A plugin that implements the API without providing any actual |
| authentication service. This may be used for testing purposes, but is not suitable for |
| production use due to lack of effective security.</li> |
| <li><b>authd</b>—Brett Chun's Linux authd.</li> |
| <li><b>munge</b>—LLNL's munge protocol (recommended plugin for production use).</li> |
| <li><b>krb5</b>—Kerberos 5 (not implemented as of 8 June 2004).</li> |
| </ul> |
| <p>The <span class="commandline">plugin_name</span> and <span class="commandline">plugin_version</span> |
| symbols required by the SLURM Plugin API require no specialization for authentication. |
| Note carefully, however, the versioning discussion below.</p> |
| <p>The programmer is urged to study <span class="commandline">src/plugins/auth/none/auth_none.c</span> |
| for an example implementation of a SLURM authentication plugin.</p> |
| <p class="footer"><a href="#top">top</a></p> |
| <h2>Data Objects</h2> |
| <p> The implementation must support an opaque class, which it defines, to be used |
| as an authentication "credential." This class must encapsulate all user-specific |
| information necessary for the operation of the API specification below. The credential |
| is referred to in SLURM code by an anonymous pointer (void *).</p> |
| <p>The implementation must maintain (though not necessarily directly export) an |
| enumerated <b>errno</b> to allow SLURM to discover as practically as possible |
| the reason for any failed API call. The following enumerated integer values (declared |
| in <span class="commandline">src/common/slurm_auth.h</span>) must be used when |
| appropriate.</p> |
| <p style="margin-left:.2in">SLURM_AUTH_BADARG—an argument to an API function |
| was invalid or malformed.<br> |
| SLURM_AUTH_MEMORY—a request could not be satisfied because memory for it |
| could not be allocated.<br> |
| SLURM_AUTH_NOUSER—a credential is improper because it refers to an unknown |
| user.<br> |
| SLURM_AUTH_INVALID—a credential is improper because the validation of it |
| has failed. This is specifically distinct from the expiration of a credential.<br> |
| SLURM_AUTH_MISMATCH—a credential could not be properly unpacked because it |
| is of an incompatible type or version.</p> |
| <p>These values must not be used as return values in integer-valued functions |
| in the API. The proper error return value from integer-valued functions is SLURM_ERROR. |
| While it is most practical to associate a different errno with each instance of |
| a credential, this is not necessarily enforced by the API. The implementation |
| should endeavor to provide useful and pertinent information by whatever means |
| is practical. In most cases, this means an errno for each credential, since plugins |
| must be re-entrant. If a plugin maintains a global errno in place of or in addition |
| to a per-credential errno, it is not required to enforce mutual exclusion on it. |
| Successful API calls are not required to reset any errno to a known value. However, |
| the initial value of any errno, prior to any error condition arising, should be |
| SLURM_SUCCESS. </p> |
| <p>Plugins may assign implementation-specific values to errno so long as they |
| do not conflict with the values assigned above. This is done programmatically |
| by assigning plugin-specific errno values which are arithmetically greater than |
| or equal to the symbol SLURM_AUTH_FIRST_LOCAL_ERROR.</p> |
| <p class="footer"><a href="#top">top</a></p> |
| |
| <h2>API Functions</h2> |
| <p>The following functions must appear. Functions which are not implemented should |
| be stubbed.</p> |
| <p class="commandline">void *slurm_auth_alloc (void);</p> |
| <p style="margin-left:.2in"><b>Description</b>: Allocates from the free store |
| an anonymous credential object and returns a pointer to it. The pointer should |
| be valid until passed to <span class="commandline">slurm_auth_destroy()</span> for |
| disposal. SLURM will not pass |
| credentials to the API which have not been allocated by this function.</p> |
| <p style="margin-left:.2in"><b>Arguments</b>: None.</p> |
| <p style="margin-left:.2in"><b>Returns</b>: A pointer to a newly allocated credential |
| if successful. On failure, the plugin should return NULL and set its errno to |
| an appropriate value to indicate the reason for failure.</p> |
| <p class="commandline">int slurm_auth_destroy (void *cr);</p> |
| <p style="margin-left:.2in"><b>Description</b>: Deallocates a credential that |
| was allocated with <span class="commandline">slurm_auth_alloc()</span> and any |
| associated storage that has been allocated for it during its use.</p> |
| <p style="margin-left:.2in"><b>Arguments</b>:<span class="commandline"> cr</span> |
| (input) pointer to the credential that is to be deallocated. Cannot |
| be NULL.</p> |
| <p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure, |
| the plugin should return SLURM_ERROR and set the errno to an appropriate value |
| to indicate the reason for failure.</p> |
| <p class="footer"><a href="#top">top</a></p> |
| <p class="commandline">int slurm_auth_verify (void *cr );</p> |
| <p style="margin-left:.2in"><b>Description</b>: Verifies that a credential is |
| in order and correctly identifies the associated user. It also verifies that the |
| credential has not expired. If verification is successful, the return values of |
| <span class="commandline">slurm_auth_get_uid()</span> and <span class="commandline">slurm_auth_get_gid()</span> |
| in subsequent calls must correspond to the actual verified system UID and GID |
| of the user associated with the credential. Verification must fail if the credential |
| has not previously been activated, even if a credential implementation cannot |
| exist in an unactivated state. A credential's valid term is defined at activation |
| and verification must fail if the credential has expired, even if it would otherwise |
| be valid.</p> |
| <p style="margin-left:.2in"><b>Arguments</b>: <span class="commandline">cr</span> |
| (input) pointer to the credential which is to be verified. Cannot |
| be NULL.</p> |
| <p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if the credential is |
| verified to be in order and has not expired. If the credential cannot be verified, |
| or if the credential has expired, the function should return SLURM_ERROR and set |
| its errno to an appropriate value to indicate the reason for failure.</p> |
| <p class="commandline">uid_t slurm_auth_get_uid (void *cr);<br> |
| gid_t slurm_auth_get_gid (void *cr);</p> |
| <p style="margin-left:.2in"><b>Description</b>: Extracts the numerical UID (GID) |
| of the user corresponding to the given credential. SLURM considers this value |
| trustworthy only if the credential has been successfully verified using <span class="commandline">slurm_auth_verify()</span>. |
| An unverified credential does not immediately give rise to an error condition |
| in these functions, since this would require a plugin to distinguish between a |
| verified and an unverified credential, which may be computationally expensive. |
| A plugin may consider the lack of verification as an error.</p> |
| <p style="margin-left:.2in"><b>Arguments</b>: <span class="commandline">cr</span> |
| (input) pointer to the credential containing the desired identification. |
| Cannot be NULL.</p> |
| <p style="margin-left:.2in"><b>Returns</b>: If successful, the Linux UID (GID) |
| associated with the credential. In case of error, SLURM_AUTH_NOBODY should be |
| returned and errno set appropriately to indicate the cause of the failure.</p> |
| <p class="footer"><a href="#top">top</a></p> |
| <p class="commandline">int slurm_auth_pack (void *cr, Buf buf);</p> |
| <p style="margin-left:.2in"><b>Description</b>: Marshals a credential into a buffer |
| for transmission according to the SLURM packing protocol. All authentication plugins |
| must first pack the plugin_type and then the plugin_version data before any plugin-specific |
| data elements are packed. slurm_auth_pack() and slurm_auth_pack() are strictly |
| reciprocal. The esult of a packing followed by an unpacking must be a functionally |
| equivalent credential. A credential is deemed appropriate for marshalling at any |
| time after its allocation and before its destruction.</p> |
| <p style="margin-left:.2in"><b>Arguments</b>:<br> |
| <span class="commandline">cr</span> (input) pointer to the credential |
| to pack.<br> |
| <span class="commandline">buf</span> (input/output) the buffer |
| into which the credential should be packed.</p> |
| <p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure |
| the plugin should return SLURM_ERROR and set the errno to indicate the reason |
| for the failure.</p> |
| <p class="commandline">int slurm_auth_unpack (void *cr, Buf buf);</p> |
| <p style="margin-left:.2in"><b>Description</b>: Unmarshals a credential from a |
| buffer according to the SLURM packing protocol into a supplied (and presumed empty) |
| credential object. The unmarshalled credential is not assumed to be activated |
| or verified. The <span class="commandline">plugin_type</span> and <span class="commandline">plugin_version</span> |
| data should first be unpacked from the buffer and verified for applicability. |
| The API does not enforce that they must be equivalent, merely compatible. Compatibility |
| is implementation-dependent.</p> |
| <p style="margin-left:.2in"><b>Arguments</b>:<br> |
| <span class="commandline">cr</span> (output) pointer to the |
| credential to pack.<br> |
| <span class="commandline">buf</span> (input/output) the buffer |
| from which the credential should be unpacked.</p> |
| <p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if the credential was |
| successfully unpacked. In case of failure, the function should return SLURM_ERROR |
| and set errno appropriately to indicate the cause of the failure. If the function |
| fails, no assumptions are made about the state of the credential except its suitability |
| for destruction via <span class="commandline">slurm_auth_destroy()</span>.</p> |
| <p class="commandline">int slurm_auth_print (void *cr, FILE *fp);</p> |
| <p style="margin-left:.2in"><b>Description</b>: Writes a human-readable representation |
| of the credential to a standard I/O stream. There are no strict API constraints |
| on the behavior of this function, however it is recommended that the information |
| be as complete and as concise as possible. For example, lengthy digital "signatures" |
| need not be printed bitwise, but may be represented by their checksum. The intent |
| is to provide a depiction of the credential for debugging purposes.</p> |
| <p style="margin-left:.2in"><b>Arguments</b>: None.</p> |
| <p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure |
| the plugin should return SLURM_ERROR and set the errno appropriately to indicate |
| the cause of failure.</p> |
| <p class="footer"><a href="#top">top</a></p> |
| <p class="commandline">int slurm_auth_errno (void *cr);</p> |
| <p style="margin-left:.2in"><b>Description</b>: Returns the current value of errno. |
| Whether the value is associated with the given credential or with the plugin as |
| a whole is implementation-dependent. Because this function can be used to discover |
| the reason why a credential allocation has failed, the argument is advisory. </p> |
| <p style="margin-left:.2in"><b>Arguments</b>: <span class="commandline">cr</span> |
| (input) pointer to the credential, the status of whose most recently executed |
| API function is to be returned. This value may be NULL, indicating that the most |
| recent errno value applicable to the plugin as a whole is to be returned.</p> |
| <p style="margin-left:.2in"><b>Returns</b>: The current value of errno or SLURM_SUCCESS |
| if there is no error to report.</p> |
| <p class="commandline">const char *slurm_auth_errstr (int errno);</p> |
| <p style="margin-left:.2in"><b>Description</b>: Provides a human-readable string |
| associated with the given errno. The plugin need only supply error strings for |
| the errno values it defines and not for errno values listed above that are required |
| by the API.</p> |
| <p style="margin-left:.2in"><b>Arguments</b>: <span class="commandline">errno</span> |
| (input) the plugin-specific errno for which a corresponding error message is desired.</p> |
| <p style="margin-left:.2in"><b>Returns</b>: A pointer to a static error message. |
| This function must always return a pointer to a string, even if the string is |
| empty or ambiguous such as "unknown error."</p> |
| |
| <h2>Versioning</h2> |
| <p> This document describes version 0 of the SLURM Authentication API. Future |
| releases of SLURM may revise this API. An authentication plugin conveys its ability |
| to implement a particular API version using the mechanism outlined for SLURM plugins. |
| In addition, the credential is transmitted along with the version number of the |
| plugin that transmitted it. It is at the discretion of the plugin author whether |
| to maintain data format compatibility across different versions of the plugin.</p> |
| <p class="footer"><a href="#top">top</a></p> |
| |
| <p style="text-align:center;">Last modified 8 June 2004</p> |
| |
| <!--#include virtual="footer.txt"--> |
