.\" Copyright (c) 2003-2012
.\" Distributed Systems Software.  All rights reserved.
.\" See the file LICENSE for redistribution information.
.\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $
'\" t
.\"     Title: dacskey
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 08/23/2020
.\"    Manual: DACS Commands Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACSKEY" "1" "08/23/2020" "DACS 1.4.40" "DACS Commands Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
dacskey \- generate encryption keys for \fBDACS\fR
.SH "SYNOPSIS"
.HP \w'\fBdacskey\fR\ 'u
\fBdacskey\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR]
.br
[\fB\-check\fR | \fB\-gen\fR | \fB\-priv\fR | \fB\-private\fR | \fB\-pub\fR | \fB\-public\fR]
.br
[\fB\-p\fR | \fB\-pf\ \fR\fB\fIpassphrase\-file\fR\fR] [\fB\-pem\fR] [\fB\-vfs\fR] [\fB\-rsa_key_bits\fR\ \fInumber\fR] [\fB\-\-\fR] \fIkeyfile\fR
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacskey\fR
utility generates encryption keys for
\fBDACS\fR
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\&.
.PP
Keys are created for at least three different purposes, although every keyfile has the same format:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Keys that are shared by all of the jurisdictions within the same
\fBDACS\fR
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\&.
.sp
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)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Keys that are used by a
\fBDACS\fR
application at a particular jurisdiction for its own purposes (\m[blue]\fBdacsgrid(1)\fR\m[]\&\s-2\u[2]\d\s+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\&.
.RE
.PP
The program ordinarily uses
\fBOpenSSL\fR\*(Aqs
\m[blue]\fBssl(3)\fR\m[]\&\s-2\u[3]\d\s+2
library to acquire high\-quality random material\&. In certain situations, an experienced administrator might find the
\fB\-p\fR
and
\fB\-pf\fR
options useful; others should avoid them, however\&.
.PP
When keys are generated, the output is written to
\fIkeyfile\fR, which is either created or truncated\&. In this context,
\fIkeyfile\fR
must be a pathname\&. Unless directly written to where
federation_keys
(or
jurisdiction_keys) points,
\fIkeyfile\fR
must be copied there\&.
.PP
Assuming that the default site configuration file (conf/site\&.conf\-std, which establishes default locations for these files) has been installed:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacskey \-u mysite\&.example\&.com \-q fkeys
% install \-o root \-g www \-m 0640 fkeys \e
      /usr/local/dacs/federations/example\&.com/federation_keyfile
% dacskey \-u mysite\&.example\&.com \-q jkeys
% install \-o root \-g www \-m 0640 jkeys \e
      /usr/local/dacs/federations/example\&.com/mysite/jurisdiction_keyfile
.fi
.if n \{\
.RE
.\}
.sp
The owner, group, and mode assigned to these files in this example are typical but are only suggestions\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
A keyfile generated by this command must be accessible (readable and writable)
\fIonly\fR
by
\fBDACS\fR
web services and the
\fBDACS\fR
administrator\&. It must be kept unreadable and unwritable by all others\&.
.sp .5v
.RE
.PP
When not generating keys, by default
\fIkeyfile\fR
is a pathname\&. If the
\fB\-vfs\fR
flag is given, then
\fIkeyfile\fR
is a
\fBDACS\fR
URI, item type, or absolute pathname\&.
.SH "OPTIONS"
.PP
In addition to the standard
\m[blue]\fB\fIdacsoptions\fR\fR\m[]\&\s-2\u[1]\d\s+2,
\fBdacskey\fR
recognizes these options:
.PP
\fB\-gen\fR
.RS 4
Generate new keys\&. This is the default operation\&.
.RE
.PP
\fB\-check\fR
.RS 4
Validate
\fIkeyfile\fR, an existing keyfile\&. The
\fIkeyfile\fR
is expressed as a
vfs\-ref
or an absolute filename (see
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[4]\d\s+2)\&.
.RE
.PP
\fB\-priv\fR
.br
\fB\-private\fR
.RS 4
Print the private key found in
\fIkeyfile\fR, an existing keyfile, to
stdout\&. The private key is
\fInot\fR
encrypted\&. If the
\fB\-pem\fR
flag is present, the PEM format is used, otherwise the
\fBDACS\fR
base\-64 encoding is used (the latter is used when keys appear in XML attribute values)\&.
.RE
.PP
\fB\-pub\fR
.br
\fB\-public\fR
.RS 4
Print the public key found in
\fIkeyfile\fR, an existing keyfile, to
stdout\&. If the
\fB\-pem\fR
flag is present, the PEM format is used, otherwise the
\fBDACS\fR
base\-64 encoding is used (the latter is used when keys appear in XML attribute values)\&.
.RE
.PP
\fB\-p\fR
.RS 4
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\&.
.RE
.PP
\fB\-pem\fR
.RS 4
When printing a key, use the PEM format\&.
.RE
.PP
\fB\-pf\fR \fIpassphrase\-file\fR
.RS 4
Rather than using the default source for generating random strings, derive the random strings from material read from
\fIpassphrase\-file\fR\&. If the filename argument is "\fB\-\fR", the standard input is read\&. This option should not be used under normal circumstances\&.
.RE
.PP
\fB\-rsa_key_bits\fR \fInumber\fR
.RS 4
This specifies the length of the RSA modulus, in bits, used for asymmetric key generation\&. Used as the
\fInum\fR
argument to
\m[blue]\fBRSA_generate_key(3)\fR\m[]\&\s-2\u[5]\d\s+2, the value must satisfy that function\*(Aqs constraints\&.
.RE
.PP
\fB\-\-\fR
.RS 4
This argument explicitly marks the end of the flags\&.
.RE
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[6]\d\s+2,
\m[blue]\fBdacsgrid(1)\fR\m[]\&\s-2\u[2]\d\s+2,
\m[blue]\fBdacsinit(1)\fR\m[]\&\s-2\u[7]\d\s+2,
\m[blue]\fBdacsrlink(1)\fR\m[]\&\s-2\u[8]\d\s+2
\m[blue]\fBdacstoken(1)\fR\m[]\&\s-2\u[9]\d\s+2,
\m[blue]\fBdacs\&.install(7)\fR\m[]\&\s-2\u[10]\d\s+2,
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[11]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[12]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2018 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[13]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
dacsoptions
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#dacsoptions
.RE
.IP " 2." 4
dacsgrid(1)
.RS 4
\%http://dacs.dss.ca/man/dacsgrid.1.html
.RE
.IP " 3." 4
ssl(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=ssl&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP " 4." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#VFS
.RE
.IP " 5." 4
RSA_generate_key(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=RSA_generate_key&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP " 6." 4
dacsauth(1)
.RS 4
\%http://dacs.dss.ca/man/dacsauth.1.html
.RE
.IP " 7." 4
dacsinit(1)
.RS 4
\%http://dacs.dss.ca/man/dacsinit.1.html
.RE
.IP " 8." 4
dacsrlink(1)
.RS 4
\%http://dacs.dss.ca/man/dacsrlink.1.html
.RE
.IP " 9." 4
dacstoken(1)
.RS 4
\%http://dacs.dss.ca/man/dacstoken.1.html
.RE
.IP "10." 4
dacs.install(7)
.RS 4
\%http://dacs.dss.ca/man/dacs.install.7.html
.RE
.IP "11." 4
dacs_acs(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html
.RE
.IP "12." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "13." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE