1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
|
.. _mozilla_projects_nss_reference_nss_certificate_functions:
NSS Certificate Functions
=========================
.. _certificate_functions:
`Certificate Functions <#certificate_functions>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
This chapter describes the functions and related types used to work with a certificate database
such as the cert8.db database provided with NSS. This was converted from `"Chapter 5: Certificate
Functions" <https://www.mozilla.org/projects/security/pki/nss/ref/ssl/sslcrt.html>`__.
- :ref:`mozilla_projects_nss_reference`
- `Validating Certificates <NSS_Certificate_Functions#Validating_Certificates>`__
- `Manipulating Certificates <NSS_Certificate_Functions#Manipulating_Certificates>`__
- `Getting Certificate
Information <NSS_Certificate_Functions#Getting_Certificate_Information>`__
- `Comparing SecItem Objects <NSS_Certificate_Functions#Comparing_SecItem_Objects>`__
.. rubric:: Validating Certificates
:name: validating_certificates
- `CERT_VerifyCertNow <NSS_Certificate_Functions#CERT_VerifyCertNow>`__
- `CERT_VerifyCert <NSS_Certificate_Functions#CERT_VerifyCert>`__
- `CERT_VerifyCertName <NSS_Certificate_Functions#CERT_VerifyCertName>`__
- `CERT_CheckCertValidTimes <NSS_Certificate_Functions#CERT_CheckCertValidTimes>`__
- `NSS_CmpCertChainWCANames <NSS_Certificate_Functions#NSS_CmpCertChainWCANames>`__
.. rubric:: CERT_VerifyCertNow
:name: cert_verifycertnow
Checks that the current date is within the certificate's validity period and that the CA
signature on the certificate is valid.
.. rubric:: Syntax
:name: syntax
.. code:: eval
#include <cert.h>
.. code:: eval
SECStatus CERT_VerifyCertNow(
CERTCertDBHandle *handle,
CERTCertificate *cert,
PRBool checkSig,
SECCertUsage certUsage,
void *wincx);
.. rubric:: Parameters
:name: parameters
This function has the following parameters:
*handle*\ A pointer to the certificate database handle.
*cert*\ A pointer to the certificate to be checked.
*checkSig*\ Indicates whether certificate signatures are to be checked.
- PR_TRUE means certificate signatures are to be checked.
- PR_FALSE means certificate signatures will not be checked.
*certUsage*\ One of these values:
- certUsageSSLClient
- certUsageSSLServer
- certUsageSSLServerWithStepUp
- certUsageSSLCA
- certUsageEmailSigner
- certUsageEmailRecipient
- certUsageObjectSigner
- certUsageUserCertImport
- certUsageVerifyCA
- certUsageProtectedObjectSigner
*wincx*\ The PIN argument value to pass to PK11 functions. See description below for more
information.
.. rubric:: Returns
:name: returns
The function returns one of these values:
- If successful, SECSuccess.
- If unsuccessful, SECFailure. Use PR_GetError to obtain the error code.
.. rubric:: Description
:name: description
The CERT_VerifyCertNow function must call one or more PK11 functions to obtain the services of a
PKCS #11 module. Some of the PK11 functions require a PIN argument (see SSL_SetPKCS11PinArg for
details), which must be specified in the wincx parameter. To obtain the value to pass in the
wincx parameter, call SSL_RevealPinArg.
.. rubric:: CERT_VerifyCert
:name: cert_verifycert
Checks that the a given aribrary date is within the certificate's validity period and that the CA
signature on the certificate is valid. It also optionally returns a log of all the problems with
the chain. Calling CERT_VerifyCert with the parameters: CERT_VerifyCert(handle, cert, checkSig,
certUsage, PR_Now(), wincx, NULL) is equivalent to calling CERT_VerifyNow(handle, cert, checkSig,
certUsage, wincx).
.. rubric:: Syntax
:name: syntax_2
.. code:: eval
#include <cert.h>
.. code:: eval
SECStatus CERT_VerifyCert(
CERTCertDBHandle *handle,
CERTCertificate *cert,
PRBool checkSig,
SECCertUsage certUsage,
int 64 t,
void *wincx
CERTVerifyLog *log);
.. rubric:: Parameters
:name: parameters_2
This function has the following parameters:
*handle*\ A pointer to the certificate database handle.
*cert*\ A pointer to the certificate to be checked.
*checkSig*\ Indicates whether certificate signatures are to be checked.
- PR_TRUE means certificate signatures are to be checked.
- PR_FALSE means certificate signatures will not be checked.
*certUsage*\ One of these values:
- certUsageSSLClient
- certUsageSSLServer
- certUsageSSLServerWithStepUp
- certUsageSSLCA
- certUsageEmailSigner
- certUsageEmailRecipient
- certUsageObjectSigner
- certUsageUserCertImport
- certUsageVerifyCA
- certUsageProtectedObjectSigner
*t*\ Time in which to validate the certificate.
*wincx*\ The PIN argument value to pass to PK11 functions. See description below for more
information.
*log*\ Optional certificate log which returns all the errors in processing a given certificate
chain. See :ref:`mozilla_projects_nss_certverify_log` for more information.
.. rubric:: Returns
:name: returns_2
The function returns one of these values:
- If successful, SECSuccess.
- If unsuccessful, SECFailure. Use PR_GetError to obtain the error code.
.. rubric:: Description
:name: description_2
The CERT_VerifyCert function must call one or more PK11 functions to obtain the services of a
PKCS #11 module. Some of the PK11 functions require a PIN argument (see SSL_SetPKCS11PinArg for
details), which must be specified in the wincx parameter. To obtain the value to pass in the
wincx parameter, call SSL_RevealPinArg.
.. rubric:: CERT_VerifyCertName
:name: cert_verifycertname
Compares the common name specified in the subject DN for a certificate with a specified hostname.
.. rubric:: Syntax
:name: syntax_3
.. code:: eval
#include <cert.h>
.. code:: eval
SECStatus CERT_VerifyCertName(
CERTCertificate *cert,
char *hostname);
.. rubric:: Parameters
:name: parameters_3
This function has the following parameters:
*cert*\ A pointer to the certificate against which to check the hostname referenced by hostname.
*hostname*\ The hostname to be checked.
.. rubric:: Returns
:name: returns_3
The function returns one of these values:
- If the common name in the subject DN for the certificate matches the domain name passed in the
hostname parameter, SECSuccess.
- If the common name in the subject DN for the certificate is not identical to the domain name
passed in the hostname parameter, SECFailure. Use PR_GetError to obtain the error code.
.. rubric:: Description
:name: description_3
The comparison performed by CERT_VerifyCertName is not a simple string comparison. Instead, it
takes account of the following rules governing the construction of common names in SSL server
certificates:
- \* matches anything
- ? matches one character
- \\ escapes a special character
- $ matches the end of the string
- [abc] matches one occurrence of a, b, or c. The only character that needs to be escaped in
this is ], all others are not special.
- [a-z] matches any character between a and z
- [^az] matches any character except a or z
- ~ followed by another shell expression removes any pattern matching the shell expression from
the match list
- (foo|bar) matches either the substring foo or the substring bar. These can be shell
expressions as well.
.. rubric:: CERT_CheckCertValidTimes
:name: cert_checkcertvalidtimes
Checks whether a specified time is within a certificate's validity period.
.. rubric:: Syntax
:name: syntax_4
.. code:: eval
#include <cert.h>
#include <certt.h>
.. code:: eval
SECCertTimeValidity CERT_CheckCertValidTimes(
CERTCertificate *cert,
int64 t);
.. rubric:: Parameters
:name: parameters_4
This function has the following parameters:
*cert*\ A pointer to the certificate whose validity period you want to check against.
*t*\ The time to check against the certificate's validity period. For more information, see the
NSPR header pr_time.h.
.. rubric:: Returns
:name: returns_4
The function returns an enumerator of type SECCertTimeValidity:
.. code:: eval
typedef enum {
secCertTimeValid,
secCertTimeExpired,
secCertTimeNotValidYet
} SECCertTimeValidity;
.. rubric:: NSS_CmpCertChainWCANames
:name: nss_cmpcertchainwcanames
Determines whether any of the signers in the certificate chain for a specified certificate are on
a specified list of CA names.
.. rubric:: Syntax
:name: syntax_5
.. code:: eval
#include <nss.h>
SECStatus NSS_CmpCertChainWCANames(
CERTCertificate *cert,
CERTDistNames *caNames);
.. rubric:: Parameters
:name: parameters_5
This function has the following parameters:
*cert*\ A pointer to the certificate structure for the certificate whose certificate chain is to
be checked.
*caNames*\ A pointer to a structure that contains a list of distinguished names (DNs) against
which to check the DNs for the signers in the certificate chain.
.. rubric:: Returns
:name: returns_5
The function returns one of these values:
- If successful, SECSuccess.
- If unsuccessful, SECFailure. Use PR_GetError to obtain the error code.
.. rubric:: Manipulating Certificates
:name: manipulating_certificates
- `CERT_DupCertificate <#cert_dupcertificate>`__
- `CERT_DestroyCertificate <#cert_destroycertificate>`__
.. rubric:: CERT_DupCertificate
:name: cert_dupcertificate
Makes a shallow copy of a specified certificate.
.. rubric:: Syntax
:name: syntax_6
.. code:: eval
#include <cert.h>
.. code:: eval
CERTCertificate *CERT_DupCertificate(CERTCertificate *c)
.. rubric:: Parameter
:name: parameter
This function has the following parameter:
*c*\ A pointer to the certificate object to be duplicated.
.. rubric:: Returns
:name: returns_6
If successful, the function returns a pointer to a certificate object of type CERTCertificate.
.. rubric:: Description
:name: description_4
The CERT_DupCertificate function increments the reference count for the certificate passed in the
c parameter.
.. rubric:: CERT_DestroyCertificate
:name: cert_destroycertificate
Destroys a certificate object.
.. rubric:: Syntax
:name: syntax_7
.. code:: eval
#include <cert.h>
#include <certt.h>
.. code:: eval
void CERT_DestroyCertificate(CERTCertificate *cert);
.. rubric:: Parameters
:name: parameters_6
This function has the following parameter:
*cert*\ A pointer to the certificate to destroy.
.. rubric:: Description
:name: description_5
Certificate and key structures are shared objects. When an application makes a copy of a
particular certificate or key structure that already exists in memory, SSL makes a shallow
copy--that is, it increments the reference count for that object rather than making a whole new
copy. When you call CERT_DestroyCertificate or SECKEY_DestroyPrivateKey, the function decrements
the reference count and, if the reference count reaches zero as a result, both frees the memory
and sets all the bits to zero. The use of the word "destroy" in function names or in the
description of a function implies reference counting.
Never alter the contents of a certificate or key structure. If you attempt to do so, the change
affects all the shallow copies of that structure and can cause severe problems.
.. rubric:: Getting Certificate Information
:name: getting_certificate_information
- `CERT_FindCertByName <#cert_findcertbyname>`__
- `CERT_GetCertNicknames <#cert_getcertnicknames>`__
- `CERT_FreeNicknames <#cert_freenicknames>`__
- `CERT_GetDefaultCertDB <#cert_getdefaultcertdb>`__
- `NSS_FindCertKEAType <#nss_findcertkeatype>`__
.. rubric:: CERT_FindCertByName
:name: cert_findcertbyname
Finds the certificate in the certificate database with a specified DN.
.. rubric:: Syntax
:name: syntax_8
.. code:: eval
#include <cert.h>
.. code:: eval
CERTCertificate *CERT_FindCertByName (
CERTCertDBHandle *handle,
SECItem *name);
.. rubric:: Parameters
:name: parameters_7
This function has the following parameters:
*handle*\ A pointer to the certificate database handle.
*name*\ The subject DN of the certificate you wish to find.
.. rubric:: Returns
:name: returns_7
If successful, the function returns a certificate object of type CERTCertificate.
.. rubric:: CERT_GetCertNicknames
:name: cert_getcertnicknames
Returns the nicknames of the certificates in a specified certificate database.
.. rubric:: Syntax
:name: syntax_9
.. code:: eval
#include <cert.h>
#include <certt.h>
.. code:: eval
CERTCertNicknames *CERT_GetCertNicknames (
CERTCertDBHandle *handle,
int what,
void *wincx);
.. rubric:: Parameters
:name: parameters_8
This function has the following parameters:
*handle*\ A pointer to the certificate database handle.
*what*\ One of these values:
- SEC_CERT_NICKNAMES_ALL
- SEC_CERT_NICKNAMES_USER
- SEC_CERT_NICKNAMES_SERVER
- SEC_CERT_NICKNAMES_CA
*wincx*\ The PIN argument value to pass to PK11 functions. See description below for more
information.
.. rubric:: Returns
:name: returns_8
The function returns a CERTCertNicknames object containing the requested nicknames.
.. rubric:: Description
:name: description_6
CERT_GetCertNicknames must call one or more PK11 functions to obtain the services of a PKCS #11
module. Some of the PK11 functions require a PIN argument (see SSL_SetPKCS11PinArg for details),
which must be specified in the wincx parameter. To obtain the value to pass in the wincx
parameter, call SSL_RevealPinArg.
.. rubric:: CERT_FreeNicknames
:name: cert_freenicknames
Frees a CERTCertNicknames structure. This structure is returned by CERT_GetCertNicknames.
.. rubric:: Syntax
:name: syntax_10
.. code:: eval
#include <cert.h>
.. code:: eval
void CERT_FreeNicknames(CERTCertNicknames *nicknames);
.. rubric:: Parameters
:name: parameters_9
This function has the following parameter:
*nicknames*\ A pointer to the CERTCertNicknames structure to be freed.
.. rubric:: CERT_GetDefaultCertDB
:name: cert_getdefaultcertdb
Returns a handle to the default certificate database.
.. rubric:: Syntax
:name: syntax_11
.. code:: eval
#include <cert.h>
.. code:: eval
CERTCertDBHandle *CERT_GetDefaultCertDB(void);
.. rubric:: Returns
:name: returns_9
The function returns the CERTCertDBHandle for the default certificate database.
.. rubric:: Description
:name: description_7
This function is useful for determining whether the default certificate database has been opened.
.. rubric:: NSS_FindCertKEAType
:name: nss_findcertkeatype
Returns key exchange type of the keys in an SSL server certificate.
.. rubric:: Syntax
:name: syntax_12
.. code:: eval
#include <nss.h>
.. code:: eval
SSLKEAType NSS_FindCertKEAType(CERTCertificate * cert);
.. rubric:: Parameter
:name: parameter_2
This function has the following parameter:
*a*\ The certificate to check.
.. rubric:: Returns
:name: returns_10
The function returns one of these values:
- kt_null = 0
- kt_rsa
- kt_dh
- kt_fortezza
- kt_kea_size
.. rubric:: Comparing SecItem Objects
:name: comparing_secitem_objects
.. rubric:: SECITEM_CompareItem
:name: secitem_compareitem
Compares two SECItem objects and returns a SECComparison enumerator that shows the difference
between them.
.. rubric:: Syntax
:name: syntax_13
.. code:: eval
#include <secitem.h>
#include <seccomon.h>
.. code:: eval
SECComparison SECITEM_CompareItem(
SECItem *a,
SECItem *b);
.. rubric:: Parameters
:name: parameters_10
This function has the following parameters:
*a*\ A pointer to one of the items to be compared.
*b*\ A pointer to one of the items to be compared.
.. rubric:: Returns
:name: returns_11
The function returns an enumerator of type SECComparison.
.. code:: eval
typedef enum _SECComparison {
SECLessThan = -1,
SECEqual = 0,
SECGreaterThan = 1
} SECComparison;
|