Configuring certificate handshake security feature

Learn to configure the enhanced certificate handshake security feature on CRM.launcher.

System administrators can configure the enhanced certificate handshake security feature supported by Aurea.CRM to ensure secure communication between CRM.Web and CRM.Launcher. This ensures that only CRM.web signed commands initiated and authorized by both the system administrator and user can be executed by CRM.launcher.

To configure the enhanced certificate handshake security feature, perform the following steps:

Ensure you have administrative access to the following:
- to Aurea CRM.web deployed on a target host
- to all the client hosts deploying CRM.launcher
Ensure you have a certificate for both signing and encryption (with key exchange to establish public and private keys between the CRM.launcher host and the CRM.Web host).
- You require a certificate container (folder) on the CRM.Web host for the private key.
- Public key for deployment on the clients hosting CRM.launcher.
- Configure the CRM.Web and CRM.launcher host machines to synchronize time online, between varying time zones. Local NTP servers may be used.
Cetificates can be obtained by one of the following methods:
- Purchase a signed certificate from a certification authority, such as VeriSign, Inc.
- Prepare your own self signed certificates. This procedure uses a self signed certificate. To create your own self signed certificate in a windows powershell, run the New-SelfSignedCertificate command with the following options:
```
New-SelfSignedCertificate -FriendlyName "CRM Launcher Handshake Certificate" -Type Custom
      -Subject "CN=CRM Launcher" -KeySpec KeyExchange -KeyUsage DigitalSignature,DataEncipherment
      -KeyAlgorithm RSA -KeyLength 2048 -HashAlgorithm "SHA256" -CertStoreLocation
      "Cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(99) -Provider "Microsoft Enhanced RSA and
      AES Cryptographic Provider"
```
  Note: : Run this command on the CRM.launcher host and change the value of the CertStoreLocation option to the current user’s personal certificate container folder. You can also customize the other options according to your needs. For a synopsis of the command, see New-SelfSignedCertificate.
  This command generates a certificate valid for 99 years from current date and place the certificate into the Current User’s personal certificate storage. You can then export both private and public keys from it to secure the CRM Launcher communication.
  Note down the certificate thumbprint as it is required for configuring CRM.Web and CRM.launcher. For more information, see How to: Retrieve the Thumbprint of a Certificate.
Deploy the private key to the CRM.Web host and the public key to the CRM.launcher host machines.
The private key must be deployed to the TrustedPeople of LocalMachine certificate secure windows store of the machine hosting CRM.Web. To allow the windows processes running the CRM application pool access to the private key perfom the configurations described in the following article: How to: Make X.509 Certificates Accessible to WCF. For example, you can use the following windows batch command to grant IIS_USRS group read access to stored private certificate:
```
for /F %f in ('FindPrivateKey.exe TrustedPeople LocalMachine -t "CEERTIFICATE THUMB-PRINT
     HERE" -a') do icacls %f /grant BUILTIN\IIS_IUSRS:R
```
Similarly, the public key must be deployed to TrustedPeople of LocalMachine certificate windows store of client machines hosting CRM.launcher.

Note: The FindPrivateKey.exe tool helps you to find the location and name of the private key file associated with a specific X.509 certificate in the certificate store. This program needs to be compiled from the sample source code provided as part of the Windows Communication Foundation framework.
Configure CRM.Web and CRM.launcher with the certificate thumbprint values.
1. To configure CRM.Web, add the thumbprint to the web.config file as shown below.
```
<appSettings>...<add key="AuthenticationCertificateThumbprint"
      value="CERTIFICATE THUMBPRINT HERE" /></appSettings>   
```
2. To configure the CRM.launcher, add the certificate thumbprint to the update.Launcher.exe.config and update.Launcher.NamedPipeServer.exe.config(if CRM.Launcher is used in a shared mode service) files as shown below:
```
<update.net>       
      <update.launcher>              
      ...          
      <AuthenticationCertificateThumbprint>CERTIFICATE THUMBPRINT
      HERE</AuthenticationCertificateThumbprint>
      </update.launcher>
      </update.net> 
```
  Note: The Thumbprint must be entered using uppercase letters.
Restart the CRM.launcher client manually or the CRM.launcher service if you have installed it as a service.
CRM.launcher now establishes secure certificate handshake negotiation and allows user actions without the use of the authorization request popup dialog.
Note: If for some reason secure handshake negotiation is not possible, unauthorized user actions is denied and no popus are presented either.