HowTo establish and test an encrypted https connection Version 1.0.0 11. October 2016
Copyright 2000-2016 Matrix42 AG This documentation is copyright protected. All rights are reserved by Matrix42 AG. Any other use, in particular the disclosure to third parties, storage in a data system, dissemination, processing, presentation, performance and demonstration are prohibited. This applies to the entire document, as well as parts thereof. Subject to change. Reprint, also in excerpts, is permitted only with the written consent of Matrix42 AG. The software described in this document is subject to a permanent development due to which there may be differences in the documentation and the actual software. This documentation is not entitled to the actual functionality of the software. Apple and Mac OS X are registered trademarks of Apple Inc. Citrix software or Citrix server are Trademarks and Registered Trademarks of Citrix Systems, Inc. in the United States and other countries. cygwin is copyrighted by Red Hat Inc. 1996-2003. expat is copyrighted by Thai Open Source Software Center Ltd. gsoap is copyrighted by Robert A. van Engelen, Genivia, Inc. All rights reserved. Iconv is copyrighted by 1999-2003 Free Software Foundation, Inc. Iperf is copyrighted by the University of Illinois, except for the gnu_getopt.c, gnu_getopt_long.c, gnu_getopt.h files, and inet_aton.c, which are under the GNU General Public License. Libmspack (C) 2003-2004 by Stuart Caie <kyzer@4u.net>. OpenSSL This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. PuTTY is copyrighted by Simon Tatham. Portions copyright Robert de Bath, Joris van Rantwijk, Delian Delchev, Andreas Schultz, Jeroen Massar, Wez Furlong, Nicolas Barry, Justin Bradford, Ben Harris, Malcolm Smith, Ahmad Khalifa, Markus Kuhn, and CORE SDI S.A. RSA Data Security, Inc. MD5 Message-Digest Algorithm is copyrighted by RSA Data Security Inc. Created 1991. All rights reserved. rsync is an open source utility that provides fast incremental file transfer. rsync is freely available under the GNU General Public License version 2. runcontrol The Initial Developer of the Original Code is James Clark. Portions created by James Clark are Copyright (c) 1998 James Clark. All rights reserved. SNMP++ Copyright (c) 1996 Hewlett-Packard Company. VMware, the VMware "boxes" logo and design, Virtual SMP, VMotion vsphere, vsphere Hypervisor (ESXi), ESX, View, ThinApp, vcenter and vcloud are registered trademarks or trademarks of VMware, Inc. in the United States and/or other jurisdictions. Windows, Windows 2000, Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008, Windows 10, Windows 7, Windows Server 2008 R2, Windows 8, Windows 8.1, Windows Server 2012, Windows Server 2012 R2 and Windows Server 2016 are registered trademarks of Microsoft Corporation. Others, at this point not explicitly listed, company, brand and product names are trademarks or registered trademarks of their respective owners and are subject to trademark protection. Author: Matrix42 Client Management
Table of Contents 1. Preface 4 2. Requirements 5 3. Setup steps (Server-side) 6 3.1. Import of the certificate 6 4. Setup steps (Client-side) 7 4.1. Import of the certificate 7 5. Test the https connection with Powershell 8 6. Troubleshooting 9 Author: Matrix42 Client Management - 3 -
1. Preface This document describes how to establish and test an encrypted https connection with the Matrix42 Empirum SDK. Author: Matrix42 Client Management
2. Requirements Matrix42 Empirum SDK (v1.1.6 or later) Empirum-API service (v16.1.1 or later) Official or self-signed certificate (*.pfx) Author: Matrix42 Client Management - 5 -
3. Setup steps (Server-side) 3.1. 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, please reinstall the Empirum-API service via context menu. Author: Matrix42 Client Management
4. Setup steps (Client-side) 4.1. Import of the certificate Please note: The certificate must be imported into the store of the user with which the Powershell script will be executed. Run Certmgr.msc (Current User 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. Install the Matrix42 SDK MSI (e.g. Matrix42_Empirum SDK _1.1.6.0_x64.msi). Author: Matrix42 Client Management - 7 -
5. Test the https connection with Powershell Run an Powershell ISE Editor as Administrator and copy and paste the following lines into the window: Set ExecutionPolicy Unrestricted $thumbprint="<certificate Thumbprint>" $encryptedpassword="<aes256 encrypted password>" $servername="<fqdn of the Empirum Server>" $port="9200" $username="<domain>\<user Account>" $certificate=get-childitem -Path Cert:\CurrentUser\My where { $_.Thumbprint -eq $thumbprint } $session=open-matrix42serviceconnection -ServerName $servername - Port $port -UserName $username -EncryptedPassword $encryptedpassword -Certificate $certificate $session Copy and paste the following line into a new window and execute the following command to get the Thumbprint of the certificate. Get-ChildItem -Path Cert:\CurrentUser\My Copy and paste the Thumbprint into the variable $thumbprint. Create an AES encrypted password for the user account you want to run the Powershell script. Please use the tool EmpCrypt.exe with the option /AES256 (\\<EmpirumServer>\Empirum$\AddOns\Encrypter). EmpCrypt.exe /AES256 <Password> Copy and paste the password into the variable $encryptedpassword. 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. Author: Matrix42 Client Management
6. 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. Matrix42 AG Elbinger Straße 7 60487 Frankfurt am Main Germany Tel.: +49 (0)6102-816-0 Fax: +49 (0)6102-816-100 E-Mail: info@matrix42.com Web: http://www.matrix42.com/ Author: Matrix42 Client Management - 9 -