dacskey

DACSKEY(1)                    DACS Commands Manual                    DACSKEY(1)



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.

SEE ALSO
       dacsauth(1)[6], dacsgrid(1)[2], dacsinit(1)[7], dacsrlink(1)[8]
       dacstoken(1)[9], dacs.install(7)[10], dacs_acs(8)[11]

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



DACS 1.4.40                        02/19/2019                         DACSKEY(1)