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