Ubuntu Manpage: dacskey - generate encryption keys for DACS

NAME

       dacskey - generate encryption keys for DACS

SYNOPSIS

       dacskey [dacsoptions[1]]
               [-check | -gen | -priv | -private | -pub | -public]
               [-p | -pf passphrase-file] [-pem] [-vfs] [-rsa_key_bits number] [--] keyfile

DESCRIPTION

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.

OPTIONS

       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.

DIAGNOSTICS

       The program exits 0 if everything was fine, 1 if an error occurred.

AUTHOR

       Distributed Systems Software (www.dss.ca[12])

COPYING

       Copyright © 2003-2018 Distributed Systems Software. See the LICENSE[13] file that
       accompanies the distribution for licensing information.

NOTES

        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