NSS:Revocation API Proposals

From MozillaWiki
Revision as of 19:05, 7 March 2008 by Nelsonb (talk | contribs) (Put page in NSS category)
Jump to navigation Jump to search

Proposal 5

Revocation checking strategy

The NSS engine is always allowed to look at any cached information that might indicate "is revoked". When designing the API for verification functions, no parameter will be available to change this behavior.

In other words

  • if a crl is locally available, even if the crl is no longer fresh and/or
  • if an ocsp response is locally available, even if the response is no longer fresh then the engine may look at it and abort on a known revoked status.

(Note, one must carefully distinguish between "cached valid ocsp response or valid crl available" and "the cache contains information about a very recent failure". In soft failure mode (param 4), "cached recent failure" might mean we will skip testing. In hard failure mode, it's necessary to allow a retry (except maybe a very short grace period to repetitive network hits). )


Parameter 1:

Which actions are allowed that might hit the network?

  • try to obtain fresh OCSP response using AIA (use cached OCSP response if still considered fresh)
  • try to obtain fresh CRL using CRLDP (used locally avaialble CRL if still considered fresh)
  • try either mechanism, stop as soon as fresh data has been found
bits: 000000xx

CERT_REV_DO_NOT_DOWNLOAD_OCSP         0
CERT_REV_MAY_DOWNLOAD_OCSP            0x01

CERT_REV_DO_NOT_DOWNLOAD_CRL          0
CERT_REV_MAY_DOWNLOAD_CRL             0x02

Set both bits for specifying "try either".

The first attempt to obtain fresh information will be sufficient. If the first attempt has fresh good information, we'll never attempt to download using the second mechanism.


Parameter 2:

Does the caller have a preference which network actions should be preferred (tried first)?

(If only a single network action is allowed, then specifying this parameter does not make sense. The implementation is allowed to abort with error "invalid parameters" or it might simply ignore this parameter.)

  • try ocsp network download first, then try other mechanism(s)
  • try crl network download first, then try other mechanism(s)

In addition, this parameter also defines which locally cached information should be checked first. If a preference for CRL is signalled, then the implementation shall begin by looking for a locally avaialble fresh CRL, and if fresh, and if not revoked, no further tests will be done. 

bits: 00000x00

CERT_REV_PREFER_DOWNLOAD_OCSP        0
CERT_REV_PREFER_DOWNLOAD_CRL         0x04

Parameter 3:

When verifying the chain for a cert, which parts of the chain may trigger downloading of revocation information? By default, network activity for each cert in the chain is allowed. Use this parameter to limit revocation network activity to the leaf cert. 

bits: 0000x000

CERT_REV_DOWNLOAD_ALL_CERTS              0
CERT_REV_DOWNLOAD_LEAF_ONLY              0x08

Parameter 4:

By default, all performed tests are allowed to fail without being able to obtain a fresh result (fail soft). Failure reasons for obtaining a result can be network errors, invalid signatures on response, etc. By default, even if all network tests failed, the verification succeeeds.

This parameter is used to change that behavior to mean: For at least one requested mechanism it must be possible to find fresh information, either locally available, or obtained from the network. In other words, if it's impossible to find or download good fresh information, the verification fails (fail hard).

This is a three state parameter, in order to specify soft/hard failure independently for the leaf cert or the full chain.

  • fail soft on both leaf and intermediates
  • fail hard on leaf, fail soft on intermediates
  • fail hard on both leaf and intermediates

(the 4th state "fail soft on leaf, fail hard on intermediate" will not get implemented, the implementation should return with "invalid args" when requested by a caller) 

bits: 00xx0000

CERT_REV_DOWNLOAD_LEAF_FAIL_SOFT         0
CERT_REV_DOWNLOAD_CHAIN_FAIL_SOFT        0

CERT_REV_DOWNLOAD_LEAF_FAIL_HARD         0x10
CERT_REV_DOWNLOAD_CHAIN_FAIL_HARD        0x20

Parameter 5:

Even if a test mechanism is allowed to hit the network, it may not be possible to perform the action, because it's necessary to know the source of revocation information. For CRL, the CRLDP extension of a cert may or may not indicate a CRL download location. For OCSP, the AIA extension of a cert may or may not indicate an OCSP responder. For OCSP, in addition, a default OCSP responder might have been configured in the application context, and is another valid OCSP source.

By default, if no download location is known, it is treated as "skip test". This parameter can be set to say "treat missing location as a test failure".

If mutliple download mechanisms are allowed (OCSP and CRL) and failure on missing source is requested, then it's sufficient to have the source for at least one mechanism available. The test where the source is available will be performed, and failure will be treated according to the other flags.

This is a three state parameter:

  • skip if missing on any cert
  • fail if missing on leaf cert, skip if missing on intermediates
  • fail is missing on any cert

(the 4th state "skip test when missing in leaf, fail when missing in intermediate" will not get implemented, the implementation should return with "invalid args" when requested by a caller) 

bits: xx000000

CERT_REV_SOURCE_MISSING_LEAF_SKIP         0
CERT_REV_SOURCE_MISSING_CHAIN_SKIP        0

CERT_REV_SOURCE_MISSING_LEAF_FAIL         0x40
CERT_REV_SOURCE_MISSING_CHAIN_FAIL        0x80

Additional details regarding parameters 4 and 5

If parameter is set to "fail soft", then parameter 5 will get ignored.

In other words: 

CERT_REV_DOWNLOAD_LEAF_FAIL_SOFT
=> ignore CERT_REV_SOURCE_MISSING_LEAF_*

and 

CERT_REV_DOWNLOAD_CHAIN_FAIL_SOFT
=> ignore CERT_REV_SOURCE_MISSING_CHAIN_*

Official EV revocation checking

The definition of revocation checking for EV (according to specs), together with our preferrence for OCSP, is expressed as: 

CERT_REV_MAY_DOWNLOAD_OCSP
CERT_REV_MAY_DOWNLOAD_CRL
CERT_REV_PREFER_DOWNLOAD_OCSP
CERT_REV_DOWNLOAD_ALL_CERTS
CERT_REV_DOWNLOAD_LEAF_FAIL_HARD
CERT_REV_DOWNLOAD_CHAIN_FAIL_HARD
CERT_REV_SOURCE_MISSING_LEAF_FAIL
CERT_REV_SOURCE_MISSING_CHAIN_FAIL

However, for the initial implementation in PSM, because of our inability to download CRLs on demand, we might relax that policy and be strict on the leaf cert only, in other words we might define: 

CERT_REV_MAY_DOWNLOAD_OCSP
CERT_REV_MAY_DOWNLOAD_CRL
CERT_REV_PREFER_DOWNLOAD_OCSP
CERT_REV_DOWNLOAD_ALL_CERTS
CERT_REV_DOWNLOAD_LEAF_FAIL_HARD
CERT_REV_DOWNLOAD_CHAIN_FAIL_SOFT ###
CERT_REV_SOURCE_MISSING_LEAF_FAIL
CERT_REV_SOURCE_MISSING_CHAIN_SKIP ###

Comparing with Nelson's latest proposal

Here is how Nelson's alternate proposal (sent by email) matches these flags.

In the either group, Nelson defines a "prefer OCSP" flag. I've converted that into global flag CERT_REV_PREFER_DOWNLOAD_OCSP / _CRL, which gets ignored if only a single download mechanism is specified. 

attempt OCSP   = CERT_REV_MAY_DOWNLOAD_OCSP
attempt CRL    = CERT_REV_MAY_DOWNLOAD_CRL
attempt either = CERT_REV_MAY_DOWNLOAD_OCSP 
                 | CERT_REV_MAY_DOWNLOAD_CRL

OCSP only if present = CERT_REV_MAY_DOWNLOAD_OCSP
                       | CERT_REV_SOURCE_MISSING_LEAF_SKIP
                       | CERT_REV_SOURCE_MISSING_CHAIN_SKIP

CRL only if present  = CERT_REV_MAY_DOWNLOAD_CRL
                       | CERT_REV_SOURCE_MISSING_LEAF_SKIP
                       | CERT_REV_SOURCE_MISSING_CHAIN_SKIP

either only if present = CERT_REV_MAY_DOWNLOAD_OCSP
                         | CERT_REV_MAY_DOWNLOAD_CRL
                         | CERT_REV_SOURCE_MISSING_LEAF_SKIP
                         | CERT_REV_SOURCE_MISSING_CHAIN_SKIP

OCSP fail hard    = CERT_REV_MAY_DOWNLOAD_OCSP
                    | CERT_REV_SOURCE_MISSING_LEAF_FAIL
                    | CERT_REV_SOURCE_MISSING_CHAIN_FAIL

CRL fail hard     = CERT_REV_MAY_DOWNLOAD_CRL
                    | CERT_REV_SOURCE_MISSING_LEAF_FAIL
                    | CERT_REV_SOURCE_MISSING_CHAIN_FAIL

either fail hard  = CERT_REV_MAY_DOWNLOAD_CRL
                    | CERT_REV_MAY_DOWNLOAD_OCSP
                    | CERT_REV_SOURCE_MISSING_LEAF_FAIL
                    | CERT_REV_SOURCE_MISSING_CHAIN_FAIL

note: if CERT_REV_MAY_DOWNLOAD_CRL is specified, then the test "already has fresh CRL" must come first in the implementation, and only afterwards it should test for "has CRL source". (That is, fresh revocation information avoids download attempts, and the check for available/missing source only happens on download attempts.) This way a locally available fresh CRL is sufficient, even if no CRL source is known and even if failure on unknown CRL source is requested.

Matrix

This PDF file contains a matrix that fully describes this proposal number 5.


Definition of freshness

In our first iteration, the implementation will make use of the current global parameters that define freshness of OCSP responses in the cache. The implementation will use an internal default value to define freshness of CRLs. We might add functions to allow for application defined CRL freshness at a later time.

Retrieved from "https://wiki.allizom.org/index.php?title=NSS:Revocation_API_Proposals&oldid=85838"