security/nss/lib/certdb/certi.h

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4 /*
   5  * certi.h - private data structures for the certificate library
   6  */
   7 #ifndef _CERTI_H_
   8 #define _CERTI_H_
   9
  10 #include "certt.h"
  11 #include "nssrwlkt.h"
  12
  13 /*
  14 #define GLOBAL_RWLOCK 1
  15 */
  16
  17 #define DPC_RWLOCK 1
  18
  19 /* all definitions in this file are subject to change */
  20
  21 typedef struct OpaqueCRLFieldsStr OpaqueCRLFields;
  22 typedef struct CRLEntryCacheStr CRLEntryCache;
  23 typedef struct CRLDPCacheStr CRLDPCache;
  24 typedef struct CRLIssuerCacheStr CRLIssuerCache;
  25 typedef struct CRLCacheStr CRLCache;
  26 typedef struct CachedCrlStr CachedCrl;
  27 typedef struct NamedCRLCacheStr NamedCRLCache;
  28 typedef struct NamedCRLCacheEntryStr NamedCRLCacheEntry;
  29
  30 struct OpaqueCRLFieldsStr {
  31     PRBool partial;
  32     PRBool decodingError;
  33     PRBool badEntries;
  34     PRBool badDER;
  35     PRBool badExtensions;
  36     PRBool heapDER;
  37 };
  38
  39 typedef struct PreAllocatorStr PreAllocator;
  40
  41 struct PreAllocatorStr {
  42     PRSize len;
  43     void* data;
  44     PRSize used;
  45     PLArenaPool* arena;
  46     PRSize extra;
  47 };
  48
  49 /*  CRL entry cache.
  50     This is the same as an entry plus the next/prev pointers for the hash table
  51 */
  52
  53 struct CRLEntryCacheStr {
  54     CERTCrlEntry entry;
  55     CRLEntryCache *prev, *next;
  56 };
  57
  58 #define CRL_CACHE_INVALID_CRLS 0x0001      /* this state will be set             \
  59                  if we have CRL objects with an invalid DER or signature. Can be \
  60                  cleared if the invalid objects are deleted from the token */
  61 #define CRL_CACHE_LAST_FETCH_FAILED 0x0002 /* this state will be set        \
  62             if the last CRL fetch encountered an error. Can be cleared if a \
  63             new fetch succeeds */
  64
  65 #define CRL_CACHE_OUT_OF_MEMORY 0x0004 /* this state will be set \
  66             if we don't have enough memory to build the hash table of entries */
  67
  68 typedef enum {
  69     CRL_OriginToken = 0,   /* CRL came from PKCS#11 token */
  70     CRL_OriginExplicit = 1 /* CRL was explicitly added to the cache, from RAM */
  71 } CRLOrigin;
  72
  73 typedef enum {
  74     dpcacheNoEntry = 0,           /* no entry found for this SN */
  75     dpcacheFoundEntry = 1,        /* entry found for this SN */
  76     dpcacheCallerError = 2,       /* invalid args */
  77     dpcacheInvalidCacheError = 3, /* CRL in cache may be bad DER */
  78                                   /* or unverified */
  79     dpcacheEmpty = 4,             /* no CRL in cache */
  80     dpcacheLookupError = 5        /* internal error */
  81 } dpcacheStatus;
  82
  83 struct CachedCrlStr {
  84     CERTSignedCrl* crl;
  85     CRLOrigin origin;
  86     /* hash table of entries. We use a PLHashTable and pre-allocate the
  87        required amount of memory in one shot, so that our allocator can
  88        simply pass offsets into it when hashing.
  89
  90        This won't work anymore when we support delta CRLs and iCRLs, because
  91        the size of the hash table will vary over time. At that point, the best
  92        solution will be to allocate large CRLEntry structures by modifying
  93        the DER decoding template. The extra space would be for next/prev
  94        pointers. This would allow entries from different CRLs to be mixed in
  95        the same hash table.
  96     */
  97     PLHashTable* entries;
  98     PreAllocator* prebuffer; /* big pre-allocated buffer mentioned above */
  99     PRBool sigChecked;       /* this CRL signature has already been checked */
 100     PRBool sigValid;         /* signature verification status .
 101                                 Only meaningful if checked is PR_TRUE . */
 102     PRBool unbuildable;      /* Avoid using assosiated CRL is it fails
 103                               * a decoding step */
 104 };
 105
 106 /*  CRL distribution point cache object
 107     This is a cache of CRL entries for a given distribution point of an issuer
 108     It is built from a collection of one full and 0 or more delta CRLs.
 109 */
 110
 111 struct CRLDPCacheStr {
 112 #ifdef DPC_RWLOCK
 113     NSSRWLock* lock;
 114 #else
 115     PRLock* lock;
 116 #endif
 117     SECItem* issuerDERCert; /* issuer DER cert. Don't hold a reference
 118                                to the actual cert so the trust can be
 119                                updated on the cert automatically.
 120                                XXX there may be multiple issuer certs,
 121                                with different validity dates. Also
 122                                need to deal with SKID/AKID . See
 123                                bugzilla 217387, 233118 */
 124
 125     CERTCertDBHandle* dbHandle;
 126
 127     SECItem* subject;           /* DER of issuer subject */
 128     SECItem* distributionPoint; /* DER of distribution point. This may be
 129                                    NULL when distribution points aren't
 130                                    in use (ie. the CA has a single CRL).
 131                                    Currently not used. */
 132
 133     /* array of full CRLs matching this distribution point */
 134     PRUint32 ncrls;   /* total number of CRLs in crls */
 135     CachedCrl** crls; /* array of all matching CRLs */
 136     /* XCRL With iCRLs and multiple DPs, the CRL can be shared accross several
 137        issuers. In the future, we'll need to globally recycle the CRL in a
 138        separate list in order to avoid extra lookups, decodes, and copies */
 139
 140     /* pointers to good decoded CRLs used to build the cache */
 141     CachedCrl* selected; /* full CRL selected for use in the cache */
 142 #if 0
 143     /* for future use */
 144     PRInt32 numdeltas;      /* number of delta CRLs used for the cache */
 145     CachedCrl** deltas;     /* delta CRLs used for the cache */
 146 #endif
 147     /* cache invalidity bitflag */
 148     PRUint16 invalid;  /* this state will be set if either
 149         CRL_CACHE_INVALID_CRLS or CRL_CACHE_LAST_FETCH_FAILED is set.
 150         In those cases, all certs are considered to have unknown status.
 151         The invalid state can only be cleared during an update if all
 152         error states are cleared */
 153     PRBool refresh;    /* manual refresh from tokens has been forced */
 154     PRBool mustchoose; /* trigger reselection algorithm, for case when
 155                           RAM CRL objects are dropped from the cache */
 156     PRTime lastfetch;  /* time a CRL token fetch was last performed */
 157     PRTime lastcheck;  /* time CRL token objects were last checked for
 158                           existence */
 159 };
 160
 161 /*  CRL issuer cache object
 162     This object tracks all the distribution point caches for a given issuer.
 163     XCRL once we support multiple issuing distribution points, this object
 164     will be a hash table. For now, it just holds the single CRL distribution
 165     point cache structure.
 166 */
 167
 168 struct CRLIssuerCacheStr {
 169     SECItem* subject; /* DER of issuer subject */
 170     CRLDPCache* dpp;
 171 };
 172
 173 /*  CRL revocation cache object
 174     This object tracks all the issuer caches
 175 */
 176
 177 struct CRLCacheStr {
 178 #ifdef GLOBAL_RWLOCK
 179     NSSRWLock* lock;
 180 #else
 181     PRLock* lock;
 182 #endif
 183     /* hash table of issuer to CRLIssuerCacheStr,
 184        indexed by issuer DER subject */
 185     PLHashTable* issuers;
 186 };
 187
 188 SECStatus InitCRLCache(void);
 189 SECStatus ShutdownCRLCache(void);
 190
 191 /* Returns a pointer to an environment-like string, a series of
 192 ** null-terminated strings, terminated by a zero-length string.
 193 ** This function is intended to be internal to NSS.
 194 */
 195 extern char* cert_GetCertificateEmailAddresses(CERTCertificate* cert);
 196
 197 /*
 198  * These functions are used to map subjectKeyID extension values to certs
 199  * and to keep track of the checks for user certificates in each slot
 200  */
 201 SECStatus cert_CreateSubjectKeyIDHashTable(void);
 202
 203 SECStatus cert_AddSubjectKeyIDMapping(SECItem* subjKeyID,
 204                                       CERTCertificate* cert);
 205
 206 SECStatus cert_UpdateSubjectKeyIDSlotCheck(SECItem* slotid, int series);
 207
 208 int cert_SubjectKeyIDSlotCheckSeries(SECItem* slotid);
 209
 210 /*
 211  * Call this function to remove an entry from the mapping table.
 212  */
 213 SECStatus cert_RemoveSubjectKeyIDMapping(SECItem* subjKeyID);
 214
 215 SECStatus cert_DestroySubjectKeyIDHashTable(void);
 216
 217 SECItem* cert_FindDERCertBySubjectKeyID(SECItem* subjKeyID);
 218
 219 /* return maximum length of AVA value based on its type OID tag. */
 220 extern int cert_AVAOidTagToMaxLen(SECOidTag tag);
 221
 222 /* Make an AVA, allocated from pool, from OID and DER encoded value */
 223 extern CERTAVA* CERT_CreateAVAFromRaw(PLArenaPool* pool, const SECItem* OID,
 224                                       const SECItem* value);
 225
 226 /* Make an AVA from binary input specified by SECItem */
 227 extern CERTAVA* CERT_CreateAVAFromSECItem(PLArenaPool* arena, SECOidTag kind,
 228                                           int valueType, SECItem* value);
 229
 230 /*
 231  * get a DPCache object for the given issuer subject and dp
 232  * Automatically creates the cache object if it doesn't exist yet.
 233  */
 234 SECStatus AcquireDPCache(CERTCertificate* issuer, const SECItem* subject,
 235                          const SECItem* dp, PRTime t, void* wincx,
 236                          CRLDPCache** dpcache, PRBool* writeLocked);
 237
 238 /* check if a particular SN is in the CRL cache and return its entry */
 239 dpcacheStatus DPCache_Lookup(CRLDPCache* cache, const SECItem* sn,
 240                              CERTCrlEntry** returned);
 241
 242 /* release a DPCache object that was previously acquired */
 243 void ReleaseDPCache(CRLDPCache* dpcache, PRBool writeLocked);
 244
 245 /*
 246  * map Stan errors into NSS errors
 247  * This function examines the stan error stack and automatically sets
 248  * PORT_SetError(); to the appropriate SEC_ERROR value.
 249  */
 250 void CERT_MapStanError();
 251
 252 /* Like CERT_VerifyCert, except with an additional argument, flags. The
 253  * flags are defined immediately below.
 254  */
 255 SECStatus cert_VerifyCertWithFlags(CERTCertDBHandle* handle,
 256                                    CERTCertificate* cert, PRBool checkSig,
 257                                    SECCertUsage certUsage, PRTime t,
 258                                    PRUint32 flags, void* wincx,
 259                                    CERTVerifyLog* log);
 260
 261 /* Use the default settings.
 262  * cert_VerifyCertWithFlags(..., CERT_VERIFYCERT_USE_DEFAULTS, ...) is
 263  * equivalent to CERT_VerifyCert(...);
 264  */
 265 #define CERT_VERIFYCERT_USE_DEFAULTS 0
 266
 267 /* Skip all the OCSP checks during certificate verification, regardless of
 268  * the global OCSP settings. By default, certificate |cert| will have its
 269  * revocation status checked via OCSP according to the global OCSP settings.
 270  *
 271  * OCSP checking is always skipped when certUsage is certUsageStatusResponder.
 272  */
 273 #define CERT_VERIFYCERT_SKIP_OCSP 1
 274
 275 /* Interface function for libpkix cert validation engine:
 276  * cert_verify wrapper. */
 277 SECStatus cert_VerifyCertChainPkix(CERTCertificate* cert, PRBool checkSig,
 278                                    SECCertUsage requiredUsage, PRTime time,
 279                                    void* wincx, CERTVerifyLog* log,
 280                                    PRBool* sigError, PRBool* revoked);
 281
 282 SECStatus cert_InitLocks(void);
 283
 284 SECStatus cert_DestroyLocks(void);
 285
 286 /*
 287  * fill in nsCertType field of the cert based on the cert extension
 288  */
 289 extern SECStatus cert_GetCertType(CERTCertificate* cert);
 290
 291 /*
 292  * compute and return the value of nsCertType for cert, but do not
 293  * update the CERTCertificate.
 294  */
 295 extern PRUint32 cert_ComputeCertType(CERTCertificate* cert);
 296
 297 extern PRBool cert_EKUAllowsIPsecIKE(CERTCertificate* cert,
 298                                      PRBool* isCritical);
 299
 300 void cert_AddToVerifyLog(CERTVerifyLog* log, CERTCertificate* cert,
 301                          long errorCode, unsigned int depth, void* arg);
 302
 303 /* Insert a DER CRL into the CRL cache, and take ownership of it.
 304  *
 305  * cert_CacheCRLByGeneralName takes ownership of the memory in crl argument
 306  * completely.  crl must be freeable by SECITEM_FreeItem. It will be freed
 307  * immediately if it is rejected from the CRL cache, or later during cache
 308  * updates when a new crl is available, or at shutdown time.
 309  *
 310  * canonicalizedName represents the source of the CRL, a GeneralName.
 311  * The format of the encoding is not restricted, but all callers of
 312  * cert_CacheCRLByGeneralName and cert_FindCRLByGeneralName must use
 313  * the same encoding. To facilitate X.500 name matching, a canonicalized
 314  * encoding of the GeneralName should be used, if available.
 315  */
 316
 317 SECStatus cert_CacheCRLByGeneralName(CERTCertDBHandle* dbhandle, SECItem* crl,
 318                                      const SECItem* canonicalizedName);
 319
 320 struct NamedCRLCacheStr {
 321     PRLock* lock;
 322     PLHashTable* entries;
 323 };
 324
 325 /* NamedCRLCacheEntryStr is filled in by cert_CacheCRLByGeneralName,
 326  * and read by cert_FindCRLByGeneralName */
 327 struct NamedCRLCacheEntryStr {
 328     SECItem* canonicalizedName;
 329     SECItem* crl; /* DER, kept only if CRL
 330                    * is successfully cached */
 331     PRBool inCRLCache;
 332     PRTime successfulInsertionTime; /* insertion time */
 333     PRTime lastAttemptTime;         /* time of last call to
 334                               cert_CacheCRLByGeneralName with this name */
 335     PRBool badDER;                  /* ASN.1 error */
 336     PRBool dupe;                    /* matching DER CRL already in CRL cache */
 337     PRBool unsupported;             /* IDP, delta, any other reason */
 338 };
 339
 340 typedef enum {
 341     certRevocationStatusRevoked = 0,
 342     certRevocationStatusValid = 1,
 343     certRevocationStatusUnknown = 2
 344 } CERTRevocationStatus;
 345
 346 /* Returns detailed status of the cert(revStatus variable). Tells if
 347  * issuer cache has OriginFetchedWithTimeout crl in it. */
 348 SECStatus cert_CheckCertRevocationStatus(CERTCertificate* cert,
 349                                          CERTCertificate* issuer,
 350                                          const SECItem* dp, PRTime t,
 351                                          void* wincx,
 352                                          CERTRevocationStatus* revStatus,
 353                                          CERTCRLEntryReasonCode* revReason);
 354
 355 SECStatus cert_AcquireNamedCRLCache(NamedCRLCache** returned);
 356
 357 /* cert_FindCRLByGeneralName must be called only while the named cache is
 358  * acquired, and the entry is only valid until cache is released.
 359  */
 360 SECStatus cert_FindCRLByGeneralName(NamedCRLCache* ncc,
 361                                     const SECItem* canonicalizedName,
 362                                     NamedCRLCacheEntry** retEntry);
 363
 364 SECStatus cert_ReleaseNamedCRLCache(NamedCRLCache* ncc);
 365
 366 /* This is private for now.  Maybe shoule be public. */
 367 CERTGeneralName* cert_GetSubjectAltNameList(const CERTCertificate* cert,
 368                                             PLArenaPool* arena);
 369
 370 /* Count DNS names and IP addresses in a list of GeneralNames */
 371 PRUint32 cert_CountDNSPatterns(CERTGeneralName* firstName);
 372
 373 /*
 374  * returns the trust status of the leaf certificate based on usage.
 375  * If the leaf is explicitly untrusted, this function will fail and
 376  * failedFlags will be set to the trust bit value that lead to the failure.
 377  * If the leaf is trusted, isTrusted is set to true and the function returns
 378  * SECSuccess. This function does not check if the cert is fit for a
 379  * particular usage.
 380  */
 381 SECStatus cert_CheckLeafTrust(CERTCertificate* cert, SECCertUsage usage,
 382                               unsigned int* failedFlags, PRBool* isTrusted);
 383
 384 /*
 385  * Acquire the cert temp/perm lock
 386  */
 387 void CERT_LockCertTempPerm(const CERTCertificate* cert);
 388
 389 /*
 390  * Release the temp/perm lock
 391  */
 392 void CERT_UnlockCertTempPerm(const CERTCertificate* cert);
 393
 394 /*
 395  * Acquire the cert trust lock
 396  * There is currently one global lock for all certs, but I'm putting a cert
 397  * arg here so that it will be easy to make it per-cert in the future if
 398  * that turns out to be necessary.
 399  */
 400 void CERT_LockCertTrust(const CERTCertificate* cert);
 401
 402 /*
 403  * Release the cert trust lock
 404  */
 405 void CERT_UnlockCertTrust(const CERTCertificate* cert);
 406
 407 #endif /* _CERTI_H_ */