Encrypted https connection HowTo
Preface
This document describes how to establish and test an encrypted https connection with the Matrix42 Empirum SDK.
Requirements
- Matrix42 Empirum SDK (v1.3.x or later)
- Empirum-API service (v17.0.3 or later)
- Official or self-signed certificate (*.pfx)
Create a self-signed certificate (Sample)
$cert = New-SelfSignedCertificate -DnsName <FQDN of Empirum Server> -CertStoreLocation cert:\LocalMachine\My
Setup steps (Server-side)
Import of the certificate
Run Certlm.msc (Local Machine Certificate) or use the MMC.exe to get access to the certificate snap-in.
- Import the PFX certificate in the Personal Certificate Store.
- Only for self-signed certificates: Import the PFX certificate in the Trusted Root Certification Authorities certificate store.
- Run Empirum DBUtil, select the Empirum-API service and choose Select Certificate to select the previous imported certificate. Click OK and then Apply.
- After configuration, the Empirum API service must be reinstalled via the context menu.
Setup steps (Client-side)
Install the Matrix42 SDK MSI (e.g., Matrix42_Empirum SDK _x.x.x.x_x64.msi).
Test the https connection with PowerShell
- Run a PowerShell ISE Editor as Administrator and copy and paste the following lines into the window:
Set ExecutionPolicy Unrestricted
$EncryptedPassword="<AES256 encrypted password>"
$UserName="<Domain>\<UserName>"
$ServerName="<FQDN of Empirum Server>"
$Port="9200"
$session = Open-Matrix42ServiceConnection `
-ServerName $ServerName `
-Port $Port `
-UserName $UserName `
-EncryptedPassword $EncryptedPassword `
-IsSecured $true
$session - Replace the variables $ServerName and $UserName with your values.
- Execute the complete script to test the connection.
If the connection can be established, you will get a response like in the following screenshot otherwise you will get an error message.
Troubleshooting
Q: I got the following error message:
Could not establish trust relationship for the SSL/TLS secure channel with authority '<Server>:9200'.
A: Please use the FQDN name for the Empirum Server.
Q: I got the following error message:
Open-Matrix42ServiceConnection: Log files can be found in the directory: '%Temp%\Matrix42 SDK'. Cannot create Session object. Invalid URI: Invalid port specified.
A: Please make sure that the used port is the correct one.