aboutsummaryrefslogtreecommitdiffstats
path: root/lacme-accountd.md
blob: 403c68c1ffe4126dd94758278bd9d05b1a828f09 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
% lacme-accountd(1)
% [Guilhem Moulin](mailto:guilhem@fripost.org)
% March 2016

Name
====

lacme-accountd - [ACME] client written with process isolation and
minimal privileges in mind (account key manager)

Synopsis
========

`lacme-accountd` [`--config=FILENAME`] [`--privkey=ARG`] [`--socket=PATH`] [`--quiet`]

Description
===========

`lacme-accountd` is the account key manager component of [`lacme`(1)], a
small [ACME] client written with process isolation and minimal
privileges in mind.  No other [`lacme`(1)] component needs access to the
account key; in fact the account key could as well be stored on another
host or a smartcard.

`lacme-accountd` binds to a UNIX-domain socket (specified with
`--socket=`), which [ACME] clients can connect to in order to request
data signatures.
As a consequence, `lacme-accountd` needs to be up and running before
using [`lacme`(1)] to issue [ACME] commands.  Also, the process does not
automatically terminate after the last signature request: instead, one
sends an `INT` or `TERM` [`signal`(7)] to bring the server down.

Furthermore, one can use the UNIX-domain socket forwarding facility of
[OpenSSH] 6.7 and later to run `lacme-accountd` and [`lacme`(1)] on
different hosts.  For instance one could store the account key on a
machine that is not exposed to the internet.  See the
**[examples](#examples)** section below.

Options
=======

`--config=`*filename*

:   Use *filename* as configuration file.  See the **[configuration
    file](#configuration-file)** section below for the configuration
    options.

`--privkey=`*arg*

:   Specify the (private) account key to use for signing requests.
    Currently supported *arg*uments are:

    * `file:`*FILE*, to specify an encrypted private key (in PEM
      format); and
    * `gpg:`*FILE*, to specify a [`gpg`(1)]-encrypted private key (in
      PEM format).

    The following command can be used to generate a new 4096-bits RSA
    key in PEM format with mode 0600:

        openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/account.key

`--socket=`*path*

:   Use *path* as the UNIX-domain socket to bind against for signature
    requests from the [ACME] client.  `lacme-accountd` aborts if *path*
    exists or if its parent directory is writable by other users.

`-h`, `--help`

:   Display a brief help and exit.

`-q`, `--quiet`

:   Be quiet.

`--debug`

:   Turn on debug mode.

Configuration file
==================

If `--config=` is not given, `lacme-accountd` uses the first existing
configuration file among *./lacme-accountd.conf*,
*$XDG_CONFIG_HOME/lacme/lacme-accountd.conf* (or
*~/.config/lacme/lacme-accountd.conf* if the `XDG_CONFIG_HOME`
environment variable is not set), and */etc/lacme/lacme-accountd.conf*.

When given on the command line, the `--privkey=`, `--socket=` and
`--quiet` options take precedence over their counterpart (without
leading `--`) in the configuration file.  Valid options are:

*privkey*

:   See `--privkey=`.  This option is required when `--privkey=` is not
    specified on the command line.

*gpg*

:   For a [`gpg`(1)]-encrypted private account key, specify the binary
    [`gpg`(1)] to use, as well as some default options.
    Default: `gpg --quiet`.

*socket*

:   See `--socket=`.
    Default: *$XDG_RUNTIME_DIR/S.lacme* if the `XDG_RUNTIME_DIR`
    environment variable is set.

*quiet*

:   Be quiet. Possible values: `Yes`/`No`.

Examples
========

Run `lacme-accountd` in a first terminal:

    ~$ lacme-accountd --privkey=file:/path/to/account.key --socket=$XDG_RUNTIME_DIR/S.lacme

Then, while `lacme-accountd` is running, execute locally [`lacme`(1)] in
another terminal:

    ~$ sudo lacme --socket=$XDG_RUNTIME_DIR/S.lacme newOrder

Alternatively, use [OpenSSH] 6.7 or later to forward the socket and
execute [`lacme`(1)] remotely:

    ~$ ssh -oExitOnForwardFailure=yes -tt -R /path/to/remote.sock:$XDG_RUNTIME_DIR/S.lacme user@example.org \
       sudo lacme --socket=/path/to/remote.sock newOrder

See also
========

[`lacme`(1)], [`ssh`(1)]

[ACME]: https://tools.ietf.org/html/rfc8555
[`lacme`(1)]: lacme.1.html
[`signal`(7)]: http://linux.die.net/man/7/signal
[`gpg`(1)]: https://www.gnupg.org/documentation/manpage.en.html
[OpenSSH]: http://www.openssh.com/
[`ssh`(1)]: http://man.openbsd.org/ssh