Skip to content

Commit 42788d4

Browse files
meldrameldra
committed
Reorganize the certfp guide, add adiirc instructions
1 parent 341f16d commit 42788d4

File tree

1 file changed

+166
-90
lines changed

1 file changed

+166
-90
lines changed

‎content/_guides/certfp.md‎

Lines changed: 166 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -11,17 +11,26 @@ automatically.
1111

1212
For `SASL EXTERNAL` to work, you must [connect over TLS](/guides/connect).
1313

14+
<!-- markdownlint-disable MD022 -->
1415
## Creating a self-signed certificate
16+
{: .no_toc}
17+
1518

1619
In order to follow these instructions, you will need the `openssl` utility. If
1720
you are using Windows and do not have a copy, you might consider using Cygwin.
1821

19-
You can generate a certificate with the following command:
22+
You can generate a certificate with the following command (recommended):
2023

2124
```sh
2225
openssl req -x509 -new -newkey ed25519 -sha256 -nodes -out libera.pem -keyout libera.pem
2326
```
2427

28+
If your client does not support using `ed25519`, use the following command:
29+
30+
```sh
31+
openssl req -x509 -new -newkey rsa:4096 -sha256 -nodes -out libera.pem -keyout libera.pem
32+
```
33+
2534
You will be prompted for various pieces of information about the certificate.
2635
The contents do not matter for our purposes, but `openssl` needs at least one
2736
of them to be non-empty. This certificate will have the default expiry of 30
@@ -31,6 +40,7 @@ The `.pem` file will have the same access to your NickServ account as your
3140
password does, so take appropriate care in securing it.
3241

3342
## Inspecting your certificate
43+
{: .no_toc}
3444

3545
The fingerprint can be checked with the following command:
3646

@@ -39,78 +49,94 @@ openssl x509 -in libera.pem -noout -fingerprint -sha512 | awk -F= '{gsub(":","")
3949
```
4050

4151
## Connecting to Libera.Chat with your certificate
52+
{: .no_toc}
53+
<!-- markdownlint-restore -->
4254

4355
IRC clients generally differ in where they look for a certificate and how you
4456
configure them to offer it to the server. If yours is not yet listed here,
4557
advice in this section is unlikely to apply, but guides may be available
4658
elsewhere on the web.
4759

60+
- TOC
61+
{:toc}
62+
4863
### Irssi
4964

50-
Move the certificates you created above to ~/.irssi/certs
65+
1. Move the certificates you created above to ~/.irssi/certs:
5166

52-
```sh
53-
mkdir ~/.irssi/certs
54-
mv libera.pem ~/.irssi/certs
55-
```
67+
```sh
68+
mkdir ~/.irssi/certs
69+
mv libera.pem ~/.irssi/certs
70+
```
5671

57-
Configure your `/server` entry for Libera.Chat to use this certificate. You
58-
may need to adapt this example for your existing configuration (the network
59-
and hostname should match what you already use).
72+
2. Configure your `/server` entry for Libera.Chat to use this certificate. You
73+
may need to adapt this example for your existing configuration (the network
74+
and hostname should match what you already use).
6075

61-
```irc
62-
/server add -tls_cert ~/.irssi/certs/libera.pem -network LiberaChat irc.libera.chat 6697
63-
```
76+
```irc
77+
/server add -tls_cert ~/.irssi/certs/libera.pem -network LiberaChat irc.libera.chat 6697
78+
```
6479

65-
For the first time, connect to Libera.Chat using password authentication so
66-
that you can add the certificate fingerprint to NickServ.
80+
3. Connect to Libera.Chat using password authentication so that you can add
81+
the certificate fingerprint to NickServ.
6782

68-
```irc
69-
/connect LiberaChat
70-
```
83+
```irc
84+
/connect LiberaChat
85+
```
7186

72-
Now follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv).
73-
When done, you can switch the authentication to certificates.
87+
4. Now follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv).
88+
When done, you can switch the authentication to certificates.
7489

75-
```irc
76-
/disconnect LiberaChat
77-
/network add -sasl_password '' -sasl_mechanism EXTERNAL LiberaChat
78-
/connect LiberaChat
79-
```
90+
```irc
91+
/disconnect LiberaChat
92+
/network add -sasl_password '' -sasl_mechanism EXTERNAL LiberaChat
93+
/connect LiberaChat
94+
```
8095

8196
If you did everything right you should now be authenticated using your
8297
certificate.
8398

8499
### weechat
85100

86-
Move the certificates you created above to ~/.weechat/certs
101+
1. Move the [certificates you created](#creating-a-self-signed-certificate)
102+
to `~/.weechat/certs`
87103

88-
```sh
89-
mkdir ~/.weechat/certs
90-
mv libera.pem ~/.weechat/certs
91-
```
104+
```sh
105+
mkdir ~/.weechat/certs
106+
mv libera.pem ~/.weechat/certs
107+
```
92108

93-
Now disconnect and remove the current Libera.Chat server(s). Re-add it with
94-
the SSL flag, using your newly generated certificate. Note that these commands
95-
are just examples, you have to adapt them to your current servers.
109+
2. Configure your Libera Chat server to use your newly generated certificate.
110+
These commands are examples and you must adapt the `liberachat` portion of
111+
them to the name you gave to the network, as shown with `/server list`.
96112

97-
```irc
98-
# For Weechat version >= 4.0.0
99-
/set irc.server.liberachat.addresses irc.libera.chat/6697
100-
/set irc.server.liberachat.tls on
101-
/set irc.server.liberachat.tls_verify on
102-
/set irc.server.liberachat.tls_cert %h/certs/libera.pem
103-
/set irc.server.liberachat.sasl_mechanism external
104-
105-
# For Weechat version < 4.0.0
106-
/set irc.server.liberachat.addresses irc.libera.chat/6697
107-
/set irc.server.liberachat.ssl on
108-
/set irc.server.liberachat.ssl_verify on
109-
/set irc.server.liberachat.ssl_cert %h/certs/libera.pem
110-
/set irc.server.liberachat.sasl_mechanism external
111-
```
113+
```irc
114+
# For Weechat version >= 4.0.0
115+
/set irc.server.liberachat.addresses irc.libera.chat/6697
116+
/set irc.server.liberachat.tls on
117+
/set irc.server.liberachat.tls_verify on
118+
/set irc.server.liberachat.tls_cert %h/certs/libera.pem
119+
120+
# For Weechat version < 4.0.0
121+
/set irc.server.liberachat.addresses irc.libera.chat/6697
122+
/set irc.server.liberachat.ssl on
123+
/set irc.server.liberachat.ssl_verify on
124+
/set irc.server.liberachat.ssl_cert %h/certs/libera.pem
125+
```
112126

113-
and then reconnect to Libera.Chat.
127+
3. (Re)connect to the network.
128+
4. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv)
129+
to your account.
130+
5. Set the server's sasl_mechanism to `external`
131+
132+
```irc
133+
/set irc.server.liberachat.sasl_mechanism external
134+
```
135+
136+
Future connections will now use your certificate to authenticate you.
137+
138+
Note that if you are using CertFP to connect to our tor hidden service,
139+
either set up the alias for palladium or set `ssl_verify` to `off`.
114140

115141
### znc
116142

@@ -124,48 +150,64 @@ see `certfp generate` in the [IRC service manual](https://soju.im/doc/soju.1.htm
124150

125151
### HexChat
126152

127-
Place the .pem file in `certs/client.pem` in the HexChat config
128-
directory (`~/.config/hexchat/` or `%appdata%\HexChat`). Note
129-
that the `certs` directory does not exist by default and you will have to
130-
create it yourself. Once the file is there, all subsequent SSL connections
131-
will use the certificate.
153+
1. [Create the certificate](#creating-a-self-signed-certificate)
154+
2. Place the file in `certs/client.pem` in the HexChat config directory
155+
(`~/.config/hexchat/` or `%appdata%\HexChat`). Note that the `certs`
156+
directory does not exist by default and you may need to create it.
157+
3. Once the file is there, all subsequent SSL connections will use the
158+
certificate.
132159

133160
If you connect to multiple IRC networks, you should keep in mind that using
134161
the filename `certs/client.pem` will send the same certificate to all networks.
135162
If you prefer per-network certificates, use the name of the network exactly
136-
as it appears in the network list (Ctrl-S), including capitalisation and
137-
punctuation (e.g. `certs/libera.pem` or `certs/Example Server.pem`).
163+
as it appears in the network list (Ctrl-S), **including capitalisation and
164+
punctuation** (e.g. `certs/libera.pem` or `certs/Example Server.pem`).
138165

139166
### Konversation
140167

141-
Create the .pem file as per above using `rsa:4096` instead of `ed25519`,
142-
then place it wherever you want. Start Konversation, then open the Identity
143-
dialogue by either pressing <kbd>F8</kbd> or via the Settings menu entry.
144-
Choose the identity you use for the Libera.Chat network or create a new one.
145-
In the part `Auto Identify` you have to choose `SASL External (Cert)`
146-
as the `Type` for SASL External or `SSL CLient Certificate` for CertFP.
147-
SASL External requires at least version 1.7 of Konversation.
148-
Optionally fill in your account name in the `Account` field.
149-
You can then choose the certificate you created with the file picker
150-
or enter the path manually in the field next to it.
151-
Once done, apply the configuration and (re)connect to Libera.Chat.
168+
1. [Create a certificate](#creating-a-self-signed-certificate) using the
169+
`rsa:4096` algorithm, putting it wherever you want.
170+
2. Start Konversation, then open the Identity dialogue by either pressing
171+
`F8` or via the Settings menu entry.
172+
3. Choose the identity you use for Libera.Chat, or create a new one.
173+
4. In the `Auto Identify` section, choose `SASL External (Cert)`
174+
as the `Type` for SASL External (requires version 1.7 or newer),
175+
or `SSL CLient Certificate` for CertFP.
176+
5. (optional) Fill in your account name in the `Account` field.
177+
6. Choose the certificate you created with the file picker or enter the path
178+
manually in the field next to it.
179+
7. Apply the configuration and (re)connect to Libera.Chat.
180+
8. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv)
181+
to your account.
182+
183+
Future connections will use the certificate to authenticate you.
152184

153185
### Revolution
154186

155-
Create the .pem file as per above, transfer it to your Android device, and
156-
place it wherever you want (`Downloads` is a common location).
157-
Start Revolution and navigate to the `Manage servers` screen if you are not
158-
there already, long-press on the server you wish configure certFP for, and
159-
select `Edit`. When presented with the `Edit a server` screen, tap on
160-
`Authentication mode` and select `Client certificate (CertFP)`, then tap on
161-
`IMPORT PEM` and navigate to where where you put the pem file and select it.
162-
Tap the tick symbol on the top right of the `Edit a server` screen to save.
187+
1. Create the .pem file as per above.
188+
2. Transfer it to your Android device, and place it wherever you want
189+
(`Downloads` is a common location).
190+
3. Start Revolution and navigate to the `Manage servers` screen.
191+
4. Long-press on the server you wish configure certFP for, and
192+
select `Edit`.
193+
5. When presented with the `Edit a server` screen, tap on
194+
`Authentication mode` and select `Client certificate (CertFP)`, then tap on
195+
`IMPORT PEM`.
196+
6. Navigate to where where you put the pem file and select it.
197+
7. Tap the tick symbol on the top right of the `Edit a server` screen to save.
163198

164199
Alternatively, Revolution has the ability to generate a client certificate for
165-
you. Once you are presented with `IMPORT PEM`, there will also be an option
166-
to `CREATE NEW` and when you tap this, a certificate will be randomly generated
167-
and a certificate fingerprint will be displayed. Tap the tick symbol on the top
168-
right of the screen to save.
200+
you:
201+
202+
1. When you are presented with `IMPORT PEM`, there will also be an option
203+
to `CREATE NEW`.
204+
2. When you tap this option, a certificate will be randomly generated
205+
and a certificate fingerprint will be displayed.
206+
3. Tap the tick symbol on the top right of the screen to save.
207+
208+
Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv)
209+
to your account. Future connections will now use your certificate to
210+
authenticate you.
169211

170212
### KVIrc
171213

@@ -177,25 +219,55 @@ right of the screen to save.
177219
5. At `Certificate location` configure the location of libera.pem.
178220
6. Check `Use SSL private key`.
179221
7. At `Private key location` configure the location of libera.pem.
180-
8. If you have certificate and private key in separate files, use these
181-
respectively.
222+
8. (optional) If you have certificate and private key in separate files, use
223+
these in the respective fields instead.
182224
9. Click `OK` or `Apply`.
225+
10. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv)
226+
to your account.
227+
228+
Future connections will now use your certificate to authenticate you.
183229

184230
### mIRC
185231

186-
1. In the File menu, click Select Servers...
187-
2. In the Connect -> Servers section of the mIRC Options window,
188-
select Libera.Chat, click the hamburger menu button, then click Edit.
232+
1. In the `File` menu, click `Select Server...`
233+
2. In the `Connect` -> `Servers` section of the `mIRC Options` window,
234+
select Libera.Chat, click the hamburger menu button, then click `Edit`.
189235
3. In the `Login Method` dropdown, select `SASL External /CAP`.
190236
4. Click the `SSL` Tab.
191237
5. Check `Use private certificate`.
192-
6. Click the rectange box below and select the certificate file.
238+
6. Click the rectangle box below and select the certificate file.
193239
The file must contain both the certificate and private key.
194-
7. Click the OK button.
240+
7. Click the `OK` button.
241+
8. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv)
242+
to your account.
243+
244+
Future connections will now use your certificate to authenticate you.
245+
246+
### Adiirc
247+
248+
1. Follow the [certificate creation instructions](#creating-a-self-signed-certificate)
249+
above to generate a `rsa:4096` certificate.
250+
2. Convert the cert to the needed `.pfx` format with
251+
`openssl pkcs12 -export -out libera.pfx -in libera.pem`
252+
3. Add the path to the `libera.pfx` file in the `SSL` tab of the `Server List`,
253+
and **uncheck** the `Use global client certificate` option.
254+
4. Click `Save`.
255+
5. (Re)connect to the network using password authentication.
256+
6. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv)
257+
to your account.
258+
7. Change your login method to SASL (external).
259+
260+
Future connections will now use your certificate to authenticate you.
261+
262+
Note: The option to have Adiirc generate a certificate for you does not
263+
currently generate a compatible certificate.
195264

265+
<!-- markdownlint-disable MD022 -->
196266
## Add your fingerprint to NickServ
267+
{: .no_toc}
197268

198-
You can then check whether you have a fingerprint by using `whois` on yourself:
269+
You can then check whether you have a fingerprint by using `whois` on
270+
yourself:
199271

200272
```irc
201273
/whois YourOwnNick
@@ -216,13 +288,17 @@ You can then authorise your current certificate fingerprint:
216288

217289
In the future, any connections you make to Libera.Chat with your certificate
218290
will be logged into your account automatically. Optionally, or if you wish to
219-
[connect via Tor](/guides/connect), you can enable SASL with the `EXTERNAL` mechanism.
291+
[connect via Tor](/guides/connect), you can enable SASL with the `EXTERNAL`
292+
mechanism.
220293

221294
## Troubleshooting
295+
{: .no_toc}
222296

223297
### Expecting an rsa key
298+
{: .no_toc}
299+
<!-- markdownlint-restore -->
224300

225301
This can happen if your client does not support the `ed25519` algorithm. If
226-
you wish to continue with this client, you will need to replace your
227-
certificate using the same command as above, but with `rsa:4096` in place of
228-
`ed25519`.
302+
you wish to continue with this client, you will need to
303+
[make a new certificate](#creating-a-self-signed-certificate) that is using
304+
the `rsa:4096` algorithm.

0 commit comments

Comments
 (0)