How to use HTTPS and upload certificates to MiR products
This guide describes how you can use HTTPS to interface with MiR products. It describes the main relevant differences between HTTP and HTTPS and how you can further improve the IT security of your MiR applications by using certificates.
HTTPS was introduced in MiR products with software version 2.10.0. Since the release of this software version, all communications between MiR robots and MiR Fleet use HTTPS.
HTTP and HTTPS
HTTP and HTTPS are protocols used to communicate across a computer network. HTTPS is an extension of HTTP that adds security features. The main features relevant to MiR robots are:
Encryption
Communication between devices that use HTTPS is encrypted. This means that any third-party devices that try to read the communication will not be able to interpret it.Verification
If you upload a network certificate to your MiR product, only devices that have been configured to trust the certificate will connect without security warnings. This enables you to ensure that you are connecting to authorized MiR products, eliminating the possibility of an unauthorized middleman device intercepting the communications you intended to send to your MiR product.
HTTPS communication is done via port 443/tcp. This port must be reachable if you want to use HTTPS with your MiR products.
HTTP communication is done via ports 80, 8080, and 9090. If you want to prevent anyone from communicating with your MiR products over HTTP, traffic on these ports must be denied.
How to use HTTPS with the robot and MiR Fleet interface
From software 2.10.0, all robots connected to MiR Fleet use HTTPS to communicate data across the fleet. You can also use HTTPS when opening the robot or fleet interface to make sure that all of the data that goes between your device and the robot is encrypted.
If you have uploaded certificates to your MiR products, all devices you use to connect to the product interfaces must be configured to trust the certificates.
The following steps describe how to connect to the robot or MiR Fleet interface using HTTPS:
Connect your device to the robot or MiR Fleet network.
Open a browser, and in the address bar type: https://, followed by the IP address of the product. If you have not uploaded a certificate to the product and your device does not have a security exception configured to trust the certificate, a security message will be displayed. This message indicates that the server you are connecting to does not have a certificate that your device trusts.
Select Advanced.
Select "Proceed to the <IP address of your MiR product>". You will now be directed to the sign in page for the robot or MiR Fleet interface.
If you use HTTPS to navigate to the MiR Fleet interface without uploading a certificate to all the devices in the fleet, the interface map cannot display updated positions of all the connected robots, unless you have made a security exception with your device for all the fleet robots.
Using REST API with HTTPS
If you want to use HTTPS when communicating through REST API, there are a few changes you need to remember to apply in the endpoint. Take the example:
http://192.168.9.93:8080/v2.0.0/status
Where 192.168.9.93 is the IP address of a robot we want to read the status from. If we want to use HTTPS to receive the status data we need to apply the following changes:
Insert https instead of http at the start:
https://192.168.9.93:8080/v2.0.0/statusUse port 443 instead of port 8080:
https://192.168.9.93:443/v2.0.0/statusInclude /api after the IP and port number:
https://192.168.9.93:443/api/v2.0.0/statusIf you have not uploaded a certificate that is accepted by your REST API client, configure the client to implicitly trust the server. Depending on the client, this is done in different ways. For example, when using the requests library for Python, the optional parameter verify must be set to False.
Uploading a certificate to a MiR product
The following steps assume you are familiar with JSON and REST API. If you are not, consult an experienced JSON and REST API user.
Create a suitable x509 server certificate and certificate key of .pem format, and configure your devices to accept the certificate. You will need to contact your IT department or an expert in network certificates to create a secure verification setup.
Place the two files in a specific subdirectory within the fleet software's configuration directory.
Create a file with a JSON body that passes the data from the certificate and certificate key files content in a base64 encoded format. More explicitly, the POST request body should contain a JSON object of the following format:
{"cert_pem_file": "<certificate file encoded in base64>","cert_key_file": "<certificate key file encoded in base64>"}
The method of extracting and encoding the certificate data is up to you.
In order to transfer the certificate and key files, the content of both files should be converted to base64 encoding, before inserting it into the JSON object's fields.
Manually convert the certificate and private key to base64 encoding
Run either of the two commands, depending on your operating system.
POSIX shell (Linux)
Run the following Linux command in the directory with the two files (certificate and private key) to convert them to base64 encoding and transfer them with a POST request to the /ssl/cert endpoint:
USERNAME="admin"
PASSWORD="admin"
AUTH=$(printf "%s" "$USERNAME:$(printf "%s" "$PASSWORD" | sha256sum | cut -d ' ' -f1)" | base64 -w0) && \
CERT=$(base64 -w0 cert.pem) && \
KEY=$(base64 -w0 key.pem) && \
curl -X POST "http://$IP/api/v2.0.0/ssl/cert" \
-H "Authorization: Basic $AUTH" \
-H "Accept-Language: en_US" \
-H "Content-Type: application/json" \
-d "{ \"cert_pem_file\": \"$CERT\", \"cert_key_file\": \"$KEY\"}"
PowerShell (Windows)
Run the following PowerShell command in the directory with the two files (certificate and private key) to convert them to base64 encoding and transfer them with a POST request to the /ssl/cert endpoint:
$USER = "admin"
$PASS = "admin"
$PASS_HASH = [Security.Cryptography.HashAlgorithm]::Create('sha256').ComputeHash([Text.Encoding]::ASCII.GetBytes($PASS))
$PASS_HASH_STRING = [BitConverter]::ToString($PASS_HASH).Replace('-', '')
$CREDENTIALS = "${USER}:${PASS_HASH_STRING}"$CREDENTIALS_BYTES = [System.Text.Encoding]::ASCII.GetBytes($CREDENTIALS)
$AUTH = [System.Convert]::ToBase64String($CREDENTIALS_BYTES)
$CERT = [Convert]::ToBase64String([IO.File]::ReadAllBytes((Join-Path -Path $pwd -ChildPath "cert.pem")))
$KEY = [Convert]::ToBase64String([IO.File]::ReadAllBytes((Join-Path -Path $pwd -ChildPath "key.pem")))
$HEADERS = @{
"Authorization" = "Basic $AUTH"
"Accept-Language" = "en_US"
"Content-Type" = "application/json"
}
"cert_pem_file" = "$CERT"
"cert_key_file" = "$KEY"
} | ConvertTo-Json
Invoke-WebRequest -Uri http://$IP/api/v2.0.0/ssl/cert -Method Post -Headers $HEADERS -Body $BODY
The MiR product will now use the provided certificate for all future HTTPS communication.
You do not need to restart the product for the changes to take effect.
If you ever want to remove the certificate, use the REST DELETE method with the /ssl/cert endpoint.
To verify that the certificate has been uploaded, connect to the MiR product, open the interface, and check the icon displayed to the left of the address bar. If a small lock symbol is displayed, it means you are connected to a trusted server. This is only displayed if you have uploaded a certificate to the MiR product and your device is configured to trust the certificate.
Uploading a certificate on MiR Fleet 3.0 or higher
On MiR Fleet servers that have been updated to software 3.0, the certificate and matching key file can be accessed from the MiR Fleet host device. They are found in the following locations within the fleet directory:
/mir_persistence/certificate/cert.pem for the certificate file.
/mir_persistence/certificate/key.pem for the key file.
These files are automatically generated by MiR Fleet if a certificate was not already present on MiR Fleet before updating to 3.0.
You can replace these files with a custom certificate and key file generated for your site.
After replacing these files, you must restart the Docker container fleet_traefik for the changes to take effect. To do so, run the following command on the host device:
docker restart fleet_traefik
After running the command, the new certificates are used by MiR Fleet for all communication on port 443.
Related Articles
How to use zones on a map
How to use zones on a map SW 2.10.3 and higher | HW All | en Last updated: 2023-12-13 Download as PDF Date: 2023-12-13 Document version: 2.0 Valid for: All robots and MiR Fleet Valid for software version: 2.10.3 and higher Valid for hardware version: ...How to use backups and recover data on MiR Fleet
SW 2.x and 3.x | HW All | en Last updated: 2024-02-07 Download as PDF Date: 2024-02-07 Document version: 2.0 Valid for: MiR Fleet Valid for software version: Software 2.x and software 3.x Valid for hardware version: All There are several ways to ...How to use WISE modules
Date: 2024-03-01 Document version: 1.4 Document number: 300016 Part number: ADVANTECH WISE 4060-B I/O modules Wi-Fi: 130004 ADVANTECH WISE 4060-B I/O modules LAN: 130005 Valid for: All MiR products This guide describes how to set up a wireless or ...How to use MiR Serial Interface
The MiR Serial interface is a generic interface protocol suitable for interfacing, for example, PLCs to the MiR mobile robot platform. The interface offers possibilities of setting new positions, starting and stopping robot mission execution, and ...Request help from Mobile Industrial Robots
Request help from Mobile Industrial Robots Technical Support Before creating a technical support ticket Check MiR Support Portal for documentation, and check MiR Academy [mir.docebosaas.com] for relevant online courses. Where should I create my ...