content/kb/using/certfp.md

   1 ---
   2 Title: CertFP
   3 Slug: certfp
   4 ---
   5
   6 As an alternative to password-based authentication, you can connect to freenode
   7 with a TLS certificate and have services recognise it automatically.
   8
   9 For SASL EXTERNAL to work, you must connect over SSL.
  10
  11 Creating a self-signed certificate
  12 ==================================
  13
  14 In order to follow these instructions, you will need the `openssl` utility. If
  15 you are using Windows and do not have a copy, you might consider using Cygwin.
  16
  17 You can generate a certificate with the following command:
  18
  19     openssl req -x509 -new -newkey rsa:4096 -sha256 -days 1000 -nodes -out freenode.pem -keyout freenode.pem
  20
  21 You will be prompted for various pieces of information about the certificate.
  22 The contents do not matter for our purposes, but `openssl` needs at least one of
  23 them to be non-empty.
  24
  25 The `.pem` file will have the same access to your NickServ account as your
  26 password does, so take appropriate care in securing it.
  27
  28 Under Unix-like environments, the following command:
  29
  30     openssl x509 -in freenode.pem -outform der | sha1sum -b | cut -d' ' -f1
  31
  32 will list the certificate fingerprint.
  33
  34
  35 Connecting to freenode with your certificate
  36 ============================================
  37
  38 IRC clients generally differ in where they look for a certificate and how you
  39 configure them to offer it to the server. If yours is not yet listed here,
  40 advice in this section is unlikely to apply, but guides may be available
  41 elsewhere on the web.
  42
  43 irssi
  44 -----
  45
  46 Move the certificates you created above to ~/.irssi/certs
  47
  48     mkdir ~/.irssi/certs
  49     mv freenode.pem ~/.irssi/certs
  50
  51 Now configure your `/server` entry for freenode to use this certificate. You
  52 may need to adapt this example for your existing configuration (the network
  53 and hostname should match what you already use).
  54
  55     /server add -auto -ssl -ssl_cert ~/.irssi/certs/freenode.pem -network freenode chat.freenode.net 6697
  56
  57 weechat
  58 -------
  59
  60 Move the certificates you created above to ~/.weechat/certs
  61
  62     mkdir ~/.weechat/certs
  63     mv freenode.pem ~/.weechat/certs
  64
  65 Now disconnect and remove the current freenode server(s). Re-add it with the
  66 SSL flag, using your newly generated certificate. Note that these commands are
  67 just examples, you have to adapt them to your current servers.
  68
  69     /set irc.server.freenode.addresses chat.freenode.net/6697
  70     /set irc.server.freenode.ssl on
  71     /set irc.server.freenode.ssl_verify on
  72     /set irc.server.freenode.ssl_cert %h/certs/freenode.pem
  73     /set irc.server.freenode.sasl_mechanism external
  74
  75 and then reconnect to freenode.
  76
  77 znc
  78 ---
  79
  80 Refer to znc's [official documentation](http://wiki.znc.in/Cert).
  81
  82 HexChat
  83 -------
  84
  85 Place the pem file in `certs/client.pem` in the HexChat config
  86 directory (`~/.config/hexchat/` or `%appdata%\HexChat`). Note
  87 that the `certs` directory does not exist by default and you will have to
  88 create it yourself. Once the file is there, all subsequent SSL connections
  89 will use the certificate.
  90
  91 If you connect to multiple IRC networks, you should keep in mind that using the
  92 filename `certs/client.pem` will send the same certificate to all networks. If
  93 you prefer per-network certificates, use the name of the network exactly
  94 as it appears in the network list (Ctrl-S), including capitalisation and
  95 punctuation (e.g. `certs/freenode.pem` or `certs/Example Server.pem`).
  96
  97 Konversation
  98 ------------
  99
 100 Create the pem file as per above, then place it wherever you want.
 101 Start Konversation, then open the Identity dialogue by either pressing F8
 102 or via the Settings menu entry. Choose the identity you use for the
 103 freenode network or create a new one.
 104 In the part `Auto Identity` you have to choose `SASL External (Cert)`
 105 as the `Type` for SASL External or `SSL CLient Certificate` for CertFP.
 106 SASL External requires at least version 1.7 of Konversation.
 107 Optionally fill in your account name in the `Account`field.
 108 You can then choose the certificate you created with the file picker
 109 or enter the path manually in the field next to it.
 110 Once done, apply the configuration and (re)connect to freenode.
 111
 112 Add your fingerprint to NickServ
 113 ================================
 114
 115 You can then check whether you have a fingerprint by using `whois` on yourself:
 116
 117     /whois YourOwnNick
 118     ...
 119     YourOwnNick has client certificate fingerprint f3a1aad46ca88e180c25c9c7021a4b3a
 120     ...
 121
 122 To allow NickServ to recognise you based on your certificate, you need to add
 123 the fingerprint to your account (you will need to log in by other means in order
 124 to do so).
 125
 126 You can then authorise your current certificate fingerprint:
 127
 128     /msg NickServ CERT ADD
 129
 130 In the future, any connections you make to freenode with your certificate will
 131 be logged into your account automatically. Optionally, or if you wish to connect
 132 via Tor, you can enable SASL with the `EXTERNAL` mechanism.