Understanding certificate validation and testing

Overview of the two-phase approach

The certificate upload process consists of two distinct phases designed to protect your system from invalid or incompatible certificates:

1. Validation Phase: Quick verification (1-3 seconds) that the certificate meets format and encryption requirements
2. Testing Phase: Optional functional test (up to 120 seconds) that verifies the certificate works correctly with the web server

This two-phase approach ensures that only valid certificates are applied and gives you the option to test before committing to the change. If either phase fails, your current certificate configuration remains unchanged.

Phase 1: Certificate validation

The validation phase occurs automatically and immediately after you select a certificate file and click OK or Apply. This phase is fast, typically completing in 1-3 seconds.

What the validation phase checks:

• Certificate file format (must be PEM format)
• Certificate structure (must contain both certificate and private key)
• Encryption type (must use AES encryption; DES is not supported)
• Signature algorithm (must use SHA256; SHA1 and MD5 are not allowed)
• Key format (RSA keys are recommended)
• Password correctness (if the private key is encrypted)

Validation behavior:

• The main certificate upload dialog remains open during validation
• If validation succeeds, you proceed to the testing phase
• If validation fails, an error message displays the specific issue
• No changes are applied to the web server if validation fails
• You can retry with a corrected certificate or password without closing the dialog

Phase 2: Certificate testing (optional)

After successful validation, a confirmation dialog appears asking if you want to test the certificate with the web server. This phase is optional but strongly recommended.

What the testing phase does:

• Temporarily applies the new certificate to the web server
• Restarts the web server to load the new certificate
• Verifies that the web server starts successfully with the new certificate
• Confirms that HTTPS connections work correctly

Testing phase timing:

• The test can take up to 120 seconds to complete
• A progress dialog displays a countdown timer showing remaining time
• The progress dialog cannot be dismissed during testing
• The countdown helps you track the test progress

Testing phase outcomes:

If you select Yes to test:

• Test succeeds: The new certificate is permanently applied, SSL is enabled, and you are logged out. Reconnect using HTTPS with the new certificate.
• Test fails: The system automatically rolls back to your previous certificate configuration. No changes are applied. Your current certificate remains active and you stay logged in.

If you select No to skip testing:

• The new certificate is not applied
• No changes are made to the web server
• The temporary certificate file is automatically cleaned up
• Your current certificate configuration remains unchanged

Error handling and troubleshooting

The two-phase approach includes comprehensive error handling to protect your system:

Validation failures

Common validation errors and solutions:

• Invalid certificate format: Ensure the file is in PEM format and contains both the certificate and private key
• Incorrect password: Verify the password for the encrypted private key and try again
• Unsupported encryption: Certificates must use AES encryption (DES is not supported)
• Invalid signature algorithm: Use SHA256 signature algorithm (SHA1 and MD5 are not allowed)
• Missing certificate components: Ensure the PEM file contains both the certificate and the private key

When validation fails, the error message indicates the specific problem. The main dialog remains open so you can correct the issue and retry immediately.

Testing failures

Testing can fail for several reasons:

• Web server startup failure: The certificate may be incompatible with the configuration
• Connection timeout: The web server may take longer than expected to restart
• Certificate compatibility issues: The certificate may not work with the specific web server version
• Network interruption: Connection issues during the restart

When testing fails, the system automatically performs a rollback:

1. The new certificate is removed
2. The previous certificate is restored
3. The web server is restarted with the previous configuration
4. You remain logged in with your current session

Attention: If the test fails due to connection issues during the restart, you may temporarily lose connection to the management GUI. Wait for the automatic rollback to complete (up to 120 seconds), then reconnect. Your previous certificate will be active.

Automatic rollback behavior

The automatic rollback feature ensures your system remains operational even if testing fails:

• Rollback is automatic and requires no user intervention
• The previous certificate is always preserved during testing
• Rollback completes within the 120-second testing window
• After rollback, your system is in the same state as before the upload attempt
• You can retry with a different certificate after rollback completes

Remember: The automatic rollback feature only applies during the testing phase. If you skip testing and later manually enable SSL with an untested certificate, automatic rollback is not available.

Best practices

• Always test certificates: Use the testing phase to verify certificate compatibility before permanent application
• Verify certificate requirements: Ensure your certificate meets all format and encryption requirements before uploading
• Test during maintenance windows: Schedule certificate updates during planned maintenance to minimize impact
• Keep passwords secure: Store certificate passwords securely and have them ready before starting the upload process
• Monitor the countdown: Watch the progress dialog countdown to track testing progress
• Wait for completion: Do not attempt to close the browser or navigate away during the testing phase
• Document your certificates: Keep records of which certificates are installed and when they expire