View source for NSS:Revocation API Proposals

== Proposal 4 (Nelson's proposal)==

I decided that the most important requirement was that we be able to
express every policy and combination that we might want, and that
concerns about number of bits and meaningless combinations are
important but secondary.

My proposal calls for two sets of flags, one set for the leaf only, and
one set for intermediates only.  The two sets are identical except for
that distinction.  The intermediate flags do not imply "also the leaf".
If you want both intermediate and leaf, you must set both sets of flags.

Each each set of flags (leaf, intermediate) there are 3 groups of flags,
one for OCSP, one for CRLs, and one for "either".
The OCSP and CRL flag sets are identical. 
There is no set for "both", because that is specified simply by setting 
the flags in both the OCSP and CRL sets.

The flags in the OCSP and CRL groups are named:

* attempt
* only if present
* fail soft

Meanings:

* attempt - must try to do this.

* only if present
** for OCSP, 
*** 1 means skip it if the AIA extension is absent
*** 0 means fail    if the AIA extension is absent
** for CRLs, 
*** 1 means skip it if the CRLDP extension is absent, AND a recent CRL is not locally available.
*** 0 means fail if the CRLDP extension is absent, AND a recent CRL is not locally available.

* fail hard 
** 1 means if unable to perform the revocation check, force the cert validation to fail.
** 0 means fail soft. If unable to perform, do NOT force validation to fail.

The flags for the "either" group are:

* fail hard 
** 1 means that at least one of (OCSP,CRL) must succeed, (and not merely fail soft) or else the cert validation must fail.  Overrides the attempt and fail hard bits for both OCSP and CRL groups.
** 0 means no additional requirements on cert validation for both OCSP and CRL

* prefer OCSP 
** 1 means that OCSP checking should be tried, even if a CRL is locally present.  It could also imply: check OCSP before checking the CRL, and skip the CRL check if OCSP reports not revoked.
** 0 means that a local CRL is sufficient, and OCSP need not also be tried if a local CRL is present.




== Proposal 5 (Kai's Proposal)==

===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
<pre>
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
</pre>
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.
<pre>
bits: 00000x00

CERT_REV_PREFER_DOWNLOAD_OCSP        0
CERT_REV_PREFER_DOWNLOAD_CRL         0x04
</pre>

===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.
<pre>
bits: 0000x000

CERT_REV_DOWNLOAD_ALL_CERTS              0
CERT_REV_DOWNLOAD_LEAF_ONLY              0x08
</pre>

===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)
<pre>
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
</pre>

===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)
<pre>
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
</pre>

===Additional details regarding parameters 4 and 5===

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

In other words:
<pre>
CERT_REV_DOWNLOAD_LEAF_FAIL_SOFT
=> ignore CERT_REV_SOURCE_MISSING_LEAF_*
</pre>
and
<pre>
CERT_REV_DOWNLOAD_CHAIN_FAIL_SOFT
=> ignore CERT_REV_SOURCE_MISSING_CHAIN_*
</pre>

===Official EV revocation checking===

The definition of revocation checking for EV (according to specs),
together with our preferrence for OCSP, is expressed as:
<pre>
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
</pre>
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:
<pre>
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 ###
</pre>

===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.
<pre>
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
</pre>

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===
[https://bugzilla.mozilla.org/attachment.cgi?id=307921 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.


[[Category:NSS]]