Using SSL client certificate authentication with QualysGuard API v1 and v2

Document created by Eric Perraudeau Employee on Jan 16, 2012Last modified by Jeff Leggett on Mar 30, 2016
Version 4Show Document
  • View in full screen mode

UPDATE: In spite of what this DOC  says, we do not support certificate auth for API endpoints.  That only works because the certs.qualys.com and qualysapi.qualys.com on POD1 line up properly for the cert to work.  It won't work for customers on POD2/EU or elsewhere, and it's not truly certificate auth even then, it's more like 2 factor, as you still have to use basic auth or session auth even if you specify the cert.

 

If your QualysGuard account is configured with SSL certificates for two factor authentication, you also need a certificate to make call to the API v1 and API v2.

Here is an example using "curl" that shows you how to use the certificates in a PEM format.

 

API v1:

 

$ curl --cert ./cert.pem:my_passphrase -u "user:pass" "https://certs.qualysguard.qualys.com/msp/about.php"

 

 

API v2:

$ curl --cert ./cert.pem:my_passphrase -u "user:pass" -H "X-Requested-With:curl"  "https://certs.qualysguard.qualys.com/api/2.0/fo/scan/?action=list"

 

Important comments:

  1. The option --cert is used to indicate to curl where the certificate is located. In this example the file "cert.pem" is located in the current folder and the prefix "./" must be used
  2. Also, the certicate "cert.pem" must contain a private key protected with the pass phrase "my_passphrase" passed to curl as shown in the example
  3. -u "user:pass" is used to do basic authentication using the QualysGuard user names "user" and the password "pass"
  4. -H "X-Requested-With:curl" is the special HTTP header parameter required for any QualysGuard API v2 call.
  5. the URL for client certificate authentication is "https://certs.qualysguard.qualys.com"

 

Your certificate might be provided in a PKCS12 format (.p12 or .pfx file extension). Please use to following command to create a .pem certificate file:

 

$ openssl pkcs12 -in cert.p12 -out cert.pem -clcerts
Enter Import Password: ********          ## enter the password used to protect the private key)
MAC verified OK
Enter PEM pass phrase: **********        ## enter your pass phrase to protect the private key in the new cert.pem file
Verifying - Enter PEM pass phrase: **********

 

YOU MUST PROVIDE A PASS PHRASE AS SHOWN IN THE TWO LAST LINES. If you don't provide a passphrase, you will get the following curl error message:

curl: (58) unable to set private key file: 'cert.pem' type PEM
1 person found this helpful

Attachments

    Outcomes