This article is to assist Gateway Administrators with the creation of a new client certificate when their client certificate is expired or expiring.
You must be listed as a licensee admin to perform the steps outlined in this article. Please submit a ticket if you need to be added as a licensee admin.
In this Article:
- FAQs
- Logging into Gateway
- Creating a CSR and private key using OpenSSL:
- Further notes:
- Removing password from private key:
- Combining Certificate and Private key into pfx file.
- Note for Windows Users.
FAQs
What is a certificate signing request?
In Public Key Infrastructure (PKI) systems, a Certificate Signing Request (also CSR or certification request) is a message sent from an applicant to a Certificate Authority in order to apply for a digital identity certificate.
If a State requires "Client Certificate Authentication" AKA 2-way SSL then web service requests will require a Client Certificate signed against Gateway's Certificate Authority.
Gateway contains a form that allows a certificate signing request to be signed against the Gateway Certificate Authority for this environment. The resulting client certificate can be used to make requests to the 2-way SSL enabled URL for this environment.
How do I create a certificate signing request?
There are several ways to create a certificate signing request. The most industry accepted tool is OpenSSL. That is the tool we shall demonstrate in the example below. You can find more information on OpenSSL including download instructions on their web site click here.
Does my licensee need to do Client Certificate Authentication?
To make in-state requests the following PDMPs require client certificate authentication: PA MA
If your licensee will be making requests then you should use Client Certificate Authentication.
What is the 2-way SSL enabled URL for this environment?
If 2-way SSL is required you must make a request with a client certificate to the 2-way SSL enabled endpoint. This is a different endpoint then the one normally used to make requests. This endpoint is mutualauth.pmpgateway.net
Can I use the 2-way SSL enabled URL for all of my requests even if they do not require 2-way SSL?
Yes.
Logging into Gateway
Step 1: Navigate to pmpgateway.net and login with your username and password.
Step 2: navigate to the Licensees page.
Step 3: Click on the gear icon next to the licensee name.
Step 4: Click on "Client Certificates"
Step 5: Click on "New Certificate Signing Request"
You will find these same instructions that you see below in the new certificate signing request page.
Creating a CSR and private key using OpenSSL:
Step 1: Create the private key:
The command openssl genrsa -des3 -out client.key 4096 creates a new private in local file called client.key. Note: For windows the exe file extension will need to be added.
$ openssl genrsa -des3 -out client.key 4096
Generating RSA private key, 4096 bit long modulus
..........++
.++
e is 65537 (0x10001)
Enter pass phrase for client.key:
Verifying - Enter pass phrase for client.key:
After the above command is completed. There will be a new file called 'client.key' that will contain the private key. Keep this a secret. This will be needed when you make requests with the certificate.
Step 2: Create the CSR:
The command openssl req -new -key client.key -out client.csr uses the private key created in step 1 to generate a certificate signing request in the file client.csr
During this process you will be prompted to input information. Please use a State, Locality, Organization Name and Organizational Unit name that is related to this licensee's account.
Please select a common name related to the licensee name and supply an email address for contact with your organization.
$ openssl req -new -key client.key -out client.csr
Enter pass phrase for client.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:KY
Locality Name (eg, city) []:Louisville
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Appriss, Inc
Organizational Unit Name (eg, section) []:Healthcare
Common Name (e.g. server FQDN or YOUR name) []:Appriss Test Account
Email Address []:pmpsupport@hbu.co
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
The above command produces a file named 'client.csr'. This is the certificate signing request.
The certificate signing request file will have contents that start with "-----BEGIN CERTIFICATE REQUEST-----" and end with "-----END CERTIFICATE REQUEST-----"
It might look something like this but a little longer:
-----BEGIN CERTIFICATE REQUEST----- MIIBvjCCAScCAQAwfjELMAkGA1UEBhMCTVMxDTALBgNVBAgTBE1BU1MxDTALBgNV BAcTBE1BU1MxDTALBgNVBAoTBE1BU1MxDTALBgNVBAsTBE1BU1MxFDASBgNVBAMT C01BU1MtQ0xJRU5UMR0wGwYJKoZIhvcNAQkBFg5tYXNzQGVtYWlsLmNvbTCBnzAN BgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAtdX9iol7RNG+NugRaTOdhFgsEkKwzhSc grBgZQCD5O0HvmJTfU6Kc/YoX+Y39Ycsl5f1kavCQINqoUzqvwKp4swIB0hdq5aQ b8zkT0FAy10HvYU2ojj1h78EbsydS3qxKAZZlq3/O25AJmWS4W8Ld8KsKCAy7C3/ 84lfm62ivi0CAwEAAaAAMA0GCSqGSIb3DQEBBQUAA4GBACLWRIPMuxsG7pkCoA8V mWiHQJ3rStrzW7QIVjO4DQAInYhwhBEBf9Q9aZ+pX8scKRLCHLOsBY8MWUszgjH6 Z7hPVtPJ/clYhh3Q4DWXelCayNUoIh7GTDTjwXn8Mv6mz6+o2OwTc84PnR1XQcER ALIlnEIq4mCCIYCvN975zrHQ -----END CERTIFICATE REQUEST-----
The contents of the certificate signing request file of 'client.csr' is what you must copy into the textarea above marked 'Certificate Signing Request'. Then click the button to have Gateway generate a certificate that will be available for download. The combination of this 'certificate' and the 'private key' created in Step 1 will be what is required to do requests via 2-way SSL.
Further notes:
Removing password from private key:
Once you have a client certificate it might not be practical to enter the password associated with the private key in an automated system.
If this is the case the password can easily be removed from the private key via the following commands.
$ openssl rsa -in client.key -out client-no-password.key
This would generate a new file name 'client-no-password.key' that will contain the private key without the password protection.
Combining Certificate and Private key into pfx file.
Some tools might require the certificate and private key to be combined into a single file to be processed. A common format for this is a Personal Information Exchange file or pfx
OpenSSL can be used to create a pfx from the certificate and the private key.
$ openssl pkcs12 -inkey client.key -in GatewayClientAuth.crt -export -out certificate.pfx
In the above example we are combining the certificate located in the file GatewayClientAuth.crt and the private key contained in the file client.key into a new file called certificate.pfx
Note for Windows Users.
In windows the openssl commands presented should work. However keep in mind you may need to convert openssl to OpenSSL.exe as that is actual file name of the executable. Also be mindful that you are in the same directory as the OpenSSL.exe excutable or that it present in your path.
C:\>OpenSSL.exe genrsa -des3 -out client.key 4096 Generating RSA private key, 4096 bit long modulus ..............................................++ ...........++ unable to write 'random state' e is 65537 (0x10001) Enter pass phrase for client.key: Verifying - Enter pass phrase for client.key: