| <!--#include virtual="header.txt"--> |
| |
| <h1><a name="top">SLURM Cryptographic Plugin Programmer Guide</a></h1> |
| |
| <h2> Overview</h2> |
| <p> This document describes SLURM cryptographic plugins and the API that |
| defines them. |
| It is intended as a resource to programmers wishing to write their own |
| SLURM cryptographic plugins. |
| This is version 0 of the API.</p> |
| |
| <p>SLURM cryptographic plugins are SLURM plugins that implement |
| a digital signature mechanism. |
| The slurmctld daemon generates a job step credential, signs it, |
| and transmits it to an srun program. |
| The srun program then transmits it to the slurmd daemons directly. |
| The slurmctld daemon does not communicate directly with the slurmd |
| daemons at this time for performance reasons, but the job step |
| credential must be validated by the slurmd daemon as being |
| generated by the slurmctld daemon. |
| Digital signatures provide this validation mechanism. |
| The plugins 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 "crypto." |
| The minor type can be any recognizable abbreviation for the type of |
| cryptographic mechanism. |
| We recommend, for example:</p> |
| <ul> |
| <li><b>munge</b>—LLNL's Munge system.</li> |
| <li><b>openssl</b>—Open SSL.</li> |
| </ul></p> |
| |
| <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 |
| cryptographic support. |
| Note carefully, however, the versioning discussion below.</p> |
| |
| <h2>Data Objects</h2> |
| <p>The implementation must maintain (though not necessarily directly export) an |
| enumerated <span class="commandline">errno</span> to allow SLURM to discover |
| as practically as possible the reason for any failed API call. |
| Plugin-specific enumerated integer values may be used when appropriate. |
| |
| <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. |
| The implementation should endeavor to provide useful and pertinent |
| information by whatever means is practical. |
| 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 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 * crypto_read_private_key (const char *path);</p> |
| <p style="margin-left:.2in"><b>Description</b>: Generate a private key |
| based upon the contents of the supplied file.</p> |
| <p style="margin-left:.2in"><b>Argument</b>:<span class="commandline">path</span> |
| (input) fully-qualified pathname to the private key |
| as specified by the <b>JobCredentialPrivateKey</b> configuration parameter.</p> |
| <p style="margin-left:.2in"><b>Returns</b>: The pointer to a key on |
| success or NULL on failure. |
| Call crypto_destroy_key() to release memory associated with this key.</p> |
| |
| |
| <p class="commandline">void * crypto_read_public_key (const char *path);</p> |
| <p style="margin-left:.2in"><b>Description</b>: Generate a public key |
| based upon the contents of the supplied file.</p> |
| <p style="margin-left:.2in"><b>Argument</b>:<span class="commandline">path</span> |
| (input) fully-qualified pathname to the public key |
| as specified by the <b>JobCredentialPublicCertificate</b> configuration |
| parameter.</p> |
| <p style="margin-left:.2in"><b>Returns</b>: The pointer to a key on |
| success or NULL on failure. |
| Call crypto_destroy_key() to release memory associated with this key.</p> |
| |
| |
| <p class="commandline">void crypto_destroy_key (void *key);</p> |
| <p style="margin-left:.2in"><b>Description</b>: Release storage for |
| a public or private key.</p> |
| <p style="margin-left:.2in"><b>Argument</b>:<span class="commandline"> key</span> |
| (input/output) pointer to the key previously allocated |
| by crypto_read_private_key() or crypto_read_public_key().</p> |
| |
| |
| <p class="commandline">char *crypto_str_error(void);</p> |
| <p style="margin-left:.2in"><b>Description</b>: Return a string |
| describing the last error generated by the the cryptographic software.</p> |
| <p style="margin-left:.2in"><b>Returns</b>: A pointer to a string.</p> |
| |
| <p class="commandline">int crypto_sign (void *key, char *buffer, int buf_size, |
| char **sig_pp, unsigned int *sig_size_p);</p> |
| <p style="margin-left:.2in"><b>Description</b>: Generate a signature for |
| the supplied buffer.</p> |
| <p style="margin-left:.2in"><b>Arguments</b>:</br> |
| <span class="commandline"> key</span> |
| (input) pointer to the key previously generated by |
| crypto_read_private_key() or crypto_read_public_key().<br> |
| <span class="commandline"> buffer</span> (input) data to |
| be signed.<br> |
| <span class="commandline"> buf_size</span> (input) |
| size of buffer, in bytes.<br> |
| <span class="commandline"> sig_pp</span> (input/output) |
| Location in which to store the signature. NOTE: The storage for |
| sig_pp should be allocated using xmalloc() and will be freed by |
| the caller using xfree().<br> |
| <span class="commandline"> sig_size_p</span> (input/output) |
| Location in which to store the size of the signature (sig_pp).</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="commandline">int crypto_verify_sign (void *key, char *buffer, |
| int buf_size, char *signature, unsigned int sig_size);</p> |
| <p style="margin-left:.2in"><b>Description</b>: Generate a signature for |
| the supplied buffer.</p> |
| <p style="margin-left:.2in"><b>Arguments</b>:</br> |
| <span class="commandline"> key</span> |
| (input) pointer to the key previously generated by |
| crypto_read_private_key() or crypto_read_public_key().<br> |
| <span class="commandline"> buffer</span> (input) data |
| previously signed by crypto_sign().<br> |
| <span class="commandline"> buf_size</span> (input) |
| size of buffer, in bytes.<br> |
| <span class="commandline"> signature</span> (input) |
| Signature as returned in sig_pp by the crypto_sign() function and |
| to be confirmed.</br> |
| <span class="commandline"> sig_size</span> (input) |
| Size of the signature as returned in sig_size_p by crypto_sign().</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> |
| |
| |
| <h2>Versioning</h2> |
| <p> This document describes version 0 of the SLURM cryptographic API. |
| Future releases of SLURM may revise this API. |
| A cryptographic plugin conveys its ability to implement a particular |
| API version using the mechanism outlined for SLURM plugins.</p> |
| <p class="footer"><a href="#top">top</a></p> |
| |
| <p style="text-align:center;">Last modified 24 July 2007</p> |
| |
| <!--#include virtual="footer.txt"--> |
