Instructions for Installing Certificates for phiMail Integrated into PHP/Ruby/Node.js Frameworks

The following knowledge base note contains instructions for installing your (1) client authentication certificate, (2) server certificate, and (3) how to verify that your private key has the correct password and verify the TLS handshake.

(1) Organizations using client certificate-based authentication will first request and then follow the documentation for submitting CSRs to us and obtaining your client authentication certificate. Once you have the certificate, use the instructions in your framework-specific certificate documentation and additional instructions below to set up and then test your sandbox certificate in the test environment, then request, obtain, and set up and use your production certificate in the production environment.

The production server and port variables are set to the values below:

   $phiMailServer = "{server_name}"; // replace {server_name} with your assigned HISP server. Please contact support@emrdirect.com if you cannot locate your assigned HISP server.
   $phiMailPort = {port}; // replace {port} with your assigned port number

In the sandbox, username and password for authentication to the phiMail server are:

   $phiMailUser = "something@test.directproject.net"; // as assigned in your Developer account
   $phiMailPass = "{password}"; // as assigned in your Developer account

Refer to phiMail sample code for an example of how to invoke the use of the client authentication certificate by your system. Note that if you request certificate-only authentication in production, your sandbox account will be configured the same way and will not require a password. Refer to your "welcome" email message from when your first Direct certificate was issued for the appropriate production user and password or contact support@emrdirect.com if you need this information to be re-sent.

You will need to append the three PEM files in the ZIP file, which we will send to you, to the end of the key file you generated when you made the CSR. The order of these PEM segments is important –

1. The production client authentication certificate you received from EMR Direct
2. The phiCertDirectDeviceCA intermediate certificate
3. The phiCertDirectRootCA Certificate

Next, check that parameters passed to setClientCertificate(..) function contain the correct path to your complete key file and the pass phrase for the key file. Also ensure that the application has read access to the key file.

(2) In addition, make sure that the parameter passed to the setServerCertificate(..) function contains the correct path to the EMRDirectTestCA.pem file. If the server certificate has the .crt extension, you will need to convert it to a .pem extension using the following command:

   $ openssl x509 -in phiCertDirectRootCA.crt -inform der -out phiCertDirectRootCA.pem

The calls to setClientCertificate(..) and setServerCertificate(..) should occur before you create a new instance of the PhiMailConnector class.

(3) To confirm that you have the right passphrase for the key file, you can check at command line with:

   $ openssl rsa -check -in /path/to/your/sandboxClient.key

You can also manually test the handshake for mutual TLS when using a client authentication certificate by using this command:

For Sandbox:

   $ openssl s_client -cert /path/to/your/sandboxClient.key -CAfile /path/to/EMRDirectTestCA.pem -connect sandbox.phimail-dev.com:32541

For Production - replace {server_name:port} with your assigned production server and port number:

   $ openssl s_client -cert /path/to/your/yourProductionKeyfile.pem -CAfile /path/to/phiCertDirectRootCA.pem -connect {server_name:port}


Did this article answer your question? If not, please contact us.