dacskey - generate encryption keys for DACS
dacskey [dacsoptions[1]]
[-check | -gen | -priv | -private | -pub |
-public]
[-p | -pf passphrase-file] [-pem]
[-vfs] [-rsa_key_bits number] [--]
keyfile
This program is part of the DACS suite.
The dacskey utility generates encryption keys for
DACS that are cryptographically sound. Keys are represented
externally as an XML document called a keyfile. The program can also
validate a keyfile or display a key.
Keys are created for at least three different purposes, although
every keyfile has the same format:
•Keys that are shared by all of the jurisdictions
within the same
DACS federation, identified by the virtual filestore
item type federation_keys. 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.
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).
•Keys that are used by a jurisdiction for its own
purposes, identified by the virtual filestore item type jurisdiction_keys.
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.
•Keys that are used by a
DACS application
at a particular jurisdiction for its own purposes (
dacsgrid(1)[2], 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.
The program ordinarily uses OpenSSL's ssl(3)[3]
library to acquire high-quality random material. In certain situations, an
experienced administrator might find the -p and -pf options
useful; others should avoid them, however.
When keys are generated, the output is written to keyfile,
which is either created or truncated. In this context, keyfile must
be a pathname. Unless directly written to where federation_keys (or
jurisdiction_keys) points, keyfile must be copied there.
Assuming that the default site configuration file
(conf/site.conf-std, which establishes default locations for these files)
has been installed:
% 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
The owner, group, and mode assigned to these files in this example
are typical but are only suggestions.
Security
A keyfile generated by this command must be accessible (readable
and writable) only by DACS web services and the DACS
administrator. It must be kept unreadable and unwritable by all others.
When not generating keys, by default keyfile is a pathname.
If the -vfs flag is given, then keyfile is a DACS URI,
item type, or absolute pathname.
In addition to the standard dacsoptions[1],
dacskey recognizes these options:
-gen
Generate new keys. This is the default operation.
-check
Validate
keyfile, an existing keyfile. The
keyfile is expressed as a vfs-ref or an absolute filename (see
dacs.conf(5)[4]).
-priv
-private
Print the private key found in keyfile, an
existing keyfile, to stdout. The private key is not encrypted. If the
-pem flag is present, the PEM format is used, otherwise the DACS
base-64 encoding is used (the latter is used when keys appear in XML attribute
values).
-pub
-public
Print the public key found in keyfile, an existing
keyfile, to stdout. If the -pem flag is present, the PEM format is
used, otherwise the DACS base-64 encoding is used (the latter is used
when keys appear in XML attribute values).
-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.
-pem
When printing a key, use the PEM format.
-pf passphrase-file
Rather than using the default source for generating
random strings, derive the random strings from material read from
passphrase-file. If the filename argument is "-", the
standard input is read. This option should not be used under normal
circumstances.
-rsa_key_bits number
This specifies the length of the RSA modulus, in bits,
used for asymmetric key generation. Used as the
num argument to
RSA_generate_key(3)[5], the value must satisfy that function's
constraints.
--
This argument explicitly marks the end of the
flags.
The program exits 0 if everything was fine, 1 if an error
occurred.
Distributed Systems Software (www.dss.ca[12])
Copyright © 2003-2018 Distributed Systems Software. See the
LICENSE[13] file that accompanies the distribution for licensing
information.
- 1.
- dacsoptions
http://dacs.dss.ca/man/dacs.1.html#dacsoptions
- 2.
- dacsgrid(1)
http://dacs.dss.ca/man/dacsgrid.1.html
- 3.
- ssl(3)
https://www.freebsd.org/cgi/man.cgi?query=ssl&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
- 4.
- dacs.conf(5)
http://dacs.dss.ca/man/dacs.conf.5.html#VFS
- 5.
- RSA_generate_key(3)
https://www.freebsd.org/cgi/man.cgi?query=RSA_generate_key&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
- 6.
- dacsauth(1)
http://dacs.dss.ca/man/dacsauth.1.html
- 7.
- dacsinit(1)
http://dacs.dss.ca/man/dacsinit.1.html
- 8.
- dacsrlink(1)
http://dacs.dss.ca/man/dacsrlink.1.html
- 9.
- dacstoken(1)
http://dacs.dss.ca/man/dacstoken.1.html
- 10.
- dacs.install(7)
http://dacs.dss.ca/man/dacs.install.7.html
- 11.
- dacs_acs(8)
http://dacs.dss.ca/man/dacs_acs.8.html
- 12.
- www.dss.ca
http://www.dss.ca
- 13.
- LICENSE
http://dacs.dss.ca/man/../misc/LICENSE