---
name: "dacskey"
section: "1"
platform: "linux"
package: "dacs"
version: "1.4.40-2"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/dacskey"
---

# dacskey(1)

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)](/dacsgrid/1.md)**\[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)](/ssl/3.md)**\[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)](/dacs.conf/5.md)**\[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)](/dacsauth/1.md)**\[6\], **[dacsgrid(1)](/dacsgrid/1.md)**\[2\], **[dacsinit(1)](/dacsinit/1.md)**\[7\], **[dacsrlink(1)](/dacsrlink/1.md)**\[8\] **[dacstoken(1)](/dacstoken/1.md)**\[9\], **[dacs.install(7)](/dacs.install/7.md)**\[10\], **[dacs\_acs(8)](/dacs_acs/8.md)**\[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)](/dacsgrid/1.md)

  http://dacs.dss.ca/man/dacsgrid.1.html

- 3\.

  [ssl(3)](/ssl/3.md)

  https://www.freebsd.org/cgi/man.cgi?query=ssl&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html

- 4\.

  [dacs.conf(5)](/dacs.conf/5.md)

  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)](/dacsauth/1.md)

  http://dacs.dss.ca/man/dacsauth.1.html

- 7\.

  [dacsinit(1)](/dacsinit/1.md)

  http://dacs.dss.ca/man/dacsinit.1.html

- 8\.

  [dacsrlink(1)](/dacsrlink/1.md)

  http://dacs.dss.ca/man/dacsrlink.1.html

- 9\.

  [dacstoken(1)](/dacstoken/1.md)

  http://dacs.dss.ca/man/dacstoken.1.html

- 10\.

  [dacs.install(7)](/dacs.install/7.md)

  http://dacs.dss.ca/man/dacs.install.7.html

- 11\.

  [dacs\_acs(8)](/dacs_acs/8.md)

  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