security/nss/lib/certdb/cert.h

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is the Netscape security libraries.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Netscape Communications Corporation.
  18  * Portions created by the Initial Developer are Copyright (C) 1994-2000
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *
  23  * Alternatively, the contents of this file may be used under the terms of
  24  * either the GNU General Public License Version 2 or later (the "GPL"), or
  25  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  26  * in which case the provisions of the GPL or the LGPL are applicable instead
  27  * of those above. If you wish to allow use of your version of this file only
  28  * under the terms of either the GPL or the LGPL, and not to allow others to
  29  * use your version of this file under the terms of the MPL, indicate your
  30  * decision by deleting the provisions above and replace them with the notice
  31  * and other provisions required by the GPL or the LGPL. If you do not delete
  32  * the provisions above, a recipient may use your version of this file under
  33  * the terms of any one of the MPL, the GPL or the LGPL.
  34  *
  35  * ***** END LICENSE BLOCK ***** */
  36
  37 /*
  38  * cert.h - public data structures and prototypes for the certificate library
  39  *
  40  * $Id: cert.h,v 1.74 2008/08/04 22:31:54 nelson%bolyard.com Exp $
  41  */
  42
  43 #ifndef _CERT_H_
  44 #define _CERT_H_
  45
  46 #include "utilrename.h"
  47 #include "plarena.h"
  48 #include "plhash.h"
  49 #include "prlong.h"
  50 #include "prlog.h"
  51
  52 #include "seccomon.h"
  53 #include "secdert.h"
  54 #include "secoidt.h"
  55 #include "keyt.h"
  56 #include "certt.h"
  57
  58 SEC_BEGIN_PROTOS
  59
  60 /****************************************************************************
  61  *
  62  * RFC1485 ascii to/from X.? RelativeDistinguishedName (aka CERTName)
  63  *
  64  ****************************************************************************/
  65
  66 /*
  67 ** Convert an ascii RFC1485 encoded name into its CERTName equivalent.
  68 */
  69 extern CERTName *CERT_AsciiToName(char *string);
  70
  71 /*
  72 ** Convert an CERTName into its RFC1485 encoded equivalent.
  73 ** Returns a string that must be freed with PORT_Free().
  74 ** This version produces a string for maximum human readability,
  75 ** not for strict RFC compliance.
  76 */
  77 extern char *CERT_NameToAscii(CERTName *name);
  78
  79 /*
  80 ** Convert an CERTName into its RFC1485 encoded equivalent.
  81 ** Returns a string that must be freed with PORT_Free().
  82 ** Caller chooses encoding rules.
  83 */
  84 extern char *CERT_NameToAsciiInvertible(CERTName *name,
  85                                         CertStrictnessLevel strict);
  86
  87 extern CERTAVA *CERT_CopyAVA(PLArenaPool *arena, CERTAVA *src);
  88
  89 /* convert an OID to dotted-decimal representation */
  90 /* Returns a string that must be freed with PR_smprintf_free(). */
  91 extern char * CERT_GetOidString(const SECItem *oid);
  92
  93 /*
  94 ** Examine an AVA and return the tag that refers to it. The AVA tags are
  95 ** defined as SEC_OID_AVA*.
  96 */
  97 extern SECOidTag CERT_GetAVATag(CERTAVA *ava);
  98
  99 /*
 100 ** Compare two AVA's, returning the difference between them.
 101 */
 102 extern SECComparison CERT_CompareAVA(const CERTAVA *a, const CERTAVA *b);
 103
 104 /*
 105 ** Create an RDN (relative-distinguished-name). The argument list is a
 106 ** NULL terminated list of AVA's.
 107 */
 108 extern CERTRDN *CERT_CreateRDN(PLArenaPool *arena, CERTAVA *avas, ...);
 109
 110 /*
 111 ** Make a copy of "src" storing it in "dest".
 112 */
 113 extern SECStatus CERT_CopyRDN(PLArenaPool *arena, CERTRDN *dest, CERTRDN *src);
 114
 115 /*
 116 ** Destory an RDN object.
 117 **      "rdn" the RDN to destroy
 118 **      "freeit" if PR_TRUE then free the object as well as its sub-objects
 119 */
 120 extern void CERT_DestroyRDN(CERTRDN *rdn, PRBool freeit);
 121
 122 /*
 123 ** Add an AVA to an RDN.
 124 **      "rdn" the RDN to add to
 125 **      "ava" the AVA to add
 126 */
 127 extern SECStatus CERT_AddAVA(PLArenaPool *arena, CERTRDN *rdn, CERTAVA *ava);
 128
 129 /*
 130 ** Compare two RDN's, returning the difference between them.
 131 */
 132 extern SECComparison CERT_CompareRDN(CERTRDN *a, CERTRDN *b);
 133
 134 /*
 135 ** Create an X.500 style name using a NULL terminated list of RDN's.
 136 */
 137 extern CERTName *CERT_CreateName(CERTRDN *rdn, ...);
 138
 139 /*
 140 ** Make a copy of "src" storing it in "dest". Memory is allocated in
 141 ** "dest" for each of the appropriate sub objects. Memory is not freed in
 142 ** "dest" before allocation is done (use CERT_DestroyName(dest, PR_FALSE) to
 143 ** do that).
 144 */
 145 extern SECStatus CERT_CopyName(PLArenaPool *arena, CERTName *dest, CERTName *src);
 146
 147 /*
 148 ** Destroy a Name object.
 149 **      "name" the CERTName to destroy
 150 **      "freeit" if PR_TRUE then free the object as well as its sub-objects
 151 */
 152 extern void CERT_DestroyName(CERTName *name);
 153
 154 /*
 155 ** Add an RDN to a name.
 156 **      "name" the name to add the RDN to
 157 **      "rdn" the RDN to add to name
 158 */
 159 extern SECStatus CERT_AddRDN(CERTName *name, CERTRDN *rdn);
 160
 161 /*
 162 ** Compare two names, returning the difference between them.
 163 */
 164 extern SECComparison CERT_CompareName(CERTName *a, CERTName *b);
 165
 166 /*
 167 ** Convert a CERTName into something readable
 168 */
 169 extern char *CERT_FormatName (CERTName *name);
 170
 171 /*
 172 ** Convert a der-encoded integer to a hex printable string form.
 173 ** Perhaps this should be a SEC function but it's only used for certs.
 174 */
 175 extern char *CERT_Hexify (SECItem *i, int do_colon);
 176
 177 /******************************************************************************
 178  *
 179  * Certificate handling operations
 180  *
 181  *****************************************************************************/
 182
 183 /*
 184 ** Create a new validity object given two unix time values.
 185 **      "notBefore" the time before which the validity is not valid
 186 **      "notAfter" the time after which the validity is not valid
 187 */
 188 extern CERTValidity *CERT_CreateValidity(PRTime notBefore, PRTime notAfter);
 189
 190 /*
 191 ** Destroy a validity object.
 192 **      "v" the validity to destroy
 193 **      "freeit" if PR_TRUE then free the object as well as its sub-objects
 194 */
 195 extern void CERT_DestroyValidity(CERTValidity *v);
 196
 197 /*
 198 ** Copy the "src" object to "dest". Memory is allocated in "dest" for
 199 ** each of the appropriate sub-objects. Memory in "dest" is not freed
 200 ** before memory is allocated (use CERT_DestroyValidity(v, PR_FALSE) to do
 201 ** that).
 202 */
 203 extern SECStatus CERT_CopyValidity
 204    (PLArenaPool *arena, CERTValidity *dest, CERTValidity *src);
 205
 206 /*
 207 ** The cert lib considers a cert or CRL valid if the "notBefore" time is
 208 ** in the not-too-distant future, e.g. within the next 24 hours. This
 209 ** prevents freshly issued certificates from being considered invalid
 210 ** because the local system's time zone is incorrectly set.
 211 ** The amount of "pending slop time" is adjustable by the application.
 212 ** Units of SlopTime are seconds.  Default is 86400  (24 hours).
 213 ** Negative SlopTime values are not allowed.
 214 */
 215 PRInt32 CERT_GetSlopTime(void);
 216
 217 SECStatus CERT_SetSlopTime(PRInt32 slop);
 218
 219 /*
 220 ** Create a new certificate object. The result must be wrapped with an
 221 ** CERTSignedData to create a signed certificate.
 222 **      "serialNumber" the serial number
 223 **      "issuer" the name of the certificate issuer
 224 **      "validity" the validity period of the certificate
 225 **      "req" the certificate request that prompted the certificate issuance
 226 */
 227 extern CERTCertificate *
 228 CERT_CreateCertificate (unsigned long serialNumber, CERTName *issuer,
 229                         CERTValidity *validity, CERTCertificateRequest *req);
 230
 231 /*
 232 ** Destroy a certificate object
 233 **      "cert" the certificate to destroy
 234 ** NOTE: certificate's are reference counted. This call decrements the
 235 ** reference count, and if the result is zero, then the object is destroyed
 236 ** and optionally freed.
 237 */
 238 extern void CERT_DestroyCertificate(CERTCertificate *cert);
 239
 240 /*
 241 ** Make a shallow copy of a certificate "c". Just increments the
 242 ** reference count on "c".
 243 */
 244 extern CERTCertificate *CERT_DupCertificate(CERTCertificate *c);
 245
 246 /*
 247 ** Create a new certificate request. This result must be wrapped with an
 248 ** CERTSignedData to create a signed certificate request.
 249 **      "name" the subject name (who the certificate request is from)
 250 **      "spki" describes/defines the public key the certificate is for
 251 **      "attributes" if non-zero, some optional attribute data
 252 */
 253 extern CERTCertificateRequest *
 254 CERT_CreateCertificateRequest (CERTName *name, CERTSubjectPublicKeyInfo *spki,
 255                                SECItem **attributes);
 256
 257 /*
 258 ** Destroy a certificate-request object
 259 **      "r" the certificate-request to destroy
 260 **      "freeit" if PR_TRUE then free the object as well as its sub-objects
 261 */
 262 extern void CERT_DestroyCertificateRequest(CERTCertificateRequest *r);
 263
 264 /*
 265 ** Start adding extensions to a certificate request.
 266 */
 267 void *
 268 CERT_StartCertificateRequestAttributes(CERTCertificateRequest *req);
 269
 270 /*
 271 ** Reformat the certificate extension list into a CertificateRequest
 272 ** attribute list.
 273 */
 274 SECStatus
 275 CERT_FinishCertificateRequestAttributes(CERTCertificateRequest *req);
 276
 277 /*
 278 ** Extract the Extension Requests from a DER CertRequest attribute list.
 279 */
 280 SECStatus
 281 CERT_GetCertificateRequestExtensions(CERTCertificateRequest *req,
 282                                      CERTCertExtension ***exts);
 283
 284 /*
 285 ** Extract a public key object from a certificate
 286 */
 287 extern SECKEYPublicKey *CERT_ExtractPublicKey(CERTCertificate *cert);
 288
 289 /*
 290  * used to get a public key with Key Material ID. Only used for fortezza V1
 291  * certificates.
 292  */
 293 extern SECKEYPublicKey *CERT_KMIDPublicKey(CERTCertificate *cert);
 294
 295
 296 /*
 297 ** Retrieve the Key Type associated with the cert we're dealing with
 298 */
 299
 300 extern KeyType CERT_GetCertKeyType (CERTSubjectPublicKeyInfo *spki);
 301
 302 /*
 303 ** Initialize the certificate database.  This is called to create
 304 **  the initial list of certificates in the database.
 305 */
 306 extern SECStatus CERT_InitCertDB(CERTCertDBHandle *handle);
 307
 308 extern int CERT_GetDBContentVersion(CERTCertDBHandle *handle);
 309
 310 /*
 311 ** Default certificate database routines
 312 */
 313 extern void CERT_SetDefaultCertDB(CERTCertDBHandle *handle);
 314
 315 extern CERTCertDBHandle *CERT_GetDefaultCertDB(void);
 316
 317 extern CERTCertList *CERT_GetCertChainFromCert(CERTCertificate *cert,
 318                                                PRTime time,
 319                                                SECCertUsage usage);
 320 extern CERTCertificate *
 321 CERT_NewTempCertificate (CERTCertDBHandle *handle, SECItem *derCert,
 322                          char *nickname, PRBool isperm, PRBool copyDER);
 323
 324
 325 /******************************************************************************
 326  *
 327  * X.500 Name handling operations
 328  *
 329  *****************************************************************************/
 330
 331 /*
 332 ** Create an AVA (attribute-value-assertion)
 333 **      "arena" the memory arena to alloc from
 334 **      "kind" is one of SEC_OID_AVA_*
 335 **      "valueType" is one of DER_PRINTABLE_STRING, DER_IA5_STRING, or
 336 **         DER_T61_STRING
 337 **      "value" is the null terminated string containing the value
 338 */
 339 extern CERTAVA *CERT_CreateAVA
 340    (PLArenaPool *arena, SECOidTag kind, int valueType, char *value);
 341
 342 /*
 343 ** Extract the Distinguished Name from a DER encoded certificate
 344 **      "derCert" is the DER encoded certificate
 345 **      "derName" is the SECItem that the name is returned in
 346 */
 347 extern SECStatus CERT_NameFromDERCert(SECItem *derCert, SECItem *derName);
 348
 349 /*
 350 ** Extract the Issuers Distinguished Name from a DER encoded certificate
 351 **      "derCert" is the DER encoded certificate
 352 **      "derName" is the SECItem that the name is returned in
 353 */
 354 extern SECStatus CERT_IssuerNameFromDERCert(SECItem *derCert,
 355                                             SECItem *derName);
 356
 357 extern SECItem *
 358 CERT_EncodeGeneralName(CERTGeneralName *genName, SECItem *dest,
 359                        PLArenaPool *arena);
 360
 361 extern CERTGeneralName *
 362 CERT_DecodeGeneralName(PLArenaPool *reqArena, SECItem *encodedName,
 363                        CERTGeneralName  *genName);
 364
 365
 366
 367 /*
 368 ** Generate a database search key for a certificate, based on the
 369 ** issuer and serial number.
 370 **      "arena" the memory arena to alloc from
 371 **      "derCert" the DER encoded certificate
 372 **      "key" the returned key
 373 */
 374 extern SECStatus CERT_KeyFromDERCert(PLArenaPool *reqArena, SECItem *derCert,
 375                                      SECItem *key);
 376
 377 extern SECStatus CERT_KeyFromIssuerAndSN(PLArenaPool *arena, SECItem *issuer,
 378                                          SECItem *sn, SECItem *key);
 379
 380 extern SECStatus CERT_SerialNumberFromDERCert(SECItem *derCert,
 381                                                 SECItem *derName);
 382
 383
 384 /*
 385 ** Generate a database search key for a crl, based on the
 386 ** issuer.
 387 **      "arena" the memory arena to alloc from
 388 **      "derCrl" the DER encoded crl
 389 **      "key" the returned key
 390 */
 391 extern SECStatus CERT_KeyFromDERCrl(PLArenaPool *arena, SECItem *derCrl, SECItem *key);
 392
 393 /*
 394 ** Open the certificate database.  Use callback to get name of database.
 395 */
 396 extern SECStatus CERT_OpenCertDB(CERTCertDBHandle *handle, PRBool readOnly,
 397                                  CERTDBNameFunc namecb, void *cbarg);
 398
 399 /* Open the certificate database.  Use given filename for database. */
 400 extern SECStatus CERT_OpenCertDBFilename(CERTCertDBHandle *handle,
 401                                          char *certdbname, PRBool readOnly);
 402
 403 /*
 404 ** Open and initialize a cert database that is entirely in memory.  This
 405 ** can be used when the permanent database can not be opened or created.
 406 */
 407 extern SECStatus CERT_OpenVolatileCertDB(CERTCertDBHandle *handle);
 408
 409 /*
 410 ** Extract the list of host names, host name patters, IP address strings
 411 ** this cert is valid for.
 412 ** This function does NOT return nicknames.
 413 ** Type CERTCertNicknames is being used because it's a convenient
 414 ** data structure to carry a list of strings and its count.
 415 */
 416 extern CERTCertNicknames *
 417   CERT_GetValidDNSPatternsFromCert(CERTCertificate *cert);
 418
 419 /*
 420 ** Check the hostname to make sure that it matches the shexp that
 421 ** is given in the common name of the certificate.
 422 */
 423 extern SECStatus CERT_VerifyCertName(CERTCertificate *cert, const char *hostname);
 424
 425 /*
 426 ** Add a domain name to the list of names that the user has explicitly
 427 ** allowed (despite cert name mismatches) for use with a server cert.
 428 */
 429 extern SECStatus CERT_AddOKDomainName(CERTCertificate *cert, const char *hostname);
 430
 431 /*
 432 ** Decode a DER encoded certificate into an CERTCertificate structure
 433 **      "derSignedCert" is the DER encoded signed certificate
 434 **      "copyDER" is true if the DER should be copied, false if the
 435 **              existing copy should be referenced
 436 **      "nickname" is the nickname to use in the database.  If it is NULL
 437 **              then a temporary nickname is generated.
 438 */
 439 extern CERTCertificate *
 440 CERT_DecodeDERCertificate (SECItem *derSignedCert, PRBool copyDER, char *nickname);
 441 /*
 442 ** Decode a DER encoded CRL/KRL into an CERTSignedCrl structure
 443 **      "derSignedCrl" is the DER encoded signed crl/krl.
 444 **      "type" is this a CRL or KRL.
 445 */
 446 #define SEC_CRL_TYPE    1
 447 #define SEC_KRL_TYPE    0
 448
 449 extern CERTSignedCrl *
 450 CERT_DecodeDERCrl (PLArenaPool *arena, SECItem *derSignedCrl,int type);
 451
 452 /*
 453  * same as CERT_DecodeDERCrl, plus allow options to be passed in
 454  */
 455
 456 extern CERTSignedCrl *
 457 CERT_DecodeDERCrlWithFlags(PLArenaPool *narena, SECItem *derSignedCrl,
 458                           int type, PRInt32 options);
 459
 460 /* CRL options to pass */
 461
 462 #define CRL_DECODE_DEFAULT_OPTIONS          0x00000000
 463
 464 /* when CRL_DECODE_DONT_COPY_DER is set, the DER is not copied . The
 465    application must then keep derSignedCrl until it destroys the
 466    CRL . Ideally, it should allocate derSignedCrl in an arena
 467    and pass that arena in as the first argument to
 468    CERT_DecodeDERCrlWithFlags */
 469
 470 #define CRL_DECODE_DONT_COPY_DER            0x00000001
 471 #define CRL_DECODE_SKIP_ENTRIES             0x00000002
 472 #define CRL_DECODE_KEEP_BAD_CRL             0x00000004
 473 #define CRL_DECODE_ADOPT_HEAP_DER           0x00000008
 474
 475 /* complete the decoding of a partially decoded CRL, ie. decode the
 476    entries. Note that entries is an optional field in a CRL, so the
 477    "entries" pointer in CERTCrlStr may still be NULL even after
 478    function returns SECSuccess */
 479
 480 extern SECStatus CERT_CompleteCRLDecodeEntries(CERTSignedCrl* crl);
 481
 482 /* Validate CRL then import it to the dbase.  If there is already a CRL with the
 483  * same CA in the dbase, it will be replaced if derCRL is more up to date.
 484  * If the process successes, a CRL will be returned.  Otherwise, a NULL will
 485  * be returned. The caller should call PORT_GetError() for the exactly error
 486  * code.
 487  */
 488 extern CERTSignedCrl *
 489 CERT_ImportCRL (CERTCertDBHandle *handle, SECItem *derCRL, char *url,
 490                                                 int type, void * wincx);
 491
 492 extern void CERT_DestroyCrl (CERTSignedCrl *crl);
 493
 494 /* this is a hint to flush the CRL cache. crlKey is the DER subject of
 495    the issuer (CA). */
 496 void CERT_CRLCacheRefreshIssuer(CERTCertDBHandle* dbhandle, SECItem* crlKey);
 497
 498 /* add the specified DER CRL object to the CRL cache. Doing so will allow
 499    certificate verification functions (such as CERT_VerifyCertificate)
 500    to automatically find and make use of this CRL object.
 501    Once a CRL is added to the CRL cache, the application must hold on to
 502    the object's memory, because the cache will reference it directly. The
 503    application can only free the object after it calls CERT_UncacheCRL to
 504    remove it from the CRL cache.
 505 */
 506 SECStatus CERT_CacheCRL(CERTCertDBHandle* dbhandle, SECItem* newcrl);
 507
 508 /* remove a previously added CRL object from the CRL cache. It is OK
 509    for the application to free the memory after a successful removal
 510 */
 511 SECStatus CERT_UncacheCRL(CERTCertDBHandle* dbhandle, SECItem* oldcrl);
 512
 513 /*
 514 ** Decode a certificate and put it into the temporary certificate database
 515 */
 516 extern CERTCertificate *
 517 CERT_DecodeCertificate (SECItem *derCert, char *nickname,PRBool copyDER);
 518
 519 /*
 520 ** Find a certificate in the database
 521 **      "key" is the database key to look for
 522 */
 523 extern CERTCertificate *CERT_FindCertByKey(CERTCertDBHandle *handle, SECItem *key);
 524
 525 /*
 526 ** Find a certificate in the database by name
 527 **      "name" is the distinguished name to look up
 528 */
 529 extern CERTCertificate *
 530 CERT_FindCertByName (CERTCertDBHandle *handle, SECItem *name);
 531
 532 /*
 533 ** Find a certificate in the database by name
 534 **      "name" is the distinguished name to look up (in ascii)
 535 */
 536 extern CERTCertificate *
 537 CERT_FindCertByNameString (CERTCertDBHandle *handle, char *name);
 538
 539 /*
 540 ** Find a certificate in the database by name and keyid
 541 **      "name" is the distinguished name to look up
 542 **      "keyID" is the value of the subjectKeyID to match
 543 */
 544 extern CERTCertificate *
 545 CERT_FindCertByKeyID (CERTCertDBHandle *handle, SECItem *name, SECItem *keyID);
 546
 547 /*
 548 ** Generate a certificate key from the issuer and serialnumber, then look it
 549 ** up in the database.  Return the cert if found.
 550 **      "issuerAndSN" is the issuer and serial number to look for
 551 */
 552 extern CERTCertificate *
 553 CERT_FindCertByIssuerAndSN (CERTCertDBHandle *handle, CERTIssuerAndSN *issuerAndSN);
 554
 555 /*
 556 ** Find a certificate in the database by a subject key ID
 557 **      "subjKeyID" is the subject Key ID to look for
 558 */
 559 extern CERTCertificate *
 560 CERT_FindCertBySubjectKeyID (CERTCertDBHandle *handle, SECItem *subjKeyID);
 561
 562 /*
 563 ** Encode Certificate SKID (Subject Key ID) extension.
 564 **
 565 */
 566 extern SECStatus
 567 CERT_EncodeSubjectKeyID(PLArenaPool *arena, const SECItem* srcString,
 568                         SECItem *encodedValue);
 569
 570 /*
 571 ** Find a certificate in the database by a nickname
 572 **      "nickname" is the ascii string nickname to look for
 573 */
 574 extern CERTCertificate *
 575 CERT_FindCertByNickname (CERTCertDBHandle *handle, const char *nickname);
 576
 577 /*
 578 ** Find a certificate in the database by a DER encoded certificate
 579 **      "derCert" is the DER encoded certificate
 580 */
 581 extern CERTCertificate *
 582 CERT_FindCertByDERCert(CERTCertDBHandle *handle, SECItem *derCert);
 583
 584 /*
 585 ** Find a certificate in the database by a email address
 586 **      "emailAddr" is the email address to look up
 587 */
 588 CERTCertificate *
 589 CERT_FindCertByEmailAddr(CERTCertDBHandle *handle, char *emailAddr);
 590
 591 /*
 592 ** Find a certificate in the database by a email address or nickname
 593 **      "name" is the email address or nickname to look up
 594 */
 595 CERTCertificate *
 596 CERT_FindCertByNicknameOrEmailAddr(CERTCertDBHandle *handle, const char *name);
 597
 598 /*
 599 ** Find a certificate in the database by a digest of a subject public key
 600 **      "spkDigest" is the digest to look up
 601 */
 602 extern CERTCertificate *
 603 CERT_FindCertBySPKDigest(CERTCertDBHandle *handle, SECItem *spkDigest);
 604
 605 /*
 606  * Find the issuer of a cert
 607  */
 608 CERTCertificate *
 609 CERT_FindCertIssuer(CERTCertificate *cert, PRTime validTime, SECCertUsage usage);
 610
 611 /*
 612 ** Check the validity times of a certificate vs. time 't', allowing
 613 ** some slop for broken clocks and stuff.
 614 **      "cert" is the certificate to be checked
 615 **      "t" is the time to check against
 616 **      "allowOverride" if true then check to see if the invalidity has
 617 **              been overridden by the user.
 618 */
 619 extern SECCertTimeValidity CERT_CheckCertValidTimes(CERTCertificate *cert,
 620                                                     PRTime t,
 621                                                     PRBool allowOverride);
 622
 623 /*
 624 ** WARNING - this function is deprecated, and will either go away or have
 625 **              a new API in the near future.
 626 **
 627 ** Check the validity times of a certificate vs. the current time, allowing
 628 ** some slop for broken clocks and stuff.
 629 **      "cert" is the certificate to be checked
 630 */
 631 extern SECStatus CERT_CertTimesValid(CERTCertificate *cert);
 632
 633 /*
 634 ** Extract the validity times from a certificate
 635 **      "c" is the certificate
 636 **      "notBefore" is the start of the validity period
 637 **      "notAfter" is the end of the validity period
 638 */
 639 extern SECStatus
 640 CERT_GetCertTimes (CERTCertificate *c, PRTime *notBefore, PRTime *notAfter);
 641
 642 /*
 643 ** Extract the issuer and serial number from a certificate
 644 */
 645 extern CERTIssuerAndSN *CERT_GetCertIssuerAndSN(PLArenaPool *,
 646                                                         CERTCertificate *);
 647
 648 /*
 649 ** verify the signature of a signed data object with a given certificate
 650 **      "sd" the signed data object to be verified
 651 **      "cert" the certificate to use to check the signature
 652 */
 653 extern SECStatus CERT_VerifySignedData(CERTSignedData *sd,
 654                                        CERTCertificate *cert,
 655                                        PRTime t,
 656                                        void *wincx);
 657 /*
 658 ** verify the signature of a signed data object with the given DER publickey
 659 */
 660 extern SECStatus
 661 CERT_VerifySignedDataWithPublicKeyInfo(CERTSignedData *sd,
 662                                        CERTSubjectPublicKeyInfo *pubKeyInfo,
 663                                        void *wincx);
 664
 665 /*
 666 ** verify the signature of a signed data object with a SECKEYPublicKey.
 667 */
 668 extern SECStatus
 669 CERT_VerifySignedDataWithPublicKey(CERTSignedData *sd,
 670                                    SECKEYPublicKey *pubKey, void *wincx);
 671
 672 /*
 673 ** NEW FUNCTIONS with new bit-field-FIELD SECCertificateUsage - please use
 674 ** verify a certificate by checking validity times against a certain time,
 675 ** that we trust the issuer, and that the signature on the certificate is
 676 ** valid.
 677 **      "cert" the certificate to verify
 678 **      "checkSig" only check signatures if true
 679 */
 680 extern SECStatus
 681 CERT_VerifyCertificate(CERTCertDBHandle *handle, CERTCertificate *cert,
 682                 PRBool checkSig, SECCertificateUsage requiredUsages,
 683                 PRTime t, void *wincx, CERTVerifyLog *log,
 684                 SECCertificateUsage* returnedUsages);
 685
 686 /* same as above, but uses current time */
 687 extern SECStatus
 688 CERT_VerifyCertificateNow(CERTCertDBHandle *handle, CERTCertificate *cert,
 689                    PRBool checkSig, SECCertificateUsage requiredUsages,
 690                    void *wincx, SECCertificateUsage* returnedUsages);
 691
 692 /*
 693 ** Verify that a CA cert can certify some (unspecified) leaf cert for a given
 694 ** purpose. This is used by UI code to help identify where a chain may be
 695 ** broken and why. This takes identical parameters to CERT_VerifyCert
 696 */
 697 extern SECStatus
 698 CERT_VerifyCACertForUsage(CERTCertDBHandle *handle, CERTCertificate *cert,
 699                 PRBool checkSig, SECCertUsage certUsage, PRTime t,
 700                 void *wincx, CERTVerifyLog *log);
 701
 702 /*
 703 ** OLD OBSOLETE FUNCTIONS with enum SECCertUsage - DO NOT USE FOR NEW CODE
 704 ** verify a certificate by checking validity times against a certain time,
 705 ** that we trust the issuer, and that the signature on the certificate is
 706 ** valid.
 707 **      "cert" the certificate to verify
 708 **      "checkSig" only check signatures if true
 709 */
 710 extern SECStatus
 711 CERT_VerifyCert(CERTCertDBHandle *handle, CERTCertificate *cert,
 712                 PRBool checkSig, SECCertUsage certUsage, PRTime t,
 713                 void *wincx, CERTVerifyLog *log);
 714
 715 /* same as above, but uses current time */
 716 extern SECStatus
 717 CERT_VerifyCertNow(CERTCertDBHandle *handle, CERTCertificate *cert,
 718                    PRBool checkSig, SECCertUsage certUsage, void *wincx);
 719
 720 SECStatus
 721 CERT_VerifyCertChain(CERTCertDBHandle *handle, CERTCertificate *cert,
 722                      PRBool checkSig, SECCertUsage certUsage, PRTime t,
 723                      void *wincx, CERTVerifyLog *log);
 724
 725 /*
 726 ** Read a base64 ascii encoded DER certificate and convert it to our
 727 ** internal format.
 728 **      "certstr" is a null-terminated string containing the certificate
 729 */
 730 extern CERTCertificate *CERT_ConvertAndDecodeCertificate(char *certstr);
 731
 732 /*
 733 ** Read a certificate in some foreign format, and convert it to our
 734 ** internal format.
 735 **      "certbuf" is the buffer containing the certificate
 736 **      "certlen" is the length of the buffer
 737 ** NOTE - currently supports netscape base64 ascii encoded raw certs
 738 **  and netscape binary DER typed files.
 739 */
 740 extern CERTCertificate *CERT_DecodeCertFromPackage(char *certbuf, int certlen);
 741
 742 extern SECStatus
 743 CERT_ImportCAChain (SECItem *certs, int numcerts, SECCertUsage certUsage);
 744
 745 extern SECStatus
 746 CERT_ImportCAChainTrusted(SECItem *certs, int numcerts, SECCertUsage certUsage);
 747
 748 /*
 749 ** Read a certificate chain in some foreign format, and pass it to a
 750 ** callback function.
 751 **      "certbuf" is the buffer containing the certificate
 752 **      "certlen" is the length of the buffer
 753 **      "f" is the callback function
 754 **      "arg" is the callback argument
 755 */
 756 typedef SECStatus (PR_CALLBACK *CERTImportCertificateFunc)
 757    (void *arg, SECItem **certs, int numcerts);
 758
 759 extern SECStatus
 760 CERT_DecodeCertPackage(char *certbuf, int certlen, CERTImportCertificateFunc f,
 761                        void *arg);
 762
 763 /*
 764 ** Returns the value of an AVA.  This was a formerly static
 765 ** function that has been exposed due to the need to decode
 766 ** and convert unicode strings to UTF8.
 767 **
 768 ** XXX This function resides in certhtml.c, should it be
 769 ** moved elsewhere?
 770 */
 771 extern SECItem *CERT_DecodeAVAValue(const SECItem *derAVAValue);
 772
 773
 774
 775 /*
 776 ** extract various element strings from a distinguished name.
 777 **      "name" the distinguished name
 778 */
 779
 780 extern char *CERT_GetCertificateEmailAddress(CERTCertificate *cert);
 781
 782 extern char *CERT_GetCertEmailAddress(CERTName *name);
 783
 784 extern const char * CERT_GetFirstEmailAddress(CERTCertificate * cert);
 785
 786 extern const char * CERT_GetNextEmailAddress(CERTCertificate * cert,
 787                                              const char * prev);
 788
 789 /* The return value must be freed with PORT_Free. */
 790 extern char *CERT_GetCommonName(CERTName *name);
 791
 792 extern char *CERT_GetCountryName(CERTName *name);
 793
 794 extern char *CERT_GetLocalityName(CERTName *name);
 795
 796 extern char *CERT_GetStateName(CERTName *name);
 797
 798 extern char *CERT_GetOrgName(CERTName *name);
 799
 800 extern char *CERT_GetOrgUnitName(CERTName *name);
 801
 802 extern char *CERT_GetDomainComponentName(CERTName *name);
 803
 804 extern char *CERT_GetCertUid(CERTName *name);
 805
 806 /* manipulate the trust parameters of a certificate */
 807
 808 extern SECStatus CERT_GetCertTrust(CERTCertificate *cert, CERTCertTrust *trust);
 809
 810 extern SECStatus
 811 CERT_ChangeCertTrust (CERTCertDBHandle *handle, CERTCertificate *cert,
 812                       CERTCertTrust *trust);
 813
 814 extern SECStatus
 815 CERT_ChangeCertTrustByUsage(CERTCertDBHandle *certdb, CERTCertificate *cert,
 816                             SECCertUsage usage);
 817
 818 /*************************************************************************
 819  *
 820  * manipulate the extensions of a certificate
 821  *
 822  ************************************************************************/
 823
 824 /*
 825 ** Set up a cert for adding X509v3 extensions.  Returns an opaque handle
 826 ** used by the next two routines.
 827 **      "cert" is the certificate we are adding extensions to
 828 */
 829 extern void *CERT_StartCertExtensions(CERTCertificate *cert);
 830
 831 /*
 832 ** Add an extension to a certificate.
 833 **      "exthandle" is the handle returned by the previous function
 834 **      "idtag" is the integer tag for the OID that should ID this extension
 835 **      "value" is the value of the extension
 836 **      "critical" is the critical extension flag
 837 **      "copyData" is a flag indicating whether the value data should be
 838 **              copied.
 839 */
 840 extern SECStatus CERT_AddExtension (void *exthandle, int idtag,
 841                         SECItem *value, PRBool critical, PRBool copyData);
 842
 843 extern SECStatus CERT_AddExtensionByOID (void *exthandle, SECItem *oid,
 844                          SECItem *value, PRBool critical, PRBool copyData);
 845
 846 extern SECStatus CERT_EncodeAndAddExtension
 847    (void *exthandle, int idtag, void *value, PRBool critical,
 848     const SEC_ASN1Template *atemplate);
 849
 850 extern SECStatus CERT_EncodeAndAddBitStrExtension
 851    (void *exthandle, int idtag, SECItem *value, PRBool critical);
 852
 853
 854 extern SECStatus
 855 CERT_EncodeAltNameExtension(PLArenaPool *arena,  CERTGeneralName  *value, SECItem *encodedValue);
 856
 857
 858 /*
 859 ** Finish adding cert extensions.  Does final processing on extension
 860 ** data, putting it in the right format, and freeing any temporary
 861 ** storage.
 862 **      "exthandle" is the handle used to add extensions to a certificate
 863 */
 864 extern SECStatus CERT_FinishExtensions(void *exthandle);
 865
 866 /*
 867 ** Merge an external list of extensions into a cert's extension list, adding one
 868 ** only when its OID matches none of the cert's existing extensions. Call this
 869 ** immediately before calling CERT_FinishExtensions().
 870 */
 871 SECStatus
 872 CERT_MergeExtensions(void *exthandle, CERTCertExtension **exts);
 873
 874 /* If the extension is found, return its criticality and value.
 875 ** This allocate storage for the returning extension value.
 876 */
 877 extern SECStatus CERT_GetExtenCriticality
 878    (CERTCertExtension **extensions, int tag, PRBool *isCritical);
 879
 880 extern void
 881 CERT_DestroyOidSequence(CERTOidSequence *oidSeq);
 882
 883 /****************************************************************************
 884  *
 885  * DER encode and decode extension values
 886  *
 887  ****************************************************************************/
 888
 889 /* Encode the value of the basicConstraint extension.
 890 **      arena - where to allocate memory for the encoded value.
 891 **      value - extension value to encode
 892 **      encodedValue - output encoded value
 893 */
 894 extern SECStatus CERT_EncodeBasicConstraintValue
 895    (PLArenaPool *arena, CERTBasicConstraints *value, SECItem *encodedValue);
 896
 897 /*
 898 ** Encode the value of the authorityKeyIdentifier extension.
 899 */
 900 extern SECStatus CERT_EncodeAuthKeyID
 901    (PLArenaPool *arena, CERTAuthKeyID *value, SECItem *encodedValue);
 902
 903 /*
 904 ** Encode the value of the crlDistributionPoints extension.
 905 */
 906 extern SECStatus CERT_EncodeCRLDistributionPoints
 907    (PLArenaPool *arena, CERTCrlDistributionPoints *value,SECItem *derValue);
 908
 909 /*
 910 ** Decodes a DER encoded basicConstaint extension value into a readable format
 911 **      value - decoded value
 912 **      encodedValue - value to decoded
 913 */
 914 extern SECStatus CERT_DecodeBasicConstraintValue
 915    (CERTBasicConstraints *value, SECItem *encodedValue);
 916
 917 /* Decodes a DER encoded authorityKeyIdentifier extension value into a
 918 ** readable format.
 919 **      arena - where to allocate memory for the decoded value
 920 **      encodedValue - value to be decoded
 921 **      Returns a CERTAuthKeyID structure which contains the decoded value
 922 */
 923 extern CERTAuthKeyID *CERT_DecodeAuthKeyID
 924                         (PLArenaPool *arena, SECItem *encodedValue);
 925
 926
 927 /* Decodes a DER encoded crlDistributionPoints extension value into a
 928 ** readable format.
 929 **      arena - where to allocate memory for the decoded value
 930 **      der - value to be decoded
 931 **      Returns a CERTCrlDistributionPoints structure which contains the
 932 **          decoded value
 933 */
 934 extern CERTCrlDistributionPoints * CERT_DecodeCRLDistributionPoints
 935    (PLArenaPool *arena, SECItem *der);
 936
 937 /* Extract certain name type from a generalName */
 938 extern void *CERT_GetGeneralNameByType
 939    (CERTGeneralName *genNames, CERTGeneralNameType type, PRBool derFormat);
 940
 941
 942 extern CERTOidSequence *
 943 CERT_DecodeOidSequence(SECItem *seqItem);
 944
 945
 946
 947
 948 /****************************************************************************
 949  *
 950  * Find extension values of a certificate
 951  *
 952  ***************************************************************************/
 953
 954 extern SECStatus CERT_FindCertExtension
 955    (CERTCertificate *cert, int tag, SECItem *value);
 956
 957 extern SECStatus CERT_FindNSCertTypeExtension
 958    (CERTCertificate *cert, SECItem *value);
 959
 960 extern char * CERT_FindNSStringExtension (CERTCertificate *cert, int oidtag);
 961
 962 extern SECStatus CERT_FindIssuerCertExtension
 963    (CERTCertificate *cert, int tag, SECItem *value);
 964
 965 extern SECStatus CERT_FindCertExtensionByOID
 966    (CERTCertificate *cert, SECItem *oid, SECItem *value);
 967
 968 extern char *CERT_FindCertURLExtension (CERTCertificate *cert, int tag,
 969                                                                 int catag);
 970
 971 /* Returns the decoded value of the authKeyID extension.
 972 **   Note that this uses passed in the arena to allocate storage for the result
 973 */
 974 extern CERTAuthKeyID * CERT_FindAuthKeyIDExten (PLArenaPool *arena,CERTCertificate *cert);
 975
 976 /* Returns the decoded value of the basicConstraint extension.
 977  */
 978 extern SECStatus CERT_FindBasicConstraintExten
 979    (CERTCertificate *cert, CERTBasicConstraints *value);
 980
 981 /* Returns the decoded value of the crlDistributionPoints extension.
 982 **  Note that the arena in cert is used to allocate storage for the result
 983 */
 984 extern CERTCrlDistributionPoints * CERT_FindCRLDistributionPoints
 985    (CERTCertificate *cert);
 986
 987 /* Returns value of the keyUsage extension.  This uses PR_Alloc to allocate
 988 ** buffer for the decoded value. The caller should free up the storage
 989 ** allocated in value->data.
 990 */
 991 extern SECStatus CERT_FindKeyUsageExtension (CERTCertificate *cert,
 992                                                         SECItem *value);
 993
 994 /* Return the decoded value of the subjectKeyID extension. The caller should
 995 ** free up the storage allocated in retItem->data.
 996 */
 997 extern SECStatus CERT_FindSubjectKeyIDExtension (CERTCertificate *cert,
 998                                                            SECItem *retItem);
 999
1000 /*
1001 ** If cert is a v3 certificate, and a critical keyUsage extension is included,
1002 ** then check the usage against the extension value.  If a non-critical
1003 ** keyUsage extension is included, this will return SECSuccess without
1004 ** checking, since the extension is an advisory field, not a restriction.
1005 ** If cert is not a v3 certificate, this will return SECSuccess.
1006 **      cert - certificate
1007 **      usage - one of the x.509 v3 the Key Usage Extension flags
1008 */
1009 extern SECStatus CERT_CheckCertUsage (CERTCertificate *cert,
1010                                                         unsigned char usage);
1011
1012 /****************************************************************************
1013  *
1014  *  CRL v2 Extensions supported routines
1015  *
1016  ****************************************************************************/
1017
1018 extern SECStatus CERT_FindCRLExtensionByOID
1019    (CERTCrl *crl, SECItem *oid, SECItem *value);
1020
1021 extern SECStatus CERT_FindCRLExtension
1022    (CERTCrl *crl, int tag, SECItem *value);
1023
1024 extern SECStatus
1025    CERT_FindInvalidDateExten (CERTCrl *crl, PRTime *value);
1026
1027 /*
1028 ** Set up a crl for adding X509v3 extensions.  Returns an opaque handle
1029 ** used by routines that take an exthandle (void*) argument .
1030 **      "crl" is the CRL we are adding extensions to
1031 */
1032 extern void *CERT_StartCRLExtensions(CERTCrl *crl);
1033
1034 /*
1035 ** Set up a crl entry for adding X509v3 extensions.  Returns an opaque handle
1036 ** used by routines that take an exthandle (void*) argument .
1037 **      "crl" is the crl we are adding certs entries to
1038 **      "entry" is the crl entry we are adding extensions to
1039 */
1040 extern void *CERT_StartCRLEntryExtensions(CERTCrl *crl, CERTCrlEntry *entry);
1041
1042 extern CERTCertNicknames *CERT_GetCertNicknames (CERTCertDBHandle *handle,
1043                                                  int what, void *wincx);
1044
1045 /*
1046 ** Finds the crlNumber extension and decodes its value into 'value'
1047 */
1048 extern SECStatus CERT_FindCRLNumberExten (PLArenaPool *arena, CERTCrl *crl,
1049                                           SECItem *value);
1050
1051 extern SECStatus CERT_FindCRLEntryReasonExten (CERTCrlEntry *crlEntry,
1052                                                CERTCRLEntryReasonCode *value);
1053
1054 extern void CERT_FreeNicknames(CERTCertNicknames *nicknames);
1055
1056 extern PRBool CERT_CompareCerts(CERTCertificate *c1, CERTCertificate *c2);
1057
1058 extern PRBool CERT_CompareCertsForRedirection(CERTCertificate *c1,
1059                                                          CERTCertificate *c2);
1060
1061 /*
1062 ** Generate an array of the Distinguished Names that the given cert database
1063 ** "trusts"
1064 */
1065 extern CERTDistNames *CERT_GetSSLCACerts(CERTCertDBHandle *handle);
1066
1067 extern void CERT_FreeDistNames(CERTDistNames *names);
1068
1069 /*
1070 ** Generate an array of Distinguished names from an array of nicknames
1071 */
1072 extern CERTDistNames *CERT_DistNamesFromNicknames
1073    (CERTCertDBHandle *handle, char **nicknames, int nnames);
1074
1075 /*
1076 ** Generate a certificate chain from a certificate.
1077 */
1078 extern CERTCertificateList *
1079 CERT_CertChainFromCert(CERTCertificate *cert, SECCertUsage usage,
1080                        PRBool includeRoot);
1081
1082 extern CERTCertificateList *
1083 CERT_CertListFromCert(CERTCertificate *cert);
1084
1085 extern CERTCertificateList *
1086 CERT_DupCertList(CERTCertificateList * oldList);
1087
1088 extern void CERT_DestroyCertificateList(CERTCertificateList *list);
1089
1090 /*
1091 ** is cert a user cert? i.e. does it have CERTDB_USER trust,
1092 ** i.e. a private key?
1093 */
1094 PRBool CERT_IsUserCert(CERTCertificate* cert);
1095
1096 /* is cert a newer than cert b? */
1097 PRBool CERT_IsNewer(CERTCertificate *certa, CERTCertificate *certb);
1098
1099 /* currently a stub for address book */
1100 PRBool
1101 CERT_IsCertRevoked(CERTCertificate *cert);
1102
1103 void
1104 CERT_DestroyCertArray(CERTCertificate **certs, unsigned int ncerts);
1105
1106 /* convert an email address to lower case */
1107 char *CERT_FixupEmailAddr(const char *emailAddr);
1108
1109 /* decode string representation of trust flags into trust struct */
1110 SECStatus
1111 CERT_DecodeTrustString(CERTCertTrust *trust, char *trusts);
1112
1113 /* encode trust struct into string representation of trust flags */
1114 char *
1115 CERT_EncodeTrustString(CERTCertTrust *trust);
1116
1117 /* find the next or prev cert in a subject list */
1118 CERTCertificate *
1119 CERT_PrevSubjectCert(CERTCertificate *cert);
1120 CERTCertificate *
1121 CERT_NextSubjectCert(CERTCertificate *cert);
1122
1123 /*
1124  * import a collection of certs into the temporary or permanent cert
1125  * database
1126  */
1127 SECStatus
1128 CERT_ImportCerts(CERTCertDBHandle *certdb, SECCertUsage usage,
1129                  unsigned int ncerts, SECItem **derCerts,
1130                  CERTCertificate ***retCerts, PRBool keepCerts,
1131                  PRBool caOnly, char *nickname);
1132
1133 char *
1134 CERT_MakeCANickname(CERTCertificate *cert);
1135
1136 PRBool
1137 CERT_IsCACert(CERTCertificate *cert, unsigned int *rettype);
1138
1139 PRBool
1140 CERT_IsCADERCert(SECItem *derCert, unsigned int *rettype);
1141
1142 PRBool
1143 CERT_IsRootDERCert(SECItem *derCert);
1144
1145 SECStatus
1146 CERT_SaveSMimeProfile(CERTCertificate *cert, SECItem *emailProfile,
1147                       SECItem *profileTime);
1148
1149 /*
1150  * find the smime symmetric capabilities profile for a given cert
1151  */
1152 SECItem *
1153 CERT_FindSMimeProfile(CERTCertificate *cert);
1154
1155 SECStatus
1156 CERT_AddNewCerts(CERTCertDBHandle *handle);
1157
1158 CERTCertificatePolicies *
1159 CERT_DecodeCertificatePoliciesExtension(SECItem *extnValue);
1160
1161 void
1162 CERT_DestroyCertificatePoliciesExtension(CERTCertificatePolicies *policies);
1163
1164 CERTCertificatePolicyMappings *
1165 CERT_DecodePolicyMappingsExtension(SECItem *encodedCertPolicyMaps);
1166
1167 SECStatus
1168 CERT_DestroyPolicyMappingsExtension(CERTCertificatePolicyMappings *mappings);
1169
1170 SECStatus
1171 CERT_DecodePolicyConstraintsExtension(
1172     CERTCertificatePolicyConstraints *decodedValue, SECItem *encodedValue);
1173
1174 SECStatus CERT_DecodeInhibitAnyExtension
1175     (CERTCertificateInhibitAny *decodedValue, SECItem *extnValue);
1176
1177 CERTUserNotice *
1178 CERT_DecodeUserNotice(SECItem *noticeItem);
1179
1180 extern CERTGeneralName *
1181 CERT_DecodeAltNameExtension(PLArenaPool *reqArena, SECItem *EncodedAltName);
1182
1183 extern CERTNameConstraints *
1184 CERT_DecodeNameConstraintsExtension(PLArenaPool *arena,
1185                                     SECItem *encodedConstraints);
1186
1187 /* returns addr of a NULL termainated array of pointers to CERTAuthInfoAccess */
1188 extern CERTAuthInfoAccess **
1189 CERT_DecodeAuthInfoAccessExtension(PLArenaPool *reqArena,
1190                                    SECItem     *encodedExtension);
1191
1192 extern CERTPrivKeyUsagePeriod *
1193 CERT_DecodePrivKeyUsagePeriodExtension(PLArenaPool *arena, SECItem *extnValue);
1194
1195 extern CERTGeneralName *
1196 CERT_GetNextGeneralName(CERTGeneralName *current);
1197
1198 extern CERTGeneralName *
1199 CERT_GetPrevGeneralName(CERTGeneralName *current);
1200
1201 CERTNameConstraint *
1202 CERT_GetNextNameConstraint(CERTNameConstraint *current);
1203
1204 CERTNameConstraint *
1205 CERT_GetPrevNameConstraint(CERTNameConstraint *current);
1206
1207 void
1208 CERT_DestroyUserNotice(CERTUserNotice *userNotice);
1209
1210 typedef char * (* CERTPolicyStringCallback)(char *org,
1211                                                unsigned long noticeNumber,
1212                                                void *arg);
1213 void
1214 CERT_SetCAPolicyStringCallback(CERTPolicyStringCallback cb, void *cbarg);
1215
1216 char *
1217 CERT_GetCertCommentString(CERTCertificate *cert);
1218
1219 PRBool
1220 CERT_GovtApprovedBitSet(CERTCertificate *cert);
1221
1222 SECStatus
1223 CERT_AddPermNickname(CERTCertificate *cert, char *nickname);
1224
1225 CERTCertList *
1226 CERT_MatchUserCert(CERTCertDBHandle *handle,
1227                    SECCertUsage usage,
1228                    int nCANames, char **caNames,
1229                    void *proto_win);
1230
1231 CERTCertList *
1232 CERT_NewCertList(void);
1233
1234 void
1235 CERT_DestroyCertList(CERTCertList *certs);
1236
1237 /* remove the node and free the cert */
1238 void
1239 CERT_RemoveCertListNode(CERTCertListNode *node);
1240
1241 SECStatus
1242 CERT_AddCertToListTail(CERTCertList *certs, CERTCertificate *cert);
1243
1244 SECStatus
1245 CERT_AddCertToListHead(CERTCertList *certs, CERTCertificate *cert);
1246
1247 SECStatus
1248 CERT_AddCertToListTailWithData(CERTCertList *certs, CERTCertificate *cert,
1249                                                          void *appData);
1250
1251 SECStatus
1252 CERT_AddCertToListHeadWithData(CERTCertList *certs, CERTCertificate *cert,
1253                                                          void *appData);
1254
1255 typedef PRBool (* CERTSortCallback)(CERTCertificate *certa,
1256                                     CERTCertificate *certb,
1257                                     void *arg);
1258 SECStatus
1259 CERT_AddCertToListSorted(CERTCertList *certs, CERTCertificate *cert,
1260                          CERTSortCallback f, void *arg);
1261
1262 /* callback for CERT_AddCertToListSorted that sorts based on validity
1263  * period and a given time.
1264  */
1265 PRBool
1266 CERT_SortCBValidity(CERTCertificate *certa,
1267                     CERTCertificate *certb,
1268                     void *arg);
1269
1270 SECStatus
1271 CERT_CheckForEvilCert(CERTCertificate *cert);
1272
1273 CERTGeneralName *
1274 CERT_GetCertificateNames(CERTCertificate *cert, PLArenaPool *arena);
1275
1276 char *
1277 CERT_GetNickName(CERTCertificate   *cert, CERTCertDBHandle *handle, PLArenaPool *nicknameArena);
1278
1279 /*
1280  * Creates or adds to a list of all certs with a give subject name, sorted by
1281  * validity time, newest first.  Invalid certs are considered older than
1282  * valid certs. If validOnly is set, do not include invalid certs on list.
1283  */
1284 CERTCertList *
1285 CERT_CreateSubjectCertList(CERTCertList *certList, CERTCertDBHandle *handle,
1286                            SECItem *name, PRTime sorttime, PRBool validOnly);
1287
1288 /*
1289  * remove certs from a list that don't have keyUsage and certType
1290  * that match the given usage.
1291  */
1292 SECStatus
1293 CERT_FilterCertListByUsage(CERTCertList *certList, SECCertUsage usage,
1294                            PRBool ca);
1295
1296 /*
1297  * check the key usage of a cert against a set of required values
1298  */
1299 SECStatus
1300 CERT_CheckKeyUsage(CERTCertificate *cert, unsigned int requiredUsage);
1301
1302 /*
1303  * return required key usage and cert type based on cert usage
1304  */
1305 SECStatus
1306 CERT_KeyUsageAndTypeForCertUsage(SECCertUsage usage,
1307                                  PRBool ca,
1308                                  unsigned int *retKeyUsage,
1309                                  unsigned int *retCertType);
1310 /*
1311  * return required trust flags for various cert usages for CAs
1312  */
1313 SECStatus
1314 CERT_TrustFlagsForCACertUsage(SECCertUsage usage,
1315                               unsigned int *retFlags,
1316                               SECTrustType *retTrustType);
1317
1318 /*
1319  * Find all user certificates that match the given criteria.
1320  *
1321  *      "handle" - database to search
1322  *      "usage" - certificate usage to match
1323  *      "oneCertPerName" - if set then only return the "best" cert per
1324  *                      name
1325  *      "validOnly" - only return certs that are curently valid
1326  *      "proto_win" - window handle passed to pkcs11
1327  */
1328 CERTCertList *
1329 CERT_FindUserCertsByUsage(CERTCertDBHandle *handle,
1330                           SECCertUsage usage,
1331                           PRBool oneCertPerName,
1332                           PRBool validOnly,
1333                           void *proto_win);
1334
1335 /*
1336  * Find a user certificate that matchs the given criteria.
1337  *
1338  *      "handle" - database to search
1339  *      "nickname" - nickname to match
1340  *      "usage" - certificate usage to match
1341  *      "validOnly" - only return certs that are curently valid
1342  *      "proto_win" - window handle passed to pkcs11
1343  */
1344 CERTCertificate *
1345 CERT_FindUserCertByUsage(CERTCertDBHandle *handle,
1346                          const char *nickname,
1347                          SECCertUsage usage,
1348                          PRBool validOnly,
1349                          void *proto_win);
1350
1351 /*
1352  * Filter a list of certificates, removing those certs that do not have
1353  * one of the named CA certs somewhere in their cert chain.
1354  *
1355  *      "certList" - the list of certificates to filter
1356  *      "nCANames" - number of CA names
1357  *      "caNames" - array of CA names in string(rfc 1485) form
1358  *      "usage" - what use the certs are for, this is used when
1359  *              selecting CA certs
1360  */
1361 SECStatus
1362 CERT_FilterCertListByCANames(CERTCertList *certList, int nCANames,
1363                              char **caNames, SECCertUsage usage);
1364
1365 /*
1366  * Filter a list of certificates, removing those certs that aren't user certs
1367  */
1368 SECStatus
1369 CERT_FilterCertListForUserCerts(CERTCertList *certList);
1370
1371 /*
1372  * Collect the nicknames from all certs in a CertList.  If the cert is not
1373  * valid, append a string to that nickname.
1374  *
1375  * "certList" - the list of certificates
1376  * "expiredString" - the string to append to the nickname of any expired cert
1377  * "notYetGoodString" - the string to append to the nickname of any cert
1378  *              that is not yet valid
1379  */
1380 CERTCertNicknames *
1381 CERT_NicknameStringsFromCertList(CERTCertList *certList, char *expiredString,
1382                                  char *notYetGoodString);
1383
1384 /*
1385  * Extract the nickname from a nickmake string that may have either
1386  * expiredString or notYetGoodString appended.
1387  *
1388  * Args:
1389  *      "namestring" - the string containing the nickname, and possibly
1390  *              one of the validity label strings
1391  *      "expiredString" - the expired validity label string
1392  *      "notYetGoodString" - the not yet good validity label string
1393  *
1394  * Returns the raw nickname
1395  */
1396 char *
1397 CERT_ExtractNicknameString(char *namestring, char *expiredString,
1398                            char *notYetGoodString);
1399
1400 /*
1401  * Given a certificate, return a string containing the nickname, and possibly
1402  * one of the validity strings, based on the current validity state of the
1403  * certificate.
1404  *
1405  * "arena" - arena to allocate returned string from.  If NULL, then heap
1406  *      is used.
1407  * "cert" - the cert to get nickname from
1408  * "expiredString" - the string to append to the nickname if the cert is
1409  *              expired.
1410  * "notYetGoodString" - the string to append to the nickname if the cert is
1411  *              not yet good.
1412  */
1413 char *
1414 CERT_GetCertNicknameWithValidity(PLArenaPool *arena, CERTCertificate *cert,
1415                                  char *expiredString, char *notYetGoodString);
1416
1417 /*
1418  * Return the string representation of a DER encoded distinguished name
1419  * "dername" - The DER encoded name to convert
1420  */
1421 char *
1422 CERT_DerNameToAscii(SECItem *dername);
1423
1424 /*
1425  * Supported usage values and types:
1426  *      certUsageSSLClient
1427  *      certUsageSSLServer
1428  *      certUsageSSLServerWithStepUp
1429  *      certUsageEmailSigner
1430  *      certUsageEmailRecipient
1431  *      certUsageObjectSigner
1432  */
1433
1434 CERTCertificate *
1435 CERT_FindMatchingCert(CERTCertDBHandle *handle, SECItem *derName,
1436                       CERTCertOwner owner, SECCertUsage usage,
1437                       PRBool preferTrusted, PRTime validTime, PRBool validOnly);
1438
1439 /*
1440  * Acquire the global lock on the cert database.
1441  * This lock is currently used for the following operations:
1442  *      adding or deleting a cert to either the temp or perm databases
1443  *      converting a temp to perm or perm to temp
1444  *      changing(maybe just adding?) the trust of a cert
1445  *      adjusting the reference count of a cert
1446  */
1447 void
1448 CERT_LockDB(CERTCertDBHandle *handle);
1449
1450 /*
1451  * Free the global cert database lock.
1452  */
1453 void
1454 CERT_UnlockDB(CERTCertDBHandle *handle);
1455
1456 /*
1457  * Get the certificate status checking configuratino data for
1458  * the certificate database
1459  */
1460 CERTStatusConfig *
1461 CERT_GetStatusConfig(CERTCertDBHandle *handle);
1462
1463 /*
1464  * Set the certificate status checking information for the
1465  * database.  The input structure becomes part of the certificate
1466  * database and will be freed by calling the 'Destroy' function in
1467  * the configuration object.
1468  */
1469 void
1470 CERT_SetStatusConfig(CERTCertDBHandle *handle, CERTStatusConfig *config);
1471
1472
1473
1474 /*
1475  * Acquire the cert reference count lock
1476  * There is currently one global lock for all certs, but I'm putting a cert
1477  * arg here so that it will be easy to make it per-cert in the future if
1478  * that turns out to be necessary.
1479  */
1480 void
1481 CERT_LockCertRefCount(CERTCertificate *cert);
1482
1483 /*
1484  * Free the cert reference count lock
1485  */
1486 void
1487 CERT_UnlockCertRefCount(CERTCertificate *cert);
1488
1489 /*
1490  * Acquire the cert trust lock
1491  * There is currently one global lock for all certs, but I'm putting a cert
1492  * arg here so that it will be easy to make it per-cert in the future if
1493  * that turns out to be necessary.
1494  */
1495 void
1496 CERT_LockCertTrust(CERTCertificate *cert);
1497
1498 /*
1499  * Free the cert trust lock
1500  */
1501 void
1502 CERT_UnlockCertTrust(CERTCertificate *cert);
1503
1504 /*
1505  * Digest the cert's subject public key using the specified algorithm.
1506  * The necessary storage for the digest data is allocated.  If "fill" is
1507  * non-null, the data is put there, otherwise a SECItem is allocated.
1508  * Allocation from "arena" if it is non-null, heap otherwise.  Any problem
1509  * results in a NULL being returned (and an appropriate error set).
1510  */
1511 extern SECItem *
1512 CERT_GetSPKIDigest(PLArenaPool *arena, const CERTCertificate *cert,
1513                    SECOidTag digestAlg, SECItem *fill);
1514
1515
1516 SECStatus CERT_CheckCRL(CERTCertificate* cert, CERTCertificate* issuer,
1517                         SECItem* dp, PRTime t, void* wincx);
1518
1519
1520 /*
1521  * Add a CERTNameConstraint to the CERTNameConstraint list
1522  */
1523 extern CERTNameConstraint *
1524 CERT_AddNameConstraint(CERTNameConstraint *list,
1525                        CERTNameConstraint *constraint);
1526
1527 /*
1528  * Allocate space and copy CERTNameConstraint from src to dest.
1529  * Arena is used to allocate result(if dest eq NULL) and its members
1530  * SECItem data.
1531  */
1532 extern CERTNameConstraint *
1533 CERT_CopyNameConstraint(PLArenaPool         *arena,
1534                         CERTNameConstraint  *dest,
1535                         CERTNameConstraint  *src);
1536
1537 /*
1538  * Verify name against all the constraints relevant to that type of
1539  * the name.
1540  */
1541 extern SECStatus
1542 CERT_CheckNameSpace(PLArenaPool          *arena,
1543                     CERTNameConstraints  *constraints,
1544                     CERTGeneralName      *currentName);
1545
1546 /*
1547  * Extract and allocate the name constraints extension from the CA cert.
1548  */
1549 extern SECStatus
1550 CERT_FindNameConstraintsExten(PLArenaPool      *arena,
1551                               CERTCertificate  *cert,
1552                               CERTNameConstraints **constraints);
1553
1554 /*
1555  * Initialize a new GERTGeneralName fields (link)
1556  */
1557 extern CERTGeneralName *
1558 CERT_NewGeneralName(PLArenaPool *arena, CERTGeneralNameType type);
1559
1560 /*
1561  * PKIX extension encoding routines
1562  */
1563 extern SECStatus
1564 CERT_EncodePolicyConstraintsExtension(PLArenaPool *arena,
1565                                       CERTCertificatePolicyConstraints *constr,
1566                                       SECItem *dest);
1567 extern SECStatus
1568 CERT_EncodeInhibitAnyExtension(PLArenaPool *arena,
1569                                CERTCertificateInhibitAny *inhibitAny,
1570                                SECItem *dest);
1571 extern SECStatus
1572 CERT_EncodePolicyMappingExtension(PLArenaPool *arena,
1573                                   CERTCertificatePolicyMappings *maps,
1574                                   SECItem *dest);
1575
1576 extern SECStatus CERT_EncodeInfoAccessExtension(PLArenaPool *arena,
1577                                                     CERTAuthInfoAccess **info,
1578                                                     SECItem *dest);
1579 extern SECStatus
1580 CERT_EncodeUserNotice(PLArenaPool *arena,
1581                       CERTUserNotice *notice,
1582                       SECItem *dest);
1583
1584 extern SECStatus
1585 CERT_EncodeDisplayText(PLArenaPool *arena,
1586                        SECItem *text,
1587                        SECItem *dest);
1588
1589 extern SECStatus
1590 CERT_EncodeCertPoliciesExtension(PLArenaPool *arena,
1591                                  CERTPolicyInfo **info,
1592                                  SECItem *dest);
1593 extern SECStatus
1594 CERT_EncodeNoticeReference(PLArenaPool *arena,
1595                            CERTNoticeReference *reference,
1596                            SECItem *dest);
1597
1598 /*
1599  * Returns a pointer to a static structure.
1600  */
1601 extern const CERTRevocationFlags*
1602 CERT_GetPKIXVerifyNistRevocationPolicy();
1603
1604 /*
1605  * Returns a pointer to a static structure.
1606  */
1607 extern const CERTRevocationFlags*
1608 CERT_GetClassicOCSPEnabledSoftFailurePolicy();
1609
1610 /*
1611  * Returns a pointer to a static structure.
1612  */
1613 extern const CERTRevocationFlags*
1614 CERT_GetClassicOCSPEnabledHardFailurePolicy();
1615
1616 /*
1617  * Returns a pointer to a static structure.
1618  */
1619 extern const CERTRevocationFlags*
1620 CERT_GetClassicOCSPDisabledPolicy();
1621
1622 /*
1623  * Verify a Cert with libpkix
1624  *  paramsIn control the verification options. If a value isn't specified
1625  *   in paramsIn, it reverts to the application default.
1626  *  paramsOut specifies the parameters the caller would like to get back.
1627  *   the caller may pass NULL, in which case no parameters are returned.
1628  */
1629 extern SECStatus CERT_PKIXVerifyCert(
1630         CERTCertificate *cert,
1631         SECCertificateUsage usages,
1632         CERTValInParam *paramsIn,
1633         CERTValOutParam *paramsOut,
1634         void *wincx);
1635 /*
1636  * This function changes the application defaults for the Verify function.
1637  * It should be called once at app initialization time, and only changes
1638  * if the default configuration changes.
1639  *
1640  * This changes the default values for the parameters specified. These
1641  * defaults can be overridden in CERT_PKIXVerifyCert() by explicitly
1642  * setting the value in paramsIn.
1643  */
1644 extern SECStatus CERT_PKIXSetDefaults(CERTValInParam *paramsIn);
1645
1646 /* Makes old cert validation APIs(CERT_VerifyCert, CERT_VerifyCertificate)
1647  * to use libpkix validation engine. The function should be called ones at
1648  * application initialization time.
1649  * Function is not thread safe.*/
1650 SECStatus CERT_SetUsePKIXForValidation(PRBool enable);
1651
1652 /* The function return PR_TRUE if cert validation should use
1653  * libpkix cert validation engine. */
1654 PRBool CERT_GetUsePKIXForValidation();
1655
1656 SEC_END_PROTOS
1657
1658 #endif /* _CERT_H_ */