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