Back to index

lightning-sunbird  0.9+nobinonly
cert.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 /*
00038  * cert.h - public data structures and prototypes for the certificate library
00039  *
00040  * $Id: cert.h,v 1.53 2005/03/09 23:02:47 neil.williams%sun.com Exp $
00041  */
00042 
00043 #ifndef _CERT_H_
00044 #define _CERT_H_
00045 
00046 #include "plarena.h"
00047 #include "plhash.h"
00048 #include "prlong.h"
00049 #include "prlog.h"
00050 
00051 #include "seccomon.h"
00052 #include "secdert.h"
00053 #include "secoidt.h"
00054 #include "keyt.h"
00055 #include "certt.h"
00056 
00057 SEC_BEGIN_PROTOS
00058    
00059 /****************************************************************************
00060  *
00061  * RFC1485 ascii to/from X.? RelativeDistinguishedName (aka CERTName)
00062  *
00063  ****************************************************************************/
00064 
00065 /*
00066 ** Convert an ascii RFC1485 encoded name into its CERTName equivalent.
00067 */
00068 extern CERTName *CERT_AsciiToName(char *string);
00069 
00070 /*
00071 ** Convert an CERTName into its RFC1485 encoded equivalent.
00072 ** Returns a string that must be freed with PORT_Free().
00073 */
00074 extern char *CERT_NameToAscii(CERTName *name);
00075 
00076 extern CERTAVA *CERT_CopyAVA(PRArenaPool *arena, CERTAVA *src);
00077 
00078 /* convert an OID to dotted-decimal representation */
00079 /* Returns a string that must be freed with PR_smprintf_free(). */
00080 extern char * CERT_GetOidString(const SECItem *oid);
00081 
00082 /*
00083 ** Examine an AVA and return the tag that refers to it. The AVA tags are
00084 ** defined as SEC_OID_AVA*.
00085 */
00086 extern SECOidTag CERT_GetAVATag(CERTAVA *ava);
00087 
00088 /*
00089 ** Compare two AVA's, returning the difference between them.
00090 */
00091 extern SECComparison CERT_CompareAVA(const CERTAVA *a, const CERTAVA *b);
00092 
00093 /*
00094 ** Create an RDN (relative-distinguished-name). The argument list is a
00095 ** NULL terminated list of AVA's.
00096 */
00097 extern CERTRDN *CERT_CreateRDN(PRArenaPool *arena, CERTAVA *avas, ...);
00098 
00099 /*
00100 ** Make a copy of "src" storing it in "dest".
00101 */
00102 extern SECStatus CERT_CopyRDN(PRArenaPool *arena, CERTRDN *dest, CERTRDN *src);
00103 
00104 /*
00105 ** Destory an RDN object.
00106 **     "rdn" the RDN to destroy
00107 **     "freeit" if PR_TRUE then free the object as well as its sub-objects
00108 */
00109 extern void CERT_DestroyRDN(CERTRDN *rdn, PRBool freeit);
00110 
00111 /*
00112 ** Add an AVA to an RDN.
00113 **     "rdn" the RDN to add to
00114 **     "ava" the AVA to add
00115 */
00116 extern SECStatus CERT_AddAVA(PRArenaPool *arena, CERTRDN *rdn, CERTAVA *ava);
00117 
00118 /*
00119 ** Compare two RDN's, returning the difference between them.
00120 */
00121 extern SECComparison CERT_CompareRDN(CERTRDN *a, CERTRDN *b);
00122 
00123 /*
00124 ** Create an X.500 style name using a NULL terminated list of RDN's.
00125 */
00126 extern CERTName *CERT_CreateName(CERTRDN *rdn, ...);
00127 
00128 /*
00129 ** Make a copy of "src" storing it in "dest". Memory is allocated in
00130 ** "dest" for each of the appropriate sub objects. Memory is not freed in
00131 ** "dest" before allocation is done (use CERT_DestroyName(dest, PR_FALSE) to
00132 ** do that).
00133 */
00134 extern SECStatus CERT_CopyName(PRArenaPool *arena, CERTName *dest, CERTName *src);
00135 
00136 /*
00137 ** Destroy a Name object.
00138 **     "name" the CERTName to destroy
00139 **     "freeit" if PR_TRUE then free the object as well as its sub-objects
00140 */
00141 extern void CERT_DestroyName(CERTName *name);
00142 
00143 /*
00144 ** Add an RDN to a name.
00145 **     "name" the name to add the RDN to
00146 **     "rdn" the RDN to add to name
00147 */
00148 extern SECStatus CERT_AddRDN(CERTName *name, CERTRDN *rdn);
00149 
00150 /*
00151 ** Compare two names, returning the difference between them.
00152 */
00153 extern SECComparison CERT_CompareName(CERTName *a, CERTName *b);
00154 
00155 /*
00156 ** Convert a CERTName into something readable
00157 */
00158 extern char *CERT_FormatName (CERTName *name);
00159 
00160 /*
00161 ** Convert a der-encoded integer to a hex printable string form.
00162 ** Perhaps this should be a SEC function but it's only used for certs.
00163 */
00164 extern char *CERT_Hexify (SECItem *i, int do_colon);
00165 
00166 /******************************************************************************
00167  *
00168  * Certificate handling operations
00169  *
00170  *****************************************************************************/
00171 
00172 /*
00173 ** Create a new validity object given two unix time values.
00174 **     "notBefore" the time before which the validity is not valid
00175 **     "notAfter" the time after which the validity is not valid
00176 */
00177 extern CERTValidity *CERT_CreateValidity(int64 notBefore, int64 notAfter);
00178 
00179 /*
00180 ** Destroy a validity object.
00181 **     "v" the validity to destroy
00182 **     "freeit" if PR_TRUE then free the object as well as its sub-objects
00183 */
00184 extern void CERT_DestroyValidity(CERTValidity *v);
00185 
00186 /*
00187 ** Copy the "src" object to "dest". Memory is allocated in "dest" for
00188 ** each of the appropriate sub-objects. Memory in "dest" is not freed
00189 ** before memory is allocated (use CERT_DestroyValidity(v, PR_FALSE) to do
00190 ** that).
00191 */
00192 extern SECStatus CERT_CopyValidity
00193    (PRArenaPool *arena, CERTValidity *dest, CERTValidity *src);
00194 
00195 /*
00196 ** The cert lib considers a cert or CRL valid if the "notBefore" time is
00197 ** in the not-too-distant future, e.g. within the next 24 hours. This 
00198 ** prevents freshly issued certificates from being considered invalid
00199 ** because the local system's time zone is incorrectly set.  
00200 ** The amount of "pending slop time" is adjustable by the application.
00201 ** Units of SlopTime are seconds.  Default is 86400  (24 hours).
00202 ** Negative SlopTime values are not allowed.
00203 */
00204 PRInt32 CERT_GetSlopTime(void);
00205 
00206 SECStatus CERT_SetSlopTime(PRInt32 slop);
00207 
00208 /*
00209 ** Create a new certificate object. The result must be wrapped with an
00210 ** CERTSignedData to create a signed certificate.
00211 **     "serialNumber" the serial number
00212 **     "issuer" the name of the certificate issuer
00213 **     "validity" the validity period of the certificate
00214 **     "req" the certificate request that prompted the certificate issuance
00215 */
00216 extern CERTCertificate *
00217 CERT_CreateCertificate (unsigned long serialNumber, CERTName *issuer,
00218                      CERTValidity *validity, CERTCertificateRequest *req);
00219 
00220 /*
00221 ** Destroy a certificate object
00222 **     "cert" the certificate to destroy
00223 ** NOTE: certificate's are reference counted. This call decrements the
00224 ** reference count, and if the result is zero, then the object is destroyed
00225 ** and optionally freed.
00226 */
00227 extern void CERT_DestroyCertificate(CERTCertificate *cert);
00228 
00229 /*
00230 ** Make a shallow copy of a certificate "c". Just increments the
00231 ** reference count on "c".
00232 */
00233 extern CERTCertificate *CERT_DupCertificate(CERTCertificate *c);
00234 
00235 /*
00236 ** Create a new certificate request. This result must be wrapped with an
00237 ** CERTSignedData to create a signed certificate request.
00238 **     "name" the subject name (who the certificate request is from)
00239 **     "spki" describes/defines the public key the certificate is for
00240 **     "attributes" if non-zero, some optional attribute data
00241 */
00242 extern CERTCertificateRequest *
00243 CERT_CreateCertificateRequest (CERTName *name, CERTSubjectPublicKeyInfo *spki,
00244                             SECItem **attributes);
00245 
00246 /*
00247 ** Destroy a certificate-request object
00248 **     "r" the certificate-request to destroy
00249 **     "freeit" if PR_TRUE then free the object as well as its sub-objects
00250 */
00251 extern void CERT_DestroyCertificateRequest(CERTCertificateRequest *r);
00252 
00253 /*
00254 ** Start adding extensions to a certificate request.
00255 */
00256 void *
00257 CERT_StartCertificateRequestAttributes(CERTCertificateRequest *req);
00258 
00259 /*
00260 ** Reformat the certifcate extension list into a CertificateRequest
00261 ** attribute list.
00262 */
00263 SECStatus
00264 CERT_FinishCertificateRequestAttributes(CERTCertificateRequest *req);
00265 
00266 /*
00267 ** Extract the Extension Requests from a DER CertRequest attribute list.
00268 */
00269 SECStatus
00270 CERT_GetCertificateRequestExtensions(CERTCertificateRequest *req,
00271                                      CERTCertExtension ***exts);
00272 
00273 /*
00274 ** Extract a public key object from a certificate
00275 */
00276 extern SECKEYPublicKey *CERT_ExtractPublicKey(CERTCertificate *cert);
00277 
00278 /*
00279  * used to get a public key with Key Material ID. Only used for fortezza V1
00280  * certificates.
00281  */
00282 extern SECKEYPublicKey *CERT_KMIDPublicKey(CERTCertificate *cert);
00283 
00284 
00285 /*
00286 ** Retrieve the Key Type associated with the cert we're dealing with
00287 */
00288 
00289 extern KeyType CERT_GetCertKeyType (CERTSubjectPublicKeyInfo *spki);
00290 
00291 /*
00292 ** Initialize the certificate database.  This is called to create
00293 **  the initial list of certificates in the database.
00294 */
00295 extern SECStatus CERT_InitCertDB(CERTCertDBHandle *handle);
00296 
00297 extern int CERT_GetDBContentVersion(CERTCertDBHandle *handle);
00298 
00299 /*
00300 ** Default certificate database routines
00301 */
00302 extern void CERT_SetDefaultCertDB(CERTCertDBHandle *handle);
00303 
00304 extern CERTCertDBHandle *CERT_GetDefaultCertDB(void);
00305 
00306 extern CERTCertList *CERT_GetCertChainFromCert(CERTCertificate *cert, 
00307                                           int64 time, 
00308                                           SECCertUsage usage);
00309 extern CERTCertificate *
00310 CERT_NewTempCertificate (CERTCertDBHandle *handle, SECItem *derCert,
00311                          char *nickname, PRBool isperm, PRBool copyDER);
00312 
00313 
00314 /******************************************************************************
00315  *
00316  * X.500 Name handling operations
00317  *
00318  *****************************************************************************/
00319 
00320 /*
00321 ** Create an AVA (attribute-value-assertion)
00322 **     "arena" the memory arena to alloc from
00323 **     "kind" is one of SEC_OID_AVA_*
00324 **     "valueType" is one of DER_PRINTABLE_STRING, DER_IA5_STRING, or
00325 **        DER_T61_STRING
00326 **     "value" is the null terminated string containing the value
00327 */
00328 extern CERTAVA *CERT_CreateAVA
00329    (PRArenaPool *arena, SECOidTag kind, int valueType, char *value);
00330 
00331 /*
00332 ** Extract the Distinguished Name from a DER encoded certificate
00333 **     "derCert" is the DER encoded certificate
00334 **     "derName" is the SECItem that the name is returned in
00335 */
00336 extern SECStatus CERT_NameFromDERCert(SECItem *derCert, SECItem *derName);
00337 
00338 /*
00339 ** Extract the Issuers Distinguished Name from a DER encoded certificate
00340 **     "derCert" is the DER encoded certificate
00341 **     "derName" is the SECItem that the name is returned in
00342 */
00343 extern SECStatus CERT_IssuerNameFromDERCert(SECItem *derCert, 
00344                                        SECItem *derName);
00345 
00346 extern SECItem *
00347 CERT_EncodeGeneralName(CERTGeneralName *genName, SECItem *dest,
00348                      PRArenaPool *arena);
00349 
00350 extern CERTGeneralName *
00351 CERT_DecodeGeneralName(PRArenaPool *arena, SECItem *encodedName,
00352                      CERTGeneralName  *genName);
00353 
00354 
00355 
00356 /*
00357 ** Generate a database search key for a certificate, based on the
00358 ** issuer and serial number.
00359 **     "arena" the memory arena to alloc from
00360 **     "derCert" the DER encoded certificate
00361 **     "key" the returned key
00362 */
00363 extern SECStatus CERT_KeyFromDERCert(PRArenaPool *arena, SECItem *derCert, SECItem *key);
00364 
00365 extern SECStatus CERT_KeyFromIssuerAndSN(PRArenaPool *arena, SECItem *issuer,
00366                                     SECItem *sn, SECItem *key);
00367 
00368 extern SECStatus CERT_SerialNumberFromDERCert(SECItem *derCert, 
00369                                           SECItem *derName);
00370 
00371 
00372 /*
00373 ** Generate a database search key for a crl, based on the
00374 ** issuer.
00375 **     "arena" the memory arena to alloc from
00376 **     "derCrl" the DER encoded crl
00377 **     "key" the returned key
00378 */
00379 extern SECStatus CERT_KeyFromDERCrl(PRArenaPool *arena, SECItem *derCrl, SECItem *key);
00380 
00381 /*
00382 ** Open the certificate database.  Use callback to get name of database.
00383 */
00384 extern SECStatus CERT_OpenCertDB(CERTCertDBHandle *handle, PRBool readOnly,
00385                              CERTDBNameFunc namecb, void *cbarg);
00386 
00387 /* Open the certificate database.  Use given filename for database. */
00388 extern SECStatus CERT_OpenCertDBFilename(CERTCertDBHandle *handle,
00389                                     char *certdbname, PRBool readOnly);
00390 
00391 /*
00392 ** Open and initialize a cert database that is entirely in memory.  This
00393 ** can be used when the permanent database can not be opened or created.
00394 */
00395 extern SECStatus CERT_OpenVolatileCertDB(CERTCertDBHandle *handle);
00396 
00397 /*
00398 ** Check the hostname to make sure that it matches the shexp that
00399 ** is given in the common name of the certificate.
00400 */
00401 extern SECStatus CERT_VerifyCertName(CERTCertificate *cert, const char *hostname);
00402 
00403 /*
00404 ** Add a domain name to the list of names that the user has explicitly
00405 ** allowed (despite cert name mismatches) for use with a server cert.
00406 */
00407 extern SECStatus CERT_AddOKDomainName(CERTCertificate *cert, const char *hostname);
00408 
00409 /*
00410 ** Decode a DER encoded certificate into an CERTCertificate structure
00411 **     "derSignedCert" is the DER encoded signed certificate
00412 **     "copyDER" is true if the DER should be copied, false if the
00413 **            existing copy should be referenced
00414 **     "nickname" is the nickname to use in the database.  If it is NULL
00415 **            then a temporary nickname is generated.
00416 */
00417 extern CERTCertificate *
00418 CERT_DecodeDERCertificate (SECItem *derSignedCert, PRBool copyDER, char *nickname);
00419 /*
00420 ** Decode a DER encoded CRL/KRL into an CERTSignedCrl structure
00421 **     "derSignedCrl" is the DER encoded signed crl/krl.
00422 **     "type" is this a CRL or KRL.
00423 */
00424 #define SEC_CRL_TYPE 1
00425 #define SEC_KRL_TYPE 0
00426 
00427 extern CERTSignedCrl *
00428 CERT_DecodeDERCrl (PRArenaPool *arena, SECItem *derSignedCrl,int type);
00429 
00430 /*
00431  * same as CERT_DecodeDERCrl, plus allow options to be passed in
00432  */
00433 
00434 extern CERTSignedCrl *
00435 CERT_DecodeDERCrlWithFlags(PRArenaPool *narena, SECItem *derSignedCrl,
00436                           int type, PRInt32 options);
00437 
00438 /* CRL options to pass */
00439 
00440 #define CRL_DECODE_DEFAULT_OPTIONS          0x00000000
00441 
00442 /* when CRL_DECODE_DONT_COPY_DER is set, the DER is not copied . The
00443    application must then keep derSignedCrl until it destroys the
00444    CRL . Ideally, it should allocate derSignedCrl in an arena
00445    and pass that arena in as the first argument to
00446    CERT_DecodeDERCrlWithFlags */
00447 
00448 #define CRL_DECODE_DONT_COPY_DER            0x00000001
00449 #define CRL_DECODE_SKIP_ENTRIES             0x00000002
00450 #define CRL_DECODE_KEEP_BAD_CRL             0x00000004
00451 #define CRL_DECODE_ADOPT_HEAP_DER           0x00000008
00452 
00453 /* complete the decoding of a partially decoded CRL, ie. decode the
00454    entries. Note that entries is an optional field in a CRL, so the
00455    "entries" pointer in CERTCrlStr may still be NULL even after
00456    function returns SECSuccess */
00457 
00458 extern SECStatus CERT_CompleteCRLDecodeEntries(CERTSignedCrl* crl);
00459 
00460 /* Validate CRL then import it to the dbase.  If there is already a CRL with the
00461  * same CA in the dbase, it will be replaced if derCRL is more up to date.  
00462  * If the process successes, a CRL will be returned.  Otherwise, a NULL will 
00463  * be returned. The caller should call PORT_GetError() for the exactly error 
00464  * code.
00465  */
00466 extern CERTSignedCrl *
00467 CERT_ImportCRL (CERTCertDBHandle *handle, SECItem *derCRL, char *url, 
00468                                           int type, void * wincx);
00469 
00470 extern void CERT_DestroyCrl (CERTSignedCrl *crl);
00471 
00472 /* this is a hint to flush the CRL cache. crlKey is the DER subject of
00473    the issuer (CA). */
00474 void CERT_CRLCacheRefreshIssuer(CERTCertDBHandle* dbhandle, SECItem* crlKey);
00475 
00476 /* add the specified DER CRL object to the CRL cache. Doing so will allow
00477    certificate verification functions (such as CERT_VerifyCertificate)
00478    to automatically find and make use of this CRL object.
00479    Once a CRL is added to the CRL cache, the application must hold on to
00480    the object's memory, because the cache will reference it directly. The
00481    application can only free the object after it calls CERT_UncacheCRL to
00482    remove it from the CRL cache.
00483 */
00484 SECStatus CERT_CacheCRL(CERTCertDBHandle* dbhandle, SECItem* newcrl);
00485 
00486 /* remove a previously added CRL object from the CRL cache. It is OK
00487    for the application to free the memory after a successful removal
00488 */
00489 SECStatus CERT_UncacheCRL(CERTCertDBHandle* dbhandle, SECItem* oldcrl);
00490 
00491 /*
00492 ** Decode a certificate and put it into the temporary certificate database
00493 */
00494 extern CERTCertificate *
00495 CERT_DecodeCertificate (SECItem *derCert, char *nickname,PRBool copyDER);
00496 
00497 /*
00498 ** Find a certificate in the database
00499 **     "key" is the database key to look for
00500 */
00501 extern CERTCertificate *CERT_FindCertByKey(CERTCertDBHandle *handle, SECItem *key);
00502 
00503 /*
00504 ** Find a certificate in the database by name
00505 **     "name" is the distinguished name to look up
00506 */
00507 extern CERTCertificate *
00508 CERT_FindCertByName (CERTCertDBHandle *handle, SECItem *name);
00509 
00510 /*
00511 ** Find a certificate in the database by name
00512 **     "name" is the distinguished name to look up (in ascii)
00513 */
00514 extern CERTCertificate *
00515 CERT_FindCertByNameString (CERTCertDBHandle *handle, char *name);
00516 
00517 /*
00518 ** Find a certificate in the database by name and keyid
00519 **     "name" is the distinguished name to look up
00520 **     "keyID" is the value of the subjectKeyID to match
00521 */
00522 extern CERTCertificate *
00523 CERT_FindCertByKeyID (CERTCertDBHandle *handle, SECItem *name, SECItem *keyID);
00524 
00525 /*
00526 ** Generate a certificate key from the issuer and serialnumber, then look it
00527 ** up in the database.  Return the cert if found.
00528 **     "issuerAndSN" is the issuer and serial number to look for
00529 */
00530 extern CERTCertificate *
00531 CERT_FindCertByIssuerAndSN (CERTCertDBHandle *handle, CERTIssuerAndSN *issuerAndSN);
00532 
00533 /*
00534 ** Find a certificate in the database by a subject key ID
00535 **     "subjKeyID" is the subject Key ID to look for
00536 */
00537 extern CERTCertificate *
00538 CERT_FindCertBySubjectKeyID (CERTCertDBHandle *handle, SECItem *subjKeyID);
00539 
00540 /*
00541 ** Find a certificate in the database by a nickname
00542 **     "nickname" is the ascii string nickname to look for
00543 */
00544 extern CERTCertificate *
00545 CERT_FindCertByNickname (CERTCertDBHandle *handle, char *nickname);
00546 
00547 /*
00548 ** Find a certificate in the database by a DER encoded certificate
00549 **     "derCert" is the DER encoded certificate
00550 */
00551 extern CERTCertificate *
00552 CERT_FindCertByDERCert(CERTCertDBHandle *handle, SECItem *derCert);
00553 
00554 /*
00555 ** Find a certificate in the database by a email address
00556 **     "emailAddr" is the email address to look up
00557 */
00558 CERTCertificate *
00559 CERT_FindCertByEmailAddr(CERTCertDBHandle *handle, char *emailAddr);
00560 
00561 /*
00562 ** Find a certificate in the database by a email address or nickname
00563 **     "name" is the email address or nickname to look up
00564 */
00565 CERTCertificate *
00566 CERT_FindCertByNicknameOrEmailAddr(CERTCertDBHandle *handle, char *name);
00567 
00568 /*
00569 ** Find a certificate in the database by a digest of a subject public key
00570 **     "spkDigest" is the digest to look up
00571 */
00572 extern CERTCertificate *
00573 CERT_FindCertBySPKDigest(CERTCertDBHandle *handle, SECItem *spkDigest);
00574 
00575 /*
00576  * Find the issuer of a cert
00577  */
00578 CERTCertificate *
00579 CERT_FindCertIssuer(CERTCertificate *cert, int64 validTime, SECCertUsage usage);
00580 
00581 /*
00582 ** Check the validity times of a certificate vs. time 't', allowing
00583 ** some slop for broken clocks and stuff.
00584 **     "cert" is the certificate to be checked
00585 **     "t" is the time to check against
00586 **     "allowOverride" if true then check to see if the invalidity has
00587 **            been overridden by the user.
00588 */
00589 extern SECCertTimeValidity CERT_CheckCertValidTimes(CERTCertificate *cert,
00590                                               PRTime t,
00591                                               PRBool allowOverride);
00592 
00593 /*
00594 ** WARNING - this function is depricated, and will either go away or have
00595 **            a new API in the near future.
00596 **
00597 ** Check the validity times of a certificate vs. the current time, allowing
00598 ** some slop for broken clocks and stuff.
00599 **     "cert" is the certificate to be checked
00600 */
00601 extern SECStatus CERT_CertTimesValid(CERTCertificate *cert);
00602 
00603 /*
00604 ** Extract the validity times from a certificate
00605 **     "c" is the certificate
00606 **     "notBefore" is the start of the validity period
00607 **     "notAfter" is the end of the validity period
00608 */
00609 extern SECStatus
00610 CERT_GetCertTimes (CERTCertificate *c, PRTime *notBefore, PRTime *notAfter);
00611 
00612 /*
00613 ** Extract the issuer and serial number from a certificate
00614 */
00615 extern CERTIssuerAndSN *CERT_GetCertIssuerAndSN(PRArenaPool *, 
00616                                                  CERTCertificate *);
00617 
00618 /*
00619 ** verify the signature of a signed data object with a given certificate
00620 **     "sd" the signed data object to be verified
00621 **     "cert" the certificate to use to check the signature
00622 */
00623 extern SECStatus CERT_VerifySignedData(CERTSignedData *sd,
00624                                    CERTCertificate *cert,
00625                                    int64 t,
00626                                    void *wincx);
00627 /*
00628 ** verify the signature of a signed data object with the given DER publickey
00629 */
00630 extern SECStatus
00631 CERT_VerifySignedDataWithPublicKeyInfo(CERTSignedData *sd,
00632                                        CERTSubjectPublicKeyInfo *pubKeyInfo,
00633                                        void *wincx);
00634 
00635 /*
00636 ** verify the signature of a signed data object with a SECKEYPublicKey.
00637 */
00638 extern SECStatus
00639 CERT_VerifySignedDataWithPublicKey(CERTSignedData *sd,
00640                                    SECKEYPublicKey *pubKey, void *wincx);
00641 
00642 /*
00643 ** NEW FUNCTIONS with new bit-field-FIELD SECCertificateUsage - please use
00644 ** verify a certificate by checking validity times against a certain time,
00645 ** that we trust the issuer, and that the signature on the certificate is
00646 ** valid.
00647 **     "cert" the certificate to verify
00648 **     "checkSig" only check signatures if true
00649 */
00650 extern SECStatus
00651 CERT_VerifyCertificate(CERTCertDBHandle *handle, CERTCertificate *cert,
00652               PRBool checkSig, SECCertificateUsage requiredUsages,
00653                 int64 t, void *wincx, CERTVerifyLog *log,
00654                 SECCertificateUsage* returnedUsages);
00655 
00656 /* same as above, but uses current time */
00657 extern SECStatus
00658 CERT_VerifyCertificateNow(CERTCertDBHandle *handle, CERTCertificate *cert,
00659                  PRBool checkSig, SECCertificateUsage requiredUsages,
00660                    void *wincx, SECCertificateUsage* returnedUsages);
00661 
00662 /*
00663 ** Verify that a CA cert can certify some (unspecified) leaf cert for a given
00664 ** purpose. This is used by UI code to help identify where a chain may be
00665 ** broken and why. This takes identical parameters to CERT_VerifyCert
00666 */
00667 extern SECStatus
00668 CERT_VerifyCACertForUsage(CERTCertDBHandle *handle, CERTCertificate *cert,
00669               PRBool checkSig, SECCertUsage certUsage, int64 t,
00670               void *wincx, CERTVerifyLog *log);
00671 
00672 /*
00673 ** OLD OBSOLETE FUNCTIONS with enum SECCertUsage - DO NOT USE FOR NEW CODE
00674 ** verify a certificate by checking validity times against a certain time,
00675 ** that we trust the issuer, and that the signature on the certificate is
00676 ** valid.
00677 **     "cert" the certificate to verify
00678 **     "checkSig" only check signatures if true
00679 */
00680 extern SECStatus
00681 CERT_VerifyCert(CERTCertDBHandle *handle, CERTCertificate *cert,
00682               PRBool checkSig, SECCertUsage certUsage, int64 t,
00683               void *wincx, CERTVerifyLog *log);
00684 
00685 /* same as above, but uses current time */
00686 extern SECStatus
00687 CERT_VerifyCertNow(CERTCertDBHandle *handle, CERTCertificate *cert,
00688                  PRBool checkSig, SECCertUsage certUsage, void *wincx);
00689 
00690 SECStatus
00691 CERT_VerifyCertChain(CERTCertDBHandle *handle, CERTCertificate *cert,
00692                    PRBool checkSig, SECCertUsage certUsage, int64 t,
00693                    void *wincx, CERTVerifyLog *log);
00694 
00695 /*
00696 ** Read a base64 ascii encoded DER certificate and convert it to our
00697 ** internal format.
00698 **     "certstr" is a null-terminated string containing the certificate
00699 */
00700 extern CERTCertificate *CERT_ConvertAndDecodeCertificate(char *certstr);
00701 
00702 /*
00703 ** Read a certificate in some foreign format, and convert it to our
00704 ** internal format.
00705 **     "certbuf" is the buffer containing the certificate
00706 **     "certlen" is the length of the buffer
00707 ** NOTE - currently supports netscape base64 ascii encoded raw certs
00708 **  and netscape binary DER typed files.
00709 */
00710 extern CERTCertificate *CERT_DecodeCertFromPackage(char *certbuf, int certlen);
00711 
00712 extern SECStatus
00713 CERT_ImportCAChain (SECItem *certs, int numcerts, SECCertUsage certUsage);
00714 
00715 extern SECStatus
00716 CERT_ImportCAChainTrusted(SECItem *certs, int numcerts, SECCertUsage certUsage);
00717 
00718 /*
00719 ** Read a certificate chain in some foreign format, and pass it to a 
00720 ** callback function.
00721 **     "certbuf" is the buffer containing the certificate
00722 **     "certlen" is the length of the buffer
00723 **     "f" is the callback function
00724 **     "arg" is the callback argument
00725 */
00726 typedef SECStatus (PR_CALLBACK *CERTImportCertificateFunc)
00727    (void *arg, SECItem **certs, int numcerts);
00728 
00729 extern SECStatus
00730 CERT_DecodeCertPackage(char *certbuf, int certlen, CERTImportCertificateFunc f,
00731                      void *arg);
00732 
00733 /*
00734 ** Pretty print a certificate in HTML
00735 **     "cert" is the certificate to print
00736 **     "showImages" controls whether or not to use about:security URLs
00737 **            for subject and issuer images.  This should only be true
00738 **            in the browser.
00739 */
00740 extern char *CERT_HTMLCertInfo(CERTCertificate *cert, PRBool showImages,
00741                             PRBool showIssuer);
00742 
00743 /* 
00744 ** Returns the value of an AVA.  This was a formerly static 
00745 ** function that has been exposed due to the need to decode
00746 ** and convert unicode strings to UTF8.  
00747 **
00748 ** XXX This function resides in certhtml.c, should it be
00749 ** moved elsewhere?
00750 */
00751 extern SECItem *CERT_DecodeAVAValue(const SECItem *derAVAValue);
00752 
00753 
00754 
00755 /*
00756 ** extract various element strings from a distinguished name.
00757 **     "name" the distinguished name
00758 */
00759 
00760 extern char *CERT_GetCertificateEmailAddress(CERTCertificate *cert);
00761 
00762 extern char *CERT_GetCertEmailAddress(CERTName *name);
00763 
00764 extern const char * CERT_GetFirstEmailAddress(CERTCertificate * cert);
00765 
00766 extern const char * CERT_GetNextEmailAddress(CERTCertificate * cert, 
00767                                              const char * prev);
00768 
00769 /* The return value must be freed with PORT_Free. */
00770 extern char *CERT_GetCommonName(CERTName *name);
00771 
00772 extern char *CERT_GetCountryName(CERTName *name);
00773 
00774 extern char *CERT_GetLocalityName(CERTName *name);
00775 
00776 extern char *CERT_GetStateName(CERTName *name);
00777 
00778 extern char *CERT_GetOrgName(CERTName *name);
00779 
00780 extern char *CERT_GetOrgUnitName(CERTName *name);
00781 
00782 extern char *CERT_GetDomainComponentName(CERTName *name);
00783 
00784 extern char *CERT_GetCertUid(CERTName *name);
00785 
00786 /* manipulate the trust parameters of a certificate */
00787 
00788 extern SECStatus CERT_GetCertTrust(CERTCertificate *cert, CERTCertTrust *trust);
00789 
00790 extern SECStatus
00791 CERT_ChangeCertTrust (CERTCertDBHandle *handle, CERTCertificate *cert,
00792                     CERTCertTrust *trust);
00793 
00794 extern SECStatus
00795 CERT_ChangeCertTrustByUsage(CERTCertDBHandle *certdb, CERTCertificate *cert,
00796                          SECCertUsage usage);
00797 
00798 /*************************************************************************
00799  *
00800  * manipulate the extensions of a certificate
00801  *
00802  ************************************************************************/
00803 
00804 /*
00805 ** Set up a cert for adding X509v3 extensions.  Returns an opaque handle
00806 ** used by the next two routines.
00807 **     "cert" is the certificate we are adding extensions to
00808 */
00809 extern void *CERT_StartCertExtensions(CERTCertificate *cert);
00810 
00811 /*
00812 ** Add an extension to a certificate.
00813 **     "exthandle" is the handle returned by the previous function
00814 **     "idtag" is the integer tag for the OID that should ID this extension
00815 **     "value" is the value of the extension
00816 **     "critical" is the critical extension flag
00817 **     "copyData" is a flag indicating whether the value data should be
00818 **            copied.
00819 */
00820 extern SECStatus CERT_AddExtension (void *exthandle, int idtag, 
00821                      SECItem *value, PRBool critical, PRBool copyData);
00822 
00823 extern SECStatus CERT_AddExtensionByOID (void *exthandle, SECItem *oid,
00824                       SECItem *value, PRBool critical, PRBool copyData);
00825 
00826 extern SECStatus CERT_EncodeAndAddExtension
00827    (void *exthandle, int idtag, void *value, PRBool critical,
00828     const SEC_ASN1Template *atemplate);
00829 
00830 extern SECStatus CERT_EncodeAndAddBitStrExtension
00831    (void *exthandle, int idtag, SECItem *value, PRBool critical);
00832 
00833 
00834 extern SECStatus
00835 CERT_EncodeAltNameExtension(PRArenaPool *arena,  CERTGeneralName  *value, SECItem *encodedValue);
00836 
00837 
00838 /*
00839 ** Finish adding cert extensions.  Does final processing on extension
00840 ** data, putting it in the right format, and freeing any temporary
00841 ** storage.
00842 **     "exthandle" is the handle used to add extensions to a certificate
00843 */
00844 extern SECStatus CERT_FinishExtensions(void *exthandle);
00845 
00846 /*
00847 ** Merge an external list of extensions into a cert's extension list, adding one
00848 ** only when its OID matches none of the cert's existing extensions. Call this
00849 ** immediately before calling CERT_FinishExtensions().
00850 */
00851 SECStatus
00852 CERT_MergeExtensions(void *exthandle, CERTCertExtension **exts);
00853 
00854 /* If the extension is found, return its criticality and value.
00855 ** This allocate storage for the returning extension value.
00856 */
00857 extern SECStatus CERT_GetExtenCriticality
00858    (CERTCertExtension **extensions, int tag, PRBool *isCritical);
00859 
00860 extern void
00861 CERT_DestroyOidSequence(CERTOidSequence *oidSeq);
00862 
00863 /****************************************************************************
00864  *
00865  * DER encode and decode extension values
00866  *
00867  ****************************************************************************/
00868 
00869 /* Encode the value of the basicConstraint extension.
00870 **     arena - where to allocate memory for the encoded value.
00871 **     value - extension value to encode
00872 **     encodedValue - output encoded value
00873 */
00874 extern SECStatus CERT_EncodeBasicConstraintValue
00875    (PRArenaPool *arena, CERTBasicConstraints *value, SECItem *encodedValue);
00876 
00877 /*
00878 ** Encode the value of the authorityKeyIdentifier extension.
00879 */
00880 extern SECStatus CERT_EncodeAuthKeyID
00881    (PRArenaPool *arena, CERTAuthKeyID *value, SECItem *encodedValue);
00882 
00883 /*
00884 ** Encode the value of the crlDistributionPoints extension.
00885 */
00886 extern SECStatus CERT_EncodeCRLDistributionPoints
00887    (PRArenaPool *arena, CERTCrlDistributionPoints *value,SECItem *derValue);
00888 
00889 /*
00890 ** Decodes a DER encoded basicConstaint extension value into a readable format
00891 **     value - decoded value
00892 **     encodedValue - value to decoded
00893 */
00894 extern SECStatus CERT_DecodeBasicConstraintValue
00895    (CERTBasicConstraints *value, SECItem *encodedValue);
00896 
00897 /* Decodes a DER encoded authorityKeyIdentifier extension value into a
00898 ** readable format.
00899 **     arena - where to allocate memory for the decoded value
00900 **     encodedValue - value to be decoded
00901 **     Returns a CERTAuthKeyID structure which contains the decoded value
00902 */
00903 extern CERTAuthKeyID *CERT_DecodeAuthKeyID 
00904                      (PRArenaPool *arena, SECItem *encodedValue);
00905 
00906 
00907 /* Decodes a DER encoded crlDistributionPoints extension value into a 
00908 ** readable format.
00909 **     arena - where to allocate memory for the decoded value
00910 **     der - value to be decoded
00911 **     Returns a CERTCrlDistributionPoints structure which contains the 
00912 **          decoded value
00913 */
00914 extern CERTCrlDistributionPoints * CERT_DecodeCRLDistributionPoints
00915    (PRArenaPool *arena, SECItem *der);
00916 
00917 /* Extract certain name type from a generalName */
00918 extern void *CERT_GetGeneralNameByType
00919    (CERTGeneralName *genNames, CERTGeneralNameType type, PRBool derFormat);
00920 
00921 
00922 extern CERTOidSequence *
00923 CERT_DecodeOidSequence(SECItem *seqItem);
00924 
00925 
00926 
00927 
00928 /****************************************************************************
00929  *
00930  * Find extension values of a certificate 
00931  *
00932  ***************************************************************************/
00933 
00934 extern SECStatus CERT_FindCertExtension
00935    (CERTCertificate *cert, int tag, SECItem *value);
00936 
00937 extern SECStatus CERT_FindNSCertTypeExtension
00938    (CERTCertificate *cert, SECItem *value);
00939 
00940 extern char * CERT_FindNSStringExtension (CERTCertificate *cert, int oidtag);
00941 
00942 extern SECStatus CERT_FindIssuerCertExtension
00943    (CERTCertificate *cert, int tag, SECItem *value);
00944 
00945 extern SECStatus CERT_FindCertExtensionByOID
00946    (CERTCertificate *cert, SECItem *oid, SECItem *value);
00947 
00948 extern char *CERT_FindCertURLExtension (CERTCertificate *cert, int tag, 
00949                                                         int catag);
00950 
00951 /* Returns the decoded value of the authKeyID extension.
00952 **   Note that this uses passed in the arena to allocate storage for the result
00953 */
00954 extern CERTAuthKeyID * CERT_FindAuthKeyIDExten (PRArenaPool *arena,CERTCertificate *cert);
00955 
00956 /* Returns the decoded value of the basicConstraint extension.
00957  */
00958 extern SECStatus CERT_FindBasicConstraintExten
00959    (CERTCertificate *cert, CERTBasicConstraints *value);
00960 
00961 /* Returns the decoded value of the crlDistributionPoints extension.
00962 **  Note that the arena in cert is used to allocate storage for the result
00963 */
00964 extern CERTCrlDistributionPoints * CERT_FindCRLDistributionPoints
00965    (CERTCertificate *cert);
00966 
00967 /* Returns value of the keyUsage extension.  This uses PR_Alloc to allocate 
00968 ** buffer for the decoded value. The caller should free up the storage 
00969 ** allocated in value->data.
00970 */
00971 extern SECStatus CERT_FindKeyUsageExtension (CERTCertificate *cert, 
00972                                                  SECItem *value);
00973 
00974 /* Return the decoded value of the subjectKeyID extension. The caller should 
00975 ** free up the storage allocated in retItem->data.
00976 */
00977 extern SECStatus CERT_FindSubjectKeyIDExtension (CERTCertificate *cert, 
00978                                                     SECItem *retItem);
00979 
00980 /*
00981 ** If cert is a v3 certificate, and a critical keyUsage extension is included,
00982 ** then check the usage against the extension value.  If a non-critical 
00983 ** keyUsage extension is included, this will return SECSuccess without 
00984 ** checking, since the extension is an advisory field, not a restriction.  
00985 ** If cert is not a v3 certificate, this will return SECSuccess.
00986 **     cert - certificate
00987 **     usage - one of the x.509 v3 the Key Usage Extension flags
00988 */
00989 extern SECStatus CERT_CheckCertUsage (CERTCertificate *cert, 
00990                                                  unsigned char usage);
00991 
00992 /****************************************************************************
00993  *
00994  *  CRL v2 Extensions supported routines
00995  *
00996  ****************************************************************************/
00997 
00998 extern SECStatus CERT_FindCRLExtensionByOID
00999    (CERTCrl *crl, SECItem *oid, SECItem *value);
01000 
01001 extern SECStatus CERT_FindCRLExtension
01002    (CERTCrl *crl, int tag, SECItem *value);
01003 
01004 extern SECStatus
01005    CERT_FindInvalidDateExten (CERTCrl *crl, int64 *value);
01006 
01007 /*
01008 ** Set up a crl for adding X509v3 extensions.  Returns an opaque handle
01009 ** used by routines that take an exthandle (void*) argument .
01010 **     "crl" is the CRL we are adding extensions to
01011 */
01012 extern void *CERT_StartCRLExtensions(CERTCrl *crl);
01013 
01014 /*
01015 ** Set up a crl entry for adding X509v3 extensions.  Returns an opaque handle
01016 ** used by routines that take an exthandle (void*) argument .
01017 **     "crl" is the crl we are adding certs entries to
01018 **      "entry" is the crl entry we are adding extensions to
01019 */
01020 extern void *CERT_StartCRLEntryExtensions(CERTCrl *crl, CERTCrlEntry *entry);
01021 
01022 extern CERTCertNicknames *CERT_GetCertNicknames (CERTCertDBHandle *handle,
01023                                            int what, void *wincx);
01024 
01025 /*
01026 ** Finds the crlNumber extension and decodes its value into 'value'
01027 */
01028 extern SECStatus CERT_FindCRLNumberExten (CERTCrl *crl, CERTCrlNumber *value);
01029 
01030 extern void CERT_FreeNicknames(CERTCertNicknames *nicknames);
01031 
01032 extern PRBool CERT_CompareCerts(CERTCertificate *c1, CERTCertificate *c2);
01033 
01034 extern PRBool CERT_CompareCertsForRedirection(CERTCertificate *c1,
01035                                                   CERTCertificate *c2);
01036 
01037 /*
01038 ** Generate an array of the Distinguished Names that the given cert database
01039 ** "trusts"
01040 */
01041 extern CERTDistNames *CERT_GetSSLCACerts(CERTCertDBHandle *handle);
01042 
01043 extern void CERT_FreeDistNames(CERTDistNames *names);
01044 
01045 /*
01046 ** Generate an array of Distinguished names from an array of nicknames
01047 */
01048 extern CERTDistNames *CERT_DistNamesFromNicknames
01049    (CERTCertDBHandle *handle, char **nicknames, int nnames);
01050 
01051 /*
01052 ** Generate a certificate chain from a certificate.
01053 */
01054 extern CERTCertificateList *
01055 CERT_CertChainFromCert(CERTCertificate *cert, SECCertUsage usage,
01056                      PRBool includeRoot);
01057 
01058 extern CERTCertificateList *
01059 CERT_CertListFromCert(CERTCertificate *cert);
01060 
01061 extern CERTCertificateList *
01062 CERT_DupCertList(CERTCertificateList * oldList);
01063 
01064 extern void CERT_DestroyCertificateList(CERTCertificateList *list);
01065 
01066 /*
01067 ** is cert a user cert? i.e. does it have CERTDB_USER trust,
01068 ** i.e. a private key?
01069 */
01070 PRBool CERT_IsUserCert(CERTCertificate* cert);
01071 
01072 /* is cert a newer than cert b? */
01073 PRBool CERT_IsNewer(CERTCertificate *certa, CERTCertificate *certb);
01074 
01075 /* currently a stub for address book */
01076 PRBool
01077 CERT_IsCertRevoked(CERTCertificate *cert);
01078 
01079 void
01080 CERT_DestroyCertArray(CERTCertificate **certs, unsigned int ncerts);
01081 
01082 /* convert an email address to lower case */
01083 char *CERT_FixupEmailAddr(char *emailAddr);
01084 
01085 /* decode string representation of trust flags into trust struct */
01086 SECStatus
01087 CERT_DecodeTrustString(CERTCertTrust *trust, char *trusts);
01088 
01089 /* encode trust struct into string representation of trust flags */
01090 char *
01091 CERT_EncodeTrustString(CERTCertTrust *trust);
01092 
01093 /* find the next or prev cert in a subject list */
01094 CERTCertificate *
01095 CERT_PrevSubjectCert(CERTCertificate *cert);
01096 CERTCertificate *
01097 CERT_NextSubjectCert(CERTCertificate *cert);
01098 
01099 /*
01100  * import a collection of certs into the temporary or permanent cert
01101  * database
01102  */
01103 SECStatus
01104 CERT_ImportCerts(CERTCertDBHandle *certdb, SECCertUsage usage,
01105                unsigned int ncerts, SECItem **derCerts,
01106                CERTCertificate ***retCerts, PRBool keepCerts,
01107                PRBool caOnly, char *nickname);
01108 
01109 SECStatus
01110 CERT_SaveImportedCert(CERTCertificate *cert, SECCertUsage usage,
01111                     PRBool caOnly, char *nickname);
01112 
01113 char *
01114 CERT_MakeCANickname(CERTCertificate *cert);
01115 
01116 PRBool
01117 CERT_IsCACert(CERTCertificate *cert, unsigned int *rettype);
01118 
01119 PRBool
01120 CERT_IsCADERCert(SECItem *derCert, unsigned int *rettype);
01121 
01122 PRBool
01123 CERT_IsRootDERCert(SECItem *derCert);
01124 
01125 SECStatus
01126 CERT_SaveSMimeProfile(CERTCertificate *cert, SECItem *emailProfile,
01127                     SECItem *profileTime);
01128 
01129 /*
01130  * find the smime symmetric capabilities profile for a given cert
01131  */
01132 SECItem *
01133 CERT_FindSMimeProfile(CERTCertificate *cert);
01134 
01135 SECStatus
01136 CERT_AddNewCerts(CERTCertDBHandle *handle);
01137 
01138 CERTPackageType
01139 CERT_CertPackageType(SECItem *package, SECItem *certitem);
01140 
01141 CERTCertificatePolicies *
01142 CERT_DecodeCertificatePoliciesExtension(SECItem *extnValue);
01143 
01144 void
01145 CERT_DestroyCertificatePoliciesExtension(CERTCertificatePolicies *policies);
01146 
01147 CERTUserNotice *
01148 CERT_DecodeUserNotice(SECItem *noticeItem);
01149 
01150 extern CERTGeneralName *
01151 CERT_DecodeAltNameExtension(PRArenaPool *arena, SECItem *EncodedAltName);
01152 
01153 extern CERTNameConstraints *
01154 CERT_DecodeNameConstraintsExtension(PRArenaPool *arena, 
01155                                     SECItem *encodedConstraints);
01156 
01157 /* returns addr of a NULL termainated array of pointers to CERTAuthInfoAccess */
01158 extern CERTAuthInfoAccess **
01159 CERT_DecodeAuthInfoAccessExtension(PRArenaPool *arena,
01160                                SECItem     *encodedExtension);
01161 
01162 extern CERTPrivKeyUsagePeriod *
01163 CERT_DecodePrivKeyUsagePeriodExtension(PLArenaPool *arena, SECItem *extnValue);
01164 
01165 extern CERTGeneralName *
01166 CERT_GetNextGeneralName(CERTGeneralName *current);
01167 
01168 extern CERTGeneralName *
01169 CERT_GetPrevGeneralName(CERTGeneralName *current);
01170 
01171 CERTNameConstraint *
01172 CERT_GetNextNameConstraint(CERTNameConstraint *current);
01173 
01174 CERTNameConstraint *
01175 CERT_GetPrevNameConstraint(CERTNameConstraint *current);
01176 
01177 void
01178 CERT_DestroyUserNotice(CERTUserNotice *userNotice);
01179 
01180 typedef char * (* CERTPolicyStringCallback)(char *org,
01181                                           unsigned long noticeNumber,
01182                                           void *arg);
01183 void
01184 CERT_SetCAPolicyStringCallback(CERTPolicyStringCallback cb, void *cbarg);
01185 
01186 char *
01187 CERT_GetCertCommentString(CERTCertificate *cert);
01188 
01189 PRBool
01190 CERT_GovtApprovedBitSet(CERTCertificate *cert);
01191 
01192 SECStatus
01193 CERT_AddPermNickname(CERTCertificate *cert, char *nickname);
01194 
01195 /*
01196  * Given a cert, find the cert with the same subject name that
01197  * has the given key usage.  If the given cert has the correct keyUsage, then
01198  * return it, otherwise search the list in order.
01199  */
01200 CERTCertificate *
01201 CERT_FindCertByUsage(CERTCertificate *basecert, unsigned int requiredKeyUsage);
01202 
01203 
01204 CERTCertList *
01205 CERT_MatchUserCert(CERTCertDBHandle *handle,
01206                  SECCertUsage usage,
01207                  int nCANames, char **caNames,
01208                  void *proto_win);
01209 
01210 CERTCertList *
01211 CERT_NewCertList(void);
01212 
01213 void
01214 CERT_DestroyCertList(CERTCertList *certs);
01215 
01216 /* remove the node and free the cert */
01217 void
01218 CERT_RemoveCertListNode(CERTCertListNode *node);
01219 
01220 SECStatus
01221 CERT_AddCertToListTail(CERTCertList *certs, CERTCertificate *cert);
01222 
01223 SECStatus
01224 CERT_AddCertToListHead(CERTCertList *certs, CERTCertificate *cert);
01225 
01226 SECStatus
01227 CERT_AddCertToListTailWithData(CERTCertList *certs, CERTCertificate *cert,
01228                                                   void *appData);
01229 
01230 SECStatus
01231 CERT_AddCertToListHeadWithData(CERTCertList *certs, CERTCertificate *cert,
01232                                                   void *appData);
01233 
01234 typedef PRBool (* CERTSortCallback)(CERTCertificate *certa,
01235                                 CERTCertificate *certb,
01236                                 void *arg);
01237 SECStatus
01238 CERT_AddCertToListSorted(CERTCertList *certs, CERTCertificate *cert,
01239                       CERTSortCallback f, void *arg);
01240 
01241 /* callback for CERT_AddCertToListSorted that sorts based on validity
01242  * period and a given time.
01243  */
01244 PRBool
01245 CERT_SortCBValidity(CERTCertificate *certa,
01246                   CERTCertificate *certb,
01247                   void *arg);
01248 
01249 SECStatus
01250 CERT_CheckForEvilCert(CERTCertificate *cert);
01251 
01252 CERTGeneralName *
01253 CERT_GetCertificateNames(CERTCertificate *cert, PRArenaPool *arena);
01254 
01255 
01256 SECStatus 
01257 CERT_EncodeSubjectKeyID(PRArenaPool *arena, char *value, int len, SECItem *encodedValue);
01258 
01259 char *
01260 CERT_GetNickName(CERTCertificate   *cert, CERTCertDBHandle *handle, PRArenaPool *nicknameArena);
01261 
01262 /*
01263  * Creates or adds to a list of all certs with a give subject name, sorted by
01264  * validity time, newest first.  Invalid certs are considered older than
01265  * valid certs. If validOnly is set, do not include invalid certs on list.
01266  */
01267 CERTCertList *
01268 CERT_CreateSubjectCertList(CERTCertList *certList, CERTCertDBHandle *handle,
01269                         SECItem *name, int64 sorttime, PRBool validOnly);
01270 
01271 /*
01272  * Creates or adds to a list of all certs with a give nickname, sorted by
01273  * validity time, newest first.  Invalid certs are considered older than valid
01274  * certs. If validOnly is set, do not include invalid certs on list.
01275  */
01276 CERTCertList *
01277 CERT_CreateNicknameCertList(CERTCertList *certList, CERTCertDBHandle *handle,
01278                          char *nickname, int64 sorttime, PRBool validOnly);
01279 
01280 /*
01281  * Creates or adds to a list of all certs with a give email addr, sorted by
01282  * validity time, newest first.  Invalid certs are considered older than valid
01283  * certs. If validOnly is set, do not include invalid certs on list.
01284  */
01285 CERTCertList *
01286 CERT_CreateEmailAddrCertList(CERTCertList *certList, CERTCertDBHandle *handle,
01287                           char *emailAddr, int64 sorttime, PRBool validOnly);
01288 
01289 /*
01290  * remove certs from a list that don't have keyUsage and certType
01291  * that match the given usage.
01292  */
01293 SECStatus
01294 CERT_FilterCertListByUsage(CERTCertList *certList, SECCertUsage usage,
01295                         PRBool ca);
01296 
01297 /*
01298  * check the key usage of a cert against a set of required values
01299  */
01300 SECStatus
01301 CERT_CheckKeyUsage(CERTCertificate *cert, unsigned int requiredUsage);
01302 
01303 /*
01304  * return required key usage and cert type based on cert usage
01305  */
01306 SECStatus
01307 CERT_KeyUsageAndTypeForCertUsage(SECCertUsage usage,
01308                              PRBool ca,
01309                              unsigned int *retKeyUsage,
01310                              unsigned int *retCertType);
01311 /*
01312  * return required trust flags for various cert usages for CAs
01313  */
01314 SECStatus
01315 CERT_TrustFlagsForCACertUsage(SECCertUsage usage,
01316                            unsigned int *retFlags,
01317                            SECTrustType *retTrustType);
01318 
01319 /*
01320  * Find all user certificates that match the given criteria.
01321  * 
01322  *     "handle" - database to search
01323  *     "usage" - certificate usage to match
01324  *     "oneCertPerName" - if set then only return the "best" cert per
01325  *                   name
01326  *     "validOnly" - only return certs that are curently valid
01327  *     "proto_win" - window handle passed to pkcs11
01328  */
01329 CERTCertList *
01330 CERT_FindUserCertsByUsage(CERTCertDBHandle *handle,
01331                        SECCertUsage usage,
01332                        PRBool oneCertPerName,
01333                        PRBool validOnly,
01334                        void *proto_win);
01335 
01336 /*
01337  * Find a user certificate that matchs the given criteria.
01338  * 
01339  *     "handle" - database to search
01340  *     "nickname" - nickname to match
01341  *     "usage" - certificate usage to match
01342  *     "validOnly" - only return certs that are curently valid
01343  *     "proto_win" - window handle passed to pkcs11
01344  */
01345 CERTCertificate *
01346 CERT_FindUserCertByUsage(CERTCertDBHandle *handle,
01347                       char *nickname,
01348                       SECCertUsage usage,
01349                       PRBool validOnly,
01350                       void *proto_win);
01351 
01352 /*
01353  * Filter a list of certificates, removing those certs that do not have
01354  * one of the named CA certs somewhere in their cert chain.
01355  *
01356  *     "certList" - the list of certificates to filter
01357  *     "nCANames" - number of CA names
01358  *     "caNames" - array of CA names in string(rfc 1485) form
01359  *     "usage" - what use the certs are for, this is used when
01360  *            selecting CA certs
01361  */
01362 SECStatus
01363 CERT_FilterCertListByCANames(CERTCertList *certList, int nCANames,
01364                           char **caNames, SECCertUsage usage);
01365 
01366 /*
01367  * Filter a list of certificates, removing those certs that aren't user certs
01368  */
01369 SECStatus
01370 CERT_FilterCertListForUserCerts(CERTCertList *certList);
01371 
01372 /*
01373  * Collect the nicknames from all certs in a CertList.  If the cert is not
01374  * valid, append a string to that nickname.
01375  *
01376  * "certList" - the list of certificates
01377  * "expiredString" - the string to append to the nickname of any expired cert
01378  * "notYetGoodString" - the string to append to the nickname of any cert
01379  *            that is not yet valid
01380  */
01381 CERTCertNicknames *
01382 CERT_NicknameStringsFromCertList(CERTCertList *certList, char *expiredString,
01383                              char *notYetGoodString);
01384 
01385 /*
01386  * Extract the nickname from a nickmake string that may have either
01387  * expiredString or notYetGoodString appended.
01388  *
01389  * Args:
01390  *     "namestring" - the string containing the nickname, and possibly
01391  *            one of the validity label strings
01392  *     "expiredString" - the expired validity label string
01393  *     "notYetGoodString" - the not yet good validity label string
01394  *
01395  * Returns the raw nickname
01396  */
01397 char *
01398 CERT_ExtractNicknameString(char *namestring, char *expiredString,
01399                         char *notYetGoodString);
01400 
01401 /*
01402  * Given a certificate, return a string containing the nickname, and possibly
01403  * one of the validity strings, based on the current validity state of the
01404  * certificate.
01405  *
01406  * "arena" - arena to allocate returned string from.  If NULL, then heap
01407  *     is used.
01408  * "cert" - the cert to get nickname from
01409  * "expiredString" - the string to append to the nickname if the cert is
01410  *            expired.
01411  * "notYetGoodString" - the string to append to the nickname if the cert is
01412  *            not yet good.
01413  */
01414 char *
01415 CERT_GetCertNicknameWithValidity(PRArenaPool *arena, CERTCertificate *cert,
01416                              char *expiredString, char *notYetGoodString);
01417 
01418 /*
01419  * Return the string representation of a DER encoded distinguished name
01420  * "dername" - The DER encoded name to convert
01421  */
01422 char *
01423 CERT_DerNameToAscii(SECItem *dername);
01424 
01425 /*
01426  * Supported usage values and types:
01427  *     certUsageSSLClient
01428  *     certUsageSSLServer
01429  *     certUsageSSLServerWithStepUp
01430  *     certUsageEmailSigner
01431  *     certUsageEmailRecipient
01432  *     certUsageObjectSigner
01433  */
01434 
01435 CERTCertificate *
01436 CERT_FindMatchingCert(CERTCertDBHandle *handle, SECItem *derName,
01437                     CERTCertOwner owner, SECCertUsage usage,
01438                     PRBool preferTrusted, int64 validTime, PRBool validOnly);
01439 
01440 /*
01441  * Acquire the global lock on the cert database.
01442  * This lock is currently used for the following operations:
01443  *     adding or deleting a cert to either the temp or perm databases
01444  *     converting a temp to perm or perm to temp
01445  *     changing(maybe just adding?) the trust of a cert
01446  *     adjusting the reference count of a cert
01447  */
01448 void
01449 CERT_LockDB(CERTCertDBHandle *handle);
01450 
01451 /*
01452  * Free the global cert database lock.
01453  */
01454 void
01455 CERT_UnlockDB(CERTCertDBHandle *handle);
01456 
01457 /*
01458  * Get the certificate status checking configuratino data for
01459  * the certificate database
01460  */
01461 CERTStatusConfig *
01462 CERT_GetStatusConfig(CERTCertDBHandle *handle);
01463 
01464 /*
01465  * Set the certificate status checking information for the
01466  * database.  The input structure becomes part of the certificate
01467  * database and will be freed by calling the 'Destroy' function in
01468  * the configuration object.
01469  */
01470 void
01471 CERT_SetStatusConfig(CERTCertDBHandle *handle, CERTStatusConfig *config);
01472 
01473 
01474 
01475 /*
01476  * Acquire the cert reference count lock
01477  * There is currently one global lock for all certs, but I'm putting a cert
01478  * arg here so that it will be easy to make it per-cert in the future if
01479  * that turns out to be necessary.
01480  */
01481 void
01482 CERT_LockCertRefCount(CERTCertificate *cert);
01483 
01484 /*
01485  * Free the cert reference count lock
01486  */
01487 void
01488 CERT_UnlockCertRefCount(CERTCertificate *cert);
01489 
01490 /*
01491  * Acquire the cert trust lock
01492  * There is currently one global lock for all certs, but I'm putting a cert
01493  * arg here so that it will be easy to make it per-cert in the future if
01494  * that turns out to be necessary.
01495  */
01496 void
01497 CERT_LockCertTrust(CERTCertificate *cert);
01498 
01499 /*
01500  * Free the cert trust lock
01501  */
01502 void
01503 CERT_UnlockCertTrust(CERTCertificate *cert);
01504 
01505 /*
01506  * Digest the cert's subject public key using the specified algorithm.
01507  * The necessary storage for the digest data is allocated.  If "fill" is
01508  * non-null, the data is put there, otherwise a SECItem is allocated.
01509  * Allocation from "arena" if it is non-null, heap otherwise.  Any problem
01510  * results in a NULL being returned (and an appropriate error set).
01511  */ 
01512 extern SECItem *
01513 CERT_SPKDigestValueForCert(PRArenaPool *arena, CERTCertificate *cert,
01514                         SECOidTag digestAlg, SECItem *fill);
01515 
01516 /*
01517  * fill in nsCertType field of the cert based on the cert extension
01518  */
01519 extern SECStatus cert_GetCertType(CERTCertificate *cert);
01520 
01521 
01522 SECStatus CERT_CheckCRL(CERTCertificate* cert, CERTCertificate* issuer,
01523                         SECItem* dp, int64 t, void* wincx);
01524 
01525 
01526 SEC_END_PROTOS
01527 
01528 #endif /* _CERT_H_ */