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