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 TLS.
  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 1096 -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. This certificate will last about 3 years - set a calendar
  24 event now to ensure that you are reminded when you need to generate a new one.
  25
  26 The `.pem` file will have the same access to your NickServ account as your
  27 password does, so take appropriate care in securing it.
  28
  29 Under Unix-like environments, the following command:
  30
  31     openssl x509 -in freenode.pem -outform der | sha1sum -b | cut -d' ' -f1
  32
  33 will list the certificate fingerprint.
  34
  35
  36 Connecting to freenode with your certificate
  37 ============================================
  38
  39 IRC clients generally differ in where they look for a certificate and how you
  40 configure them to offer it to the server. If yours is not yet listed here,
  41 advice in this section is unlikely to apply, but guides may be available
  42 elsewhere on the web.
  43
  44 irssi
  45 -----
  46
  47 Move the certificates you created above to ~/.irssi/certs
  48
  49     mkdir ~/.irssi/certs
  50     mv freenode.pem ~/.irssi/certs
  51
  52 Now configure your `/server` entry for freenode to use this certificate. You
  53 may need to adapt this example for your existing configuration (the network
  54 and hostname should match what you already use).
  55
  56     /server add -auto -ssl -ssl_cert ~/.irssi/certs/freenode.pem -network freenode chat.freenode.net 6697
  57
  58 weechat
  59 -------
  60
  61 Move the certificates you created above to ~/.weechat/certs
  62
  63     mkdir ~/.weechat/certs
  64     mv freenode.pem ~/.weechat/certs
  65
  66 Now disconnect and remove the current freenode server(s). Re-add it with the
  67 SSL flag, using your newly generated certificate. Note that these commands are
  68 just examples, you have to adapt them to your current servers.
  69
  70     /set irc.server.freenode.addresses chat.freenode.net/6697
  71     /set irc.server.freenode.ssl on
  72     /set irc.server.freenode.ssl_verify on
  73     /set irc.server.freenode.ssl_cert %h/certs/freenode.pem
  74     /set irc.server.freenode.sasl_mechanism external
  75
  76 and then reconnect to freenode.
  77
  78 znc
  79 ---
  80
  81 Refer to znc's [official documentation](http://wiki.znc.in/Cert).
  82
  83 HexChat
  84 -------
  85
  86 Place the .pem file in `certs/client.pem` in the HexChat config
  87 directory (`~/.config/hexchat/` or `%appdata%\HexChat`). Note
  88 that the `certs` directory does not exist by default and you will have to
  89 create it yourself. Once the file is there, all subsequent SSL connections
  90 will use the certificate.
  91
  92 If you connect to multiple IRC networks, you should keep in mind that using the
  93 filename `certs/client.pem` will send the same certificate to all networks. If
  94 you prefer per-network certificates, use the name of the network exactly
  95 as it appears in the network list (Ctrl-S), including capitalisation and
  96 punctuation (e.g. `certs/freenode.pem` or `certs/Example Server.pem`).
  97
  98 Konversation
  99 ------------
 100
 101 Create the .pem file as per above, then place it wherever you want.
 102 Start Konversation, then open the Identity dialogue by either pressing F8
 103 or via the Settings menu entry. Choose the identity you use for the
 104 freenode network or create a new one.
 105 In the part `Auto Identity` you have to choose `SASL External (Cert)`
 106 as the `Type` for SASL External or `SSL CLient Certificate` for CertFP.
 107 SASL External requires at least version 1.7 of Konversation.
 108 Optionally fill in your account name in the `Account`field.
 109 You can then choose the certificate you created with the file picker
 110 or enter the path manually in the field next to it.
 111 Once done, apply the configuration and (re)connect to freenode.
 112
 113 Revolution
 114 ----------
 115
 116 Create the .pem file as per above, transfer it to your Android device, and place
 117 it wherever you want (`Downloads` is a common location).
 118 Start Revolution and navigate to the `Manage servers` screen if you are not
 119 there already, long-press on the server you wish configure certfp for, and
 120 select `Edit`. When presented with the `Edit a server` screen, tap on
 121 `Authentication mode` and select `Client certificate (CertFP)`, then tap on
 122 `IMPORT PEM` and navigate to where where you put the pem file and select it.
 123 Tap the tick symbol on the top right of the `Edit a server` screen to save.
 124
 125 Alternatively, Revolution has the ability to generate a client certificate for you.
 126 Once you are presented with `IMPORT PEM`, there will also be an option to `CREATE NEW`
 127 and when you tap this, a certificate will be randomly generated and a certicate
 128 fingerprint will be displayed. Tap the tick symbol on the top right of the screen
 129 to save.
 130
 131 Add your fingerprint to NickServ
 132 ================================
 133
 134 You can then check whether you have a fingerprint by using `whois` on yourself:
 135
 136     /whois YourOwnNick
 137     ...
 138     YourOwnNick has client certificate fingerprint f3a1aad46ca88e180c25c9c7021a4b3a
 139     ...
 140
 141 To allow NickServ to recognise you based on your certificate, you need to add
 142 the fingerprint to your account (you will need to log in by other means in order
 143 to do so).
 144
 145 You can then authorise your current certificate fingerprint:
 146
 147     /msg NickServ CERT ADD
 148
 149 In the future, any connections you make to freenode with your certificate will
 150 be logged into your account automatically. Optionally, or if you wish to connect
 151 via Tor, you can enable SASL with the `EXTERNAL` mechanism.