/usr/share/doc/dacs-examples/man/dacskey.1.html is in dacs-examples 1.4.38a-2build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 | <!-- Copyright (c) 2003-2013 -->
<!-- Distributed Systems Software. All rights reserved. -->
<!-- See the file LICENSE for redistribution information. -->
<!-- $Id: copyright-html 2625 2013-01-22 18:15:12Z brachman $ -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>dacskey</title><link rel="stylesheet" type="text/css" href="css/dacsdocs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div id="refentry" class="para16">
<script language="javascript" type="text/javascript" src="css/js/fontselector.js"></script>
<table width="100%"><tr>
<td align="left">
<b>DACSKEY(1)</b></td>
<td align="center">
<b>DACS Tools and Utilities</b></td>
<td align="right">
<b>DACSKEY(1)</b></td>
</tr></table>
<div class="refnamediv"><h2>NAME</h2><p>dacskey — generate encryption keys for <span class="command"><strong>DACS</strong></span></p></div><div class="refsynopsisdiv"><h2>SYNOPSIS</h2><div class="cmdsynopsis"><p><code class="command">dacskey</code> [<em class="replaceable"><code><a class="ulink" href="dacs.1.html#dacsoptions" target="_top">dacsoptions</a></code></em>]<br> [ <code class="option">-check</code> | <code class="option">-gen</code> | <code class="option">-priv</code> | <code class="option">-private</code> | <code class="option">-pub</code> | <code class="option">-public</code> ]<br> [ <code class="option">-p</code> | <code class="option">-pf <em class="replaceable"><code>passphrase-file</code></em></code> ] [<code class="option">-pem</code>] [<code class="option">-vfs</code>] [<code class="option">-rsa_key_bits</code> <em class="replaceable"><code>number</code></em>] [<code class="option">--</code>] <em class="replaceable"><code>keyfile</code></em> </p></div></div><div class="refsect1"><a name="idm49"></a><h2>DESCRIPTION</h2><p>This program is part of the <span class="command"><strong>DACS</strong></span> suite.</p><p>The <span class="command"><strong>dacskey</strong></span> utility generates encryption keys
for <span class="command"><strong>DACS</strong></span> that are cryptographically sound.
Keys are represented externally as an XML document called a
<em class="firstterm">keyfile</em>.
The program can also validate a keyfile or display a key.
</p><p>
Keys are created for at least three different purposes,
although every keyfile has the same format:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Keys that are shared by all of the jurisdictions within the
same <span class="command"><strong>DACS</strong></span> federation, identified by the virtual
filestore item type <code class="literal">federation_keys</code>.
It is through these "master" keys that any jurisdiction is able to decrypt
and validate credentials created by any other jurisdiction within the
same federation quickly and without any additional communication.
These keys are generated initially by a designated federation administrator
at the time a federation is created.
These keys can be generated at any jurisdiction within the federation.
</p><p>Ideally, new keys should be generated at regular intervals and also
whenever warranted to maintain security,
such as when a jurisdiction leaves the federation or if a key may have been
compromised.
When a jurisdiction joins a federation, it must receive a copy of
the current keys.
There is currently no automated key management support;
administrators must distribute these keys to all jurisdictions
over a secure channel whenever they are changed.
Besides using some method of encryption to ensure the keys remain
private during distribution, take care not to mangle the XML document
(e.g., through line breaks or truncation).
</p></li><li class="listitem"><p>Keys that are used by a jurisdiction for its own purposes,
identified by the virtual filestore item type
<code class="literal">jurisdiction_keys</code>.
These keys are kept private to the jurisdiction
(they are not shared with any other jurisdiction) and are ordinarily
generated at that jurisdiction.
These keys should be regenerated periodically as a routine security
measure.
</p></li><li class="listitem"><p>Keys that are used by a <span class="command"><strong>DACS</strong></span>
application at a particular jurisdiction for its own purposes
(<a class="ulink" href="dacsgrid.1.html" target="_top">dacsgrid(1)</a>, for instance).
These keys should be regenerated periodically, but take care to
retain the old keys so that they can be used for decryption
before information is re-encrypted using the new keys.
</p></li></ul></div><p>
</p><p>The program ordinarily uses <span class="command"><strong>OpenSSL</strong></span>'s
<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=ssl&apropos=0&sektion=3&manpath=FreeBSD+10.1-RELEASE&format=html" target="_top">ssl(3)</a>
library to acquire high-quality random material.
In certain situations, an experienced administrator might find the
<code class="option">-p</code> and <code class="option">-pf</code> options useful;
others should avoid them, however.
</p><p>When keys are generated,
the output is written to <em class="replaceable"><code>keyfile</code></em>,
which is either created or truncated.
In this context, <em class="replaceable"><code>keyfile</code></em> must be a pathname.
Unless directly written to where <code class="literal">federation_keys</code>
(or <code class="literal">jurisdiction_keys</code>) points,
<em class="replaceable"><code>keyfile</code></em> must be copied there.
</p><p>Assuming that the default site configuration file
(<code class="filename">conf/site.conf-std</code>, which establishes default locations
for these files) has been installed:
</p><pre class="programlisting">
% dacskey -u mysite.example.com -q fkeys
% install -o root -g www -m 0640 fkeys \
/usr/local/dacs/federations/example.com/federation_keyfile
% dacskey -u mysite.example.com -q jkeys
% install -o root -g www -m 0640 jkeys \
/usr/local/dacs/federations/example.com/mysite/jurisdiction_keyfile
</pre><p>
The owner, group, and mode assigned to these files in this example are
typical but are only suggestions.
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security1"></a>Security</h3><p>A keyfile generated by this command must be
accessible (readable and writable) <span class="emphasis"><em>only</em></span>
by <span class="command"><strong>DACS</strong></span> web services and the
<span class="command"><strong>DACS</strong></span> administrator.
It must be kept unreadable and unwritable by all others.</p></div><p>When not generating keys, by default <span class="emphasis"><em>keyfile</em></span>
is a pathname.
If the <code class="option">-vfs</code> flag is given, then
<span class="emphasis"><em>keyfile</em></span> is a <span class="command"><strong>DACS</strong></span> URI,
item type, or absolute pathname.
</p></div><div class="refsect1"><a name="idm96"></a><h2>OPTIONS</h2><p>In addition to the standard
<a class="ulink" href="dacs.1.html#dacsoptions" target="_top"><span class="emphasis"><em>dacsoptions</em></span></a>,
<span class="command"><strong>dacskey</strong></span> recognizes these options:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-gen</code></span></dt><dd><p>Generate new keys.
This is the default operation.
</p></dd><dt><span class="term"><code class="option">-check</code></span></dt><dd><p>Validate <em class="replaceable"><code>keyfile</code></em>,
an existing keyfile.
The <em class="replaceable"><code>keyfile</code></em> is expressed as a
<code class="literal">vfs-ref</code> or an absolute filename
(see <a class="ulink" href="dacs.conf.5.html#VFS" target="_top">dacs.conf(5)</a>).
</p></dd><dt><span class="term"><code class="option">-priv</code><br></span><span class="term"><code class="option">-private</code></span></dt><dd><p>Print the private key found in
<em class="replaceable"><code>keyfile</code></em>, an existing keyfile,
to <span class="symbol">stdout</span>.
The private key is <span class="emphasis"><em>not</em></span> encrypted.
If the <code class="option">-pem</code> flag is present, the PEM format is used,
otherwise the <span class="command"><strong>DACS</strong></span> base-64 encoding is used
(the latter is used when keys appear in XML attribute values).
</p></dd><dt><span class="term"><code class="option">-pub</code><br></span><span class="term"><code class="option">-public</code></span></dt><dd><p>Print the public key found in
<em class="replaceable"><code>keyfile</code></em>, an existing keyfile,
to <span class="symbol">stdout</span>.
If the <code class="option">-pem</code> flag is present, the PEM format is used,
otherwise the <span class="command"><strong>DACS</strong></span> base-64 encoding is used
(the latter is used when keys appear in XML attribute values).
</p></dd><dt><span class="term"><code class="option">-p</code></span></dt><dd><p>Rather than using the default source for generating
random strings, derive the random strings from material read from the
standard input.
The user is prompted for input.
This option should not be used under normal circumstances.
</p></dd><dt><span class="term"><code class="option">-pem</code></span></dt><dd><p>When printing a key, use the PEM format.
</p></dd><dt><span class="term"><code class="option">-pf</code> <em class="replaceable"><code>passphrase-file</code></em></span></dt><dd><p>Rather than using the default source for generating
random strings, derive the random strings from material read from
<em class="replaceable"><code>passphrase-file</code></em>.
If the filename argument is "<code class="option">-</code>", the standard input is read.
This option should not be used under normal circumstances.
</p></dd><dt><span class="term"><code class="option">-rsa_key_bits</code> <em class="replaceable"><code>number</code></em></span></dt><dd><p>This specifies the length of the RSA modulus, in bits,
used for asymmetric key generation.
Used as the <em class="parameter"><code>num</code></em> argument to
<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=RSA_generate_key&apropos=0&sektion=3&manpath=FreeBSD+10.1-RELEASE&format=html" target="_top">RSA_generate_key(3)</a>,
the value must satisfy that function's constraints.
</p></dd><dt><span class="term"><code class="option">--</code></span></dt><dd><p>This argument explicitly marks the end of the flags.
</p></dd></dl></div></div><div class="refsect1"><a name="idm171"></a><h2>DIAGNOSTICS</h2><p>The program exits <code class="literal">0</code> if everything was fine,
<code class="literal">1</code> if an error occurred.
</p></div><div class="refsect1"><a name="idm176"></a><h2>SEE ALSO</h2><p>
<a class="ulink" href="dacsauth.1.html" target="_top">dacsauth(1)</a>,
<a class="ulink" href="dacsgrid.1.html" target="_top">dacsgrid(1)</a>,
<a class="ulink" href="dacsinit.1.html" target="_top">dacsinit(1)</a>,
<a class="ulink" href="dacsrlink.1.html" target="_top">dacsrlink(1)</a>
<a class="ulink" href="dacstoken.1.html" target="_top">dacstoken(1)</a>,
<a class="ulink" href="dacs.install.7.html" target="_top">dacs.install(7)</a>,
<a class="ulink" href="dacs_acs.8.html" target="_top">dacs_acs(8)</a>
</p></div><div class="refsect1"><a name="idm186"></a><h2>AUTHOR</h2><p>Distributed Systems Software
(<a class="ulink" href="http://www.dss.ca" target="_top">www.dss.ca</a>)
</p></div><div class="refsect1"><a name="idm190"></a><h2>COPYING</h2><p>Copyright 2003-2014 Distributed Systems Software.
See the
<a class="ulink" href="../misc/LICENSE" target="_top"><code class="filename">LICENSE</code></a>
file that accompanies the distribution
for licensing information.
</p></div>
<!-- Generated from $Id: dacskey.1.xml 2759 2014-12-31 18:02:17Z brachman $ -->
<table width="100%"><tr>
<td align="left">
<b>DACS Version 1.4.38a</b></td>
<td align="center">
<b> 5-Feb-2018</b></td>
<td align="right">
<b>DACSKEY(1)</b></td>
</tr></table>
<hr><p>
<!-- Begin font size selector -->
<table width="100%"><tr><td align="left">
<span class="set_font"><a href="index.html" title="Table of Contents">Table of Contents</a></span></td>
<td align="center"><span class="logo"><a href="http://www.dss.ca"><img src="/css/images/dss-long-14y.png" title="Distributed Systems Software, Inc."></a></span></td>
<td width="5%" align="right">
<div class="fontsize_label" title="Font size selector">Font:</div>
</td>
<td width="10%" align="left">
<!-- NB: must set both left margin and padding to work in all browsers-->
<!-- The onFocus code eliminates annoying post-click decoration -->
<ul id="fontsizecontainer" class="size02">
<li><a href="javascript:setFont('0');" onFocus="if(this.blur)this.blur()" title="Smallest text size [0]"><span>Z</span></a></li>
<li><a href="javascript:setFont('1');" onFocus="if(this.blur)this.blur()" title="Medium text size [1]"><span>Z</span></a></li>
<li><a href="JavaScript:setFont('2');" onFocus="if(this.blur)this.blur()" title="Large text size [2]"><span>Z</span></a></li>
<li><a href="JavaScript:setFont('3');" onFocus="if(this.blur)this.blur()" title="Largest text size [3]"><span>Z</span></a></li>
</ul>
</td>
<td width="3%" align="center">
<span class="set_font"><a href="javascript:setFont('-');" onFocus="if(this.blur)this.blur()" title="Decrease current font size">−−</a></span>
</td>
<td width="3%" align="center">
<span class="set_font"><a href="javascript:setFontConfig();" onFocus="if(this.blur)this.blur()" title="Remember current font size">Set</a></span>
</td>
<td width="3%" align="center">
<span class="set_font"><a href="javascript:setFont('+');" onFocus="if(this.blur)this.blur()" title="Increase current font size">++</a></span>
</td></tr></table>
<!-- End font size selector -->
<script language="javascript" type="text/javascript">
doFontConfig();</script>
</p><small><p><b> $Id: dacskey.1.xml 2759 2014-12-31 18:02:17Z brachman $</b></p></small>
</div></body></html>
|