crypto_plugins.shtml 7.17 KiB
<!--#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 tranmits 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"-->