User Tools

Site Tools


maintenance:general:ssl_cerificates
LDAP: couldn't connect to LDAP server

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
maintenance:general:ssl_cerificates [2021/12/20 14:05] – [mk_ssl_cert.pl] yspeertemaintenance:general:ssl_cerificates [2021/12/20 16:55] (current) – [SSL Certificates] yspeerte
Line 1: Line 1:
 +===== SSL Certificates =====
 +
 +NetYCE can be setup to use SSL certificates when accessed using the browser (http**s**). When https is enabled, the SSL protocol will also be used for the back-end communication between browser and the NetYCE API's and to access the REST API's (XCHapi and TMFapi).
 +
 +Where the http protocol uses port 80, https will switch to port 443 forwarding any port 80 request to port 443.  
 +
 +<WRAP indent box>
 +The back-end API port will use port 8080 for http and https. Although the 8080 port number can be changed, the 8080 port will only serve http or https depending on SSL the configuration.
 +
 +This http/https behaviour of port 8080 will soon be modified to support port 8080 for http and port 8443 for https.
 +</WRAP>
 +
 +The common procedure to install SSL certificates requires to first create a Certificate Signing Request (CSR) file which is then submitted to be signed by the Certificate Authority (CA). The resulting certificate (CRT) is installed on the server at the appropriate location. Once installed, the NetYCE configuration must then be updated to include the certificate and modify the used protocols.
 +
 +To support this procedure, NetYCE includes cli tools to create the CSR and update the SSL configuration.
 +
 +
 +==== Create CSR ====
 +
 +The ''**mk_ssl_cert.pl**'' tool is used to create the CSR in a few steps. First the SSL configuration needs to be defined, then the host KEY and CSR files can be generated. A third step allows for the creation of a PEM file that some signing procedures require.
 +
 +The KEY file represents the PRIVATE KEY of the host. It is used for the SSL encryption and must be unique for the server. Normally the KEY file is generated once and should never be deleted or shared insecurely. The KEY file is also used to generate the CSR on which the CRT will be based. Losing or re-generating the KEY file of a server will render the CRT useless.
 +
 +The ''/opt/yce/system/mk_ssl_cert.pl'' tool will prompt the user with a menu. Select option 1) to create or review the certificate configuration values.
 +
 +<code>
 +$ mk_ssl_cert.pl
 +-----------------------------------------------------
 +Actions:
 +  1)  generate CONF file (certificate settings)
 +  2)  generate CSR file (certificate signing request)
 +  3)  extend   CSR into PEM and INFO files
 +  4)  generate CRT file (self-signed certificate)
 +  5)  extend   CRT into PEM and INFO files
 +  q)  quit
 +Select action:                                [1]
 +</code>
 +
 +The user is them prompted by some mandatory values. Most organizations will use some guidelines as to accepted values for these values. The responses will be stored in a ssl configuration file which will be used as defaults for later sessions: ''/opt/yce/etc/ssl_cert.conf''
 +
 +A sample session:
 +<code>
 +Select action:                                [1]
 +  Please enter appropriate values for the certificate.
 +    (blank values will be ignored)
 +    C - Country Name (2 letter code)          [NL]
 +    ST - State or Province Name               [Weesp] Hoord-Holland
 +    emailAddress - Email address              [[email protected]]
 +    OU - Organizational Unit (eg section)     [development]
 +    CN - Common Name (fqdn)                   [genesis.netyce.org]
 +    O - Organization Name                     [NetYCE]
 +    L - Locality Name (eg city)               [Weesp]
 +  -> created CONF file: /opt/yce/etc/ssl_cert.conf
 +-----------------------------------------------------
 +</code>
 +
 +To create the CSR, select option 2). If a KEY file for the server name was found (in the directory /opt/yce/etc) a warning issued not to overwrite it.
 +
 +<code>
 +Select action:                                [1] 2
 +  Creating CSR
 +  -> have    KEY file: /opt/yce/etc/genesis.netyce.org.key
 +  WARNING: a KEY file already exists - overwriting will obsolete existing certificates!
 +  Use existing KEY file?                      [Y] 
 +</code>
 +
 +If no KEY was found it will be created.
 +
 +<code>
 +  Use existing KEY file?                      [Y] y
 +/usr/bin/openssl req -out /opt/yce/etc/genesis.netyce.org.csr -key /opt/yce/etc/genesis.netyce.org.key -new -config /opt/yce/etc/ssl_cert.conf
 +  Set permissions
 +chmod 400 /opt/yce/etc/genesis.netyce.org.key /opt/yce/etc/genesis.netyce.org.csr
 +
 +  Below is the Certificate Signing Request (CSR) to submit to the Certificate Authority (CA):
 +  Make sure the '-----BEGIN/END CERTIFICATE REQUEST-----' lines are included.
 +  It can also be copied from '/opt/yce/etc/genesis.netyce.org.csr'.
 +
 +-----BEGIN CERTIFICATE REQUEST-----
 +MIIDdDCCAlwCAQAwgZUxCzAJBgNVBAYTAk5MMSAwHgYDVQQDDBdkZXZlbDdhLmxl
 +ZnQubmV0eWNlLm9yZzEOMAwGA1UEBwwFV2Vlc3AxDzANBgNVBAoMBk5ldFlDRTEU
 +     ......
 +TX8swZ8/LkM6fbVeYOA6BMpIGT2RawRaoHjHydIc4vFLZx3W64ObmYA22RVRcwUm
 +FaAYE3znKD4qW+d76RikvjbKElNnZ+Mc1+yv5HVwUEH1lRIN2QV5h7FuM4FIJWh+
 +pr7D8JMviQvHOgcZOIRtunlLBzUIIlFA
 +-----END CERTIFICATE REQUEST-----
 +
 +
 +  -> used    KEY file: /opt/yce/etc/genesis.netyce.org.key
 +  -> created CSR file: /opt/yce/etc/genesis.netyce.org.csr
 +-----------------------------------------------------
 +</code>
 +
 +Because signing by the CA requires the CSR and de KEY this is often combined in a PEM file. This file can be created using option 3).
 +
 +<code>
 +Select action:                                [3] 3
 +  Creating PEM
 +  Generating PEM from CSR
 +/usr/bin/openssl req -in /opt/yce/etc/genesis.netyce.org.csr -noout -text > /opt/yce/etc/genesis.netyce.org.info
 +cat /opt/yce/etc/genesis.netyce.org.csr /opt/yce/etc/genesis.netyce.org.key > /opt/yce/etc/genesis.netyce.org.pem
 +  Set permissions
 +chmod 400 /opt/yce/etc/genesis.netyce.org.info /opt/yce/etc/genesis.netyce.org.pem
 +  -> created INF file: /opt/yce/etc/genesis.netyce.org.info
 +  -> created PEM file: /opt/yce/etc/genesis.netyce.org.pem
 +-----------------------------------------------------
 +</code>
 +
 +Copy the content of the KEY, PEM and CSR files and submit as appropriate them for signing by the CA.
 +
 +<WRAP indent box>
 +=== ssl_cert.conf ===
 +
 +The generated CSR will include the now often required Subject Alternative Name (SAN) attributes. The ''/opt/yce/etc/ssl_cert.conf'' reflects this: 
 +
 +<code>
 +$ cat ssl_cert.conf
 +[req]
 +default_bits = 2048
 +distinguished_name = req_dn
 +prompt = no
 +req_extensions = req_ext
 +
 +[req_dn]
 +C = NL
 +CN = genesis.netyce.org
 +L = Weesp
 +O = NetYCE
 +OU = development
 +ST = Weesp
 +emailAddress = [email protected]
 +
 +[req_ext]
 +basicConstraints = CA:FALSE
 +extendedKeyUsage = serverAuth, clientAuth
 +keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
 +subjectAltName = @alt_names
 +
 +[alt_names]
 +DNS.1 = genesis.netyce.org
 +</code>
 +
 +It can be modified to include additional names/domains and ip-addresses like the example below:
 +<code>
 +[alt_names]
 +DNS.1 = genesis.netyce.org
 +DNS.2 = netyce.org
 +IP.1 = 172.17.0.24
 +IP.2 = 2003::24
 +</code>
 +</WRAP>
 +
 +==== Install CRT ====
 +
 +Assuming the signed certificate was returned in CRT format (using ''.crt'' or ''.cer'' extensions), the file must be installed in the correct directory using the correct file names and activated. 
 +
 +If a PFX format was returned, see below for the extraction.
 +
 +NetYCE expects the two SSL files in the directory ''/opt/yce/etc''. They should be named after the full qualified name of the server using the extensions ''.key'' and ''.crt'' respectively.
 +
 +As these files are highly private limited file permissions must be enforced.
 +
 +<code>
 +cd /opt/yce/etc
 +
 +sudo chown yce.nms genesis.netyce.org.key
 +sudo chown yce.nms genesis.netyce.org.crt
 +
 +chmod 0400 genesis.netyce.org.key
 +chmod 0400 genesis.netyce.org.crt
 +</code>
 +
 +<WRAP indent box>
 +=== PFX file extraction ===
 +
 +Some signing authorities do not return a CRT (or CER) file but a PFX file. In that case the CRT file must be extracted from the FPX file. 
 +
 +<code>
 +openssl pkcs12 -in genesis.netyce.org.pfx -clcerts -nokeys -out genesis.netyce.org.crt
 +</code>
 +
 +The PFX file can also provide KEY file. But if this is the same that was used to create the CSR there is no need. If that was not the case (like a CRT for an entire domain), the KEY must be extracted in two steps and requires a decryption and encryption passphrase.
 +
 +The CRT and KEY files obtained this way can be installed as described above
 +
 +<code>
 +-- extract the key in encrypted form. 
 +-- It first prompts for the decryption passphrase,
 +-- then twice for a new encryption passphrase
 +openssl pkcs12 -in netyce.org.pfx -nocerts -out netyce.org.encrypted.key
 +
 +-- now extract the unencrypted KEY file
 +-- it will prompt for the new passphrase
 +openssl rsa -in netyce.org.encrypted.key -out genesis.netyce.org.key
 +
 +</code>
 +</WRAP>
 +
 +==== Activating SSL certificate ====
 +
 +The SSL certificate will be used by the web service (apache) and the back-end service (mojo). The NetYCE setup tool ''**yce_setup.pl**'' will be used to configure these services to enable SSL.
 +
 +If the certificate only replaces an existing SSL CRT, the NetYCE application only needs to be restarted to have it activated. The yce_setup step can then be skipped.
 +
 +To configure the local NetYCE server for SSL, start ''yce_setup.pl'' and continue to the "Yce server roles" section. Select the local server and answer each prompt. Answer 'yes' to the enable SSL prompt. Choose the SSL-hardening setting as per preference.
 +
 +<code>
 +YCE servers currently in setup:
 +1) genesis.netyce.org (*)
 +   | IPv4-address          | IPv6-address
 +    172.17.0.24          |  3001::24
 +  local server is marked with (*)
 +  Select the server-number to Edit/Remove, or 'A' to add, 'C' to continue: [C]
 +
 +YCE server roles:
 +1) genesis.netyce.org (*)
 +   | Front-end     | SSL      | URL       | Backend
 +    yes          |  http    |  name      8080
 +   | Database      | Db-id
 +    yes          |  1
 +  local server is marked with (*)
 +  Select the server-number to change, 'C' to continue: [1]
 +    'genesis' is (also) a Front-end server?   [yes]
 +    'genesis' is DNS resolvable (y/n)?        [yes]
 +    'genesis' uses SSL (y/n)?                 [no] ?
 +
 +  The use of SSL or 'secure-socket-layer' is highly recommended for production systems.
 +  It requires the generation and signing of a server-certificate by the CA (certificate-
 +  authority) of your company.
 +  More information on the generation of a SSL certificate on NetYCE servers is located at:
 +  'https://wiki.netyce.com/doku.php/maintenance:general:tools:mk_ssl_cert.pl'
 +
 +    'genesis' uses SSL (y/n)?                 [no] y
 +    'genesis' uses SSL-hardening (y/n)?       [no] ?
 +
 +  SSL can be setup to accept older (weaker) levels of TLS (transport-layer-security)
 +  as well as the newer (hardened) level of TLS1.2. When selecting 'SLL-hardening'
 +  the http server will only accept connections supporting TLS1.2 and reject older
 +  levels.
 +
 +    'genesis' uses SSL-hardening (y/n)?       [no] y
 +    'genesis' portnumber of backend server?   [8080]
 +    'genesis' is (also) a Database server?    [yes]
 +    'genesis' uses database-id value (1/2)?   [1]
 +</code>
 +
 +<WRAP box>
 +=== Service restart ===
 +
 +use the commands ''go restart httpd -f'' and ''go restart mojo -f'' to restart these services. The ''-f'' option is used to force the restart instead of the standard hot-deploy.
 +
 +<code>
 +$ go restart httpd -f
 +-- restarting Daemon 'httpd'
 +httpd: 1022 11920 11923 11924 11925
 +  stop: /usr/bin/sudo /usr/bin/systemctl stop httpd.service
 +  wait stop 'httpd':
 +  start: /usr/bin/sudo /usr/bin/systemctl start httpd.service
 +  wait start 'httpd': 12272 12273 12274 12275 12276
 +done
 +
 +$ go restart mojo -f
 +-- restarting Daemon 'mojo'
 +mojo: 11990 12058 12059 12060 12061 12062 12063
 +  stop: /opt/yce/system/init/yce_mojo stop
 +  wait stop 'mojo':
 +  start: /opt/yce/system/init/yce_mojo start
 +  wait start 'mojo': 12161 12162 12163 12164 12165 12166 12167
 +done
 +</code>
 +</WRAP>