Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "BaSyx / Documentation / Components / Security"

m (Fixes wrong hierarchy)
Line 42: Line 42:
 
== Option 2: CA-signed AAS Server Certificate ==
 
== Option 2: CA-signed AAS Server Certificate ==
  
==== Step 1: Key and CSR Generation ====
+
=== Step 1: Key and CSR Generation ===
  
 
To generate a CA-signed certificate for the AAS server, the AAS server first needs an asymmetric (private/public) key pair. In addition, the subject field of the future certificate need to be set. This is done with keytool using the following command:<blockquote>keytool.exe -genkey -alias tomcat -keyalg RSA -keysize 2048 -dname "CN=example-hostname, O=Example Company, C=DE" -validity 365 -storepass secretpassword -keystore credentials.jks </blockquote>As described above for Option 1, the parameters of the command need to be adapted to the particular installation. However, unlike Option 1, a certificate signing request ([[:en:Certificate_signing_request|CSR]]) now needs to be generated for the server. This can be done with the following command: <blockquote>keytool.exe -certreq -alias tomcat -storepass secretpassword -keystore credentials.jks -file server.csr </blockquote>
 
To generate a CA-signed certificate for the AAS server, the AAS server first needs an asymmetric (private/public) key pair. In addition, the subject field of the future certificate need to be set. This is done with keytool using the following command:<blockquote>keytool.exe -genkey -alias tomcat -keyalg RSA -keysize 2048 -dname "CN=example-hostname, O=Example Company, C=DE" -validity 365 -storepass secretpassword -keystore credentials.jks </blockquote>As described above for Option 1, the parameters of the command need to be adapted to the particular installation. However, unlike Option 1, a certificate signing request ([[:en:Certificate_signing_request|CSR]]) now needs to be generated for the server. This can be done with the following command: <blockquote>keytool.exe -certreq -alias tomcat -storepass secretpassword -keystore credentials.jks -file server.csr </blockquote>
  
====== Step 2: CA signs CSR ======
+
=== Step 2: CA signs CSR ===
 
Next, the generated CSR needs to be signed by the CA. This step depends on the implementation of the CA. In general, a CA can be public (e.g., provided by DigiCert), private (e.g., running on your local machine), or hybrid (e.g., a company CA). Since there are various CA implementations and procedures for getting CSRs signed, please refer to your CA for getting the CSR signed. To perform a local test, a CA certificate can also be generated locally using openssl with the following commands:  <blockquote>openssl genrsa -out root_key.pem 4096   
 
Next, the generated CSR needs to be signed by the CA. This step depends on the implementation of the CA. In general, a CA can be public (e.g., provided by DigiCert), private (e.g., running on your local machine), or hybrid (e.g., a company CA). Since there are various CA implementations and procedures for getting CSRs signed, please refer to your CA for getting the CSR signed. To perform a local test, a CA certificate can also be generated locally using openssl with the following commands:  <blockquote>openssl genrsa -out root_key.pem 4096   
  
Line 53: Line 53:
 
The above CSR from step 1 can then be signed by the generated CA with the following openssl command:  <blockquote>openssl x509 -req -CA root_cert.pem -CAkey root_key.pem -in server.csr -out server.pem -CAcreateserial  </blockquote>
 
The above CSR from step 1 can then be signed by the generated CA with the following openssl command:  <blockquote>openssl x509 -req -CA root_cert.pem -CAkey root_key.pem -in server.csr -out server.pem -CAcreateserial  </blockquote>
  
====== Step 3: Import CA and CA-signed Certificate ======
+
=== Step 3: Import CA and CA-signed Certificate ===
 
After the CA issued a certificate for the AAS server, the certificate needs to be imported in the initial JKS from Step 1. This way, the AAS server can make use of the certificate to authenticate itself. This requires a two-step process, in which first the CA certificate and then the CA-signed AAS server certificate needs to be imported. The above-generated CA certificate for testing purposes can be imported using keytool with the following command:<blockquote>keytool.exe -importcert -storepass secretpassword -keystore credentials.jks -alias root -file root_cert.pem </blockquote>When importing the CA certificate, keytool will show a prompt where one has to confirm that the CA certificate is indeed trustworthy. In the same manner, the CA-signed AAS server certificate can be imported afterwards: <blockquote>keytool.exe -importcert -storepass secretpassword -keystore credentials.jks -alias tomcat -file server.pem </blockquote>Note that keytool verifies the trust chain when importing the AAS server certificate. Thus, if the CA certificate is not imported first, keytool will fail to establish the trust chain and refuse to import the AAS server certificate.   
 
After the CA issued a certificate for the AAS server, the certificate needs to be imported in the initial JKS from Step 1. This way, the AAS server can make use of the certificate to authenticate itself. This requires a two-step process, in which first the CA certificate and then the CA-signed AAS server certificate needs to be imported. The above-generated CA certificate for testing purposes can be imported using keytool with the following command:<blockquote>keytool.exe -importcert -storepass secretpassword -keystore credentials.jks -alias root -file root_cert.pem </blockquote>When importing the CA certificate, keytool will show a prompt where one has to confirm that the CA certificate is indeed trustworthy. In the same manner, the CA-signed AAS server certificate can be imported afterwards: <blockquote>keytool.exe -importcert -storepass secretpassword -keystore credentials.jks -alias tomcat -file server.pem </blockquote>Note that keytool verifies the trust chain when importing the AAS server certificate. Thus, if the CA certificate is not imported first, keytool will fail to establish the trust chain and refuse to import the AAS server certificate.   
  
Line 60: Line 60:
 
Finally, the AAS server securely runs in HTTPS mode with a CA-signed certificate. But before clients can make use of the HTTPS connection, they need to be provided with the CA certificate through an out-of-band channel, e.g., by transferring the certificate as a file via USB stick. Only then, clients are able to verify the trust chain for the AAS server certificate.  
 
Finally, the AAS server securely runs in HTTPS mode with a CA-signed certificate. But before clients can make use of the HTTPS connection, they need to be provided with the CA certificate through an out-of-band channel, e.g., by transferring the certificate as a file via USB stick. Only then, clients are able to verify the trust chain for the AAS server certificate.  
  
====== Step 4: Providing Clients with CA Certificate ======
+
=== Step 4: Providing Clients with CA Certificate ===
 
Providing clients with the CA certificate works in the same manner as providing clients with a self-signed certificate. Please refer to Option 1 -> Step 3 (see above) for a description of different ways to import certificates into clients or the Operating System certificate store.
 
Providing clients with the CA certificate works in the same manner as providing clients with a self-signed certificate. Please refer to Option 1 -> Step 3 (see above) for a description of different ways to import certificates into clients or the Operating System certificate store.

Revision as of 07:56, 9 March 2022

This article provides an instruction for securing the BaSyx AAS server using HTTPS.

Introduction

By default, the AAS server component uses plain Hypertext Transfer Protocol (HTTP) to communicate with clients. HTTP is unprotected against network attacks, which allows an adversary to read and manipulate any communication to and from the AAS server. However, the AAS server also supports a secure variant of HTTP named HTTPS. To secure exchanged data, HTTPS makes use of the Transport Layer Security protocol (TLS), which provides three protection layers: (1) Encryption: exchanged data cannot be read by others; (2) Integrity: exchanged data cannot be modified by others; (3) Authenticity: exchanged data indeed comes from the claimed source, the server. Today, most Websites on the Internet support HTTPS and browsers recently use HTTPS as their default mode [1].

Due to the insecure nature of HTTP, it is highly recommended to use the AAS server in HTTPS mode. This article describes how to configure the BaSyx AAS server component to use HTTPS, thereby, effectively protecting the AAS server against network attacks.

Installation Options and Requirements

In order to make use of HTTPS, the AAS server, and potentially also clients, need to be properly configured. In detail, HTTPS requires servers to hold an asymmetric (private/public) key pair and an associated certificate. Based on the certificate, clients can verify the authenticity of the server. This means that clients can verify that they are indeed communicating with the benign server and not with an adversary.

There are two types of certificates: self-signed certificates and CA-signed certificates. Self-signed certificates are signed by their own creator, which makes self-signed certificates easy to generate. On the downside, self-signed certificates provide no chain of trust, meaning that clients must initially be provided with the server self-signed certificate prior to securely communicating with the server. In contrast, CA-signed certificates are signed by a Certificate Authority (CA). Thus, generating the server certificate involves an external party, the CA. This makes the certificate generation more complex, but on the other hand, often ease the certificate verification for clients. This is because clients can make use the chain of trust established between the CA and the server certificate. Clients must only have the CA certificate to verify all certificates that are signed by this CA. Note that Operating Systems and browsers already come with preinstalled certificates of well-known public CAs and/or company CAs. In case a server certificate is signed by such a CA, clients can make use of the preinstalled CA certificates to verify the authenticity of the server. Thus, no configuration effort is needed on the clients side.

For beginners, it is recommended to start with self-signed certificates, as they are much easier to generate and use (see Option 1). For advanced installations of the AAS server, e.g., for production environments or when using multiple clients, CA-signed certificates are suited better (see Option 2).

This guideline assumes the presence of the Java Key and Certificate Management utility called keytool. Keytool is included in the installation of the Java Runtime Environment (JRE) or the Java Development Kit (JDK). For CA-signed certificates, this guideline additionally makes use of the openssl utility, which is a popular toolkit for general-purpose cryptography and secure communication. Nevertheless, there are many alternatives to openssl that can be used in similar ways as described below.

Option 1: Self-signed AAS Server Certificate

Step 1: Key and Certificate Generation

Keytool is able to generate an asymmetric (private/public) key pair and an associated self-signed certificate in a single step. This is done using the following command:
keytool.exe -genkey -alias tomcat -keyalg RSA -keysize 2048 -dname "CN=example-hostname, O=Example Company, C=DE" -validity 365 -storepass secretpassword -keystore credentials.jks
The command generates an RSA key pair of size 2048 bit. RSA is a well-proven asymmetric key cipher and 2048 bits is a key size currently recommended by the BSI [2]. In addition, the command generates a self-signed certificate and sets the "Subject" of the certificate. Please note that the configuration of the Subject needs to be adapted to the deployment environment of the AAS (see RFC 5280 for more information). Most important is the Common Name (CN) in the subject field, which must match the DNS name or IP address under which the AAS server is reachable. With the flag validity and the parameter 365, it is defined that the certificate is valid for 365 days. Finally, keys and certificate are stored in a Java Key Store (JKS) file called "credentials.jks", which is protected by the password "secretpassword". Please make sure to adapt the filename and password as needed. In addition, the alias "tomcat" is used, which is needed by the AAS server to find its keys and certificates in the JKS file.

Step 2: Providing AAS Server with Key and Certificate

After generating the JKS file, it needs to be provided to the AAS server. To this end, [TODO: input from Fraunhofer IESE needed]
TODO: AAS Docker container must enable providing AAS server with:
  • Flag to switch to HTTPS mode
  • Java KeyStore file
  • Password for Java KeyStore file

Now, the AAS server securely runs in HTTPS mode with a self-signed certificate. But before clients can make use of the HTTPS connection, they need to be provided with the server's self-signed certificate through an out-of-band channel, e.g., by transferring the certificate as a file via USB stick. This is because clients without any prior information have no means to verify that the self-signed certificate indeed belongs to the benign AAS server. After all, the adversary could have used the above-described command to generate a self-signed certificate for a rogue AAS server.

Step 3: Extracting Public Keys of AAS Server Certificate

Since the JKS also contains the server's private key, which should not leave the server, transferring the JKS store to clients is bad idea. Instead, the self-signed certificate needs to be detached from the JKS store. This can be done using the following command:
keytool.exe -export -alias tomcat -storepass secretpassword -keystore credentials.jks -file server.cer
The command extracts the self-signed certificate from a keystore "credentials.jks" using the password "secretpassword" and stores it in the file "server.cer" with DER encoding. Afterwards the certificate file needs to be transmitted to clients, e.g., using a USB stick or some other form of communication medium.

Step 4: Providing Clients with AAS Server Certificate

Finally, clients need to made aware of the self-signed certificate. Command line tools, such as wget or curl typically provide a parameter to set the certificate (wget: "--ca-certificate=server.pem", curl "--cacert server.pem"). Note that wget, curl, and other tools require the certificate to be encoded in PEM format. Exporting the certificate in PEM format can be done with keytool using the additional parameter "-rfc":
keytool.exe -export -alias tomcat -storepass secretpassword -keystore credentials.jks -rfc -file server.pem
In addition, some clients make use of a certificate store to keep track of trusted certificates. Such certificate stores are provided either by the client itself or by the Operating System (OS). For instance, browsers typically use the certificate store provided by the OS. On Windows, certificates can be imported into the Windows certificate store by double-clicking on the certificate and following these steps: Install Certificate... -> Store Location: Current User -> Certificate Store: Trusted Root Certification Authorities -> Finish. Afterwards, Windows, including browsers such as Firefox, Edge, or Chrome, recognizes the certificate as trustworthy. On Linux-based OSs, the implementation of the certificate store depend on the particular Linux distribution. Here is a link that describes the process for Ubuntu: Adding the Root Certificate to Linux.


Option 2: CA-signed AAS Server Certificate

Step 1: Key and CSR Generation

To generate a CA-signed certificate for the AAS server, the AAS server first needs an asymmetric (private/public) key pair. In addition, the subject field of the future certificate need to be set. This is done with keytool using the following command:
keytool.exe -genkey -alias tomcat -keyalg RSA -keysize 2048 -dname "CN=example-hostname, O=Example Company, C=DE" -validity 365 -storepass secretpassword -keystore credentials.jks
As described above for Option 1, the parameters of the command need to be adapted to the particular installation. However, unlike Option 1, a certificate signing request (CSR) now needs to be generated for the server. This can be done with the following command:
keytool.exe -certreq -alias tomcat -storepass secretpassword -keystore credentials.jks -file server.csr

Step 2: CA signs CSR

Next, the generated CSR needs to be signed by the CA. This step depends on the implementation of the CA. In general, a CA can be public (e.g., provided by DigiCert), private (e.g., running on your local machine), or hybrid (e.g., a company CA). Since there are various CA implementations and procedures for getting CSRs signed, please refer to your CA for getting the CSR signed. To perform a local test, a CA certificate can also be generated locally using openssl with the following commands:
openssl genrsa -out root_key.pem 4096 openssl req -x509 -key root_key.pem -outform pem -out root_cert.pem -days 3650 -subj "/O=Example Company/CN=Company CA" -addext "keyUsage=critical, digitalSignature, keyCertSign, cRLSign"
The above CSR from step 1 can then be signed by the generated CA with the following openssl command:
openssl x509 -req -CA root_cert.pem -CAkey root_key.pem -in server.csr -out server.pem -CAcreateserial

Step 3: Import CA and CA-signed Certificate

After the CA issued a certificate for the AAS server, the certificate needs to be imported in the initial JKS from Step 1. This way, the AAS server can make use of the certificate to authenticate itself. This requires a two-step process, in which first the CA certificate and then the CA-signed AAS server certificate needs to be imported. The above-generated CA certificate for testing purposes can be imported using keytool with the following command:
keytool.exe -importcert -storepass secretpassword -keystore credentials.jks -alias root -file root_cert.pem
When importing the CA certificate, keytool will show a prompt where one has to confirm that the CA certificate is indeed trustworthy. In the same manner, the CA-signed AAS server certificate can be imported afterwards:
keytool.exe -importcert -storepass secretpassword -keystore credentials.jks -alias tomcat -file server.pem
Note that keytool verifies the trust chain when importing the AAS server certificate. Thus, if the CA certificate is not imported first, keytool will fail to establish the trust chain and refuse to import the AAS server certificate.

The JKS file is now ready to be used by the AAS server. Please refer to Option 1 -> Step 2 (see above) for starting the AAS server in HTTPS mode and providing it with the JKS file and password.

Finally, the AAS server securely runs in HTTPS mode with a CA-signed certificate. But before clients can make use of the HTTPS connection, they need to be provided with the CA certificate through an out-of-band channel, e.g., by transferring the certificate as a file via USB stick. Only then, clients are able to verify the trust chain for the AAS server certificate.

Step 4: Providing Clients with CA Certificate

Providing clients with the CA certificate works in the same manner as providing clients with a self-signed certificate. Please refer to Option 1 -> Step 3 (see above) for a description of different ways to import certificates into clients or the Operating System certificate store.

Back to the top