1058870 - certutil -Z (for signature hash) is undocumented

Status: RESOLVED FIXED

(NSS :: Tools, defect)

Description

[Kai Engert (:KaiE:)]

The -Z parameter can be given to the "certutil" tool, but it is undocumented. Neither the manpage nor certutil's help output mention it.

It takes a second parameter, which is a string to specify a hash algorithm, such as SHA256. The given parameter will be used by the -R/-S/-C when creating certificates or certificate requests.

At the time of writing, the following parameters are supported:
  MD2 MD4 MD5 SHA1 SHA224 SHA256 SHA384 SHA512

Comment 1

[Adam Williamson]

+1 - this was rather annoying to find out in updating a Fedora tool for certificate generation.

Comment 2

[:Cykesiopka]

Attachment: bug1058870_doc-certutil-hashAlg-option_v1.patch

Requesting feedback for now. In particular, I'm not sure whether it would be better to display the hashAlg keywords in the HTML and man page as a bulleted list, or if it's fine as is.

Comment 3

[Elio Maldonado]

(In reply to Cykesiopka from comment #2)
> Created attachment 8535435 [details] [diff] [review]
> bug1058870_doc-certutil-hashAlg-option_v1.patch
> 
> Requesting feedback for now. In particular, I'm not sure whether it would be
> better to display the hashAlg keywords in the HTML and man page as a
> bulleted list, or if it's fine as is.

I did try it with the bulleted list and does look better. It's entirily optional.

Comment 4

[Elio Maldonado]

Comment on attachment 8535435 [details] [diff] [review]
bug1058870_doc-certutil-hashAlg-option_v1.patch

Review of attachment 8535435 [details] [diff] [review]:
-----------------------------------------------------------------

r+, I agree with  own suggestions which would make it look better plus the couple of nitpicks I had on trailing whitepace.

::: cmd/certutil/certutil.c
@@ +971,4 @@
>      FPS "Usage:  %s -N [-d certdir] [-P dbprefix] [-f pwfile] [--empty-password]\n", progName);
>      FPS "Usage:  %s -T [-d certdir] [-P dbprefix] [-h token-name]\n"
>  	"\t\t [-f pwfile] [-0 SSO-password]\n", progName);
>      FPS "\t%s -A -n cert-name -t trustargs [-d certdir] [-P dbprefix] [-a] [-i input]\n", 

nitpick: while you are it, could you remove the trailing whitespace?

@@ +982,5 @@
>          "\t\t [-6 | --extKeyUsage [extKeyUsageKeyword,...]] [-7 emailAddrs]\n"
>          "\t\t [-8 dns-names] [-a]\n",
>  	progName);
>      FPS "\t%s -D -n cert-name [-d certdir] [-P dbprefix]\n", progName);
>      FPS "\t%s -E -n cert-name -t trustargs [-d certdir] [-P dbprefix] [-a] [-i input]\n", 

nitpick: while you are it, could you remove the trailing whitespace?

::: doc/certutil.xml
@@ +462,5 @@
>        <varlistentry>
> +        <term>-Z hashAlg</term>
> +        <listitem>
> +        <para>
> +           Specify the hash algorithm to use with the -C, -S or -R command options. Possible keywords: MD2, MD4, MD5, SHA1, SHA224, SHA256, SHA384, SHA512

You yousresdleve suggested using a bulleted list. I agrre that it would look slighly better but it's entirely optional.

::: doc/nroff/certutil.1
@@ +620,5 @@
>  .RE
>  .PP
> +\-Z hashAlg
> +.RS 4
> +Specify the hash algorithm to use with the \-C, \-S or \-R command options\&. Possible keywords: MD2, MD4, MD5, SHA1, SHA224, SHA256, SHA384, SHA512

As you suggested a nested itemized list for the algorithms would make it look a but better. IIt's entirely optional.

Comment 5

[:Cykesiopka]

Attachment: bug1058870_doc-certutil-hashAlg-option_v2.patch

+ Put possible hashAlg keywords in a list in HTML and man pages
+ Remove trailing whitespace

Comment 6

[:Cykesiopka]

Thanks for the review!

Comment 7

[Kai Engert (:KaiE:)]

https://hg.mozilla.org/projects/nss/rev/2bffb88b1052

Comment 8

[Kai Engert (:KaiE:)]

mass change target milestone to 3.17.4