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
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
lws-acme-client Plugin
======================
## Introduction
lws-acme-client is a protcol plugin for libwebsockets that implements an
ACME client able to communicate with let's encrypt and other certificate
providers.
It implements `tls-sni-01` challenge, and is able to provision tls certificates
"from thin air" that are accepted by all the major browsers. It also manages
re-requesting the certificate when it only has two weeks left to run.
It works with both the OpenSSL and mbedTLS backends.
## Overview for use
You need to:
- Provide name resolution to the IP with your server, ie, myserver.com needs to
resolve to the IP that hosts your server
- Enable port forwarding / external firewall access to your port, usually 443
- Enable the "lws-acme-client" plugin on the vhosts you want it to manage
certs for
- Add per-vhost options describing what should be in the certificate
After that the plugin will sort everything else out.
## Example lwsws setup
```
"vhosts": [ {
"name": "home.warmcat.com",
"port": "443",
"host-ssl-cert": "/etc/lwsws/acme/home.warmcat.com.crt.pem",
"host-ssl-key": "/etc/lwsws/acme/home.warmcat.com.key.pem",
"ignore-missing-cert": "1",
"access-log": "/var/log/lwsws/test-access-log",
"ws-protocols": [{
"lws-acme-client": {
"auth-path": "/etc/lwsws/acme/auth.jwk",
"cert-path": "/etc/lwsws/acme/home.warmcat.com.crt.pem",
"key-path": "/etc/lwsws/acme/home.warmcat.com.key.pem",
"directory-url": "https://acme-staging.api.letsencrypt.org/directory",
"country": "TW",
"state": "Taipei",
"locality": "Xiaobitan",
"organization": "Crash Barrier Ltd",
"common-name": "home.warmcat.com",
"email": "andy@warmcat.com"
},
...
```
## Required PVOs
Notice that the `"host-ssl-cert"` and `"host-ssl-key"` entries have the same
meaning as usual, they point to your certificate and private key. However
because the ACME plugin can provision these, you should also mark the vhost with
`"ignore-missing-cert" : "1"`, so lwsws will ignore what will initially be
missing certificate / keys on that vhost, and will set about creating the
necessary certs and keys instead of erroring out.
You must make sure the directories mentioned here exist, lws doesn't create them
for you. They should be 0700 root:root, even if you drop lws privileges.
If you are implementing support in code, this corresponds to making sure the
vhost creating `info.options` has the `LWS_SERVER_OPTION_IGNORE_MISSING_CERT`
bit set.
Similarly, in code, the each of the per-vhost options shown above can be
provided in a linked-list of structs at vhost creation time. See
`./test-apps/test-server-v2.0.c` for example code for providing pvos.
### auth-path
This is where the plugin will store the auth keys it generated.
### cert-path
Where the plugin will store the certificate file. Should match `host-ssl-cert`
that the vhost wants to use.
The path should include at least one 0700 root:root directory.
### key-path
Where the plugin will store the certificate keys. Again it should match
`host-ssl-key` the vhost is trying to use.
The path should include at least one 0700 root:root directory.
### directory-url
This defines the URL of the certification server you will get your
certificates from. For let's encrypt, they have a "practice" one
- `https://acme-staging.api.letsencrypt.org/directory`
and they have a "real" one
- `https://acme-v01.api.letsencrypt.org/directory`
the main difference is the CA certificate for the real one is in most browsers
already, but the staging one's CA certificate isn't. The staging server will
also let you abuse it more in terms of repeated testing etc.
It's recommended you confirm expected operation with the staging directory-url,
and then switch to the "real" URL.
### common-name
Your server DNS name, like "libwebsockets.org". The remote ACME server will
use this to find your server to perform the SNI challenges.
### email
The contact email address for the certificate.
## Optional PVOs
These are not included in the cert by letsencrypt
### country
Two-letter country code for the certificate
### state
State "or province" for the certificate
### locality
Locality for the certificate
### organization
Your company name
## Security / Key storage considerations
The `lws-acme-client` plugin is able to provision and update your certificate
and keys in an entirely root-only storage environment, even though lws runs
as a different uid / gid with no privileges to access the storage dir.
It does this by opening and holding two WRONLY fds on "update paths" inside the
root directory structure for each cert and key it manages; these are the normal
cert and key paths with `.upd` appended. If during the time the server is up
the certs become within two weeks of expiry, the `lws-acme-client` plugin will
negotiate new certs and write them to the file descriptors.
Next time the server starts, if it sees `.upd` cert and keys, it will back up
the old ones and copy them into place as the new ones, before dropping privs.
To also handle the long-uptime server case, lws will update the vhost with the
new certs using in-memory temporary copies of the cert and key after updating
the cert.
In this way the cert and key live in root-only storage but the vhost is kept up
to date dynamically with any cert changes as well.
## Multiple vhosts using same cert
In the case you have multiple vhosts using of the same cert, just attach
the `lws-acme-client` plugin to one instance. When the cert updates, all the
vhosts are informed and vhosts using the same filepath to access the cert will
be able to update their cert.
## Implementation point
You will need to remove the auth keys when switching from OpenSSL to
mbedTLS. They will be regenerated automatically. It's the file at this
path:
```
"auth-path": "/etc/lwsws/acme/auth.jwk",
```
|
