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