Bug 606020 - nss security tools lack man pages
Summary: nss security tools lack man pages
Keywords:
Status: CLOSED ERRATA
Alias: None
Product: Fedora
Classification: Fedora
Component: nss
Version: 19
Hardware: All
OS: Linux
low
medium
Target Milestone: ---
Assignee: Elio Maldonado Batiz
QA Contact: Fedora Extras Quality Assurance
URL:
Whiteboard:
Depends On:
Blocks: 606022
TreeView+ depends on / blocked
 
Reported: 2010-06-20 00:37 UTC by Elio Maldonado Batiz
Modified: 2013-08-04 00:00 UTC (History)
10 users (show)

Fixed In Version: nss-util-3.15.1-1.fc18
Clone Of:
: 606022 (view as bug list)
Environment:
Last Closed: 2013-06-29 18:17:31 UTC
Type: ---
Embargoed:


Attachments (Terms of Use)
certutil man output as a text file (36.88 KB, text/plain)
2010-10-08 19:37 UTC, Elio Maldonado Batiz
no flags Details
certutil man output as text (37.19 KB, text/plain)
2010-10-21 00:29 UTC, Elio Maldonado Batiz
rrelyea: review-
Details


Links
System ID Private Priority Status Summary Last Updated
Mozilla Foundation 836477 0 None None None Never

Description Elio Maldonado Batiz 2010-06-20 00:37:01 UTC
Description of problem: None of the supprted nss security tools have man pages and they should.

Version-Release number of selected component (if applicable): all n-v-r's

How reproducible: always

Steps to Reproduce:
1. man certutil (or any other one of the nss tools)
  
Actual results:
No man entry for certutil (or any othet nss tool)

Expected results: 
man page descrption on how use the tool

Additional info:
Upstream has documentation on
http://www.mozilla.org/projects/security/pki/nss/tools
so one could easily use that information to start the work.

In some instances a user or sys-admin may be trouble-shooting a problem in an environment with convenient web access and the ability to do a quick check on tools would be higly desirable.

Man pages are often used as a reference in Red Hat courses.

Comment 1 Bug Zapper 2010-07-30 12:10:47 UTC
This bug appears to have been reported against 'rawhide' during the Fedora 14 development cycle.
Changing version to '14'.

More information and reason for this action is here:
http://fedoraproject.org/wiki/BugZappers/HouseKeeping

Comment 2 Fedora Admin XMLRPC Client 2010-09-07 20:53:50 UTC
This package has changed ownership in the Fedora Package Database.  Reassigning to the new owner of this component.

Comment 3 Elio Maldonado Batiz 2010-09-29 23:24:40 UTC
The work on the man pages is in progress and we have a temporary git repo for it.
To check out: git clone git://fedorapeople.org/~emaldonado/manpagesnss.git
To build a specific manpage: xmlto man tool-name.xml
To build an HTML page: man2html tool-name.1 > tool-name.html
To build all the manpages: make all

Comment 4 Elio Maldonado Batiz 2010-10-08 19:27:47 UTC
If you haven't done so, install the xmlto package.

Comment 5 Elio Maldonado Batiz 2010-10-08 19:37:58 UTC
Created attachment 452421 [details]
certutil man output as a text file

Comment 6 Elio Maldonado Batiz 2010-10-20 18:54:59 UTC
The Makefile requires Fedora-13 or better or RHEL-6.
See https://developer.mozilla.org/en/NSS_reference/NSS_tools 
for a text capture of most of the manpages output.

Comment 7 Elio Maldonado Batiz 2010-10-21 00:29:06 UTC
Created attachment 454705 [details]
certutil man output as text

Replaced copyright section with a license section as per feedback.

Comment 8 Bob Relyea 2010-10-27 22:45:53 UTC
Comment on attachment 454705 [details]
certutil man output as text

Clearly this is just the first pass, so the r- shouldn't be a surprise. Here are my comments:

I'm keeping my comments to things that clear up the text. I've listed everything as problem and suggested solution, so that other possible solutions can be proposed rather than mine.

General comment... there appears to be some non-printing special characters in the text version.
The utility talks about managing certificate and key databases, but then talks about usage with tokens. We should probably be upfront that the tools manages certs and keys in both NSS databases and other NSS tokens (such as smart cards).

--------------------------------------------------------------------

Paragraph 1: 

Problem. You say that the utility is to 'create and modify' certificates, then you say it's also to  'list, generate, modify...'. This is a bit confusing that it creates and modifies and it also modifies. I think a careful reading says it creates and modifies databases and it also modifies certificates, which is a little less redundant.

Suggested solution. I think if you change 'also' to 'specifically'.

"The Certificate Database tool, certutil, is a command-line utility that
can create and modify certificate and key databases. It can specifically
list, generate, modify, or delete certificates..."

-----------------------------------------------------------------------

Paragraph 2:

Problem: "The key and certificate management process generally begins with creating keys in the key database."

This isn't quite correct. Certificate issuance begins here, but certificate management could begin at importing certs and keys.

Possible solution. Simply change "key and certificate management process" to "certificate issuance process". It's a little clunky because certificate issuance comes out of the blue, but at least it's now correct. (maybe a note about certificate issuance as part of the certificate management process would fix the "out of the blue" issue?).

-----------------------------------------------------------------------

Paragraph 3:

Problem 1: There is a little bit of confusion here, particularly when taken together with the argument portion. These options are called:
 
      options
      command options
      certificate operations
      actions.

Later arguments are sometimes called 'options'. We should be consistant. Users, in general, would expect arguments and options to be synonymous, so I suggest calling them command options.

Problem 2: "Run the command option and -H to see the arguements available for each command option." This sounds like certutil will list out the arguments for just the given command when combined with -H. This is not the case. -H always lists all the options.

Problem 3: Not all command options are "uppercase". Specifically --merge, --update-merge. Not all upper case single letter options are command options (-X and -P are arguments).

Solutions: Make paragraph 3 read:

"Command Options and Arguments

Runing certutil always requires one and only one command option to specify the type of certificate operations. Each command option may take zero or more arguments. The command option -H will list all the command options and their relevant arguments.

Command Options

Command options are typically upper case."

Other wordings are possible. BTW I think the mapping of valid argument options should also appear in the man page, not just the -H command. Fix up the other occurances of options, making sure the really refer to command options.

----------------------------------------------------------------------

Options -F:

Problem: Litronic no longer exists, we probably should drop references to the smart card.
Solution: Delete the (for example, the Litronic card).

Options -G:

Same command as -F about Litronic

Option --merge

Problem: "This is used to merge legacy NSS databases (cert8.db and key3.db) into the newer SQLite databases (cert9.db key4.db)."
This statement is only partially correct and a little misleading. The --merge command option is to merge two databases irrespective of type (you can merge old databases into new databases, new databases into old, a new database into another new database, an old into an old, even a database into a token). It's purpose is to merge two updated (new)databases into a single database.

Option --update-merge

This statement here is OK. The --update-merge command option only works from old to new.

----------------------------------------------------------------

"Option arguements modify an action and are lower case"

Problem 1: This is only only place we call them options arguments.
Problem 2: Some arguments are numbers or symbols.

Suggested Solution: "Arguments modify a command option and are usually lower case, numbers, or symbols.


Argument -d:
Problem: "[sql:]directory"

The sql: isn't the only valid prefix. NSS recognizes the following prefixes:

rdb:
sql:
dbm:
extern:

The rdb: is deprecated, so you can skip it. extern: is reserved for future use. dbm: explicitly requests the older database. sql: explicitly requests the newer database. If no database reqester has been specified, The default type is retrieved from NSS_DEFAULT_DB_TYPE. If NSS_DEFAULT_DB_TYPE is not set then dbm: is the default. We should at least document both sql: and dbm:

NOTE: related is the line "If the prefix sql: is not used, then the tool assumes the given databases are the old format" is incorrect, per the above description.


Argument -h

Problem: The whole discussion about internal slot numbers is only partially right, and probably irrelevant. (The FIPS token will have only one slot). Best to simply say that 'internal' is the internal database slot and be done with it.

Argument -k

Problem: It seems like the two separate -k options should probably be merged. We should also specify where one finds a key id (there are lots of key id's in our system, so we need to be more specific than just 'id').

Argument -m

Question: Is it still true that the default serial number is '0'? I thought we fixed that. Please check.

Argument: -P (note this is upper case).

Problem: "This option is provided as a special case." Should be 'This argument' and should be more specific.

Suggestion solution:"This argument is provided to support legacy servers. Most apps do not use a database prefix."


Argument: -q

Problem: we should include the current curve list in the man page.

Argument: -t

Problem: A number of options here are deprecated and are noops (-w, for instance), or are effectively read only (-u, which means 'user', That bit is now set whenever a matching key is found for a certificate, and can't be explicitly set by the user). Also the descriptions of T and C are wrong. "C" is Trusted CA (implies c). "T" is Trusted CA for client auth (ssl server only). T should not appear in any position except the SSL position on any example.

Argument: -v

Problem: I think this description is wrong. Please verify.

Arguments: -1 -2 -3 -4 -5 -6 and maybe some of the --ext options may cause certutil to prompt for more information. We should specify that this is the case and specify what certutil will prompt for.

--------------------------------------------------

Examples: 

Problems: Many... Please try each of these examples. Many of them won't work on RH (like the examples that use ECC). Some will generate prompts, but the examples don't say the will. Finally there are a lot of improper uses of the -t flag which should be cleaned up.

In the text version, the actual command indents in, which is confusing because it looks like a new heading when it's not.

I'll review the remaining examples, once "verified to work" versions have been  included

----------------------------------------------------------------

Remainder:

IRC: do we really want dogtag-pki to the the irc channel?

Authors: should we include Mozilla, Google, and Oracle?

Comment 9 Fedora End Of Life 2013-04-03 20:02:45 UTC
This bug appears to have been reported against 'rawhide' during the Fedora 19 development cycle.
Changing version to '19'.

(As we did not run this process for some time, it could affect also pre-Fedora 19 development
cycle bugs. We are very sorry. It will help us with cleanup during Fedora 19 End Of Life. Thank you.)

More information and reason for this action is here:
https://fedoraproject.org/wiki/BugZappers/HouseKeeping/Fedora19

Comment 10 Fedora Update System 2013-06-23 04:43:12 UTC
nss-softokn-3.15-3.fc19, nss-util-3.15-1.fc19, nss-3.15-5.fc19, nspr-4.10-2.fc19 has been submitted as an update for Fedora 19.
https://admin.fedoraproject.org/updates/FEDORA-2013-11174/nss-3.15-5.fc19,nss-softokn-3.15-3.fc19,nss-util-3.15-1.fc19,nspr-4.10-2.fc19

Comment 11 Fedora Update System 2013-06-23 19:03:26 UTC
Package nss-softokn-3.15-3.fc19, nss-util-3.15-1.fc19, nss-3.15-5.fc19, nspr-4.10-2.fc19:
* should fix your issue,
* was pushed to the Fedora 19 testing repository,
* should be available at your local mirror within two days.
Update it with:
# su -c 'yum update --enablerepo=updates-testing nss-softokn-3.15-3.fc19 nss-util-3.15-1.fc19 nss-3.15-5.fc19 nspr-4.10-2.fc19'
as soon as you are able to.
Please go to the following url:
https://admin.fedoraproject.org/updates/FEDORA-2013-11174/nss-3.15-5.fc19,nss-softokn-3.15-3.fc19,nss-util-3.15-1.fc19,nspr-4.10-2.fc19
then log in and leave karma (feedback).

Comment 12 Fedora Update System 2013-06-29 18:17:31 UTC
nss-softokn-3.15-3.fc19, nss-util-3.15-1.fc19, nss-3.15-5.fc19, nspr-4.10-2.fc19 has been pushed to the Fedora 19 stable repository.  If problems still persist, please make note of it in this bug report.

Comment 13 Fedora Update System 2013-07-07 17:51:07 UTC
nss-3.15.1-1.fc19,nss-softokn-3.15.1-1.fc19 has been submitted as an update for Fedora 19.
https://admin.fedoraproject.org/updates/nss-3.15.1-1.fc19,nss-softokn-3.15.1-1.fc19

Comment 14 Fedora Update System 2013-07-17 03:08:50 UTC
nss-3.15.1-1.fc19, nss-softokn-3.15.1-1.fc19, nss-util-3.15.1-1.fc19 has been pushed to the Fedora 19 stable repository.  If problems still persist, please make note of it in this bug report.

Comment 15 Fedora Update System 2013-07-23 15:09:10 UTC
nss-util-3.15.1-1.fc18,nss-softokn-3.15.1-1.fc18,nss-3.15.1-1.fc18 has been submitted as an update for Fedora 18.
https://admin.fedoraproject.org/updates/nss-util-3.15.1-1.fc18,nss-softokn-3.15.1-1.fc18,nss-3.15.1-1.fc18

Comment 16 Fedora Update System 2013-08-04 00:00:13 UTC
nss-util-3.15.1-1.fc18, nss-softokn-3.15.1-1.fc18, nss-3.15.1-1.fc18 has been pushed to the Fedora 18 stable repository.  If problems still persist, please make note of it in this bug report.


Note You need to log in before you can comment on or make changes to this bug.