Skip to content

Commit dad0676

Browse files
s373nZShahanaFarooqui
authored andcommitted
doc: gRPC SSL custom certificate generation instructions with SANs.
Changelog-Added: Example documentation on generating custom gRPC certificates with SANs.
1 parent 2fbd57f commit dad0676

File tree

1 file changed

+53
-1
lines changed
  • doc/developers-guide/app-development

1 file changed

+53
-1
lines changed

doc/developers-guide/app-development/grpc.md

Lines changed: 53 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -140,4 +140,56 @@ openssl x509 -req -CA ca.pem -CAkey ca-key.pem \
140140

141141

142142

143-
This will finally create the `server.pem` file, signed by the CA, allowing you to access the node through its real domain name. You can now move `server.pem` and `server-key.pem` into the lightning directory, and they should be picked up during the start.
143+
This will finally create the `server.pem` file, signed by the CA, allowing you to access the node through its real domain name. You can now move `server.pem` and `server-key.pem` into the lightning directory (ex. `<lightning-dir>/bitcoin` for `mainnet`), and they should be picked up during the start.
144+
145+
#### Generating custom certificates using SANs (Subject Alternative Names)
146+
147+
To add additional domain names to the custom certificate, you can use a variation of the above commands. This is helpful, for example, if you are exposing the API over Tor, or experiencing errors due to client SSL verification asking for verification via a `SAN` instead of `CN`.
148+
149+
```shell
150+
openssl genrsa -out server-key.pem 2048
151+
```
152+
153+
154+
155+
As above, generate a new server key.
156+
157+
Then, create an openssl CSR configuration file name `cln-csr.conf` that looks something like the following:
158+
159+
```
160+
[req]
161+
default_bits = 2048
162+
distinguished_name = req_distinguished_name
163+
req_extensions = req_ext
164+
165+
[req_distinguished_name]
166+
CN = "cln rest server"
167+
168+
[req_ext]
169+
subjectAltName = @alt_names
170+
171+
[alt_names]
172+
IP.1 = 127.0.0.1
173+
DNS.1 = localhost
174+
DNS.2 = cln
175+
DNS.3 = <put your custom DNS name here and add more if desired>
176+
```
177+
178+
179+
Consult the `openssl` [documentation ](https://docs.openssl.org/master/man1/openssl-req/#configuration-file-format) for your version for additional customization.
180+
181+
```shell
182+
openssl req -new -key server-key.pem -out server.csr -config cln-csr.conf
183+
```
184+
185+
186+
187+
This example configuration suggests the generated default for _Common Name_, but can be changed when prompted.
188+
189+
```shell
190+
openssl x509 -req -CA ca.pem -CAkey ca-key.pem -in server.csr -out server.pem -days 365 -CAcreateserial -extensions req_ext -extfile cln-csr.conf
191+
```
192+
193+
194+
195+
As above, generate the new server certificate, but this time with the `SAN` configuration. Copy `server.pem` and `server-key.pem` into the certificates location (ex. `<lightning-dir>/bitcoin` for `mainnet`) and restart the service to take effect.

0 commit comments

Comments
 (0)