Tip of the day: If you still have users on plaintext port 6667, consider enabling Strict Transport Security to gently move users to SSL/TLS on port 6697.

Authentication types

From UnrealIRCd documentation wiki
Jump to navigation Jump to search
This page contains changes which are not marked for translation.
Other languages:

At various places in the configuration file, for example the Oper block, Vhost block, Link block and Allow block you can authenticate clients by password or other means. You can specify the password as plaintext, but you can also use other authentication types, such as a hashed password or TLS certificate fingerprint.

For passwords, we recommend using argon2, see the example argon2 password in vhost block on how to generate password hashes and use them in the config file (it works for oper passwords too).

Available auth-types

The following auth-types are available:

Auth-type Description Security level How to generate
none Plaintext / cleartext password Bad Plaintext password directly in the config. Not recommended.
crypt UNIX crypt. The exact hashing algorithm depends on the type of crypt, therefore the security can range from bad to reasonable. Bad or reasonable Not recommended.
bcrypt Blowfish crypt with salt and many rounds [1] Reasonable
(still good for long strong passwords)
On IRC: /MKPASSWD bcrypt <password>

On *NIX shell: ./unrealircd mkpasswd bcrypt
On Windows: unrealircdctl mkpasswd bcrypt passwdhere

argon2 Argon2 hashing algorithm. Many rounds, anti-GPU cracking measures, etc. [2]
Good On IRC: /MKPASSWD argon2 <password>

On *NIX shell: /unrealircd mkpasswd argon2
On Windows: unrealircdctl mkpasswd argon2 passwdhere

cert SSL/TLS Client certificate file

Note that most people use certfp or spkifp instead of this.

Excellent Path to a public SSL/TLS certificate (.pem file)
certfp SSL/TLS Client certificate fingerprint (SHA256) Excellent For a given SSL/TLS certificate such as client.pem, run:

openssl x509 -in client.pem -sha256 -noout -fingerprint
and copy the AA:BB:CC:DD:etc... fingerprint.

spkifp SPKI Fingerprint. This is similar to an SSL/TLS Client certificate fingerprint but is usually only used for server linking.

The benefit of spkifp over certfp is that the spkifp stays the same as long as the key stays the same.

Excellent For a given SSL/TLS certificate:

On *NIX: ./unrealircd spkifp conf/ssl/server.cert.pem
On Windows: unrealircdctl spkifp conf\ssl\server.cert.pem
Or, alternatively, these openssl commands

The auth-type argon2 is the best one if you want to authenticate using a password. It's slow to crack. The algorithm bcrypt is fine too, if you use long strong passwords, say 16+ characters of mixed UPPERCASE, lowercase and digits.

The types cert and certfp require a bit more work and expertise, as the user must generate their own SSL/TLS Certificate and then use it to connect to the server via SSL/TLS. We suggest to use this auth-type for /OPER (in the Oper block), see the 2nd example below. Finally the type spkifp is usually only used for linking servers.

Example 1: argon2 password in vhost block

Say, you want to use the password test and want to use argon2 hashed passwords (the best password hashing method available).

  • Create the password hash (choose 1 of these 3 methods):
    • As IRCOp (or unless you have set set::options::mkpasswd-for-everyone block) run:
      /MKPASSWD argon2 test
    • Or on the *NIX command line run:
      irc@system:~/unrealircd$ ./unrealircd mkpasswd
      Enter password to hash:
      Encrypted password is: $argon2id$v=19$m=8192,t=3,p=2$hDpgvcBOUVAJMQcJITTLnQ$fL5lg/3tZ0VgTXn61EQ6Rnxhl5j+MvESBBGpg1mZqWM
    • Or on Windows:
      C:\Program Files\UnrealIRCd 6\bin> unrealircdctl mkpasswd test
      Encrypted password is: $argon2id$v=19$m=8192,t=3,p=2$ZMPmFokpauGUQmz8xhxY+A$KARb6fJb0b9QOi95Ts1xAGgfmY5STkwlGiheNG1JvwU
  • You should get back a string that starts with $ followed by a lot of characters.
  • Put this string in your vhost block (or any other block) like this:
    vhost {
        vhost I.love.Tux;
        mask *@*;
        login Tux;
        password "$argon2id$v=19$m=8192,t=3,p=2$hDpgvcBOUVAJMQcJITTLnQ$fL5lg/3tZ0VgTXn61EQ6Rnxhl5j+MvESBBGpg1mZqWM";
  • /REHASH your IRCd server configuration (Execute /REHASH as an IRCop on IRC)
  • Try to use the new vhost by typing /VHOST Tux test

    Example 2: Oper by SSL/TLS Client certificates

    cert and certfp are exceptional auth-types which can be used to authenticate SSL/TLS users by their client certificate. With these authentication methods you can be sure the user is using SSL/TLS and is using the specified client certificate. It's very secure but is a slightly advanced feature.

    See Certificate fingerprint on how to get your client certificate fingerprint. Then, put your certfp in the unrealircd.conf like this:

    oper test {
         password "e74d46f19ff468f5e8e349cc285df96585ba4f16b64902e334e6e76afe76a798" { certfp; };
    • Rehash your server
    • Now oper up through /OPER test. When you try this, make sure that you are not already an IRCOp.
    • You should now have IRC Operator rights.
    • Congratulations, you are now using the most secure authentication method available in UnrealIRCd!

    Example 3: spkifp when linking servers

    When you are linking servers via the Link block we highly suggest you follow the Tutorial: Linking servers. It uses the spkifp method which is based on the SSL/TLS client certificate (or key, actually).