PSM:EV Testing Easy Version: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
m (added note that the tool can be run locally for debugging)
 
(62 intermediate revisions by 4 users not shown)
Line 1: Line 1:
This page is for [[CA:FAQ#What_are_CAs.3F | Certificate Authorities (CAs)]] who request to have a root certificate enabled for [https://www.cabforum.org/certificates.html Extended Validation (EV) treatment], and need to test that their CA hierarchy is ready for EV treatment.
This page is for [[CA:FAQ#What_are_CAs.3F | Certificate Authorities (CAs)]] who request to have a root certificate enabled for [https://cabforum.org/extended-validation Extended Validation (EV) treatment], and need to test that their CA hierarchy is ready for EV treatment.


To request that your root certificate be included in NSS and enabled for EV treatment, start with the [http://www.mozilla.org/projects/security/certs/policy/ Mozilla CA Certificate Policy] and the [[CA:How_to_apply | How to Apply]] guidelines.
Before requesting EV treatment, CAs should understand how [[CA/EV_Processing_for_CAs | Firefox processes EV certificates]] and ensure that they are using the CA/Browser Forum EV OID (2.23.140.1.1), which Mozilla requires.
 
To request that your root certificate be included in [https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS NSS] and [https://hg.mozilla.org/mozilla-central/file/tip/security/certverifier/ExtendedValidation.cpp enabled for EV treatment], see [[CA/Application_Process|Mozilla's application process]].


This page explains how you can test that your certificates and OCSP infrastructure are working correctly according to the expectations of Mozilla, Firefox, and the NSS library; and conforms to the SSL protocol specifications (as interpreted by Mozilla/NSS software.)
This page explains how you can test that your certificates and OCSP infrastructure are working correctly according to the expectations of Mozilla, Firefox, and the NSS library; and conforms to the SSL protocol specifications (as interpreted by Mozilla/NSS software.)


= Overview =
= EV-Readiness Check =
 
To test your CA hierarchy to see if it is ready to request EV treatment:
To perform this test you will:
# Browse to  
 
#* [https://github.com/mozilla/CCADB-Tools/tree/master/evReadiness NEW]: https://evready-dot-ccadb-231121.appspot.com/evready
* Use a debug version of Firefox that has been modified to allow for EV testing
#* [https://github.com/mozilla/tls-observatory OLD]: https://tls-observatory.services.mozilla.com/static/ev-checker.html
* Set an environment variable that is effective when you execute Firefox
# Enter the URL to the test website for the EV certificate
* Import your own CA root certificate into the Firefox browser
#* Example: https://observatory.mozilla.org
* Find a directory on your system that contains the Firefox browser's configuration files
# Enter the EV Policy OID
* Prepare a special configuration file that instructs the browser to treat your certificates as EV verified
#* Example: 2.23.140.1.1
* Prepare a test server that uses a matching certificate and sends all required intermediate certificates
# Enter the PEM data for the root certificate, or use the "Browse..." button to select the PEM file for the root certificate (ending of file may be .pem or .cert)
* Make sure that your OCSP server is configured correctly, in particular, the signing certificate used by your OCSP server is conforming to specifications
#* Begin with: -----BEGIN CERTIFICATE-----
* Test the above until you get a successful test result
#* End with: -----END CERTIFICATE-----
 
#* [https://crt.sh/?d=853428 Example PEM Data] - open with a plain text editor like TextEdit
= Details =
#* [http://ccadb.org/cas/fields#pem-data Help with getting PEM]
 
# Click on "Submit"
== Download Debug Version of Firefox==
 
To download a debug version of Firefox:
# Browse to ftp://ftp.mozilla.org/pub/firefox/tinderbox-builds/
# Scroll down to mozilla-release-<platform>-debug and select the folder that matches the platform you are working on. Make sure you select a folder whose name ends in "debug".
# Download any of the recent builds in the list.
#* [https://support.mozilla.org/en-US/kb/install-firefox-linux Linux Platform] - use the .tar.bz2 file.
#* [https://support.mozilla.org/en-US/kb/install-firefox-mac Mac Platofrm] - use the .dmg file.
#* [https://support.mozilla.org/en-US/kb/install-firefox-windows Windows Platform] - use the installer.exe file.
# After downloading, extract and run this debug browser, which will be called FirefoxNightlyDebug.
 
== Environment variable ==
You must set the following environment variable. It must be effective when the browser software runs:
 
ENABLE_TEST_EV_ROOTS_FILE=1  
 
== Import your root CA ==
You should be able to use the browser's menus and preferences to find the certificate manager, import it as a new Certificate Authority, and set the necessary trust flags (include trust for web sites).
 
== Profile / Configuration directory ==
You will use public Internet resources to learn about the location of Firefox configuration files on your test computer.
(e.g. on a GNU/Linux system this might be in /home/$USER/.mozilla/firefox/*default, on Mac OS X ~/Library/Application Support/Firefox/Profiles/*.default)
The directory contains files named bookmarks.html and prefs.js, this information might help you in locating the correct directory.
 
* [http://support.mozilla.org/en-US/kb/profiles-where-firefox-stores-user-data Profiles - Where Firefox stores your bookmarks, passwords and other user data]
 
Note: on Mac OS X Mountain Lion the Library folder is hidden. To find it, go into Finder, click on the "Go" pull-down menu while holding the Option key and select "Library." From Terminal the following command will make the hidden Library folder visible: chflags nohidden ~/Library. To hide the Library folder again type the following command: chflags hidden ~/Library
 
== Enable your root for EV ==
Inside the directory you have identified in the previous step, you will create a new ASCII test file, with filename '''test_ev_roots.txt'''
You will create appropriate lines that will enable your root certificate for EV.
Technical information can be found in page [[PSM:EV_Testing]]
 
The tricky technical part is producing an ASCII-encoded representation of the DER encoding of your certificate issuer name and its serial number.


We are willing to help you produce those technical representation.
== Success ==
If you have started the formal process to request being added to the Mozilla root store, and have attached your root to a bugzilla bug, you may ask us to produce it for you.
A successful result says: "Status: Success!"
Any other text indicates a failure.


== Testing ==
== Test Failure? ==
Once you have the above preparation steps done, open the "Minefield" test browser and browse to the web page of your test server.
If you have done everything correctly, and your OCSP infrastructure meets the expectations, you will see the green EV identity bar.


Attach a screen shot to the bug that shows the green EV identity bar for your web page in the "Minefield" test browser.
The purpose of this test is to make sure you have set up EV according to the [https://www.cabforum.org/documents.html EV Guidelines], so make sure you have not taken short-cuts like issuing the test cert directly from the root.
* If you get ''Error: Could not initiate scan'', then wait for 3 minutes before trying again.
* If you get ''SEC_ERROR_BAD_DATA'', then the program does not like the format of the data you entered. For instance, if you have extra spaces or characters before or after the TLS Server URL, EV Policy OID, or in the Root Certificate PEM.
* The EV test only uses the root certificate it is given. So, if you are using an intermediate certificate that has been cross-signed with another root certificate, you may see different results when browsing to the site in Firefox, as opposed to the results provided by the EV Test.
* OCSP must work without error for the intermediate certificates.
* The EV Policy OID in the end-entity and intermediate certificates must match the EV Policy OID.
** SEC_ERROR_POLICY_VALIDATION_FAILED error may mean that the intermediate certificate being sent by the server doesn't have a certificate policies extension
** SEC_ERROR_EXTENSION_NOT_FOUND may mean that the certificate being sent by the server doesn't contain the specified policy OID.
* If the test website cannot be reached by the server hosting the tool, check to see if you have a firewall preventing access.
* Still failing?  Try testing with https://certificate.revocationcheck.com/ because frequently resolving the errors listed on that page will resolve problems with EV testing.


=== Not Getting EV Treatment? ===
== About the Testing Tool ==
The code for the Testing Tool is here: https://github.com/mozilla/CCADB-Tools/tree/master/evReady


* The purpose of this test is to make sure you have set up EV according to the [https://www.cabforum.org/documents.html EV Guidelines], so make sure you have not taken short-cuts like issuing the test cert directly from the root.  
The Testing Tool...
* OCSP must work without error for the intermediate certificates. A failed OCSP response will result in EV treatment not being given. For more information see: https://wiki.mozilla.org/CA:EV_Revocation_Checking#Requirements
* Can be run on your local computer for debugging, see https://github.com/mozilla/CCADB-Tools/blob/master/evReady/README.md
* All of the characters have to be capitalized in the SHA1 Fingerprint in the test_ev_roots.txt file.
* Runs a program on a remote computer rather than the user's browser, so it should work with any browser/version.
* The EV Policy OID in the end-entity and intermediate certificates must match the 2_readable_oid field in the test_ev_roots.txt file. (Note: the intermediate cert can use the anyPolicy oid rather than the EV policy oid.)
* Does not interact with the user's profile, so the user does not need to import the root certificate in order to run the tool. The web server must serve up the intermediate cert(s) along with the end-entity cert.
* General tips
** Make sure you are using the [[PSM:EV_Testing_Easy_Version#Test_version | Minefield test browser.]]
** Make sure the [[PSM:EV_Testing_Easy_Version#Environment_variable | ENABLE_TEST_EV_ROOTS_FILE environment variable is correctly set.]]
** Make sure your [[PSM:EV_Testing_Easy_Version#Enable_your_root_for_EV | test_ev_roots.txt file is correct and matches the information in your cert chain.]]

Latest revision as of 16:53, 9 November 2023

This page is for Certificate Authorities (CAs) who request to have a root certificate enabled for Extended Validation (EV) treatment, and need to test that their CA hierarchy is ready for EV treatment.

Before requesting EV treatment, CAs should understand how Firefox processes EV certificates and ensure that they are using the CA/Browser Forum EV OID (2.23.140.1.1), which Mozilla requires.

To request that your root certificate be included in NSS and enabled for EV treatment, see Mozilla's application process.

This page explains how you can test that your certificates and OCSP infrastructure are working correctly according to the expectations of Mozilla, Firefox, and the NSS library; and conforms to the SSL protocol specifications (as interpreted by Mozilla/NSS software.)

EV-Readiness Check

To test your CA hierarchy to see if it is ready to request EV treatment:

  1. Browse to
  2. Enter the URL to the test website for the EV certificate
  3. Enter the EV Policy OID
    • Example: 2.23.140.1.1
  4. Enter the PEM data for the root certificate, or use the "Browse..." button to select the PEM file for the root certificate (ending of file may be .pem or .cert)
  5. Click on "Submit"

Success

A successful result says: "Status: Success!" Any other text indicates a failure.

Test Failure?

The purpose of this test is to make sure you have set up EV according to the EV Guidelines, so make sure you have not taken short-cuts like issuing the test cert directly from the root.

  • If you get Error: Could not initiate scan, then wait for 3 minutes before trying again.
  • If you get SEC_ERROR_BAD_DATA, then the program does not like the format of the data you entered. For instance, if you have extra spaces or characters before or after the TLS Server URL, EV Policy OID, or in the Root Certificate PEM.
  • The EV test only uses the root certificate it is given. So, if you are using an intermediate certificate that has been cross-signed with another root certificate, you may see different results when browsing to the site in Firefox, as opposed to the results provided by the EV Test.
  • OCSP must work without error for the intermediate certificates.
  • The EV Policy OID in the end-entity and intermediate certificates must match the EV Policy OID.
    • SEC_ERROR_POLICY_VALIDATION_FAILED error may mean that the intermediate certificate being sent by the server doesn't have a certificate policies extension
    • SEC_ERROR_EXTENSION_NOT_FOUND may mean that the certificate being sent by the server doesn't contain the specified policy OID.
  • If the test website cannot be reached by the server hosting the tool, check to see if you have a firewall preventing access.
  • Still failing? Try testing with https://certificate.revocationcheck.com/ because frequently resolving the errors listed on that page will resolve problems with EV testing.

About the Testing Tool

The code for the Testing Tool is here: https://github.com/mozilla/CCADB-Tools/tree/master/evReady

The Testing Tool...

  • Can be run on your local computer for debugging, see https://github.com/mozilla/CCADB-Tools/blob/master/evReady/README.md
  • Runs a program on a remote computer rather than the user's browser, so it should work with any browser/version.
  • Does not interact with the user's profile, so the user does not need to import the root certificate in order to run the tool. The web server must serve up the intermediate cert(s) along with the end-entity cert.
Retrieved from "https://wiki.mozilla.org/index.php?title=PSM:EV_Testing_Easy_Version&oldid=1248901"