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.28.2 2007/05/15 23:25:16 julien.pierre.bugs%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 ** Returns the value of an AVA.  This was a formerly static 
00735 ** function that has been exposed due to the need to decode
00736 ** and convert unicode strings to UTF8.  
00737 **
00738 ** XXX This function resides in certhtml.c, should it be
00739 ** moved elsewhere?
00740 */
00741 extern SECItem *CERT_DecodeAVAValue(const SECItem *derAVAValue);
00742 
00743 
00744 
00745 /*
00746 ** extract various element strings from a distinguished name.
00747 **     "name" the distinguished name
00748 */
00749 
00750 extern char *CERT_GetCertificateEmailAddress(CERTCertificate *cert);
00751 
00752 extern char *CERT_GetCertEmailAddress(CERTName *name);
00753 
00754 extern const char * CERT_GetFirstEmailAddress(CERTCertificate * cert);
00755 
00756 extern const char * CERT_GetNextEmailAddress(CERTCertificate * cert, 
00757                                              const char * prev);
00758 
00759 /* The return value must be freed with PORT_Free. */
00760 extern char *CERT_GetCommonName(CERTName *name);
00761 
00762 extern char *CERT_GetCountryName(CERTName *name);
00763 
00764 extern char *CERT_GetLocalityName(CERTName *name);
00765 
00766 extern char *CERT_GetStateName(CERTName *name);
00767 
00768 extern char *CERT_GetOrgName(CERTName *name);
00769 
00770 extern char *CERT_GetOrgUnitName(CERTName *name);
00771 
00772 extern char *CERT_GetDomainComponentName(CERTName *name);
00773 
00774 extern char *CERT_GetCertUid(CERTName *name);
00775 
00776 /* manipulate the trust parameters of a certificate */
00777 
00778 extern SECStatus CERT_GetCertTrust(CERTCertificate *cert, CERTCertTrust *trust);
00779 
00780 extern SECStatus
00781 CERT_ChangeCertTrust (CERTCertDBHandle *handle, CERTCertificate *cert,
00782                     CERTCertTrust *trust);
00783 
00784 extern SECStatus
00785 CERT_ChangeCertTrustByUsage(CERTCertDBHandle *certdb, CERTCertificate *cert,
00786                          SECCertUsage usage);
00787 
00788 /*************************************************************************
00789  *
00790  * manipulate the extensions of a certificate
00791  *
00792  ************************************************************************/
00793 
00794 /*
00795 ** Set up a cert for adding X509v3 extensions.  Returns an opaque handle
00796 ** used by the next two routines.
00797 **     "cert" is the certificate we are adding extensions to
00798 */
00799 extern void *CERT_StartCertExtensions(CERTCertificate *cert);
00800 
00801 /*
00802 ** Add an extension to a certificate.
00803 **     "exthandle" is the handle returned by the previous function
00804 **     "idtag" is the integer tag for the OID that should ID this extension
00805 **     "value" is the value of the extension
00806 **     "critical" is the critical extension flag
00807 **     "copyData" is a flag indicating whether the value data should be
00808 **            copied.
00809 */
00810 extern SECStatus CERT_AddExtension (void *exthandle, int idtag, 
00811                      SECItem *value, PRBool critical, PRBool copyData);
00812 
00813 extern SECStatus CERT_AddExtensionByOID (void *exthandle, SECItem *oid,
00814                       SECItem *value, PRBool critical, PRBool copyData);
00815 
00816 extern SECStatus CERT_EncodeAndAddExtension
00817    (void *exthandle, int idtag, void *value, PRBool critical,
00818     const SEC_ASN1Template *atemplate);
00819 
00820 extern SECStatus CERT_EncodeAndAddBitStrExtension
00821    (void *exthandle, int idtag, SECItem *value, PRBool critical);
00822 
00823 
00824 extern SECStatus
00825 CERT_EncodeAltNameExtension(PRArenaPool *arena,  CERTGeneralName  *value, SECItem *encodedValue);
00826 
00827 
00828 /*
00829 ** Finish adding cert extensions.  Does final processing on extension
00830 ** data, putting it in the right format, and freeing any temporary
00831 ** storage.
00832 **     "exthandle" is the handle used to add extensions to a certificate
00833 */
00834 extern SECStatus CERT_FinishExtensions(void *exthandle);
00835 
00836 /*
00837 ** Merge an external list of extensions into a cert's extension list, adding one
00838 ** only when its OID matches none of the cert's existing extensions. Call this
00839 ** immediately before calling CERT_FinishExtensions().
00840 */
00841 SECStatus
00842 CERT_MergeExtensions(void *exthandle, CERTCertExtension **exts);
00843 
00844 /* If the extension is found, return its criticality and value.
00845 ** This allocate storage for the returning extension value.
00846 */
00847 extern SECStatus CERT_GetExtenCriticality
00848    (CERTCertExtension **extensions, int tag, PRBool *isCritical);
00849 
00850 extern void
00851 CERT_DestroyOidSequence(CERTOidSequence *oidSeq);
00852 
00853 /****************************************************************************
00854  *
00855  * DER encode and decode extension values
00856  *
00857  ****************************************************************************/
00858 
00859 /* Encode the value of the basicConstraint extension.
00860 **     arena - where to allocate memory for the encoded value.
00861 **     value - extension value to encode
00862 **     encodedValue - output encoded value
00863 */
00864 extern SECStatus CERT_EncodeBasicConstraintValue
00865    (PRArenaPool *arena, CERTBasicConstraints *value, SECItem *encodedValue);
00866 
00867 /*
00868 ** Encode the value of the authorityKeyIdentifier extension.
00869 */
00870 extern SECStatus CERT_EncodeAuthKeyID
00871    (PRArenaPool *arena, CERTAuthKeyID *value, SECItem *encodedValue);
00872 
00873 /*
00874 ** Encode the value of the crlDistributionPoints extension.
00875 */
00876 extern SECStatus CERT_EncodeCRLDistributionPoints
00877    (PRArenaPool *arena, CERTCrlDistributionPoints *value,SECItem *derValue);
00878 
00879 /*
00880 ** Decodes a DER encoded basicConstaint extension value into a readable format
00881 **     value - decoded value
00882 **     encodedValue - value to decoded
00883 */
00884 extern SECStatus CERT_DecodeBasicConstraintValue
00885    (CERTBasicConstraints *value, SECItem *encodedValue);
00886 
00887 /* Decodes a DER encoded authorityKeyIdentifier extension value into a
00888 ** readable format.
00889 **     arena - where to allocate memory for the decoded value
00890 **     encodedValue - value to be decoded
00891 **     Returns a CERTAuthKeyID structure which contains the decoded value
00892 */
00893 extern CERTAuthKeyID *CERT_DecodeAuthKeyID 
00894                      (PRArenaPool *arena, SECItem *encodedValue);
00895 
00896 
00897 /* Decodes a DER encoded crlDistributionPoints extension value into a 
00898 ** readable format.
00899 **     arena - where to allocate memory for the decoded value
00900 **     der - value to be decoded
00901 **     Returns a CERTCrlDistributionPoints structure which contains the 
00902 **          decoded value
00903 */
00904 extern CERTCrlDistributionPoints * CERT_DecodeCRLDistributionPoints
00905    (PRArenaPool *arena, SECItem *der);
00906 
00907 /* Extract certain name type from a generalName */
00908 extern void *CERT_GetGeneralNameByType
00909    (CERTGeneralName *genNames, CERTGeneralNameType type, PRBool derFormat);
00910 
00911 
00912 extern CERTOidSequence *
00913 CERT_DecodeOidSequence(SECItem *seqItem);
00914 
00915 
00916 
00917 
00918 /****************************************************************************
00919  *
00920  * Find extension values of a certificate 
00921  *
00922  ***************************************************************************/
00923 
00924 extern SECStatus CERT_FindCertExtension
00925    (CERTCertificate *cert, int tag, SECItem *value);
00926 
00927 extern SECStatus CERT_FindNSCertTypeExtension
00928    (CERTCertificate *cert, SECItem *value);
00929 
00930 extern char * CERT_FindNSStringExtension (CERTCertificate *cert, int oidtag);
00931 
00932 extern SECStatus CERT_FindIssuerCertExtension
00933    (CERTCertificate *cert, int tag, SECItem *value);
00934 
00935 extern SECStatus CERT_FindCertExtensionByOID
00936    (CERTCertificate *cert, SECItem *oid, SECItem *value);
00937 
00938 extern char *CERT_FindCertURLExtension (CERTCertificate *cert, int tag, 
00939                                                         int catag);
00940 
00941 /* Returns the decoded value of the authKeyID extension.
00942 **   Note that this uses passed in the arena to allocate storage for the result
00943 */
00944 extern CERTAuthKeyID * CERT_FindAuthKeyIDExten (PRArenaPool *arena,CERTCertificate *cert);
00945 
00946 /* Returns the decoded value of the basicConstraint extension.
00947  */
00948 extern SECStatus CERT_FindBasicConstraintExten
00949    (CERTCertificate *cert, CERTBasicConstraints *value);
00950 
00951 /* Returns the decoded value of the crlDistributionPoints extension.
00952 **  Note that the arena in cert is used to allocate storage for the result
00953 */
00954 extern CERTCrlDistributionPoints * CERT_FindCRLDistributionPoints
00955    (CERTCertificate *cert);
00956 
00957 /* Returns value of the keyUsage extension.  This uses PR_Alloc to allocate 
00958 ** buffer for the decoded value. The caller should free up the storage 
00959 ** allocated in value->data.
00960 */
00961 extern SECStatus CERT_FindKeyUsageExtension (CERTCertificate *cert, 
00962                                                  SECItem *value);
00963 
00964 /* Return the decoded value of the subjectKeyID extension. The caller should 
00965 ** free up the storage allocated in retItem->data.
00966 */
00967 extern SECStatus CERT_FindSubjectKeyIDExtension (CERTCertificate *cert, 
00968                                                     SECItem *retItem);
00969 
00970 /*
00971 ** If cert is a v3 certificate, and a critical keyUsage extension is included,
00972 ** then check the usage against the extension value.  If a non-critical 
00973 ** keyUsage extension is included, this will return SECSuccess without 
00974 ** checking, since the extension is an advisory field, not a restriction.  
00975 ** If cert is not a v3 certificate, this will return SECSuccess.
00976 **     cert - certificate
00977 **     usage - one of the x.509 v3 the Key Usage Extension flags
00978 */
00979 extern SECStatus CERT_CheckCertUsage (CERTCertificate *cert, 
00980                                                  unsigned char usage);
00981 
00982 /****************************************************************************
00983  *
00984  *  CRL v2 Extensions supported routines
00985  *
00986  ****************************************************************************/
00987 
00988 extern SECStatus CERT_FindCRLExtensionByOID
00989    (CERTCrl *crl, SECItem *oid, SECItem *value);
00990 
00991 extern SECStatus CERT_FindCRLExtension
00992    (CERTCrl *crl, int tag, SECItem *value);
00993 
00994 extern SECStatus
00995    CERT_FindInvalidDateExten (CERTCrl *crl, int64 *value);
00996 
00997 /*
00998 ** Set up a crl for adding X509v3 extensions.  Returns an opaque handle
00999 ** used by routines that take an exthandle (void*) argument .
01000 **     "crl" is the CRL we are adding extensions to
01001 */
01002 extern void *CERT_StartCRLExtensions(CERTCrl *crl);
01003 
01004 /*
01005 ** Set up a crl entry for adding X509v3 extensions.  Returns an opaque handle
01006 ** used by routines that take an exthandle (void*) argument .
01007 **     "crl" is the crl we are adding certs entries to
01008 **      "entry" is the crl entry we are adding extensions to
01009 */
01010 extern void *CERT_StartCRLEntryExtensions(CERTCrl *crl, CERTCrlEntry *entry);
01011 
01012 extern CERTCertNicknames *CERT_GetCertNicknames (CERTCertDBHandle *handle,
01013                                            int what, void *wincx);
01014 
01015 /*
01016 ** Finds the crlNumber extension and decodes its value into 'value'
01017 */
01018 extern SECStatus CERT_FindCRLNumberExten (CERTCrl *crl, CERTCrlNumber *value);
01019 
01020 extern void CERT_FreeNicknames(CERTCertNicknames *nicknames);
01021 
01022 extern PRBool CERT_CompareCerts(CERTCertificate *c1, CERTCertificate *c2);
01023 
01024 extern PRBool CERT_CompareCertsForRedirection(CERTCertificate *c1,
01025                                                   CERTCertificate *c2);
01026 
01027 /*
01028 ** Generate an array of the Distinguished Names that the given cert database
01029 ** "trusts"
01030 */
01031 extern CERTDistNames *CERT_GetSSLCACerts(CERTCertDBHandle *handle);
01032 
01033 extern void CERT_FreeDistNames(CERTDistNames *names);
01034 
01035 /*
01036 ** Generate an array of Distinguished names from an array of nicknames
01037 */
01038 extern CERTDistNames *CERT_DistNamesFromNicknames
01039    (CERTCertDBHandle *handle, char **nicknames, int nnames);
01040 
01041 /*
01042 ** Generate a certificate chain from a certificate.
01043 */
01044 extern CERTCertificateList *
01045 CERT_CertChainFromCert(CERTCertificate *cert, SECCertUsage usage,
01046                      PRBool includeRoot);
01047 
01048 extern CERTCertificateList *
01049 CERT_CertListFromCert(CERTCertificate *cert);
01050 
01051 extern CERTCertificateList *
01052 CERT_DupCertList(CERTCertificateList * oldList);
01053 
01054 extern void CERT_DestroyCertificateList(CERTCertificateList *list);
01055 
01056 /*
01057 ** is cert a user cert? i.e. does it have CERTDB_USER trust,
01058 ** i.e. a private key?
01059 */
01060 PRBool CERT_IsUserCert(CERTCertificate* cert);
01061 
01062 /* is cert a newer than cert b? */
01063 PRBool CERT_IsNewer(CERTCertificate *certa, CERTCertificate *certb);
01064 
01065 /* currently a stub for address book */
01066 PRBool
01067 CERT_IsCertRevoked(CERTCertificate *cert);
01068 
01069 void
01070 CERT_DestroyCertArray(CERTCertificate **certs, unsigned int ncerts);
01071 
01072 /* convert an email address to lower case */
01073 char *CERT_FixupEmailAddr(char *emailAddr);
01074 
01075 /* decode string representation of trust flags into trust struct */
01076 SECStatus
01077 CERT_DecodeTrustString(CERTCertTrust *trust, char *trusts);
01078 
01079 /* encode trust struct into string representation of trust flags */
01080 char *
01081 CERT_EncodeTrustString(CERTCertTrust *trust);
01082 
01083 /* find the next or prev cert in a subject list */
01084 CERTCertificate *
01085 CERT_PrevSubjectCert(CERTCertificate *cert);
01086 CERTCertificate *
01087 CERT_NextSubjectCert(CERTCertificate *cert);
01088 
01089 /*
01090  * import a collection of certs into the temporary or permanent cert
01091  * database
01092  */
01093 SECStatus
01094 CERT_ImportCerts(CERTCertDBHandle *certdb, SECCertUsage usage,
01095                unsigned int ncerts, SECItem **derCerts,
01096                CERTCertificate ***retCerts, PRBool keepCerts,
01097                PRBool caOnly, char *nickname);
01098 
01099 SECStatus
01100 CERT_SaveImportedCert(CERTCertificate *cert, SECCertUsage usage,
01101                     PRBool caOnly, char *nickname);
01102 
01103 char *
01104 CERT_MakeCANickname(CERTCertificate *cert);
01105 
01106 PRBool
01107 CERT_IsCACert(CERTCertificate *cert, unsigned int *rettype);
01108 
01109 PRBool
01110 CERT_IsCADERCert(SECItem *derCert, unsigned int *rettype);
01111 
01112 PRBool
01113 CERT_IsRootDERCert(SECItem *derCert);
01114 
01115 SECStatus
01116 CERT_SaveSMimeProfile(CERTCertificate *cert, SECItem *emailProfile,
01117                     SECItem *profileTime);
01118 
01119 /*
01120  * find the smime symmetric capabilities profile for a given cert
01121  */
01122 SECItem *
01123 CERT_FindSMimeProfile(CERTCertificate *cert);
01124 
01125 SECStatus
01126 CERT_AddNewCerts(CERTCertDBHandle *handle);
01127 
01128 CERTPackageType
01129 CERT_CertPackageType(SECItem *package, SECItem *certitem);
01130 
01131 CERTCertificatePolicies *
01132 CERT_DecodeCertificatePoliciesExtension(SECItem *extnValue);
01133 
01134 void
01135 CERT_DestroyCertificatePoliciesExtension(CERTCertificatePolicies *policies);
01136 
01137 CERTUserNotice *
01138 CERT_DecodeUserNotice(SECItem *noticeItem);
01139 
01140 extern CERTGeneralName *
01141 CERT_DecodeAltNameExtension(PRArenaPool *arena, SECItem *EncodedAltName);
01142 
01143 extern CERTNameConstraints *
01144 CERT_DecodeNameConstraintsExtension(PRArenaPool *arena, 
01145                                     SECItem *encodedConstraints);
01146 
01147 /* returns addr of a NULL termainated array of pointers to CERTAuthInfoAccess */
01148 extern CERTAuthInfoAccess **
01149 CERT_DecodeAuthInfoAccessExtension(PRArenaPool *arena,
01150                                SECItem     *encodedExtension);
01151 
01152 extern CERTPrivKeyUsagePeriod *
01153 CERT_DecodePrivKeyUsagePeriodExtension(PLArenaPool *arena, SECItem *extnValue);
01154 
01155 extern CERTGeneralName *
01156 CERT_GetNextGeneralName(CERTGeneralName *current);
01157 
01158 extern CERTGeneralName *
01159 CERT_GetPrevGeneralName(CERTGeneralName *current);
01160 
01161 CERTNameConstraint *
01162 CERT_GetNextNameConstraint(CERTNameConstraint *current);
01163 
01164 CERTNameConstraint *
01165 CERT_GetPrevNameConstraint(CERTNameConstraint *current);
01166 
01167 void
01168 CERT_DestroyUserNotice(CERTUserNotice *userNotice);
01169 
01170 typedef char * (* CERTPolicyStringCallback)(char *org,
01171                                           unsigned long noticeNumber,
01172                                           void *arg);
01173 void
01174 CERT_SetCAPolicyStringCallback(CERTPolicyStringCallback cb, void *cbarg);
01175 
01176 char *
01177 CERT_GetCertCommentString(CERTCertificate *cert);
01178 
01179 PRBool
01180 CERT_GovtApprovedBitSet(CERTCertificate *cert);
01181 
01182 SECStatus
01183 CERT_AddPermNickname(CERTCertificate *cert, char *nickname);
01184 
01185 /*
01186  * Given a cert, find the cert with the same subject name that
01187  * has the given key usage.  If the given cert has the correct keyUsage, then
01188  * return it, otherwise search the list in order.
01189  */
01190 CERTCertificate *
01191 CERT_FindCertByUsage(CERTCertificate *basecert, unsigned int requiredKeyUsage);
01192 
01193 
01194 CERTCertList *
01195 CERT_MatchUserCert(CERTCertDBHandle *handle,
01196                  SECCertUsage usage,
01197                  int nCANames, char **caNames,
01198                  void *proto_win);
01199 
01200 CERTCertList *
01201 CERT_NewCertList(void);
01202 
01203 void
01204 CERT_DestroyCertList(CERTCertList *certs);
01205 
01206 /* remove the node and free the cert */
01207 void
01208 CERT_RemoveCertListNode(CERTCertListNode *node);
01209 
01210 SECStatus
01211 CERT_AddCertToListTail(CERTCertList *certs, CERTCertificate *cert);
01212 
01213 SECStatus
01214 CERT_AddCertToListHead(CERTCertList *certs, CERTCertificate *cert);
01215 
01216 SECStatus
01217 CERT_AddCertToListTailWithData(CERTCertList *certs, CERTCertificate *cert,
01218                                                   void *appData);
01219 
01220 SECStatus
01221 CERT_AddCertToListHeadWithData(CERTCertList *certs, CERTCertificate *cert,
01222                                                   void *appData);
01223 
01224 typedef PRBool (* CERTSortCallback)(CERTCertificate *certa,
01225                                 CERTCertificate *certb,
01226                                 void *arg);
01227 SECStatus
01228 CERT_AddCertToListSorted(CERTCertList *certs, CERTCertificate *cert,
01229                       CERTSortCallback f, void *arg);
01230 
01231 /* callback for CERT_AddCertToListSorted that sorts based on validity
01232  * period and a given time.
01233  */
01234 PRBool
01235 CERT_SortCBValidity(CERTCertificate *certa,
01236                   CERTCertificate *certb,
01237                   void *arg);
01238 
01239 SECStatus
01240 CERT_CheckForEvilCert(CERTCertificate *cert);
01241 
01242 CERTGeneralName *
01243 CERT_GetCertificateNames(CERTCertificate *cert, PRArenaPool *arena);
01244 
01245 
01246 SECStatus 
01247 CERT_EncodeSubjectKeyID(PRArenaPool *arena, char *value, int len, SECItem *encodedValue);
01248 
01249 char *
01250 CERT_GetNickName(CERTCertificate   *cert, CERTCertDBHandle *handle, PRArenaPool *nicknameArena);
01251 
01252 /*
01253  * Creates or adds to a list of all certs with a give subject name, sorted by
01254  * validity time, newest first.  Invalid certs are considered older than
01255  * valid certs. If validOnly is set, do not include invalid certs on list.
01256  */
01257 CERTCertList *
01258 CERT_CreateSubjectCertList(CERTCertList *certList, CERTCertDBHandle *handle,
01259                         SECItem *name, int64 sorttime, PRBool validOnly);
01260 
01261 /*
01262  * Creates or adds to a list of all certs with a give nickname, sorted by
01263  * validity time, newest first.  Invalid certs are considered older than valid
01264  * certs. If validOnly is set, do not include invalid certs on list.
01265  */
01266 CERTCertList *
01267 CERT_CreateNicknameCertList(CERTCertList *certList, CERTCertDBHandle *handle,
01268                          char *nickname, int64 sorttime, PRBool validOnly);
01269 
01270 /*
01271  * Creates or adds to a list of all certs with a give email addr, sorted by
01272  * validity time, newest first.  Invalid certs are considered older than valid
01273  * certs. If validOnly is set, do not include invalid certs on list.
01274  */
01275 CERTCertList *
01276 CERT_CreateEmailAddrCertList(CERTCertList *certList, CERTCertDBHandle *handle,
01277                           char *emailAddr, int64 sorttime, PRBool validOnly);
01278 
01279 /*
01280  * remove certs from a list that don't have keyUsage and certType
01281  * that match the given usage.
01282  */
01283 SECStatus
01284 CERT_FilterCertListByUsage(CERTCertList *certList, SECCertUsage usage,
01285                         PRBool ca);
01286 
01287 /*
01288  * check the key usage of a cert against a set of required values
01289  */
01290 SECStatus
01291 CERT_CheckKeyUsage(CERTCertificate *cert, unsigned int requiredUsage);
01292 
01293 /*
01294  * return required key usage and cert type based on cert usage
01295  */
01296 SECStatus
01297 CERT_KeyUsageAndTypeForCertUsage(SECCertUsage usage,
01298                              PRBool ca,
01299                              unsigned int *retKeyUsage,
01300                              unsigned int *retCertType);
01301 /*
01302  * return required trust flags for various cert usages for CAs
01303  */
01304 SECStatus
01305 CERT_TrustFlagsForCACertUsage(SECCertUsage usage,
01306                            unsigned int *retFlags,
01307                            SECTrustType *retTrustType);
01308 
01309 /*
01310  * Find all user certificates that match the given criteria.
01311  * 
01312  *     "handle" - database to search
01313  *     "usage" - certificate usage to match
01314  *     "oneCertPerName" - if set then only return the "best" cert per
01315  *                   name
01316  *     "validOnly" - only return certs that are curently valid
01317  *     "proto_win" - window handle passed to pkcs11
01318  */
01319 CERTCertList *
01320 CERT_FindUserCertsByUsage(CERTCertDBHandle *handle,
01321                        SECCertUsage usage,
01322                        PRBool oneCertPerName,
01323                        PRBool validOnly,
01324                        void *proto_win);
01325 
01326 /*
01327  * Find a user certificate that matchs the given criteria.
01328  * 
01329  *     "handle" - database to search
01330  *     "nickname" - nickname to match
01331  *     "usage" - certificate usage to match
01332  *     "validOnly" - only return certs that are curently valid
01333  *     "proto_win" - window handle passed to pkcs11
01334  */
01335 CERTCertificate *
01336 CERT_FindUserCertByUsage(CERTCertDBHandle *handle,
01337                       char *nickname,
01338                       SECCertUsage usage,
01339                       PRBool validOnly,
01340                       void *proto_win);
01341 
01342 /*
01343  * Filter a list of certificates, removing those certs that do not have
01344  * one of the named CA certs somewhere in their cert chain.
01345  *
01346  *     "certList" - the list of certificates to filter
01347  *     "nCANames" - number of CA names
01348  *     "caNames" - array of CA names in string(rfc 1485) form
01349  *     "usage" - what use the certs are for, this is used when
01350  *            selecting CA certs
01351  */
01352 SECStatus
01353 CERT_FilterCertListByCANames(CERTCertList *certList, int nCANames,
01354                           char **caNames, SECCertUsage usage);
01355 
01356 /*
01357  * Filter a list of certificates, removing those certs that aren't user certs
01358  */
01359 SECStatus
01360 CERT_FilterCertListForUserCerts(CERTCertList *certList);
01361 
01362 /*
01363  * Collect the nicknames from all certs in a CertList.  If the cert is not
01364  * valid, append a string to that nickname.
01365  *
01366  * "certList" - the list of certificates
01367  * "expiredString" - the string to append to the nickname of any expired cert
01368  * "notYetGoodString" - the string to append to the nickname of any cert
01369  *            that is not yet valid
01370  */
01371 CERTCertNicknames *
01372 CERT_NicknameStringsFromCertList(CERTCertList *certList, char *expiredString,
01373                              char *notYetGoodString);
01374 
01375 /*
01376  * Extract the nickname from a nickmake string that may have either
01377  * expiredString or notYetGoodString appended.
01378  *
01379  * Args:
01380  *     "namestring" - the string containing the nickname, and possibly
01381  *            one of the validity label strings
01382  *     "expiredString" - the expired validity label string
01383  *     "notYetGoodString" - the not yet good validity label string
01384  *
01385  * Returns the raw nickname
01386  */
01387 char *
01388 CERT_ExtractNicknameString(char *namestring, char *expiredString,
01389                         char *notYetGoodString);
01390 
01391 /*
01392  * Given a certificate, return a string containing the nickname, and possibly
01393  * one of the validity strings, based on the current validity state of the
01394  * certificate.
01395  *
01396  * "arena" - arena to allocate returned string from.  If NULL, then heap
01397  *     is used.
01398  * "cert" - the cert to get nickname from
01399  * "expiredString" - the string to append to the nickname if the cert is
01400  *            expired.
01401  * "notYetGoodString" - the string to append to the nickname if the cert is
01402  *            not yet good.
01403  */
01404 char *
01405 CERT_GetCertNicknameWithValidity(PRArenaPool *arena, CERTCertificate *cert,
01406                              char *expiredString, char *notYetGoodString);
01407 
01408 /*
01409  * Return the string representation of a DER encoded distinguished name
01410  * "dername" - The DER encoded name to convert
01411  */
01412 char *
01413 CERT_DerNameToAscii(SECItem *dername);
01414 
01415 /*
01416  * Supported usage values and types:
01417  *     certUsageSSLClient
01418  *     certUsageSSLServer
01419  *     certUsageSSLServerWithStepUp
01420  *     certUsageEmailSigner
01421  *     certUsageEmailRecipient
01422  *     certUsageObjectSigner
01423  */
01424 
01425 CERTCertificate *
01426 CERT_FindMatchingCert(CERTCertDBHandle *handle, SECItem *derName,
01427                     CERTCertOwner owner, SECCertUsage usage,
01428                     PRBool preferTrusted, int64 validTime, PRBool validOnly);
01429 
01430 /*
01431  * Acquire the global lock on the cert database.
01432  * This lock is currently used for the following operations:
01433  *     adding or deleting a cert to either the temp or perm databases
01434  *     converting a temp to perm or perm to temp
01435  *     changing(maybe just adding?) the trust of a cert
01436  *     adjusting the reference count of a cert
01437  */
01438 void
01439 CERT_LockDB(CERTCertDBHandle *handle);
01440 
01441 /*
01442  * Free the global cert database lock.
01443  */
01444 void
01445 CERT_UnlockDB(CERTCertDBHandle *handle);
01446 
01447 /*
01448  * Get the certificate status checking configuratino data for
01449  * the certificate database
01450  */
01451 CERTStatusConfig *
01452 CERT_GetStatusConfig(CERTCertDBHandle *handle);
01453 
01454 /*
01455  * Set the certificate status checking information for the
01456  * database.  The input structure becomes part of the certificate
01457  * database and will be freed by calling the 'Destroy' function in
01458  * the configuration object.
01459  */
01460 void
01461 CERT_SetStatusConfig(CERTCertDBHandle *handle, CERTStatusConfig *config);
01462 
01463 
01464 
01465 /*
01466  * Acquire the cert reference count lock
01467  * There is currently one global lock for all certs, but I'm putting a cert
01468  * arg here so that it will be easy to make it per-cert in the future if
01469  * that turns out to be necessary.
01470  */
01471 void
01472 CERT_LockCertRefCount(CERTCertificate *cert);
01473 
01474 /*
01475  * Free the cert reference count lock
01476  */
01477 void
01478 CERT_UnlockCertRefCount(CERTCertificate *cert);
01479 
01480 /*
01481  * Acquire the cert trust lock
01482  * There is currently one global lock for all certs, but I'm putting a cert
01483  * arg here so that it will be easy to make it per-cert in the future if
01484  * that turns out to be necessary.
01485  */
01486 void
01487 CERT_LockCertTrust(CERTCertificate *cert);
01488 
01489 /*
01490  * Free the cert trust lock
01491  */
01492 void
01493 CERT_UnlockCertTrust(CERTCertificate *cert);
01494 
01495 /*
01496  * Digest the cert's subject public key using the specified algorithm.
01497  * The necessary storage for the digest data is allocated.  If "fill" is
01498  * non-null, the data is put there, otherwise a SECItem is allocated.
01499  * Allocation from "arena" if it is non-null, heap otherwise.  Any problem
01500  * results in a NULL being returned (and an appropriate error set).
01501  */ 
01502 extern SECItem *
01503 cert_GetSPKIDigest(PRArenaPool *arena, const CERTCertificate *cert,
01504                    SECOidTag digestAlg, SECItem *fill);
01505 
01506 /*
01507  * fill in nsCertType field of the cert based on the cert extension
01508  */
01509 extern SECStatus cert_GetCertType(CERTCertificate *cert);
01510 
01511 
01512 SECStatus CERT_CheckCRL(CERTCertificate* cert, CERTCertificate* issuer,
01513                         SECItem* dp, int64 t, void* wincx);
01514 
01515 
01516 SEC_END_PROTOS
01517 
01518 #endif /* _CERT_H_ */