148860 - complete, precise documentation of certificate management API

Status: RESOLVED WONTFIX

(NSS :: Documentation, enhancement, P2)

Description

[Jamie Nicolson]

This is a requirement for the cert API. The comments in the PKI header files are
a good start, but I need deeper explanations. Essentially, the documentation for
each function should explain:

1. What the function will return, for every possible configuration of certificate
and key databases and PKCS #11 modules. Obviously you can't enumerate all
possible configurations. What I'm looking for are very precise definitions. For
example, a function to find a certificate by nickname could say "This function
will iterate across all PKCS #11 modules. On each module, it will issue a search
for all certificate objects whose CKA_LABEL attribute equals the given nickname.
The function will return a list containing all the certificates found by these
searches."

2. How the function will change the state of the certificate and key databases
and PKCS #11 modules. For example, there are currently several functions for
importing certificates in the database, and they are all subtle (if a
certificate is imported whose private key lives on a PKCS #11 hardware token,
will a copy of the certificate also be placed in cert7.db?) These sorts of
questions should be answerable by reading the documentation, without having to
read the code.

Comment 1

[Nelson Bolyard (seldom reads bugmail)]

Enhancement request, Requesting new documentation.