SSL Pinning
SSL Pinning appears only in Advanced Mode: Global Settings.
The calls to list, save, and delete domain certificates can be found under Control Center > Certificates in the HYPR Passwordless API collection.
To Synchronize SSL PINs across HYPR for a machine, see the API call GET /rp/wsapi/settings.
SSL Pinning enhances the security of the overall HYPR ecosystem and prevents MitM (Man-in-the-Middle) attacks. Before any HTTPS communication occurs, the client checks that the server is trusted by the client. After SSL Pinning is enabled, all subsequent registration, authentication, and de-registration requests are checked for a valid certificate. The client will check the server certificate and will make sure the client certificate hash matches the hash of the server certificate before proceeding with any HTTPS requests.
Two different certificates are required for SSL Pinning to work. Upload the certificates in the SSL Pinning section, located in the global Settings of the HYPR Control Center.
The Control Center supports certificates in the .PEM format in base64 ASCII. Only .pem, .crt, .cer file types can be uploaded to the Control Center.
The iOS app requires two SSL certificates to be pinned. Be sure to upload two certificates.
Enabling SSL Pinning
-
Ensure your two certificate files are available to find from the server.
-
Launch Control Center as an admin and open the Global Settings menu, then SSL Pinning.
-
Toggle SSL Pinning On.
-
Upload SSL Pinning certificates.
-
Uploaded certificates display below the Add Certificates button.
SSL Pinning Properties and Removal
The SSL Pinning properties are described here.
| Field | Description |
|---|---|
| Certificate | The file name of the certificate which is being uploaded. |
| Valid From | The start date of the certificate. |
| Valid To | The expiration date of the certificate. |
| Order | Primary | Alternate An admin can choose to make a certificate Primary while uploading the second certificate. The Primary will be one used for pinning and Alternate can be used in place of Primary when the Primary expires. |
| Status | Active | Expired The current state of the certificate. |
| Actions | Click the trash can icon to remove certificates. Deletion will not revoke the certificates. |
The HYPR Passwordless client download's .json file will now use a pinningHash key with a value of the actual hash.
Disabling SSL Pinning
An admin can disable SSL Pinning using the toggle button. A confirmation dialog will appear; click Disable to confirm.
Once you click Disable, certificates will be removed and SSL Pinning will be disabled. This cannot be undone. To use SSL Pinning again, you must upload certificates again.
Certificate Expiration
Currently, administrators can upload two certificates. If the primary certificate expires, Administrators must take one of the following steps:
- Admins can make the secondary as the primary for SSL Pinning OR
- Replace the primary with a new valid certificate
Always maintain at least one active certificate in Control Center.