|
|
| Line 1: |
Line 1: |
| The scope of this page is to be the guide to manage ZNC's certificates. To increase the security check the [[Hardening]] page.
| | [default] |
| | | default_md = sha512 |
| = ZNC PKI Management =
| | name_opt = ca_default |
| Make sure that the certificate private key file is not encrypted and does not have password protection on it, ZNC is unable to properly handle encrypted private key files.
| | cert_opt = ca_default |
| | | default_days = 375 |
| === ZNC 1.7.0+ ===
| | policy = @policy_selfsigned |
| | |
| Since 1.7, you can configure ZNC to read different parts of the certificate from different files:
| |
| | |
| SSLCertFile = /path/to/combined/cert.pem
| |
| SSLKeyFile = /path/to/private/priv.pem | |
| SSLDHParamFile = /path/to/DH/dhparam.pem
| |
| | |
| Read [[Configuration]] about how to edit config.
| |
| | |
| The old way (described below) still works.
| |
| | |
| === Before ZNC 1.7 ===
| |
| | |
| <code>znc.pem</code> '''must''' contain everything in order from the "most private" to the "most public" entries, except for the root certificate.
| |
| | |
| E.g. it may be something like this:
| |
| | |
| cat your-certificate-private-key.pem > znc.pem
| |
| cat your-certificate.pem >> znc.pem
| |
| # If your certificate wasn't signed by CA root certificate directly.
| |
| cat intermediate-certificate-of-ca.pem >> znc.pem
| |
| # Possible, but useless. If client knows the CA, this is redundant. If client doesn't know this CA, it's not trusted anyway.
| |
| cat root-certificate-of-ca.pem >> znc.pem
| |
| # DH parameters at the end
| |
| cat dhparam.pem >> znc.pem
| |
| | |
| To apply changes to certificate file to ZNC, just put (replace) it in ZNC's work folder.
| |
| | |
| As of 1.6.2, ZNC will reload <code>znc.pem</code> each time a client connects, but it'll be fixed in future.
| |
| | |
| = Algorithms =
| |
| The Public Key Infrastructures (PKI) are based on asymmetric cryptography principles: ''public'' & ''private'' key.
| |
| | |
| There are 3 primary algorithms used for PKI key generation:
| |
| * '''(ECC) Elliptic Curve Cryptography'''
| |
| It is the most recently-developed encryption method of the three, but it is going to be more supported. With shorter key lengths, it provides equivalent levels of cryptographic strength as RSA and DSA.
| |
| * '''(RSA) Rivest-Shamir-Adleman'''
| |
| The RSA algorithm was developed in 1977 by Ron Rivest, Adi Shamir, and Leonard Adleman. It is currently the most used and supported key algorithm. Nowadays the key length standard is 2048-4096 bits.
| |
| * '''(DSA) Digital Signature Algorithm'''
| |
| It uses a different algorithm than RSA to create public/private keys but both are considered to be equivalent at same key length. The main differences come down to performance, speed and adoption by the market. Moreover some software are limited to manage DSA up to 1024 bits.
| |
| | |
| {| class="wikitable"
| |
| !colspan="6"|Algorithms Key Size Comparison (bits)
| |
| |-
| |
| !Symmetric
| |
| !RSA/DSA
| |
| !ECC
| |
| |-
| |
| |80
| |
| |1024
| |
| |160-223
| |
| |-
| |
| |112
| |
| |2048
| |
| |224-255
| |
| |-
| |
| |128
| |
| |3072
| |
| |256-383
| |
| |-
| |
| |192
| |
| |7680
| |
| |384-511
| |
| |-
| |
| |256
| |
| |15360
| |
| |512+
| |
| |}
| |
| | |
| Considering the current security standards, we will continue using ''ECC'' and ''RSA''.
| |
| | |
| = Key generation =
| |
| The first step is to create a key pair. As described before, we will provide commands to create ''ECC'' or ''RSA'' keys.
| |
| | |
| '''''WARNING:''''' The folllowing commands will not encrypt/password protect the private key cause ZNC is unable to properly handle encrypted private key files. For this reason keep it secret.
| |
| | |
| Before to proceed, if you want to adopt the ''ECC'', check 2 constraints:
| |
| * Your IRC Client/Server supports ''ECC''
| |
| * In the case you want certificates signed by a [[Signed_SSL_certificate|Public CA]], be sure it supports ''ECC''
| |
| If any of these 2 points will be a ''NO'', then use the ''RSA''.
| |
| | |
| Regardless of the algorithm you choose, at the end of the process you will have:
| |
| * 1 priv.pem
| |
| * 1 pub.pem
| |
| * 1 priv.info (''optional'')
| |
| | |
| == ECC ==
| |
| # Generate the ECC private key with 256-bit key length
| |
| openssl ecparam -genkey -name prime256v1 -outform PEM -out priv.pem
| |
| # Generate the ECC public key
| |
| openssl ec -outform PEM -pubout -in priv.pem -out pub.pem
| |
| # Get information on the ECC private key
| |
| openssl ecparam -noout -text -in priv.pem
| |
| # Get sensitive information on the ECC private key
| |
| openssl ecparam -noout -text -in priv.pem -param_enc explicit
| |
| On the last two commands you can add <code>-out priv.info</code> to get information stored on a file
| |
| | |
| == RSA ==
| |
| # Generate the RSA private key with 4096-bit key length
| |
| openssl genrsa -out priv.pem 4096
| |
| # Generate the RSA public key
| |
| openssl rsa -outform PEM -pubout -in priv.pem -out pub.pem
| |
| # Get sensitive information on the RSA private key
| |
| openssl rsa -noout -text -in priv.pem
| |
| On the last command you can add <code>-out priv.info</code> to get information stored on a file
| |
| | |
| = Certificate Signing Request =
| |
| The second step is to create a Certificate Signing Request (CSR); to proceed a ''priv.pem'' is required (''ECC'' or ''RSA'' doesn't matter).
| |
| | |
| At the end of the process you will have:
| |
| * 1 csr.pem
| |
| | |
| # Generate a CSR based on the private key
| |
| openssl req -new -sha512 -key priv.key -out csr.pem
| |
| You will be prompted to fill the fields below:
| |
| {| class="wikitable"
| |
| !Country Name (2 letter code)
| |
| |The two-letter country code where your company is legally located.
| |
| |-
| |
| !State or Province Name (full name)
| |
| |The state/province where your company is legally located.
| |
| |-
| |
| !Locality Name (e.g., city)
| |
| |The city where your company is legally located.
| |
| |-
| |
| !Organization Name (e.g., company)
| |
| |Your company's legally registered name (e.g., YourCompany, Inc.).
| |
| |-
| |
| !Organizational Unit Name (e.g., section)
| |
| |The name of your department within the organization. (You can leave this option blank; simply press Enter.)
| |
| |-
| |
| !Common Name (e.g., server FQDN)
| |
| |The fully-qualified domain name (FQDN) (e.g., www.example.com).
| |
| |-
| |
| !Email Address
| |
| |Your email address. (You can leave this option blank; simply press Enter.)
| |
| |-
| |
| !A challenge password
| |
| |Leave this option blank (simply press Enter).
| |
| |-
| |
| !An optional company name
| |
| |Leave this option blank (simply press Enter).
| |
| |}
| |
| If you want automate the process, you can feed the command providing information with this additional parameter:
| |
| -subj "/C=XX/ST=XXXX/L=YYYY/O=ZZZZ/OU=XYZ/CN=FQDN/emailAddress=user [at] domain [dot] com"
| |
| If you need the certificate only for the modules [[Cert]] or [[Certauth|CertAuth]] you can simply use:
| |
| -subj "/CN=YourZncNickname" | |
| or
| |
| -subj "/CN=FQDN:Port".
| |
| '''''Note:''' Some user could encounter some issue to login via certificate due to random settings/old caching/etc; try to use your ZNC's FQDN:Port instead of YourZncNickname. Thanks to <CryptoSiD> on Freenode for the tip ''
| |
| | |
| = Certificate generation =
| |
| The last step is to generate the X.509 certificate using the CSR previously generated.
| |
| Now you can:
| |
| * submit the CSR to a [[Signed_SSL_certificate|Public CA]]
| |
| * self signing it
| |
| A security overview of the difference between a Self Signed Certificate and a Public CA Signed one, is provided on the [[Hardening]] page.
| |
| | |
| '''Note:''' If you are generating the certificate for:
| |
| * [[Cert|Cert module]] - you can go directly with a simpler/faster/costless Self Signed Certificate
| |
| * [[Certauth|CertAuth module]] - you can opt for a Self Signed Certificate, but it could be recognized as untrusted
| |
| * ZNC global certificate, you have to decide based on your scenario
| |
| | |
| At the end of the process you will have:
| |
| * 1 cert.pem
| |
| * 1 cert.info (''optional'')
| |
| * 1 bundle.pem (''optional - depending on the Public CA'')
| |
| | |
| == Public CA ==
| |
| Signed SSL certificates are recommended when more than one person share the same ZNC instance.
| |
| | |
| Most of the time they are generated by third-party companies; for this reason you can check the dedicated page [[Signed_SSL_certificate]] on the topic.
| |
| | |
| '''Note:''' remember to retrieve the ''Root'' and ''Intermediate'' certificate of the Public CA you will choose. They could be provided in a single bundle file too.
| |
| | |
| == Self Signed ==
| |
| The strict definition of ''Self Signed Certificate'' is:
| |
| In cryptography and computer security, a self-signed certificate is a security certificate that is not signed by a certificate authority (CA)
| |
| - [Source: [https://en.wikipedia.org/wiki/Self-signed_certificate Wikipedia]]
| |
| Extending the mindset, the CA is considered ''Public'', so not widely distribuited. In that case even a Private CA Signed certificate can be considered as a Self Signed (signed by our own CA - not Public).
| |
| To do not go out of the scope of this page, we will not consider the scenario of signing the CSR with a Private CA; moreover, if you have a Private CA, you should be able to sign a CSR by your self.
| |
| | |
| Regardless you opted out for an ''ECC'' or a ''RSA'' algorithms, the commands are the same.
| |
| # Generate the Certificate, selfsigning the CSR
| |
| openssl req -x509 -sha512 -days 3650 -key priv.pem -in csr.pem -out cert.pem
| |
| # Store information of the certificate
| |
| openssl x509 -fingerprint -sha512 -serial -hash -text -noout -in cert.pem -out cert.info
| |
| | |
| = DHparam=
| |
| An additional additional step is to generate the Diffie-Hellman key exchange parameters.
| |
| | |
| The Diffie-Hellman key exchange [https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange Wikipedia][https://wiki.openssl.org/index.php/Diffie_Hellman OpenSSL] is a method of securely exchanging cryptographic keys
| |
| | |
| It has to be append at the end of the <code>znc.pem</code>.
| |
| | |
| The dhparam file doesn't have to be kept secret, and can be used multiple times; you can increase 2048 as you like but be aware that this will take '''a long time'''.
| |
| # Generate DH parameters
| |
| openssl dhparam -out dhparam.pem 2048
| |
| # Check DH parameters created
| |
| openssl dhparam -noout -text -check -in dhparam.pem
| |
| | |
| If you want to speed up the generation process you can use the services of [[https://2ton.com.au/dhtool/#service 2ton]]; they offer freshly generated DHparam files.
| |
| | |
| You can simply download them (wget or curl) choosing the size you want (2048, 3072,4096,8192):
| |
| wget https://2ton.com.au/dhparam/2048 -O dhparam.pem
| |
| curl https://2ton.com.au/dhparam/2048 -o dhparam.pem
| |
| | |
| = Additional useful commands =
| |
| | |
| == PKCS#12 ==
| |
| The command below will change the format of the certificate from PEM to PKCS#12.
| |
| | |
| For example you need this kind of format when you have to interact with browser (Ex. [[Certauth| CertAuth module]])
| |
| openssl pkcs12 -export -in cert.pem -out znc_user.pfx
| |
| | |
| == Fingerprint ==
| |
| Each certificate has its own fingerprint and can be recognized by it. Fingerprints are calculated using [https://en.wikipedia.org/wiki/Cryptographic_hash_function HASHes]. Allowed hashes are: <code>MD5</code>,<code>SHA1</code>,<code>SHA256</code>,<code>SHA512</code>.
| |
| | |
| There are many reasons for which we would like to verify the fingerprint of a certificate:
| |
| * to setup the [[Cert | Cert module]]
| |
| * to check if a MITM attack is progress
| |
| * etc
| |
| | |
| We could retrieve the fingerprint as from a local certificate as from an online one.
| |
| | |
| === Local certificate ===
| |
| openssl x509 -md5 -noout -fingerprint -in cert.pem | sed -e 's/^.*=//;s/://g;y/ABCDEF/abcdef/' | |
| openssl x509 -sha1 -noout -fingerprint -in cert.pem | sed -e 's/^.*=//;s/://g;y/ABCDEF/abcdef/' | |
| openssl x509 -sha256 -noout -fingerprint -in cert.pem | sed -e 's/^.*=//;s/://g;y/ABCDEF/abcdef/' | |
| openssl x509 -sha512 -noout -fingerprint -in cert.pem | sed -e 's/^.*=//;s/://g;y/ABCDEF/abcdef/'
| |
| If you need the fingerprint in the default format, remove <code>| sed -e 's/^.*=//;s/://g;y/ABCDEF/abcdef/'</code>
| |
| | |
| '''Note:''' If you are here from the [[Cert| Cert module]], be aware that different IRC networks use different fingerprints; for example Libera.chat uses SHA-512. Consult the network you're connecting to for this information.
| |
| | |
| === Online Certificate ===
| |
| # Replace with the hostname/FQDN of your ZNC Server
| |
| sslhost=znc.example.com
| |
| # Replace with the SSL port of your ZNC Server
| |
| sslport=6697 | |
| | | |
| sslcert=$(openssl s_client -showcerts -connect "$sslhost":"$sslport" < /dev/null) | | [ req ] |
| echo "$sslcert" | openssl x509 -noout -fingerprint -md5 | | #Options from the [ req ] section are applied |
| echo "$sslcert" | openssl x509 -noout -fingerprint -sha1 | | #when creating certificates or certificate signing requests. |
| echo "$sslcert" | openssl x509 -noout -fingerprint -sha256 | | # Options for the `req` tool (`man req`). |
| echo "$sslcert" | openssl x509 -noout -fingerprint -sha512 | | default_bits = 4096 |
| | | distinguished_name = req_selfsigned |
| = Glossary = | | string_mask = utf8only |
| * '''CA:''' Certificate Authority or Certification Authority is the entity that issues digital (X.509) certificates
| | default_md = sha512 |
| * '''Certificate:''' Also known as X.509 certificate, it is used to encrypt and decrypt data relaying on a related public and private key pair.
| | |
| * '''CSR:''' Certificate Signing Request
| | |
| * '''DER:''' Distinguished Encoding Rules is a binary encoding for X.509 certificates and private keys
| | [ req_selfsigned ] |
| * '''DES:''' Data Encryption Standard is a symmetric-key algorithm for the encryption of digital data. Too insecure for encryption nowadays.
| | # The [ req_dn ] section declares the information |
| * '''DSA:''' Digital Signature Algorithm
| | # normally required in a certificate signing request. |
| * '''ECC:''' Elliptic Curve Cryptography algorithms
| | # You can optionally specify some defaults. |
| * '''FQDN:''' Fully Qualified Domain Name or Hostname
| | # See <https://en.wikipedia.org/wiki/Certificate_signing_request>. |
| * '''MITM:''' Man-In-The-Middle attack; an attacker acts as proxy sniffing and/or altering the traffic data
| | countryName = Country Name (2 letter code) |
| * '''P12:''' Common file extension for '''PKCS#12''' format
| | countryName_min = 2 |
| * '''PEM:''' Privacy Enhanced Mail is a Base64 encoded ASCII file format
| | countryName_max = 2 |
| * '''PFX:''' Common file extension for '''PKCS#12''' format
| | stateOrProvinceName = State or Province Name (full name) |
| * '''PKCS12:''' Common file extension for '''PKCS#12''' format
| | localityName = Locality Name (eg, city) |
| * '''PKCS#12:''' Binary format for storing certificate chain and private key in a single: encryptable file
| | organizationName = Organization Name (eg, company) |
| * '''PKI:''' Public Key Infrastructures
| | organizationalUnitName = Organizational Unit Name (eg, section) |
| * '''Private Key:''' One of the key pair. It is the one that must be kept secret
| | commonName = Common Name (e.g. server FQDN or YOUR name) |
| * '''Public Key:''' One of the key pair. It is the one that can be freely shared
| | emailAddress = Email Address |
| * '''RSA:''' Rivest-Shamir-Adleman algorithms
| | |
| * '''SSL:''' Secure Sockets Layer is a cryptographic protocol designed to provide communications security over a computer network
| | # Optionally, specify some defaults. |
| | countryName_default = IT |
| | stateOrProvinceName_default = Italy |
| | localityName_default = Italy |
| | organizationName_default = ZNC.in |
| | #organizationalUnitName_default = ZNC Service |
| | #commonName_default = wiki.znc.in |
| | emailAddress_default = user [at] example [dot] com |
| | |
| | [ policy_selfsigned ] |
| | # See the POLICY FORMAT section of the `ca` man page. |
| | countryName = optional |
| | stateOrProvinceName = optional |
| | localityName = optional |
| | organizationName = optional |
| | organizationalUnitName = optional |
| | commonName = optional |
| | emailAddress = optional |
| | |
| | [ usr_cert ] |
| | # We’ll apply the usr_cert extension when signing client certificates, |
| | # such as those used for remote user authentication. |
| | # Extensions for client certificates (`man x509v3_config`). |
| | basicConstraints = critical, CA:FALSE |
| | subjectKeyIdentifier = hash |
| | authorityKeyIdentifier = keyid:always, issuer:always |
| | keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment, dataEncipherment, keyAgreement |
| | extendedKeyUsage = critical, clientAuth, emailProtection, codeSigning |
| | |
| | [ server_cert ] |
| | # We’ll apply the server_cert extension when signing server certificates, |
| | # such as those used for web servers. |
| | # Extensions for server certificates (`man x509v3_config`). |
| | basicConstraints = critical, CA:FALSE |
| | subjectKeyIdentifier = hash |
| | authorityKeyIdentifier = keyid:always, issuer:always |
| | keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment, keyAgreement |
| | extendedKeyUsage = critical, serverAuth |