Encrypted https connection HowTo

+ More

Table of Contents

Preface Requirements Create a self-signed certificate (Sample) Setup steps (Server-side) Import of the certificate Setup steps (Client-side) Test the https connection with Power Shell Troubleshooting

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-Self Signed Certificate -Dns Name <FQDN of Empirum Server> -Cert Store Location cert:\Local Machine\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 previously 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 Power Shell

Run a PowerShell ISE Editor as Administrator and copy and paste the following lines into the window:

Set Execution Policy Unrestricted
$Encrypted Password="<AES256 encrypted password>"
$User Name="<Domain>\<User Name>"
$Server Name="<FQDN of Empirum Server>"
$Port="9200"
$session = Open-Matrix42Service Connection `
-Server Name $Server Name `
-Port $Port `
-User Name $User Name `
-Encrypted Password $Encrypted Password `
-Is Secured $true
$session

Replace the variables $Server Name and $User Name 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-Matrix42Service Connection: 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.