1MONKEYSPHERE-HOST(8)            System Commands           MONKEYSPHERE-HOST(8)
2
3
4

NAME

6       monkeysphere-host - Monkeysphere host key administration tool.
7
8

SYNOPSIS

10       monkeysphere-host subcommand [args]
11
12

DESCRIPTION

14       Monkeysphere  is  a  framework to leverage the OpenPGP web of trust for
15       SSH and TLS key-based authentication.
16
17       monkeysphere-host stores and manages OpenPGP certificates  for  various
18       services offered by the host.
19
20       Most  subcommands  take  a KEYID argument, which identifies (by OpenPGP
21       key ID (e.g. 0xDEADBEEF) or full OpenPGP fingerprint) which certificate
22       is  to  be operated upon.  If only one certificate is currently managed
23       by monkeysphere-host, the KEYID argument may be  omitted,  and  monkey‐
24       sphere-host will operate on it.
25
26

SUBCOMMANDS

28       monkeysphere-host takes various subcommands:
29
30       import-key FILE SCHEME://HOSTNAME[:PORT]
31              Import a PEM-encoded host secret key from file FILE.  If FILE is
32              `-', then the key will be imported from stdin.   Only  RSA  keys
33              are  supported  at the moment.  SCHEME://HOSTNAME[:PORT] is used
34              to specify the scheme (e.g. ssh or https), fully-qualified host‐
35              name (and port) used in the user ID of the new OpenPGP key (e.g.
36              ssh://example.net or https://www.example.net).  If PORT  is  not
37              specified, then no port is added to the user ID, which means the
38              default port for that service (e.g. 22 for ssh) is assumed.  `i'
39              may be used in place of `import-key'.
40
41       show-keys [KEYID ...]
42              Output information about the OpenPGP certificate(s) for services
43              offered by the host, including their KEYIDs.   If  no  KEYID  is
44              specified  (or  if  the  special string `--all' is used), output
45              information about all certificates managed by monkeysphere-host.
46              `s' may be used in place of `show-keys'.
47
48       set-expire EXPIRE [KEYID]
49              Extend  the  validity of the OpenPGP certificate specified until
50              EXPIRE from the present.  Expiration is specified as with  GnuPG
51              (measured from today's date):
52                       0 = key does not expire
53                    <n>  = key expires in n days
54                    <n>w = key expires in n weeks
55                    <n>m = key expires in n months
56                    <n>y = key expires in n years
57              `e' may be used in place of `set-expire'.
58
59       add-servicename SCHEME://HOSTNAME[:PORT] [KEYID]
60              Add  a  service-specific  user  ID to the specified certificate.
61              For example, the operator of `https://example.net' may  wish  to
62              add  an  additional  servicename of `https://www.example.net' to
63              the certificate corresponding to the  secret  key  used  by  the
64              TLS-enabled web server.  `add-name' or `n+' may be used in place
65              of `add-servicename'.
66
67       revoke-servicename SCHEME://HOSTNAME[:PORT] [KEYID]
68              Revoke a service-specific user ID from  the  specified  certifi‐
69              cate.    `revoke-name'   or   `n-'  may  be  used  in  place  of
70              `revoke-servicename'.
71
72       add-revoker REVOKER_KEYID|FILE [KEYID]
73              Add a revoker to the specified OpenPGP certificate.  The revoker
74              can  be  specified  by their own REVOKER_KEYID (in which case it
75              will be loaded from an OpenPGP keyserver), or  by  specifying  a
76              path  to a file containing the revoker's OpenPGP certificate, or
77              by specifying `-' to load from stdin.  `r+' may be  be  used  in
78              place of `add-revoker'.
79
80       revoke-key [KEYID]
81              Generate  (with  the option to publish) a revocation certificate
82              for given OpenPGP certificate.  If such a  certificate  is  pub‐
83              lished,  the  given key will be permanently revoked, and will no
84              longer be accepted by monkeysphere-enabled clients.   This  sub‐
85              command  will ask you a series of questions, and then generate a
86              key revocation certificate, sending it  to  stdout.   You  might
87              want  to  store these certificates safely offline, to publish in
88              case of compromise).  If you explicitly tell it to  publish  the
89              revocation  certificate immediately, it will send it to the pub‐
90              lic keyservers.  PUBLISH THESE CERTIFICATES ONLY IF YOU ARE SURE
91              THE CORRESPONDING KEY WILL NEVER BE RE-USED!
92
93       publish-keys [KEYID ...]
94              Publish  the  specified  OpenPGP certificates to the public key‐
95              servers.  If the special string `--all' is specified, all of the
96              host's  OpenPGP certificates will be published.  `p' may be used
97              in place of `publish-keys'.  NOTE:  that  there  is  no  way  to
98              remove a key from the public keyservers once it is published!
99
100       version
101              Show  the monkeysphere version number.  `v' may be used in place
102              of `version'.
103
104       help   Output a brief usage summary.  `h' or `?' may be used  in  place
105              of `help'.
106
107       diagnostics
108              Review  the state of the monkeysphere server host key and report
109              on suggested changes.  Among other checks, this includes  making
110              sure  there  is  a  valid host key, that the key is not expired,
111              that the sshd configuration points to the right place, etc.  `d'
112              may be used in place of `diagnostics'.
113
114

SETUP SSH SERVER CERTIFICATES

116       To  enable users to verify your SSH host's key via the monkeysphere, an
117       OpenPGP certificate must be made out of the host's RSA ssh key, and the
118       certificate  must be published to the Web of Trust.  Certificate publi‐
119       cation is not done by default.  The first step is to import the  host's
120       ssh  key  into  a monkeysphere-style OpenPGP certificate.  This is done
121       with the import-key command.  For example:
122
123       #      monkeysphere-host      import-key      /etc/ssh/ssh_host_rsa_key
124       ssh://host.example.org
125
126       On    most    systems,   sshd's   RSA   secret   key   is   stored   at
127       /etc/ssh/ssh_host_rsa_key.
128
129       See PUBLISHING AND CERTIFYING MONKEYSPHERE SERVICE CERTIFICATES for how
130       to make sure your users can verify the ssh service offered by your host
131       once the key is imported into monkeysphere-host.
132
133

SETUP WEB SERVER CERTIFICATES

135       You can set up your HTTPS-capable web server so  that  your  users  can
136       verify it via the monkeysphere, without changing your server's software
137       at all.  You just  need  access  to  a  (PEM-encoded)  version  of  the
138       server's   RSA   secret  key  (most  secret  keys  are  already  stored
139       PEM-encoded).  The first step is to import the web server's key into  a
140       monkeysphere-style   OpenPGP   certificate.   This  is  done  with  the
141       import-key command.  For example:
142
143       #     monkeysphere-host     import-key      /etc/ssl/private/host.exam‐
144       ple.net-key.pem https://host.example.net
145
146       If you don't know where the web server's key is stored on your machine,
147       consult the configuration files for your web server.  Debian-based sys‐
148       tems  using  the  `ssl-cert'  packages often have a default self-signed
149       certificate stored  in  `/etc/ssl/private/ssl-cert-snakeoil.key'  ;  if
150       you're  using  that  key, your users are getting browser warnings about
151       it.  You can keep using the same key, but help them use the OpenPGP WoT
152       to  verify  that  it  does belong to your web server by using something
153       like:
154
155       # monkeysphere-host  import-key  /etc/ssl/private/ssl-cert-snakeoil.key
156       https://$(hostname --fqdn)
157
158       If  you  offer  multiple  HTTPS websites using the same secret key, you
159       should add the additional website names with the `add-servicename' sub‐
160       command.
161
162       See  PUBLISHING  AND  CERTIFYING MONKEYSPHERE SERVICE CERTIFICATES (the
163       next section) for how to make sure your users can verify the https ser‐
164       vice  offered  by your host once the key is imported and any extra site
165       names have been added.  Note that you can add or remove additional ser‐
166       vicenames  at  any  time, but you'll need to certify any new ones sepa‐
167       rately.
168
169

PUBLISHING AND CERTIFYING MONKEYSPHERE SERVICE CERTIFICATES

171       Once the host key has been imported, the corresponding certificate must
172       be  published  to  the Web of Trust so that users can retrieve the cert
173       when connecting to the host.  The host certificates  are  published  to
174       the keyserver with the publish-key command:
175
176       $ monkeysphere-host publish-key --all
177
178       In  order  for  users  accessing  the system to be able to identify the
179       host's service via the monkeysphere, at least one person (e.g. a server
180       admin)  will  need  to sign the host's certificate.  This is done using
181       standard OpenPGP  keysigning  techniques.   Usually:  pull  the  host's
182       OpenPGP  certificate  from  the keyserver, verify and sign it, and then
183       re-publish your signature.  More than one person can certify  any  cer‐
184       tificate.   Please  see http://web.monkeysphere.info/signing-host-keys/
185       for more information and details.  Once an admin's  signature  is  pub‐
186       lished,  users  accessing  the host can use the certificate to validate
187       the host's key without having to manually check the host key's  finger‐
188       print (in the case of ssh) or without seeing a nasty "security warning"
189       in their browsers (in the case of https).
190
191

SECURITY CONSIDERATIONS

193       Note that monkeysphere-host currently caches a  copy  of  all  imported
194       secret  keys  (stored  in  OpenPGP  form  for  future  manipulation) in
195       /var/lib/monkeysphere/host/secring.gpg.  Cleartext backups of this file
196       could expose secret key material if not handled sensitively.
197
198

ENVIRONMENT

200       The  following  environment  variables will override those specified in
201       the config file (defaults in parentheses):
202
203       MONKEYSPHERE_LOG_LEVEL
204              Set the log level.  Can be SILENT, ERROR, INFO, VERBOSE,  DEBUG,
205              in increasing order of verbosity. (INFO)
206
207       MONKEYSPHERE_KEYSERVER
208              OpenPGP keyserver to use. (pool.sks-keyservers.net)
209
210       MONKEYSPHERE_PROMPT
211              If  set  to  `false',  never  prompt  the user for confirmation.
212              (true)
213
214

FILES

216       /etc/monkeysphere/monkeysphere-host.conf
217              System monkeysphere-host config file.
218
219       /var/lib/monkeysphere/host_keys.pub.pgp
220              A world-readable copy of  the  host's  OpenPGP  certificates  in
221              ASCII armored format.  This includes the certificates (including
222              the public keys, servicename-based User  IDs,  and  most  recent
223              relevant  self-signatures)  corresponding  to  every key used by
224              Monkeysphere-enabled services on the host.
225
226       /var/lib/monkeysphere/host/
227              A locked directory (readable only by the  superuser)  containing
228              copies of all imported secret keys (this is the host's GNUPGHOME
229              directory).
230
231       /etc/monkeysphere/monkeysphere-host-x509-anchors.crt                 or
232       /etc/monkeysphere/monkeysphere-x509-anchors.crt
233              If  monkeysphere-host  is  configured to query an hkps keyserver
234              for publish-keys, it will use X.509 Certificate  Authority  cer‐
235              tificates  in  this file to validate any X.509 certificates used
236              by  the  keyserver.   If  the  monkeysphere-host-x509  file   is
237              present, the monkeysphere-x509 file will be ignored.
238
239

AUTHOR

241       This  man  page  was  written  by: Jameson Rollins <jrollins@finestruc‐
242       ture.net>, Daniel Kahn Gillmor <dkg@fifthhorseman.net>,  Matthew  Goins
243       <mjgoins@openflows.com>
244
245

SEE ALSO

247       monkeysphere(1),   monkeysphere(7),   gpg(1),  monkeysphere-authentica‐
248       tion(8), ssh(1), sshd(8)
249
250
251
252monkeysphere                     January 2010             MONKEYSPHERE-HOST(8)
Impressum