From 42788d4c856e5539f3ac63aa82a2d2eee816b9be Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Fri, 28 Mar 2025 23:09:34 -0700 Subject: [PATCH 1/3] Reorganize the certfp guide, add adiirc instructions --- content/_guides/certfp.md | 256 ++++++++++++++++++++++++-------------- 1 file changed, 166 insertions(+), 90 deletions(-) diff --git a/content/_guides/certfp.md b/content/_guides/certfp.md index f281f04..c910135 100644 --- a/content/_guides/certfp.md +++ b/content/_guides/certfp.md @@ -11,17 +11,26 @@ automatically. For `SASL EXTERNAL` to work, you must [connect over TLS](/guides/connect). + ## Creating a self-signed certificate +{: .no_toc} + In order to follow these instructions, you will need the `openssl` utility. If you are using Windows and do not have a copy, you might consider using Cygwin. -You can generate a certificate with the following command: +You can generate a certificate with the following command (recommended): ```sh openssl req -x509 -new -newkey ed25519 -sha256 -nodes -out libera.pem -keyout libera.pem ``` +If your client does not support using `ed25519`, use the following command: + +```sh +openssl req -x509 -new -newkey rsa:4096 -sha256 -nodes -out libera.pem -keyout libera.pem +``` + You will be prompted for various pieces of information about the certificate. The contents do not matter for our purposes, but `openssl` needs at least one 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 password does, so take appropriate care in securing it. ## Inspecting your certificate +{: .no_toc} The fingerprint can be checked with the following command: @@ -39,78 +49,94 @@ openssl x509 -in libera.pem -noout -fingerprint -sha512 | awk -F= '{gsub(":","") ``` ## Connecting to Libera.Chat with your certificate +{: .no_toc} + IRC clients generally differ in where they look for a certificate and how you configure them to offer it to the server. If yours is not yet listed here, advice in this section is unlikely to apply, but guides may be available elsewhere on the web. +- TOC +{:toc} + ### Irssi -Move the certificates you created above to ~/.irssi/certs +1. Move the certificates you created above to ~/.irssi/certs: -```sh -mkdir ~/.irssi/certs -mv libera.pem ~/.irssi/certs -``` + ```sh + mkdir ~/.irssi/certs + mv libera.pem ~/.irssi/certs + ``` -Configure your `/server` entry for Libera.Chat to use this certificate. You -may need to adapt this example for your existing configuration (the network -and hostname should match what you already use). +2. Configure your `/server` entry for Libera.Chat to use this certificate. You + may need to adapt this example for your existing configuration (the network + and hostname should match what you already use). -```irc -/server add -tls_cert ~/.irssi/certs/libera.pem -network LiberaChat irc.libera.chat 6697 -``` + ```irc + /server add -tls_cert ~/.irssi/certs/libera.pem -network LiberaChat irc.libera.chat 6697 + ``` -For the first time, connect to Libera.Chat using password authentication so -that you can add the certificate fingerprint to NickServ. +3. Connect to Libera.Chat using password authentication so that you can add + the certificate fingerprint to NickServ. -```irc -/connect LiberaChat -``` + ```irc + /connect LiberaChat + ``` -Now follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv). -When done, you can switch the authentication to certificates. +4. Now follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv). + When done, you can switch the authentication to certificates. -```irc -/disconnect LiberaChat -/network add -sasl_password '' -sasl_mechanism EXTERNAL LiberaChat -/connect LiberaChat -``` + ```irc + /disconnect LiberaChat + /network add -sasl_password '' -sasl_mechanism EXTERNAL LiberaChat + /connect LiberaChat + ``` If you did everything right you should now be authenticated using your certificate. ### weechat -Move the certificates you created above to ~/.weechat/certs +1. Move the [certificates you created](#creating-a-self-signed-certificate) + to `~/.weechat/certs` -```sh -mkdir ~/.weechat/certs -mv libera.pem ~/.weechat/certs -``` + ```sh + mkdir ~/.weechat/certs + mv libera.pem ~/.weechat/certs + ``` -Now disconnect and remove the current Libera.Chat server(s). Re-add it with -the SSL flag, using your newly generated certificate. Note that these commands -are just examples, you have to adapt them to your current servers. +2. Configure your Libera Chat server to use your newly generated certificate. + These commands are examples and you must adapt the `liberachat` portion of + them to the name you gave to the network, as shown with `/server list`. -```irc -# For Weechat version >= 4.0.0 -/set irc.server.liberachat.addresses irc.libera.chat/6697 -/set irc.server.liberachat.tls on -/set irc.server.liberachat.tls_verify on -/set irc.server.liberachat.tls_cert %h/certs/libera.pem -/set irc.server.liberachat.sasl_mechanism external - -# For Weechat version < 4.0.0 -/set irc.server.liberachat.addresses irc.libera.chat/6697 -/set irc.server.liberachat.ssl on -/set irc.server.liberachat.ssl_verify on -/set irc.server.liberachat.ssl_cert %h/certs/libera.pem -/set irc.server.liberachat.sasl_mechanism external -``` + ```irc + # For Weechat version >= 4.0.0 + /set irc.server.liberachat.addresses irc.libera.chat/6697 + /set irc.server.liberachat.tls on + /set irc.server.liberachat.tls_verify on + /set irc.server.liberachat.tls_cert %h/certs/libera.pem + + # For Weechat version < 4.0.0 + /set irc.server.liberachat.addresses irc.libera.chat/6697 + /set irc.server.liberachat.ssl on + /set irc.server.liberachat.ssl_verify on + /set irc.server.liberachat.ssl_cert %h/certs/libera.pem + ``` -and then reconnect to Libera.Chat. +3. (Re)connect to the network. +4. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv) +to your account. +5. Set the server's sasl_mechanism to `external` + + ```irc + /set irc.server.liberachat.sasl_mechanism external + ``` + +Future connections will now use your certificate to authenticate you. + +Note that if you are using CertFP to connect to our tor hidden service, +either set up the alias for palladium or set `ssl_verify` to `off`. ### znc @@ -124,48 +150,64 @@ see `certfp generate` in the [IRC service manual](https://soju.im/doc/soju.1.htm ### HexChat -Place the .pem file in `certs/client.pem` in the HexChat config -directory (`~/.config/hexchat/` or `%appdata%\HexChat`). Note -that the `certs` directory does not exist by default and you will have to -create it yourself. Once the file is there, all subsequent SSL connections -will use the certificate. +1. [Create the certificate](#creating-a-self-signed-certificate) +2. Place the file in `certs/client.pem` in the HexChat config directory + (`~/.config/hexchat/` or `%appdata%\HexChat`). Note that the `certs` + directory does not exist by default and you may need to create it. +3. Once the file is there, all subsequent SSL connections will use the + certificate. If you connect to multiple IRC networks, you should keep in mind that using the filename `certs/client.pem` will send the same certificate to all networks. If you prefer per-network certificates, use the name of the network exactly -as it appears in the network list (Ctrl-S), including capitalisation and -punctuation (e.g. `certs/libera.pem` or `certs/Example Server.pem`). +as it appears in the network list (Ctrl-S), **including capitalisation and +punctuation** (e.g. `certs/libera.pem` or `certs/Example Server.pem`). ### Konversation -Create the .pem file as per above using `rsa:4096` instead of `ed25519`, -then place it wherever you want. Start Konversation, then open the Identity -dialogue by either pressing F8 or via the Settings menu entry. -Choose the identity you use for the Libera.Chat network or create a new one. -In the part `Auto Identify` you have to choose `SASL External (Cert)` -as the `Type` for SASL External or `SSL CLient Certificate` for CertFP. -SASL External requires at least version 1.7 of Konversation. -Optionally fill in your account name in the `Account` field. -You can then choose the certificate you created with the file picker -or enter the path manually in the field next to it. -Once done, apply the configuration and (re)connect to Libera.Chat. +1. [Create a certificate](#creating-a-self-signed-certificate) using the + `rsa:4096` algorithm, putting it wherever you want. +2. Start Konversation, then open the Identity dialogue by either pressing + `F8` or via the Settings menu entry. +3. Choose the identity you use for Libera.Chat, or create a new one. +4. In the `Auto Identify` section, choose `SASL External (Cert)` + as the `Type` for SASL External (requires version 1.7 or newer), + or `SSL CLient Certificate` for CertFP. +5. (optional) Fill in your account name in the `Account` field. +6. Choose the certificate you created with the file picker or enter the path + manually in the field next to it. +7. Apply the configuration and (re)connect to Libera.Chat. +8. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv) +to your account. + +Future connections will use the certificate to authenticate you. ### Revolution -Create the .pem file as per above, transfer it to your Android device, and -place it wherever you want (`Downloads` is a common location). -Start Revolution and navigate to the `Manage servers` screen if you are not -there already, long-press on the server you wish configure certFP for, and -select `Edit`. When presented with the `Edit a server` screen, tap on -`Authentication mode` and select `Client certificate (CertFP)`, then tap on -`IMPORT PEM` and navigate to where where you put the pem file and select it. -Tap the tick symbol on the top right of the `Edit a server` screen to save. +1. Create the .pem file as per above. +2. Transfer it to your Android device, and place it wherever you want + (`Downloads` is a common location). +3. Start Revolution and navigate to the `Manage servers` screen. +4. Long-press on the server you wish configure certFP for, and + select `Edit`. +5. When presented with the `Edit a server` screen, tap on + `Authentication mode` and select `Client certificate (CertFP)`, then tap on + `IMPORT PEM`. +6. Navigate to where where you put the pem file and select it. +7. Tap the tick symbol on the top right of the `Edit a server` screen to save. Alternatively, Revolution has the ability to generate a client certificate for -you. Once you are presented with `IMPORT PEM`, there will also be an option -to `CREATE NEW` and when you tap this, a certificate will be randomly generated -and a certificate fingerprint will be displayed. Tap the tick symbol on the top -right of the screen to save. +you: + +1. When you are presented with `IMPORT PEM`, there will also be an option + to `CREATE NEW`. +2. When you tap this option, a certificate will be randomly generated + and a certificate fingerprint will be displayed. +3. Tap the tick symbol on the top right of the screen to save. + +Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv) +to your account. Future connections will now use your certificate to +authenticate you. ### KVIrc @@ -177,25 +219,55 @@ right of the screen to save. 5. At `Certificate location` configure the location of libera.pem. 6. Check `Use SSL private key`. 7. At `Private key location` configure the location of libera.pem. -8. If you have certificate and private key in separate files, use these - respectively. +8. (optional) If you have certificate and private key in separate files, use + these in the respective fields instead. 9. Click `OK` or `Apply`. +10. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv) + to your account. + +Future connections will now use your certificate to authenticate you. ### mIRC -1. In the File menu, click Select Servers... -2. In the Connect -> Servers section of the mIRC Options window, - select Libera.Chat, click the hamburger menu button, then click Edit. +1. In the `File` menu, click `Select Server...` +2. In the `Connect` -> `Servers` section of the `mIRC Options` window, + select Libera.Chat, click the hamburger menu button, then click `Edit`. 3. In the `Login Method` dropdown, select `SASL External /CAP`. 4. Click the `SSL` Tab. 5. Check `Use private certificate`. -6. Click the rectange box below and select the certificate file. +6. Click the rectangle box below and select the certificate file. The file must contain both the certificate and private key. -7. Click the OK button. +7. Click the `OK` button. +8. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv) + to your account. + +Future connections will now use your certificate to authenticate you. + +### Adiirc + +1. Follow the [certificate creation instructions](#creating-a-self-signed-certificate) + above to generate a `rsa:4096` certificate. +2. Convert the cert to the needed `.pfx` format with + `openssl pkcs12 -export -out libera.pfx -in libera.pem` +3. Add the path to the `libera.pfx` file in the `SSL` tab of the `Server List`, + and **uncheck** the `Use global client certificate` option. +4. Click `Save`. +5. (Re)connect to the network using password authentication. +6. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv) + to your account. +7. Change your login method to SASL (external). + +Future connections will now use your certificate to authenticate you. + +Note: The option to have Adiirc generate a certificate for you does not +currently generate a compatible certificate. + ## Add your fingerprint to NickServ +{: .no_toc} -You can then check whether you have a fingerprint by using `whois` on yourself: +You can then check whether you have a fingerprint by using `whois` on +yourself: ```irc /whois YourOwnNick @@ -216,13 +288,17 @@ You can then authorise your current certificate fingerprint: In the future, any connections you make to Libera.Chat with your certificate will be logged into your account automatically. Optionally, or if you wish to -[connect via Tor](/guides/connect), you can enable SASL with the `EXTERNAL` mechanism. +[connect via Tor](/guides/connect), you can enable SASL with the `EXTERNAL` +mechanism. ## Troubleshooting +{: .no_toc} ### Expecting an rsa key +{: .no_toc} + This can happen if your client does not support the `ed25519` algorithm. If -you wish to continue with this client, you will need to replace your -certificate using the same command as above, but with `rsa:4096` in place of -`ed25519`. +you wish to continue with this client, you will need to +[make a new certificate](#creating-a-self-signed-certificate) that is using +the `rsa:4096` algorithm. From 31485ee61341e5298158e2954ad0bbba781570f0 Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Sat, 29 Mar 2025 13:03:27 -0700 Subject: [PATCH 2/3] Further copyediting --- content/_guides/certfp.md | 109 +++++++++++++++++++++----------------- 1 file changed, 60 insertions(+), 49 deletions(-) diff --git a/content/_guides/certfp.md b/content/_guides/certfp.md index c910135..dd87664 100644 --- a/content/_guides/certfp.md +++ b/content/_guides/certfp.md @@ -32,11 +32,11 @@ openssl req -x509 -new -newkey rsa:4096 -sha256 -nodes -out libera.pem -keyout l ``` You will be prompted for various pieces of information about the certificate. -The contents do not matter for our purposes, but `openssl` needs at least one -of them to be non-empty. This certificate will have the default expiry of 30 -days, as Libera.Chat no longer checks for certificate expiry. +The contents do not matter for our purposes, but `openssl` needs **at least +one** of them to be non-empty. This certificate will have the default expiry +of 30 days, as Libera.Chat no longer checks for certificate expiry. -The `.pem` file will have the same access to your NickServ account as your +This `.pem` file will have the same access to your NickServ account as your password does, so take appropriate care in securing it. ## Inspecting your certificate @@ -106,28 +106,33 @@ certificate. mv libera.pem ~/.weechat/certs ``` -2. Configure your Libera Chat server to use your newly generated certificate. +2. If you already have a Libera.Chat server, you can skip this step. If you do + **not** currently have a Libera.Chat server, you will need to create one: + + ```irc + /set irc.server.liberachat.addresses irc.libera.chat/6697 + ``` + +3. Configure your Libera.Chat server to use your newly generated certificate. These commands are examples and you must adapt the `liberachat` portion of them to the name you gave to the network, as shown with `/server list`. ```irc # For Weechat version >= 4.0.0 - /set irc.server.liberachat.addresses irc.libera.chat/6697 /set irc.server.liberachat.tls on /set irc.server.liberachat.tls_verify on /set irc.server.liberachat.tls_cert %h/certs/libera.pem # For Weechat version < 4.0.0 - /set irc.server.liberachat.addresses irc.libera.chat/6697 /set irc.server.liberachat.ssl on /set irc.server.liberachat.ssl_verify on /set irc.server.liberachat.ssl_cert %h/certs/libera.pem ``` -3. (Re)connect to the network. -4. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv) -to your account. -5. Set the server's sasl_mechanism to `external` +4. (Re)connect to the network. +5. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv) + to your account. +6. Set the server's sasl_mechanism to `external` ```irc /set irc.server.liberachat.sasl_mechanism external @@ -135,8 +140,9 @@ to your account. Future connections will now use your certificate to authenticate you. -Note that if you are using CertFP to connect to our tor hidden service, -either set up the alias for palladium or set `ssl_verify` to `off`. +**Note:** If you are using CertFP to connect to +[our tor hidden service](/guides/connect#accessing-liberachat-via-tor), +either set up the alias for palladium, or set `ssl_verify` to `off`. ### znc @@ -157,11 +163,12 @@ see `certfp generate` in the [IRC service manual](https://soju.im/doc/soju.1.htm 3. Once the file is there, all subsequent SSL connections will use the certificate. -If you connect to multiple IRC networks, you should keep in mind that using -the filename `certs/client.pem` will send the same certificate to all networks. -If you prefer per-network certificates, use the name of the network exactly -as it appears in the network list (Ctrl-S), **including capitalisation and -punctuation** (e.g. `certs/libera.pem` or `certs/Example Server.pem`). +**Note:** If you connect to multiple IRC networks, you should keep in mind +that using the filename `certs/client.pem` will send the same certificate to +all networks. If you prefer per-network certificates, use the name of the +network exactly as it appears in the network list (`Ctrl-S`), **including +capitalisation and punctuation** (e.g. `certs/libera.pem` or `certs/Example +Server.pem`). ### Konversation @@ -205,40 +212,44 @@ you: and a certificate fingerprint will be displayed. 3. Tap the tick symbol on the top right of the screen to save. -Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv) +Finally, follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv) to your account. Future connections will now use your certificate to authenticate you. ### KVIrc -1. You can create/put `libera.pem` in your KVIrc config directory (e.g. - `~/.config/KVIrc`). +1. [Create the certificate](#creating-a-self-signed-certificate) and place + it in your KVIrc config directory (e.g. `~/.config/KVIrc`). 2. In `Settings/Configure KVIrc...` expand `Connection` and click `Advanced`. -3. In the `SSL` tab ... -4. Check `Use SSL certificate`. -5. At `Certificate location` configure the location of libera.pem. -6. Check `Use SSL private key`. -7. At `Private key location` configure the location of libera.pem. -8. (optional) If you have certificate and private key in separate files, use - these in the respective fields instead. -9. Click `OK` or `Apply`. -10. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv) - to your account. +3. Select the `SSL` tab. +4. Check `Use SSL certificate` and configure `Certificate location` as the + location of `libera.pem`. +5. Check `Use SSL private key` and configure `Private key location` as the + location of `libera.pem` as well. +6. Click `OK` or `Apply`. +7. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv) + to your account. Future connections will now use your certificate to authenticate you. +**Note:** If you used the [certificate creation instructions](#creating-a-self-signed-certificate), +for steps 4 and 5, both locations should be the same. If you used other +instructions and have a certificate and private key in separate files, use +these in the respective fields instead. + ### mIRC -1. In the `File` menu, click `Select Server...` -2. In the `Connect` -> `Servers` section of the `mIRC Options` window, +1. [Create your certificate](#creating-a-self-signed-certificate). +2. In the `File` menu, click `Select Server...` +3. In the `Connect` -> `Servers` section of the `mIRC Options` window, select Libera.Chat, click the hamburger menu button, then click `Edit`. -3. In the `Login Method` dropdown, select `SASL External /CAP`. -4. Click the `SSL` Tab. -5. Check `Use private certificate`. -6. Click the rectangle box below and select the certificate file. +4. In the `Login Method` dropdown, select `SASL External /CAP`. +5. Click the `SSL` Tab. +6. Check `Use private certificate`. +7. Click the rectangle box below and select the certificate file. The file must contain both the certificate and private key. -7. Click the `OK` button. -8. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv) +8. Click the `OK` button. +9. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv) to your account. Future connections will now use your certificate to authenticate you. @@ -259,15 +270,15 @@ Future connections will now use your certificate to authenticate you. Future connections will now use your certificate to authenticate you. -Note: The option to have Adiirc generate a certificate for you does not +**Note:** The option to have Adiirc generate a certificate for you does not currently generate a compatible certificate. ## Add your fingerprint to NickServ {: .no_toc} -You can then check whether you have a fingerprint by using `whois` on -yourself: +After connecting, you can check whether you have a fingerprint by using +`whois` on yourself: ```irc /whois YourOwnNick @@ -277,19 +288,19 @@ YourOwnNick has client certificate fingerprint 959c0bdfa9877d3466c5848f55264f72f ``` To allow NickServ to recognise you based on your certificate, you need to add -the **sha512** fingerprint to your account (you will need to log in by other -means in order to do so). +the certificate's fingerprint to your account. You will need to log in to your +account with a password method to do this. -You can then authorise your current certificate fingerprint: +Once logged in, you can authorise your current certificate fingerprint: ```irc /msg NickServ CERT ADD ``` -In the future, any connections you make to Libera.Chat with your certificate -will be logged into your account automatically. Optionally, or if you wish to -[connect via Tor](/guides/connect), you can enable SASL with the `EXTERNAL` -mechanism. +Future connections you make to Libera.Chat with any client configured to use +**that** certificate, will be logged into your account automatically. You may +need to configure the client to use SASL with the `EXTERNAL` mechanism to get +the benefits of using SASL, or to [connect over tor](/guides/connect#accessing-liberachat-via-tor). ## Troubleshooting {: .no_toc} From 54aa6c76873201333a3b19e985f60afaba53c974 Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Sat, 29 Mar 2025 17:27:13 -0700 Subject: [PATCH 3/3] Lint stuff --- content/_guides/certfp.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/content/_guides/certfp.md b/content/_guides/certfp.md index dd87664..3aca845 100644 --- a/content/_guides/certfp.md +++ b/content/_guides/certfp.md @@ -15,7 +15,6 @@ For `SASL EXTERNAL` to work, you must [connect over TLS](/guides/connect). ## Creating a self-signed certificate {: .no_toc} - In order to follow these instructions, you will need the `openssl` utility. If you are using Windows and do not have a copy, you might consider using Cygwin. @@ -108,7 +107,7 @@ certificate. 2. If you already have a Libera.Chat server, you can skip this step. If you do **not** currently have a Libera.Chat server, you will need to create one: - + ```irc /set irc.server.liberachat.addresses irc.libera.chat/6697 ``` @@ -225,7 +224,7 @@ authenticate you. 4. Check `Use SSL certificate` and configure `Certificate location` as the location of `libera.pem`. 5. Check `Use SSL private key` and configure `Private key location` as the - location of `libera.pem` as well. + location of `libera.pem` as well. 6. Click `OK` or `Apply`. 7. Follow the instructions [to add the fingerprint](#add-your-fingerprint-to-nickserv) to your account.