certutils from libnss3-tools - man page contradicts Mozilla's

[DiagonalArg]

Description of certuitls here:
https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/tools/NSS_Tools_certutil#Options_and_Arguments

contradicts the man page here:
http://manpages.ubuntu.com/manpages/wily/man1/certutil.1.html

In the former "-t p" is "prohibited (explicitly distrusted)". In the latter, it's "Valid peer".

I'm listing it as a security vuln, because someone could do mistakenly do the wrong thing.

[Seth Arnold (seth-arnold)]

Could you please report this issue to Mozilla? Based on a quick look of our source code and manpage I think our manpages correctly document the situation:

lib/certdb/certdb.c

SECStatus
CERT_DecodeTrustString(CERTCertTrust *trust, const char *trusts)
{
    unsigned int i;
    unsigned int *pflags;

    if (!trust) {
        PORT_SetError(SEC_ERROR_INVALID_ARGS);
        return SECFailure;
    }
    trust->sslFlags = 0;
    trust->emailFlags = 0;
    trust->objectSigningFlags = 0;
    if (!trusts) {
        PORT_SetError(SEC_ERROR_INVALID_ARGS);
        return SECFailure;
    }

    pflags = &trust->sslFlags;

    for (i=0; i < PORT_Strlen(trusts); i++) {
        switch (trusts[i]) {
          case 'p':
              *pflags = *pflags | CERTDB_TERMINAL_RECORD;
              break;

          case 'P':
              *pflags = *pflags | CERTDB_TRUSTED | CERTDB_TERMINAL_RECORD;
              break;

lib/certdb/certdb.h

typedef unsigned int __CERTDB_VALID_PEER __attribute__((deprecated
    ("CERTDB_VALID_PEER is now CERTDB_TERMINAL_RECORD")));

There's a chance that "valid peer" is really being used to mean "not trusted for this particular feature" but that feels strange.

Thanks

[DiagonalArg (diagonalarg)]

I'm checking in with IRC. It's friday though. I'll let you know what I find.

[Gareth Williams (gareththered)]

It seems that CERTDB_TERMINAL_RECORD being set to true means that the trust record is authoritative, at which point it checks for either CERTDB_TRUSTED or CERTDB_TRUSTED_CA being true. If that's the case, then the certificate is trusted, otherwise it is distrusted.

Throughout lib/certhigh/certvfy.c you'll see variations on:

case certUsageSSLCA:
    flags = trust.sslFlags;
    if (flags & CERTDB_TERMINAL_RECORD) { /* the trust record is
                                           * authoritative */
        if ((flags & (CERTDB_TRUSTED | CERTDB_TRUSTED_CA)) == 0) {
            /* don't trust this cert */
            *failedFlags = flags;
            return SECFailure;
        }
    }
    break;

The -t p option sets CERTDB_TERMINAL_RECORD while the -t P and -t C set CERTDB_TRUSTED and CERTDB_TRUSTED_CA respectively. Without the latter two (that is, with just -t p ) the certificate is explicitly distrusted as per the latest online certutil documentation.

It seems that the src man pages haven't been updated. An older version (from Sept 2014) at https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Tools/certutil agrees with the current man page in the src package.

[Robie Basak (racb)]

Thanks Gareth. So upstream have an inconsistency in their docs so presumably need an upstream bug to fix that? And Ubuntu is currently consistent between its documentation and behaviour? Is my understanding accurate?

[Gareth Williams (gareththered)]

Robie - I believe it's an inconsistency between upstream source docs and behaviour. However, upstream docs align with Ubuntu (and presumably other distro) docs and are _not_ consistent with the current behaviour.

The distro man pages and the online docs at https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Tools/certutil (Sept 2014) do not agree with the current behaviour and the later online docs at https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/tools/NSS_Tools_certutil (Sept 2015). Therefore, the source man page needs to be updated to align with the latter 2015 online docs.

As I understand it, the relevant -t trustargs arguments are:

p - mark the trustargs settings as authoritative, but don't flag the certificate as a CA. This makes the certificate explicitly distrusted as a CA as per the Sept 2015 online docs.

c - mark the trustargs settings as authoritative and also flag the certificate as a CA. I.e trusted.

'T' and 'C' also set 'c'

So, bottom line is to raise an upstream bug to align the source code man page with the online (Sept 2015) docs and current behaviour as there doesn't seem to be one currently - https://bugzilla.mozilla.org/buglist.cgi?quicksearch=certutil+trustargs

[Robie Basak (racb)]

Thanks Gareth. Is anyone volunteering to report this upstream? If reporting, please link to the report here.

[Gareth Williams (gareththered)]

User Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.112 Safari/537.36

Steps to reproduce:

The section of the man page for certutil's trustargs is outdated as discussed at https://bugs.launchpad.net/ubuntu/+source/nss/+bug/1586538

Actual results:

The trustargs section of the man page in the nss source files correlates with the on-line version at https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Tools/certutil (last modified Sept 2014):

p - Valid peer
P - Trusted peer (implies p)
c - Valid CA
T - Trusted CA to issue client certificates (implies c)
C - Trusted CA to issue server certificates (SSL only)
      (implies c)
u - Certificate can be used for authentication or signing
w - Send warning (use with other attributes to include a warning when the certificate is used in that context)

Expected results:

The trustargs section of the man page in the nss source files should correlate with the later on-line version at https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/tools/NSS_Tools_certutil (last modified Sept 2015):

p prohibited (explicitly distrusted)
P Trusted peer
c Valid CA
T Trusted CA to issue client certificates (implies c)
C Trusted CA to issue server certificates (SSL only)
      (implies c)
u Certificate can be used for authentication or signing
w Send warning (use with other attributes to include a warning when the certificate is used in that context)

The difference being the lowercase 'p' option.

[Gareth Williams (gareththered)]

Reported a bug against nss at https://bugzilla.mozilla.org/show_bug.cgi?id=1277637

[Robie Basak (racb)]

Thanks Gareth!