diff --git a/doc/html/Makefile.am b/doc/html/Makefile.am index d377fae47b588720a8c795ef336de180d20a255e..14e02c4d1720267bd9598f62a1ed7e4f9760f65f 100644 --- a/doc/html/Makefile.am +++ b/doc/html/Makefile.am @@ -8,6 +8,7 @@ generated_html = \ bluegene.html \ checkpoint_plugins.html \ cons_res.html \ + crypto_plugins_html \ dist_plane.html \ databaseplugins.html \ documentation.html \ diff --git a/doc/html/Makefile.in b/doc/html/Makefile.in index 3f6979614c56a75c9ac49affb1f8a0406e089a10..6bbf4dd316d3f5361fadb3ccb84bc87738fce6eb 100644 --- a/doc/html/Makefile.in +++ b/doc/html/Makefile.in @@ -243,6 +243,7 @@ generated_html = \ bluegene.html \ checkpoint_plugins.html \ cons_res.html \ + crypto_plugins.html \ dist_plane.html \ databaseplugins.html \ documentation.html \ diff --git a/doc/html/checkpoint_plugins.shtml b/doc/html/checkpoint_plugins.shtml index 1313e86f07b11c392ce878672cb5ff7d015f8a92..86518ab9b1d62b1da3f2dc1bb749d794698f3b58 100644 --- a/doc/html/checkpoint_plugins.shtml +++ b/doc/html/checkpoint_plugins.shtml @@ -1,6 +1,6 @@ <!--#include virtual="header.txt"--> -<h1><a name="top">SLURM Job Checkpoint Plugin API</a></h1> +<h1><a name="top">SLURM Job Checkpoint Plugin Programmer Guide</a></h1> <h2> Overview</h2> <p> This document describes SLURM job checkpoint plugins and the API that defines @@ -13,7 +13,8 @@ The plugins must conform to the SLURM Plugin API with the following specificatio <p><span class="commandline">const char plugin_type[]</span><br> The major type must be "checkpoint." The minor type can be any recognizable -abbreviation for the type of scheduler. We recommend, for example:</p> +abbreviation for the type of checkpoint mechanism. +We recommend, for example:</p> <ul> <li><b>none</b>—No job checkpoint.</li> <li><b>aix</b>—AIX system checkpoint.</li> @@ -141,11 +142,12 @@ appropriate value to indicate the reason for failure.</p> <h2>Versioning</h2> -<p> This document describes version 0 of the SLURM checkpoint API. Future -releases of SLURM may revise this API. A scheduler plugin conveys its ability -to implement a particular API version using the mechanism outlined for SLURM plugins.</p> +<p> This document describes version 0 of the SLURM checkpoint API. +Future releases of SLURM may revise this API. +A checkpoint 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 10 July 2005</p> +<p style="text-align:center;">Last modified 24 July 2007</p> <!--#include virtual="footer.txt"--> diff --git a/doc/html/crypto_plugins.shtml b/doc/html/crypto_plugins.shtml new file mode 100644 index 0000000000000000000000000000000000000000..d96b886978ca6d4a5123639091d19e879e328c6c --- /dev/null +++ b/doc/html/crypto_plugins.shtml @@ -0,0 +1,150 @@ +<!--#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 malloc() and will be freed using free().<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"--> diff --git a/doc/html/documentation.shtml b/doc/html/documentation.shtml index 91dce0a928831155fa3089cb13d9f8dfd84c3ab8..41d9a0a43294daf49f42a4bd4f6de5dc04c18b0f 100644 --- a/doc/html/documentation.shtml +++ b/doc/html/documentation.shtml @@ -41,11 +41,11 @@ Jobs throuh LSF</a></li> <li><a href="plugins.shtml">Plugin Programmer Guide</a></li> <li><a href="authplugins.shtml">Authentication Plugin Programmer Guide</a></li> <li><a href="checkpoint_plugins.shtml">Job Checkpoint Plugin Programmer Guild</a></li> +<li><a href="crypto_plugins.shtml">Cryptographic Plugin Programmer Guild</a></li> <li><a href="databaseplugins.shtml">Database Plugin Programmer Guide</a></li> <li><a href="jobacctplugins.shtml">Job Accounting Plugin Programmer Guide</a></li> <li><a href="jobcompplugins.shtml">Job Completion Logging Plugin Programmer Guide</a></li> <li><a href="mpiplugins.shtml">MPI Plugin Programmer Guide</a></li> -</ul> <li><a href="proctrack_plugins.shtml">Process Tracking Plugin Programmer Guide</a></li> <li><a href="schedplugins.shtml">Scheduler Plugin Programmer Guide</a></li> <li><a href="selectplugins.shtml">Node Selection Plugin Programmer Guide</a></li> @@ -54,6 +54,6 @@ Jobs throuh LSF</a></li> <li><a href="mpiplugins.shtml">MPI Plugin Programmer Guide</a></li> </ul> -<p style="text-align:center;">Last modified 12 June 2007</p> +<p style="text-align:center;">Last modified 24 July 2007</p> <!--#include virtual="footer.txt"-->