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 * This file defines several platform independent functions to 6 * manipulate certificates and CRLs in a portable manner. 7 * 8 */ 9 10 #ifndef _PKIX_PL_PKI_H 11 #define _PKIX_PL_PKI_H 12 13 #include "pkixt.h" 14 #include "seccomon.h" 15 #include "certt.h" 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 /* General 22 * 23 * Please refer to the libpkix Programmer's Guide for detailed information 24 * about how to use the libpkix library. Certain key warnings and notices from 25 * that document are repeated here for emphasis. 26 * 27 * All identifiers in this file (and all public identifiers defined in 28 * libpkix) begin with "PKIX_". Private identifiers only intended for use 29 * within the library begin with "pkix_". 30 * 31 * A function returns NULL upon success, and a PKIX_Error pointer upon failure. 32 * 33 * Unless otherwise noted, for all accessor (gettor) functions that return a 34 * PKIX_PL_Object pointer, callers should assume that this pointer refers to a 35 * shared object. Therefore, the caller should treat this shared object as 36 * read-only and should not modify this shared object. When done using the 37 * shared object, the caller should release the reference to the object by 38 * using the PKIX_PL_Object_DecRef function. 39 * 40 * While a function is executing, if its arguments (or anything referred to by 41 * its arguments) are modified, free'd, or destroyed, the function's behavior 42 * is undefined. 43 * 44 */ 45 46 /* 47 * Cert 48 * 49 * A Cert represents an X.509 certificate. It can be created using the bytes 50 * of a valid ASN.1 DER encoding. Once created, a Cert is immutable. The 51 * following functions include accessors (gettors) for the various components 52 * of an X.509 certificate. Also included are functions to perform various 53 * checks on a certificate, including name constraints, key usage, validity 54 * (expiration), and signature verification. 55 */ 56 57 /* 58 * FUNCTION: PKIX_PL_Cert_Create 59 * DESCRIPTION: 60 * 61 * Creates a new certificate using the bytes in the ByteArray pointed to by 62 * "byteArray" and stores it at "pCert". If the bytes are not a valid ASN.1 63 * DER encoding of a certificate, a PKIX_Error pointer is returned. Once 64 * created, a Cert is immutable. 65 * 66 * Certificate ::= SEQUENCE { 67 * tbsCertificate TBSCertificate, 68 * signatureAlgorithm AlgorithmIdentifier, 69 * signatureValue BIT STRING } 70 * 71 * AlgorithmIdentifier ::= SEQUENCE { 72 * algorithm OBJECT IDENTIFIER, 73 * parameters ANY DEFINED BY algorithm OPTIONAL } 74 * 75 * TBSCertificate ::= SEQUENCE { 76 * version [0] EXPLICIT Version DEFAULT v1, 77 * serialNumber CertificateSerialNumber, 78 * signature AlgorithmIdentifier, 79 * issuer Name, 80 * validity Validity, 81 * subject Name, 82 * subjectPublicKeyInfo SubjectPublicKeyInfo, 83 * issuerUniqueID [1] IMPLICIT UniqueIdentifier OPTIONAL, 84 * -- If present, version MUST be v2 or v3 85 * subjectUniqueID [2] IMPLICIT UniqueIdentifier OPTIONAL, 86 * -- If present, version MUST be v2 or v3 87 * extensions [3] EXPLICIT Extensions OPTIONAL 88 * -- If present, version MUST be v3 89 * } 90 * 91 * Version ::= INTEGER { v1(0), v2(1), v3(2) } 92 * 93 * CertificateSerialNumber ::= INTEGER 94 * 95 * Validity ::= SEQUENCE { 96 * notBefore Time, 97 * notAfter Time } 98 * 99 * Time ::= CHOICE { 100 * utcTime UTCTime, 101 * generalTime GeneralizedTime } 102 * 103 * UniqueIdentifier ::= BIT STRING 104 * 105 * SubjectPublicKeyInfo ::= SEQUENCE { 106 * algorithm AlgorithmIdentifier, 107 * subjectPublicKey BIT STRING } 108 * 109 * Extensions ::= SEQUENCE SIZE (1..MAX) OF Extension 110 * 111 * Extension ::= SEQUENCE { 112 * extnID OBJECT IDENTIFIER, 113 * critical BOOLEAN DEFAULT FALSE, 114 * extnValue OCTET STRING } 115 * 116 * PARAMETERS: 117 * "byteArray" 118 * Address of ByteArray representing the CERT's DER encoding. 119 * Must be non-NULL. 120 * "pCert" 121 * Address where object pointer will be stored. Must be non-NULL. 122 * "plContext" 123 * Platform-specific context pointer. 124 * THREAD SAFETY: 125 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 126 * RETURNS: 127 * Returns NULL if the function succeeds. 128 * Returns a Cert Error if the function fails in a non-fatal way. 129 * Returns a Fatal Error if the function fails in an unrecoverable way. 130 */ 131 PKIX_Error * 132 PKIX_PL_Cert_Create( 133 PKIX_PL_ByteArray *byteArray, 134 PKIX_PL_Cert **pCert, 135 void *plContext); 136 137 /* 138 * FUNCTION: PKIX_PL_Cert_CreateFromCERTCertificate 139 * DESCRIPTION: 140 * 141 * Creates a new certificate using passed in CERTCertificate object. 142 * 143 * PARAMETERS: 144 * "nssCert" 145 * The object that will be used to create new PKIX_PL_Cert. 146 * "pCert" 147 * Address where object pointer will be stored. Must be non-NULL. 148 * "plContext" 149 * Platform-specific context pointer. 150 * THREAD SAFETY: 151 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 152 * RETURNS: 153 * Returns NULL if the function succeeds. 154 * Returns a Cert Error if the function fails in a non-fatal way. 155 * Returns a Fatal Error if the function fails in an unrecoverable way. 156 */ 157 PKIX_Error * 158 PKIX_PL_Cert_CreateFromCERTCertificate( 159 const CERTCertificate *nssCert, 160 PKIX_PL_Cert **pCert, 161 void *plContext); 162 163 /* 164 * FUNCTION: PKIX_PL_Cert_GetCERTCertificate 165 * DESCRIPTION: 166 * 167 * Returns underlying CERTCertificate structure. Return CERTCertificate 168 * object is duplicated and should be destroyed by caller. 169 * 170 * PARAMETERS: 171 * "cert" 172 * Address of PKIX_PL_Cert. Must be non-NULL. 173 * "pCert" 174 * Address where object pointer will be stored. Must be non-NULL. 175 * "plContext" 176 * Platform-specific context pointer. 177 * THREAD SAFETY: 178 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 179 * RETURNS: 180 * Returns NULL if the function succeeds. 181 * Returns a Cert Error if the function fails in a non-fatal way. 182 * Returns a Fatal Error if the function fails in an unrecoverable way. 183 */ 184 PKIX_Error * 185 PKIX_PL_Cert_GetCERTCertificate( 186 PKIX_PL_Cert *cert, 187 CERTCertificate **pnssCert, 188 void *plContext); 189 190 /* 191 * FUNCTION: PKIX_PL_Cert_GetVersion 192 * DESCRIPTION: 193 * 194 * Retrieves the version of the Cert pointed to by "cert" and stores it at 195 * "pVersion". The version number will either be 0, 1, or 2 (corresponding to 196 * v1, v2, or v3, respectively). 197 * 198 * Version ::= INTEGER { v1(0), v2(1), v3(2) } 199 * 200 * PARAMETERS: 201 * "cert" 202 * Address of Cert whose version is to be stored. Must be non-NULL. 203 * "pVersion" 204 * Address where PKIX_UInt32 will be stored. Must be non-NULL. 205 * "plContext" 206 * Platform-specific context pointer. 207 * THREAD SAFETY: 208 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 209 * RETURNS: 210 * Returns NULL if the function succeeds. 211 * Returns a Cert Error if the function fails in a non-fatal way. 212 * Returns a Fatal Error if the function fails in an unrecoverable way. 213 */ 214 PKIX_Error * 215 PKIX_PL_Cert_GetVersion( 216 PKIX_PL_Cert *cert, 217 PKIX_UInt32 *pVersion, 218 void *plContext); 219 220 /* 221 * FUNCTION: PKIX_PL_Cert_GetSerialNumber 222 * DESCRIPTION: 223 * 224 * Retrieves a pointer to the BigInt that represents the serial number of the 225 * Cert pointed to by "cert" and stores it at "pSerialNumber". 226 * 227 * CertificateSerialNumber ::= INTEGER 228 * 229 * PARAMETERS: 230 * "cert" 231 * Address of Cert whose serial number is to be stored. Must be non-NULL. 232 * "pSerial" 233 * Address where object pointer will be stored. Must be non-NULL. 234 * "plContext" 235 * Platform-specific context pointer. 236 * THREAD SAFETY: 237 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 238 * RETURNS: 239 * Returns NULL if the function succeeds. 240 * Returns a Cert Error if the function fails in a non-fatal way. 241 * Returns a Fatal Error if the function fails in an unrecoverable way. 242 */ 243 PKIX_Error * 244 PKIX_PL_Cert_GetSerialNumber( 245 PKIX_PL_Cert *cert, 246 PKIX_PL_BigInt **pSerial, 247 void *plContext); 248 249 /* 250 * FUNCTION: PKIX_PL_Cert_GetIssuer 251 * DESCRIPTION: 252 * 253 * Retrieves a pointer to the X500Name that represents the issuer DN of the 254 * Cert pointed to by "cert" and stores it at "pIssuer". 255 * 256 * PARAMETERS: 257 * "cert" 258 * Address of Cert whose issuer is to be stored. Must be non-NULL. 259 * "pIssuer" 260 * Address where object pointer will be stored. Must be non-NULL. 261 * "plContext" 262 * Platform-specific context pointer. 263 * THREAD SAFETY: 264 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 265 * RETURNS: 266 * Returns NULL if the function succeeds. 267 * Returns a Cert Error if the function fails in a non-fatal way. 268 * Returns a Fatal Error if the function fails in an unrecoverable way. 269 */ 270 PKIX_Error * 271 PKIX_PL_Cert_GetIssuer( 272 PKIX_PL_Cert *cert, 273 PKIX_PL_X500Name **pIssuer, 274 void *plContext); 275 276 /* 277 * FUNCTION: PKIX_PL_Cert_GetSubject 278 * DESCRIPTION: 279 * 280 * Retrieves a pointer to the X500Name that represents the subject DN of the 281 * Cert pointed to by "cert" and stores it at "pSubject". If the Cert does not 282 * have a subject DN, this function stores NULL at "pSubject". 283 * 284 * PARAMETERS: 285 * "cert" 286 * Address of Cert whose subject is to be stored. Must be non-NULL. 287 * "pSubject" 288 * Address where object pointer will be stored. Must be non-NULL. 289 * "plContext" 290 * Platform-specific context pointer. 291 * THREAD SAFETY: 292 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 293 * RETURNS: 294 * Returns NULL if the function succeeds. 295 * Returns a Cert Error if the function fails in a non-fatal way. 296 * Returns a Fatal Error if the function fails in an unrecoverable way. 297 */ 298 PKIX_Error * 299 PKIX_PL_Cert_GetSubject( 300 PKIX_PL_Cert *cert, 301 PKIX_PL_X500Name **pSubject, 302 void *plContext); 303 304 /* 305 * FUNCTION: PKIX_PL_Cert_GetSubjectPublicKeyAlgId 306 * DESCRIPTION: 307 * 308 * Retrieves a pointer to the OID that represents the subject public key 309 * algorithm of the Cert pointed to by "cert" and stores it at 310 * "pSubjKeyAlgId". 311 * 312 * SubjectPublicKeyInfo ::= SEQUENCE { 313 * algorithm AlgorithmIdentifier, 314 * subjectPublicKey BIT STRING } 315 * 316 * AlgorithmIdentifier ::= SEQUENCE { 317 * algorithm OBJECT IDENTIFIER, 318 * parameters ANY DEFINED BY algorithm OPTIONAL } 319 * 320 * PARAMETERS: 321 * "cert" 322 * Address of Cert whose subject public key algorithm OID is to be stored. 323 * Must be non-NULL. 324 * "pSubjKeyAlgId" 325 * Address where object pointer will be stored. Must be non-NULL. 326 * "plContext" 327 * Platform-specific context pointer. 328 * THREAD SAFETY: 329 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 330 * RETURNS: 331 * Returns NULL if the function succeeds. 332 * Returns a Cert Error if the function fails in a non-fatal way. 333 * Returns a Fatal Error if the function fails in an unrecoverable way. 334 */ 335 PKIX_Error * 336 PKIX_PL_Cert_GetSubjectPublicKeyAlgId( 337 PKIX_PL_Cert *cert, 338 PKIX_PL_OID **pSubjKeyAlgId, 339 void *plContext); 340 341 /* 342 * FUNCTION: PKIX_PL_Cert_GetSubjectPublicKey 343 * DESCRIPTION: 344 * 345 * Retrieves a pointer to the PublicKey that represents the subject public key 346 * of the Cert pointed to by "cert" and stores it at "pPublicKey". 347 * 348 * SubjectPublicKeyInfo ::= SEQUENCE { 349 * algorithm AlgorithmIdentifier, 350 * subjectPublicKey BIT STRING } 351 * 352 * PARAMETERS: 353 * "cert" 354 * Address of Cert whose subject public key is to be stored. 355 * Must be non-NULL. 356 * "pPublicKey" 357 * Address where object pointer will be stored. Must be non-NULL. 358 * "plContext" 359 * Platform-specific context pointer. 360 * THREAD SAFETY: 361 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 362 * RETURNS: 363 * Returns NULL if the function succeeds. 364 * Returns a Cert Error if the function fails in a non-fatal way. 365 * Returns a Fatal Error if the function fails in an unrecoverable way. 366 */ 367 PKIX_Error * 368 PKIX_PL_Cert_GetSubjectPublicKey( 369 PKIX_PL_Cert *cert, 370 PKIX_PL_PublicKey **pPublicKey, 371 void *plContext); 372 373 /* 374 * FUNCTION: PKIX_PL_PublicKey_NeedsDSAParameters 375 * DESCRIPTION: 376 * 377 * Determines if the PublicKey pointed to by "pubKey" is a DSA Key with null 378 * parameters and stores the result at "pNeedsParams". 379 * 380 * PARAMETERS: 381 * "pubKey" 382 * Address of the Public Key of interest. Must be non-NULL. 383 * "pNeedsParams" 384 * Address where object pointer will be stored. Must be non-NULL. 385 * "plContext" 386 * Platform-specific context pointer. 387 * THREAD SAFETY: 388 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 389 * RETURNS: 390 * Returns NULL if the function succeeds. 391 * Returns a PublicKey Error if the function fails in a non-fatal way. 392 * Returns a Fatal Error if the function fails in an unrecoverable way. 393 */ 394 PKIX_Error * 395 PKIX_PL_PublicKey_NeedsDSAParameters( 396 PKIX_PL_PublicKey *pubKey, 397 PKIX_Boolean *pNeedsParams, 398 void *plContext); 399 400 /* 401 * FUNCTION: PKIX_PL_PublicKey_MakeInheritedDSAPublicKey 402 * DESCRIPTION: 403 * 404 * This function is used for DSA key parameter inheritance, which allows a 405 * first DSA key with omitted parameters (pointed to by "firstKey") to inherit 406 * the PQG parameters of a second DSA key that does have parameters. (pointed 407 * to by "secondKey"). Once created, a PublicKey is immutable. 408 * 409 * Specifically, the algorithm used by the function is: 410 * 411 * If the first PublicKey is not a DSA public key with omitted parameters, 412 * the function stores NULL at "pResultKey". (No Error is returned) 413 * Else if the second PublicKey is not a DSA public key with non-NULL, 414 * parameters, the function returns an Error. 415 * Else 416 * the function creates a third PublicKey with a "Y" value from the 417 * first PublicKey and the DSA parameters from the second PublicKey, 418 * and stores it at "pResultKey". 419 * 420 * PARAMETERS: 421 * "firstKey" 422 * Address of a Public Key that needs to inherit DSA parameters. 423 * Must be non-NULL. 424 * "secondKey" 425 * Address of a Public Key that has DSA parameters that will be inherited 426 * by "firstKey". Must be non-NULL. 427 * "pResultKey" 428 * Address where object pointer will be stored. Must be non-NULL. 429 * "plContext" 430 * Platform-specific context pointer. 431 * THREAD SAFETY: 432 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 433 * RETURNS: 434 * Returns NULL if the function succeeds. 435 * Returns a PublicKey Error if the function fails in a non-fatal way. 436 * Returns a Fatal Error if the function fails in an unrecoverable way. 437 */ 438 PKIX_Error * 439 PKIX_PL_PublicKey_MakeInheritedDSAPublicKey( 440 PKIX_PL_PublicKey *firstKey, 441 PKIX_PL_PublicKey *secondKey, 442 PKIX_PL_PublicKey **pResultKey, 443 void *plContext); 444 445 /* 446 * FUNCTION: PKIX_PL_Cert_GetCriticalExtensionOIDs 447 * DESCRIPTION: 448 * 449 * Retrieves a pointer to the List of OIDs (each OID corresponding to a 450 * critical extension of the Cert pointed to by "cert") and stores it at 451 * "pExtensions". If "cert" does not have any critical extensions, this 452 * function stores an empty List at "pExtensions". 453 * 454 * Note that the List returned by this function is immutable. 455 * 456 * PARAMETERS: 457 * "cert" 458 * Address of Cert whose critical extension OIDs are to be stored. 459 * Must be non-NULL. 460 * "pExtensions" 461 * Address where object pointer will be stored. Must be non-NULL. 462 * "plContext" 463 * Platform-specific context pointer. 464 * THREAD SAFETY: 465 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 466 * RETURNS: 467 * Returns NULL if the function succeeds. 468 * Returns a Cert Error if the function fails in a non-fatal way. 469 * Returns a Fatal Error if the function fails in an unrecoverable way. 470 */ 471 PKIX_Error * 472 PKIX_PL_Cert_GetCriticalExtensionOIDs( 473 PKIX_PL_Cert *cert, 474 PKIX_List **pExtensions, /* list of PKIX_PL_OID */ 475 void *plContext); 476 477 /* 478 * FUNCTION: PKIX_PL_Cert_GetAuthorityKeyIdentifier 479 * DESCRIPTION: 480 * 481 * Retrieves a pointer to a ByteArray representing the authority key 482 * identifier extension of the Cert pointed to by "cert" and stores it at 483 * "pAuthKeyId". 484 * 485 * Note that this function only retrieves the keyIdentifier component 486 * (OCTET STRING) of the AuthorityKeyIdentifier extension, when present. 487 * 488 * If "cert" does not have an AuthorityKeyIdentifier extension or if the 489 * keyIdentifier component of the AuthorityKeyIdentifier extension is not 490 * present, this function stores NULL at "pAuthKeyId". 491 * 492 * AuthorityKeyIdentifier ::= SEQUENCE { 493 * keyIdentifier [0] KeyIdentifier OPTIONAL, 494 * authorityCertIssuer [1] GeneralNames OPTIONAL, 495 * authorityCertSerialNumber [2] CertificateSerialNumber OPTIONAL } 496 * 497 * PARAMETERS: 498 * "cert" 499 * Address of Cert whose authority key identifier is to be stored. 500 * Must be non-NULL. 501 * "pAuthKeyId" 502 * Address where object pointer will be stored. Must be non-NULL. 503 * "plContext" 504 * Platform-specific context pointer. 505 * THREAD SAFETY: 506 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 507 * RETURNS: 508 * Returns NULL if the function succeeds. 509 * Returns a Cert Error if the function fails in a non-fatal way. 510 * Returns a Fatal Error if the function fails in an unrecoverable way. 511 */ 512 PKIX_Error * 513 PKIX_PL_Cert_GetAuthorityKeyIdentifier( 514 PKIX_PL_Cert *cert, 515 PKIX_PL_ByteArray **pAuthKeyId, 516 void *plContext); 517 518 /* 519 * FUNCTION: PKIX_PL_Cert_GetSubjectKeyIdentifier 520 * DESCRIPTION: 521 * 522 * Retrieves a pointer to a ByteArray representing the subject key identifier 523 * extension of the Cert pointed to by "cert" and stores it at "pSubjKeyId". 524 * If "cert" does not have a SubjectKeyIdentifier extension, this function 525 * stores NULL at "pSubjKeyId". 526 * 527 * SubjectKeyIdentifier ::= KeyIdentifier 528 * 529 * PARAMETERS: 530 * "cert" 531 * Address of Cert whose subject key identifier is to be stored. 532 * Must be non-NULL. 533 * "pSubjKeyId" 534 * Address where object pointer will be stored. Must be non-NULL. 535 * "plContext" 536 * Platform-specific context pointer. 537 * THREAD SAFETY: 538 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 539 * RETURNS: 540 * Returns NULL if the function succeeds. 541 * Returns a Cert Error if the function fails in a non-fatal way. 542 * Returns a Fatal Error if the function fails in an unrecoverable way. 543 */ 544 PKIX_Error * 545 PKIX_PL_Cert_GetSubjectKeyIdentifier( 546 PKIX_PL_Cert *cert, 547 PKIX_PL_ByteArray **pSubjKeyId, 548 void *plContext); 549 550 /* 551 * FUNCTION: PKIX_PL_Cert_GetSubjectAltNames 552 * DESCRIPTION: 553 * 554 * Retrieves a pointer to the List of GeneralNames (each GeneralName 555 * representing a subject alternative name found in the subject alternative 556 * names extension of the Cert pointed to by "cert") and stores it at 557 * "pSubjectAltNames". If "cert" does not have a SubjectAlternativeNames 558 * extension, this function stores NULL at "pSubjectAltNames". 559 * 560 * Note that the List returned by this function is immutable. 561 * 562 * SubjectAltName ::= GeneralNames 563 * 564 * GeneralNames ::= SEQUENCE SIZE (1..MAX) OF GeneralName 565 * 566 * GeneralName ::= CHOICE { 567 * otherName [0] OtherName, 568 * rfc822Name [1] IA5String, 569 * dNSName [2] IA5String, 570 * x400Address [3] ORAddress, 571 * directoryName [4] Name, 572 * ediPartyName [5] EDIPartyName, 573 * uniformResourceIdentifier [6] IA5String, 574 * iPAddress [7] OCTET STRING, 575 * registeredID [8] OBJECT IDENTIFIER } 576 * 577 * OtherName ::= SEQUENCE { 578 * type-id OBJECT IDENTIFIER, 579 * value [0] EXPLICIT ANY DEFINED BY type-id } 580 * 581 * EDIPartyName ::= SEQUENCE { 582 * nameAssigner [0] DirectoryString OPTIONAL, 583 * partyName [1] DirectoryString } 584 * 585 * PARAMETERS: 586 * "cert" 587 * Address of Cert whose subjectAltNames are to be stored. 588 * Must be non-NULL. 589 * "pSubjectAltNames" 590 * Address where object pointer will be stored. Must be non-NULL. 591 * "plContext" 592 * Platform-specific context pointer. 593 * THREAD SAFETY: 594 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 595 * RETURNS: 596 * Returns NULL if the function succeeds. 597 * Returns a Cert Error if the function fails in a non-fatal way. 598 * Returns a Fatal Error if the function fails in an unrecoverable way. 599 */ 600 PKIX_Error * 601 PKIX_PL_Cert_GetSubjectAltNames( 602 PKIX_PL_Cert *cert, 603 PKIX_List **pSubjectAltNames, /* list of PKIX_PL_GeneralName */ 604 void *plContext); 605 606 /* 607 * FUNCTION: PKIX_PL_Cert_GetAllSubjectNames 608 * DESCRIPTION: 609 * 610 * Retrieves a pointer to the List of GeneralNames (each GeneralName 611 * representing a subject DN or a subject alternative name found in the 612 * subject alternative names extension of the Cert pointed to by "cert") and 613 * stores it at "pAllSubjectNames".If the Subject DN of "cert" is empty and 614 * it does not have a SubjectAlternativeNames extension, this function stores 615 * NULL at "pAllSubjectNames". 616 * 617 * Note that the List returned by this function is immutable. 618 * 619 * PARAMETERS: 620 * "cert" 621 * Address of Cert whose subject DN and subjectAltNames are to be stored. 622 * Must be non-NULL. 623 * "pAllSubjectNames" 624 * Address where object pointer will be stored. Must be non-NULL. 625 * "plContext" 626 * Platform-specific context pointer. 627 * THREAD SAFETY: 628 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 629 * RETURNS: 630 * Returns NULL if the function succeeds. 631 * Returns a Cert Error if the function fails in a non-fatal way. 632 * Returns a Fatal Error if the function fails in an unrecoverable way. 633 */ 634 PKIX_Error * 635 PKIX_PL_Cert_GetAllSubjectNames( 636 PKIX_PL_Cert *cert, 637 PKIX_List **pAllSubjectNames, /* list of PKIX_PL_GeneralName */ 638 void *plContext); 639 640 /* 641 * FUNCTION: PKIX_PL_Cert_GetExtendedKeyUsage 642 * DESCRIPTION: 643 * 644 * Retrieves a pointer to a List of OIDs (each OID corresponding to an 645 * extended key usage of the Cert pointed to by "cert") and stores it at 646 * "pKeyUsage". If "cert" does not have an extended key usage extension, this 647 * function stores a NULL at "pKeyUsage". 648 * 649 * Note that the List returned by this function is immutable. 650 * 651 * ExtKeyUsageSyntax ::= SEQUENCE SIZE (1..MAX) OF KeyPurposeId 652 * 653 * KeyPurposeId ::= OBJECT IDENTIFIER 654 * 655 * PARAMETERS: 656 * "cert" 657 * Address of Cert whose extended key usage OIDs are to be stored. 658 * Must be non-NULL. 659 * "pKeyUsage" 660 * Address where object pointer will be stored. Must be non-NULL. 661 * "plContext" 662 * Platform-specific context pointer. 663 * THREAD SAFETY: 664 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 665 * RETURNS: 666 * Returns NULL if the function succeeds. 667 * Returns a Cert Error if the function fails in a non-fatal way. 668 * Returns a Fatal Error if the function fails in an unrecoverable way. 669 */ 670 PKIX_Error * 671 PKIX_PL_Cert_GetExtendedKeyUsage( 672 PKIX_PL_Cert *cert, 673 PKIX_List **pKeyUsage, /* list of PKIX_PL_OID */ 674 void *plContext); 675 676 /* 677 * FUNCTION: PKIX_PL_Cert_GetNameConstraints 678 * DESCRIPTION: 679 * 680 * Retrieves a pointer to a CertNameConstraints object representing the name 681 * constraints extension of the Cert pointed to by "cert" and stores it at 682 * "pNameConstraints". 683 * 684 * If "cert" does not have a name constraints extension, this function stores 685 * NULL at "pNameConstraints". 686 * 687 * NameConstraints ::= SEQUENCE { 688 * permittedSubtrees [0] GeneralSubtrees OPTIONAL, 689 * excludedSubtrees [1] GeneralSubtrees OPTIONAL } 690 * 691 * GeneralSubtrees ::= SEQUENCE SIZE (1..MAX) OF GeneralSubtree 692 * 693 * GeneralSubtree ::= SEQUENCE { 694 * base GeneralName, 695 * minimum [0] BaseDistance DEFAULT 0, 696 * maximum [1] BaseDistance OPTIONAL } 697 * 698 * BaseDistance ::= INTEGER (0..MAX) 699 * 700 * PARAMETERS: 701 * "cert" 702 * Address of Cert whose name constraints extension is to be stored. 703 * Must be non-NULL. 704 * "pNameConstraints" 705 * Address where object pointer will be stored. Must be non-NULL. 706 * "plContext" 707 * Platform-specific context pointer. 708 * THREAD SAFETY: 709 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 710 * RETURNS: 711 * Returns NULL if the function succeeds. 712 * Returns a Cert Error if the function fails in a non-fatal way. 713 * Returns a Fatal Error if the function fails in an unrecoverable way. 714 */ 715 PKIX_Error * 716 PKIX_PL_Cert_GetNameConstraints( 717 PKIX_PL_Cert *cert, 718 PKIX_PL_CertNameConstraints **pNameConstraints, 719 void *plContext); 720 721 /* 722 * FUNCTION: PKIX_PL_Cert_GetBasicConstraints 723 * DESCRIPTION: 724 * 725 * Retrieves a pointer to a CertBasicConstraints object representing the basic 726 * constraints extension of the Cert pointed to by "cert" and stores it at 727 * "pBasicConstraints". 728 * 729 * If "cert" does not have a basic constraints extension, this function stores 730 * NULL at "pBasicConstraints". Once created, a CertBasicConstraints object 731 * is immutable. 732 * 733 * BasicConstraints ::= SEQUENCE { 734 * cA BOOLEAN DEFAULT FALSE, 735 * pathLenConstraint INTEGER (0..MAX) OPTIONAL } 736 * 737 * PARAMETERS: 738 * "cert" 739 * Address of Cert whose basic constraints extension is to be stored. 740 * Must be non-NULL. 741 * "pBasicConstraints" 742 * Address where object pointer will be stored. Must be non-NULL. 743 * "plContext" 744 * Platform-specific context pointer. 745 * THREAD SAFETY: 746 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 747 * RETURNS: 748 * Returns NULL if the function succeeds. 749 * Returns a Cert Error if the function fails in a non-fatal way. 750 * Returns a Fatal Error if the function fails in an unrecoverable way. 751 */ 752 PKIX_Error * 753 PKIX_PL_Cert_GetBasicConstraints( 754 PKIX_PL_Cert *cert, 755 PKIX_PL_CertBasicConstraints **pBasicConstraints, 756 void *plContext); 757 758 /* 759 * FUNCTION: PKIX_PL_BasicConstraints_GetCAFlag 760 * DESCRIPTION: 761 * 762 * Retrieves a pointer to a Boolean value representing the cA Flag component 763 * of the CertBasicConstraints object pointed to by "basicConstraints" and 764 * stores it at "pResult". 765 * 766 * BasicConstraints ::= SEQUENCE { 767 * cA BOOLEAN DEFAULT FALSE, 768 * pathLenConstraint INTEGER (0..MAX) OPTIONAL } 769 * 770 * PARAMETERS: 771 * "basicConstraints" 772 * Address of CertBasicConstraints whose cA Flag is to be stored. 773 * Must be non-NULL. 774 * "pResult" 775 * Address where object pointer will be stored. Must be non-NULL. 776 * "plContext" 777 * Platform-specific context pointer. 778 * THREAD SAFETY: 779 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 780 * RETURNS: 781 * Returns NULL if the function succeeds. 782 * Returns a Cert Error if the function fails in a non-fatal way. 783 * Returns a Fatal Error if the function fails in an unrecoverable way. 784 */ 785 PKIX_Error * 786 PKIX_PL_BasicConstraints_GetCAFlag( 787 PKIX_PL_CertBasicConstraints *basicConstraints, 788 PKIX_Boolean *pResult, 789 void *plContext); 790 791 /* 792 * FUNCTION: PKIX_PL_BasicConstraints_GetPathLenConstraint 793 * DESCRIPTION: 794 * 795 * Retrieves a pointer to an integer value representing the pathLenConstraint 796 * component of the CertBasicConstraints object pointed to by 797 * "basicConstraints" and stores it at "pPathLenConstraint". If the 798 * pathLenConstraint component is not present, this function stores -1 at 799 * "pPathLenConstraint". 800 * 801 * PARAMETERS: 802 * "basicConstraints" 803 * Address of CertBasicConstraints whose pathLen is to be stored. 804 * Must be non-NULL. 805 * "pPathLenConstraint" 806 * Address where PKIX_Int32 will be stored. Must be non-NULL. 807 * "plContext" 808 * Platform-specific context pointer. 809 * THREAD SAFETY: 810 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 811 * RETURNS: 812 * Returns NULL if the function succeeds. 813 * Returns a Cert Error if the function fails in a non-fatal way. 814 * Returns a Fatal Error if the function fails in an unrecoverable way. 815 */ 816 PKIX_Error * 817 PKIX_PL_BasicConstraints_GetPathLenConstraint( 818 PKIX_PL_CertBasicConstraints *basicConstraints, 819 PKIX_Int32 *pPathLenConstraint, 820 void *plContext); 821 822 /* 823 * FUNCTION: PKIX_PL_Cert_GetPolicyInformation 824 * DESCRIPTION: 825 * 826 * Retrieves a pointer to a List of CertPolicyInfos found in the certificate 827 * policies extension of the Cert pointed to by "cert" and stores it at 828 * "pPolicyInfo". If "cert" does not have a certificate policies extension, 829 * this function stores NULL at "pPolicyInfo". Once created, a CertPolicyInfo 830 * object is immutable. 831 * 832 * Note that the List returned by this function is immutable. 833 * 834 * certificatePolicies ::= SEQUENCE SIZE (1..MAX) OF PolicyInformation 835 * 836 * PolicyInformation ::= SEQUENCE { 837 * policyIdentifier CertPolicyId, 838 * policyQualifiers SEQUENCE SIZE (1..MAX) OF 839 * PolicyQualifierInfo OPTIONAL } 840 * 841 * PARAMETERS: 842 * "cert" 843 * Address of Cert whose CertPolicyInfos are to be stored. 844 * Must be non-NULL. 845 * "pPolicyInfo" 846 * Address where object pointer will be stored. Must be non-NULL. 847 * "plContext" 848 * Platform-specific context pointer. 849 * THREAD SAFETY: 850 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 851 * RETURNS: 852 * Returns NULL if the function succeeds. 853 * Returns a Cert Error if the function fails in a non-fatal way. 854 * Returns a Fatal Error if the function fails in an unrecoverable way. 855 */ 856 PKIX_Error * 857 PKIX_PL_Cert_GetPolicyInformation( 858 PKIX_PL_Cert *cert, 859 PKIX_List **pPolicyInfo, /* list of PKIX_PL_CertPolicyInfo */ 860 void *plContext); 861 862 /* 863 * FUNCTION: PKIX_PL_CertPolicyInfo_GetPolicyId 864 * DESCRIPTION: 865 * 866 * Retrieves a pointer to an OID representing the policyIdentifier of the 867 * CertPolicyInfo pointed to by "policyInfo" and stores it at "pCertPolicyId". 868 * 869 * certificatePolicies ::= SEQUENCE SIZE (1..MAX) OF PolicyInformation 870 * 871 * PolicyInformation ::= SEQUENCE { 872 * policyIdentifier CertPolicyId, 873 * policyQualifiers SEQUENCE SIZE (1..MAX) OF 874 * PolicyQualifierInfo OPTIONAL } 875 * 876 * CertPolicyId ::= OBJECT IDENTIFIER 877 * 878 * PARAMETERS: 879 * "policyInfo" 880 * Address of CertPolicyInfo whose policy identifier is to be stored. 881 * Must be non-NULL. 882 * "pCertPolicyId" 883 * Address where object pointer will be stored. Must be non-NULL. 884 * "plContext" 885 * Platform-specific context pointer. 886 * THREAD SAFETY: 887 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 888 * RETURNS: 889 * Returns NULL if the function succeeds. 890 * Returns a Cert Error if the function fails in a non-fatal way. 891 * Returns a Fatal Error if the function fails in an unrecoverable way. 892 */ 893 PKIX_Error * 894 PKIX_PL_CertPolicyInfo_GetPolicyId( 895 PKIX_PL_CertPolicyInfo *policyInfo, 896 PKIX_PL_OID **pCertPolicyId, 897 void *plContext); 898 899 /* 900 * FUNCTION: PKIX_PL_CertPolicyInfo_GetPolQualifiers 901 * DESCRIPTION: 902 * 903 * Retrieves a pointer to a List of the CertPolicyQualifiers representing 904 * the policyQualifiers of the CertPolicyInfo pointed to by "policyInfo" and 905 * stores it at "pPolicyQualifiers". If "policyInfo" does not have any 906 * policyQualifiers, this function stores NULL at "pPolicyQualifiers". Once 907 * created, a CertPolicyQualifier is immutable. 908 * 909 * Note that the List returned by this function is immutable. 910 * 911 * certificatePolicies ::= SEQUENCE SIZE (1..MAX) OF PolicyInformation 912 * 913 * PolicyInformation ::= SEQUENCE { 914 * policyIdentifier CertPolicyId, 915 * policyQualifiers SEQUENCE SIZE (1..MAX) OF 916 * PolicyQualifierInfo OPTIONAL } 917 * 918 * PolicyQualifierInfo ::= SEQUENCE { 919 * policyQualifierId PolicyQualifierId, 920 * qualifier ANY DEFINED BY policyQualifierId } 921 * 922 * PARAMETERS: 923 * "policyInfo" 924 * Address of CertPolicyInfo whose policy qualifiers List is to be stored. 925 * Must be non-NULL. 926 * "pPolicyQualifiers" 927 * Address where object pointer will be stored. Must be non-NULL. 928 * "plContext" 929 * Platform-specific context pointer. 930 * THREAD SAFETY: 931 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 932 * RETURNS: 933 * Returns NULL if the function succeeds. 934 * Returns a Cert Error if the function fails in a non-fatal way. 935 * Returns a Fatal Error if the function fails in an unrecoverable way. 936 */ 937 PKIX_Error * 938 PKIX_PL_CertPolicyInfo_GetPolQualifiers( 939 PKIX_PL_CertPolicyInfo *policyInfo, 940 PKIX_List **pPolicyQualifiers, /* list of PKIX_PL_CertPolicyQualifier */ 941 void *plContext); 942 943 /* 944 * FUNCTION: PKIX_PL_PolicyQualifier_GetPolicyQualifierId 945 * DESCRIPTION: 946 * 947 * Retrieves a pointer to an OID representing the policyQualifierId of the 948 * CertPolicyQualifier pointed to by "policyQualifier" and stores it at 949 * "pPolicyQualifierId". 950 * 951 * PolicyQualifierInfo ::= SEQUENCE { 952 * policyQualifierId PolicyQualifierId, 953 * qualifier ANY DEFINED BY policyQualifierId } 954 * 955 * PolicyQualifierId ::= 956 * OBJECT IDENTIFIER ( id-qt-cps | id-qt-unotice ) 957 * 958 * PARAMETERS: 959 * "policyQualifier" 960 * Address of CertPolQualifier whose policyQualifierId is to be stored. 961 * Must be non-NULL. 962 * "pPolicyQualifierId" 963 * Address where object pointer will be stored. Must be non-NULL. 964 * "plContext" 965 * Platform-specific context pointer. 966 * THREAD SAFETY: 967 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 968 * RETURNS: 969 * Returns NULL if the function succeeds. 970 * Returns a Cert Error if the function fails in a non-fatal way. 971 * Returns a Fatal Error if the function fails in an unrecoverable way. 972 */ 973 PKIX_Error * 974 PKIX_PL_PolicyQualifier_GetPolicyQualifierId( 975 PKIX_PL_CertPolicyQualifier *policyQualifier, 976 PKIX_PL_OID **pPolicyQualifierId, 977 void *plContext); 978 979 /* 980 * FUNCTION: PKIX_PL_PolicyQualifier_GetQualifier 981 * DESCRIPTION: 982 * 983 * Retrieves a pointer to a ByteArray representing the qualifier of the 984 * CertPolicyQualifier pointed to by "policyQualifier" and stores it at 985 * "pQualifier". 986 * 987 * PolicyQualifierInfo ::= SEQUENCE { 988 * policyQualifierId PolicyQualifierId, 989 * qualifier ANY DEFINED BY policyQualifierId } 990 * 991 * PARAMETERS: 992 * "policyQualifier" 993 * Address of CertPolicyQualifier whose qualifier is to be stored. 994 * Must be non-NULL. 995 * "pQualifier" 996 * Address where object pointer will be stored. Must be non-NULL. 997 * "plContext" 998 * Platform-specific context pointer. 999 * THREAD SAFETY: 1000 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1001 * RETURNS: 1002 * Returns NULL if the function succeeds. 1003 * Returns a Cert Error if the function fails in a non-fatal way. 1004 * Returns a Fatal Error if the function fails in an unrecoverable way. 1005 */ 1006 PKIX_Error * 1007 PKIX_PL_PolicyQualifier_GetQualifier( 1008 PKIX_PL_CertPolicyQualifier *policyQualifier, 1009 PKIX_PL_ByteArray **pQualifier, 1010 void *plContext); 1011 1012 /* 1013 * FUNCTION: PKIX_PL_Cert_GetPolicyMappings 1014 * DESCRIPTION: 1015 * 1016 * Retrieves a pointer to a List of CertPolicyMaps found in the policy 1017 * mappings extension of the Cert pointed to by "cert" and stores it at 1018 * "pPolicyMappings". If "cert" does not have a policy mappings extension, 1019 * this function stores NULL at "pPolicyMappings". Once created, a 1020 * CertPolicyMap is immutable. 1021 * 1022 * Note that the List returned by this function is immutable. 1023 * 1024 * PolicyMappings ::= SEQUENCE SIZE (1..MAX) OF SEQUENCE { 1025 * issuerDomainPolicy CertPolicyId, 1026 * subjectDomainPolicy CertPolicyId } 1027 * 1028 * PARAMETERS: 1029 * "cert" 1030 * Address of Cert whose CertPolicyMaps are to be stored. 1031 * Must be non-NULL. 1032 * "pPolicyMappings" 1033 * Address where object pointer will be stored. Must be non-NULL. 1034 * "plContext" 1035 * Platform-specific context pointer. 1036 * THREAD SAFETY: 1037 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1038 * RETURNS: 1039 * Returns NULL if the function succeeds. 1040 * Returns a Cert Error if the function fails in a non-fatal way. 1041 * Returns a Fatal Error if the function fails in an unrecoverable way. 1042 */ 1043 PKIX_Error * 1044 PKIX_PL_Cert_GetPolicyMappings( 1045 PKIX_PL_Cert *cert, 1046 PKIX_List **pPolicyMappings, /* list of PKIX_PL_CertPolicyMap */ 1047 void *plContext); 1048 1049 /* 1050 * FUNCTION: PKIX_PL_CertPolicyMap_GetIssuerDomainPolicy 1051 * DESCRIPTION: 1052 * 1053 * Retrieves a pointer to an OID representing the issuerDomainPolicy of the 1054 * CertPolicyMap pointed to by "policyMapping" and stores it at 1055 * "pIssuerDomainPolicy". 1056 * 1057 * PolicyMappings ::= SEQUENCE SIZE (1..MAX) OF SEQUENCE { 1058 * issuerDomainPolicy CertPolicyId, 1059 * subjectDomainPolicy CertPolicyId } 1060 * 1061 * PARAMETERS: 1062 * "policyMapping" 1063 * Address of CertPolicyMap whose issuerDomainPolicy is to be stored. 1064 * Must be non-NULL. 1065 * "pIssuerDomainPolicy" 1066 * Address where object pointer will be stored. Must be non-NULL. 1067 * "plContext" 1068 * Platform-specific context pointer. 1069 * THREAD SAFETY: 1070 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1071 * RETURNS: 1072 * Returns NULL if the function succeeds. 1073 * Returns a Cert Error if the function fails in a non-fatal way. 1074 * Returns a Fatal Error if the function fails in an unrecoverable way. 1075 */ 1076 PKIX_Error * 1077 PKIX_PL_CertPolicyMap_GetIssuerDomainPolicy( 1078 PKIX_PL_CertPolicyMap *policyMapping, 1079 PKIX_PL_OID **pIssuerDomainPolicy, 1080 void *plContext); 1081 1082 /* 1083 * FUNCTION: PKIX_PL_CertPolicyMap_GetSubjectDomainPolicy 1084 * DESCRIPTION: 1085 * 1086 * Retrieves a pointer to an OID representing the subjectDomainPolicy of the 1087 * CertPolicyMap pointed to by "policyMapping" and stores it at 1088 * "pSubjectDomainPolicy". 1089 * 1090 * PolicyMappings ::= SEQUENCE SIZE (1..MAX) OF SEQUENCE { 1091 * issuerDomainPolicy CertPolicyId, 1092 * subjectDomainPolicy CertPolicyId } 1093 * 1094 * PARAMETERS: 1095 * "policyMapping" 1096 * Address of CertPolicyMap whose subjectDomainPolicy is to be stored. 1097 * Must be non-NULL. 1098 * "pSubjectDomainPolicy" 1099 * Address where object pointer will be stored. Must be non-NULL. 1100 * "plContext" 1101 * Platform-specific context pointer. 1102 * THREAD SAFETY: 1103 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1104 * RETURNS: 1105 * Returns NULL if the function succeeds. 1106 * Returns a Cert Error if the function fails in a non-fatal way. 1107 * Returns a Fatal Error if the function fails in an unrecoverable way. 1108 */ 1109 PKIX_Error * 1110 PKIX_PL_CertPolicyMap_GetSubjectDomainPolicy( 1111 PKIX_PL_CertPolicyMap *policyMapping, 1112 PKIX_PL_OID **pSubjectDomainPolicy, 1113 void *plContext); 1114 1115 /* 1116 * FUNCTION: PKIX_PL_Cert_GetRequireExplicitPolicy 1117 * DESCRIPTION: 1118 * 1119 * Retrieves the requireExplicitPolicy value of the policy constraints 1120 * extension of the Cert pointed to by "cert" and stores it at "pSkipCerts". 1121 * If "cert" does not have a policy constraints extension or the 1122 * requireExplicitPolicy component is not populated, this function stores -1 1123 * at "pSkipCerts". 1124 * 1125 * PolicyConstraints ::= SEQUENCE { 1126 * requireExplicitPolicy [0] SkipCerts OPTIONAL, 1127 * inhibitPolicyMapping [1] SkipCerts OPTIONAL } 1128 * 1129 * SkipCerts ::= INTEGER (0..MAX) 1130 * 1131 * PARAMETERS: 1132 * "cert" 1133 * Address of Cert whose requireExplicitPolicy value is to be stored. 1134 * Must be non-NULL. 1135 * "pSkipCerts" 1136 * Address where PKIX_Int32 will be stored. Must be non-NULL. 1137 * "plContext" 1138 * Platform-specific context pointer. 1139 * THREAD SAFETY: 1140 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1141 * RETURNS: 1142 * Returns NULL if the function succeeds. 1143 * Returns a Cert Error if the function fails in a non-fatal way. 1144 * Returns a Fatal Error if the function fails in an unrecoverable way. 1145 */ 1146 PKIX_Error * 1147 PKIX_PL_Cert_GetRequireExplicitPolicy( 1148 PKIX_PL_Cert *cert, 1149 PKIX_Int32 *pSkipCerts, 1150 void *plContext); 1151 1152 /* 1153 * FUNCTION: PKIX_PL_Cert_GetPolicyMappingInhibited 1154 * DESCRIPTION: 1155 * 1156 * Retrieves the inhibitPolicyMapping value of the policy constraints 1157 * extension of the Cert pointed to by "cert" and stores it at "pSkipCerts". 1158 * If "cert" does not have a policy constraints extension or the 1159 * inhibitPolicyMapping component is not populated, this function stores -1 1160 * at "pSkipCerts". 1161 * 1162 * PolicyConstraints ::= SEQUENCE { 1163 * requireExplicitPolicy [0] SkipCerts OPTIONAL, 1164 * inhibitPolicyMapping [1] SkipCerts OPTIONAL } 1165 * 1166 * SkipCerts ::= INTEGER (0..MAX) 1167 * 1168 * PARAMETERS: 1169 * "cert" 1170 * Address of Cert whose requireExplicitPolicy value is to be stored. 1171 * Must be non-NULL. 1172 * "pSkipCerts" 1173 * Address where PKIX_Int32 will be stored. Must be non-NULL. 1174 * "plContext" 1175 * Platform-specific context pointer. 1176 * THREAD SAFETY: 1177 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1178 * RETURNS: 1179 * Returns NULL if the function succeeds. 1180 * Returns a Cert Error if the function fails in a non-fatal way. 1181 * Returns a Fatal Error if the function fails in an unrecoverable way. 1182 */ 1183 PKIX_Error * 1184 PKIX_PL_Cert_GetPolicyMappingInhibited( 1185 PKIX_PL_Cert *cert, 1186 PKIX_Int32 *pSkipCerts, 1187 void *plContext); 1188 1189 /* 1190 * FUNCTION: PKIX_PL_Cert_GetInhibitAnyPolicy 1191 * DESCRIPTION: 1192 * 1193 * Retrieves the value of the inhibit any-policy extension of the Cert 1194 * pointed to by "cert" and stores it at "pSkipCerts". If "cert" does not have 1195 * an inhibit any-policy extension, this function stores -1 at "pSkipCerts". 1196 * 1197 * InhibitAnyPolicy ::= SkipCerts 1198 * 1199 * SkipCerts ::= INTEGER (0..MAX) 1200 * 1201 * PARAMETERS: 1202 * "cert" 1203 * Address of Cert whose inhibit any-policy extensions value is to be 1204 * stored. Must be non-NULL. 1205 * "pSkipCerts" 1206 * Address where PKIX_Int32 will be stored. Must be non-NULL. 1207 * "plContext" 1208 * Platform-specific context pointer. 1209 * THREAD SAFETY: 1210 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1211 * RETURNS: 1212 * Returns NULL if the function succeeds. 1213 * Returns a Cert Error if the function fails in a non-fatal way. 1214 * Returns a Fatal Error if the function fails in an unrecoverable way. 1215 */ 1216 PKIX_Error * 1217 PKIX_PL_Cert_GetInhibitAnyPolicy( 1218 PKIX_PL_Cert *cert, 1219 PKIX_Int32 *pSkipCerts, 1220 void *plContext); 1221 1222 /* policy processing functions */ 1223 1224 /* 1225 * FUNCTION: PKIX_PL_Cert_AreCertPoliciesCritical 1226 * DESCRIPTION: 1227 * 1228 * Checks whether the certificate policies extension of the Cert pointed to 1229 * by "cert" is critical and stores the Boolean result at "pCritical". If 1230 * "cert" does not have a certificate policies extension, this function 1231 * stores NULL at "pCritical". 1232 * 1233 * XXX what distinguishes NULL from PKIX_FALSE? 1234 * 1235 * PARAMETERS: 1236 * "cert" 1237 * Address of Cert whose certificate policies extension's criticality is 1238 * to be determined. Must be non-NULL. 1239 * "pCritical" 1240 * Address where PKIX_Boolean will be stored. Must be non-NULL. 1241 * "plContext" 1242 * Platform-specific context pointer. 1243 * THREAD SAFETY: 1244 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1245 * RETURNS: 1246 * Returns NULL if the function succeeds. 1247 * Returns a Cert Error if the function fails in a non-fatal way. 1248 * Returns a Fatal Error if the function fails in an unrecoverable way. 1249 */ 1250 PKIX_Error * 1251 PKIX_PL_Cert_AreCertPoliciesCritical( 1252 PKIX_PL_Cert *cert, 1253 PKIX_Boolean *pCritical, 1254 void *plContext); 1255 1256 /* 1257 * FUNCTION: PKIX_PL_Cert_CheckNameConstraints 1258 * DESCRIPTION: 1259 * 1260 * Checks whether the subject distinguished name and subject alternative names 1261 * of the Cert pointed to by "cert" satisfy the CertNameConstraints pointed 1262 * to by "nameConstraints". If the CertNameConstraints are not satisfied, a 1263 * PKIX_Error pointer is returned. If "nameConstraints" is NULL, the function 1264 * does nothing. 1265 * 1266 * PARAMETERS: 1267 * "cert" 1268 * Address of Cert whose subject names are to be checked. 1269 * Must be non-NULL. 1270 * "nameConstraints" 1271 * Address of CertNameConstraints that need to be satisfied. 1272 * "treatCommonNameAsDNSName" 1273 * PKIX_TRUE if the subject common name should be considered a dNSName 1274 * when evaluating name constraints. 1275 * "plContext" 1276 * Platform-specific context pointer. 1277 * THREAD SAFETY: 1278 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1279 * RETURNS: 1280 * Returns NULL if the function succeeds. 1281 * Returns a Cert Error if the function fails in a non-fatal way. 1282 * Returns a Fatal Error if the function fails in an unrecoverable way. 1283 */ 1284 PKIX_Error * 1285 PKIX_PL_Cert_CheckNameConstraints( 1286 PKIX_PL_Cert *cert, 1287 PKIX_PL_CertNameConstraints *nameConstraints, 1288 PKIX_Boolean treatCommonNameAsDNSName, 1289 void *plContext); 1290 1291 /* 1292 * FUNCTION: PKIX_PL_Cert_MergeNameConstraints 1293 * DESCRIPTION: 1294 * 1295 * Merges the CertNameConstraints pointed to by "firstNC" and the 1296 * CertNameConstraints pointed to by "secondNC" and stores the merged 1297 * CertNameConstraints at "pResultNC". If "secondNC" is NULL, the 1298 * CertNameConstraints pointed to by "firstNC" is stored at "pResultNC". 1299 * 1300 * Once created, a CertNameConstraints object is immutable. 1301 * 1302 * PARAMETERS: 1303 * "firstNC" 1304 * Address of first CertNameConstraints to be merged. Must be non-NULL. 1305 * "secondNC" 1306 * Address of second CertNameConstraints to be merged 1307 * "pResultNC" 1308 * Address where object pointer will be stored. Must be non-NULL. 1309 * "plContext" 1310 * Platform-specific context pointer. 1311 * THREAD SAFETY: 1312 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1313 * RETURNS: 1314 * Returns NULL if the function succeeds. 1315 * Returns a Cert Error if the function fails in a non-fatal way. 1316 * Returns a Fatal Error if the function fails in an unrecoverable way. 1317 */ 1318 PKIX_Error * 1319 PKIX_PL_Cert_MergeNameConstraints( 1320 PKIX_PL_CertNameConstraints *firstNC, 1321 PKIX_PL_CertNameConstraints *secondNC, 1322 PKIX_PL_CertNameConstraints **pResultNC, 1323 void *plContext); 1324 1325 /* 1326 * FUNCTION: PKIX_PL_Cert_VerifyKeyUsage 1327 * DESCRIPTION: 1328 * 1329 * Verifies that the keyUsage bit(s) specified by "keyUsage" appear in the 1330 * keyUsage extension of the Cert pointed to by "cert". The keyUsage bit 1331 * values specified in pkixt.h are supported, and can be bitwise or'ed if 1332 * multiple bit values are to be verified. If the keyUsages do not all appear 1333 * in the keyUsage extension of "cert", a PKIX_Error pointer is returned. 1334 * 1335 * KeyUsage ::= BIT STRING { 1336 * digitalSignature (0), 1337 * nonRepudiation (1), 1338 * keyEncipherment (2), 1339 * dataEncipherment (3), 1340 * keyAgreement (4), 1341 * keyCertSign (5), 1342 * cRLSign (6), 1343 * encipherOnly (7), 1344 * decipherOnly (8) } 1345 * 1346 * PARAMETERS: 1347 * "cert" 1348 * Address of Cert whose keyUsage bits are to be verified. 1349 * Must be non-NULL. 1350 * "keyUsage" 1351 * Constant representing keyUsage bit(s) that all must appear in keyUsage 1352 * extension of "cert". 1353 * "plContext" - Platform-specific context pointer. 1354 * THREAD SAFETY: 1355 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1356 * RETURNS: 1357 * Returns NULL if the function succeeds. 1358 * Returns a Cert Error if the function fails in a non-fatal way. 1359 * Returns a Fatal Error if the function fails in an unrecoverable way. 1360 */ 1361 PKIX_Error * 1362 PKIX_PL_Cert_VerifyKeyUsage( 1363 PKIX_PL_Cert *cert, 1364 PKIX_UInt32 keyUsage, 1365 void *plContext); 1366 1367 /* 1368 * FUNCTION: PKIX_PL_Cert_VerifyCertAndKeyType 1369 * DESCRIPTION: 1370 * 1371 * Verifies cert and key types against certificate usage that is 1372 * a part of plContext(pkix_pl_nsscontext) structure. Throws an error 1373 * if cert or key types does not match. 1374 * 1375 * PARAMETERS: 1376 * "cert" 1377 * Address of Cert whose keyUsage bits are to be verified. 1378 * Must be non-NULL. 1379 * "isLeafCert" 1380 * What type of a cert has been verified. 1381 * "plContext" - Platform-specific context pointer. 1382 * THREAD SAFETY: 1383 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1384 * RETURNS: 1385 * Returns NULL if the function succeeds. 1386 * Returns a Cert Error if the function fails in a non-fatal way. 1387 * Returns a Fatal Error if the function fails in an unrecoverable way. 1388 */ 1389 PKIX_Error * 1390 PKIX_PL_Cert_VerifyCertAndKeyType( 1391 PKIX_PL_Cert *cert, 1392 PKIX_Boolean isChainCert, 1393 void *plContext); 1394 1395 /* 1396 * FUNCTION: PKIX_PL_Cert_CheckValidity 1397 * DESCRIPTION: 1398 * 1399 * Checks whether the Cert pointed to by "cert" would be valid at the time 1400 * represented by the Date pointed to by "date". If "date" is NULL, then this 1401 * function checks whether the Cert would be valid at the current time. If the 1402 * Cert would not be valid at the specified Date, a PKIX_Error pointer is 1403 * returned. 1404 * 1405 * Validity ::= SEQUENCE { 1406 * notBefore Time, 1407 * notAfter Time } 1408 * 1409 * Time ::= CHOICE { 1410 * utcTime UTCTime, 1411 * generalTime GeneralizedTime } 1412 * 1413 * PARAMETERS: 1414 * "cert" 1415 * Address of Cert whose validity is to be checked. Must be non-NULL. 1416 * "date" 1417 * Address of Date at which the Cert is being checked for validity. 1418 * If NULL, the current time is used for the Date. 1419 * "plContext" 1420 * Platform-specific context pointer. 1421 * THREAD SAFETY: 1422 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1423 * RETURNS: 1424 * Returns NULL if the function succeeds. 1425 * Returns a Cert Error if the function fails in a non-fatal way. 1426 * Returns a Fatal Error if the function fails in an unrecoverable way. 1427 */ 1428 PKIX_Error * 1429 PKIX_PL_Cert_CheckValidity( 1430 PKIX_PL_Cert *cert, 1431 PKIX_PL_Date *date, 1432 void *plContext); 1433 1434 /* 1435 * FUNCTION: PKIX_PL_Cert_GetValidityNotAfter 1436 * DESCRIPTION: 1437 * 1438 * Retrieves a pointer to the Date that represents the notAfter time of the 1439 * Certificate pointed to by "cert" and stores it at "pDate". 1440 * 1441 * Validity ::= SEQUENCE { 1442 * notBefore Time, 1443 * notAfter Time } 1444 * 1445 * PARAMETERS: 1446 * "cert" 1447 * Address of Cert whose validity time is to be retrieved. Must be 1448 * non-NULL. 1449 * "date" 1450 * Address of Date at which the Cert's notAfter time is being retrieved. 1451 * Must be non-NULL. 1452 * "plContext" 1453 * Platform-specific context pointer. 1454 * THREAD SAFETY: 1455 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1456 * RETURNS: 1457 * Returns NULL if the function succeeds. 1458 * Returns a Cert Error if the function fails in a non-fatal way. 1459 * Returns a Fatal Error if the function fails in an unrecoverable way. 1460 */ 1461 PKIX_Error * 1462 PKIX_PL_Cert_GetValidityNotAfter( 1463 PKIX_PL_Cert *cert, 1464 PKIX_PL_Date **pDate, 1465 void *plContext); 1466 1467 /* 1468 * FUNCTION: PKIX_PL_Cert_VerifySignature 1469 * DESCRIPTION: 1470 * 1471 * Verifies the signature on the Cert pointed to by "cert" using the 1472 * PublicKey pointed to by "pubKey". If the signature doesn't verify, an 1473 * Error pointer is returned. 1474 * 1475 * PARAMETERS: 1476 * "cert" 1477 * Address of Cert whose signature is to be verified. Must be non-NULL. 1478 * "pubKey" 1479 * Address of a Public Key used to verify the signature. Must be non-NULL. 1480 * "plContext" 1481 * Platform-specific context pointer. 1482 * THREAD SAFETY: 1483 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1484 * RETURNS: 1485 * Returns NULL if the function succeeds. 1486 * Returns a Cert Error if the function fails in a non-fatal way. 1487 * Returns a Fatal Error if the function fails in an unrecoverable way. 1488 */ 1489 PKIX_Error * 1490 PKIX_PL_Cert_VerifySignature( 1491 PKIX_PL_Cert *cert, 1492 PKIX_PL_PublicKey *pubKey, 1493 void *plContext); 1494 1495 /* A set of flags to indicate how explicitly configured trust anchors should be 1496 * handled by PKIX_PL_Cert_IsCertTrusted 1497 */ 1498 typedef enum PKIX_PL_TrustAnchorModeEnum { 1499 /* Indicates trust anchors should be ignored; only the underlying 1500 * platform's trust settings should be used. 1501 */ 1502 PKIX_PL_TrustAnchorMode_Ignore, 1503 1504 /* Indicates that explicitly configured trust anchors may be considered 1505 * trustworthy, if present. 1506 * Note: If the underlying platform supports marking a certificate as 1507 * explicitly untrustworthy, explicitly configured trust anchors 1508 * MAY be ignored/rejected. 1509 */ 1510 PKIX_PL_TrustAnchorMode_Additive, 1511 1512 /* Indicates that ONLY trust anchors should be considered as 1513 * trustworthy. 1514 * Note: If the underlying platform supports marking a certificate as 1515 * explicitly untrustworthy, explicitly configured trust anchors 1516 * MAY be ignored/rejected. 1517 */ 1518 PKIX_PL_TrustAnchorMode_Exclusive 1519 } PKIX_PL_TrustAnchorMode; 1520 1521 /* 1522 * FUNCTION: PKIX_PL_Cert_IsCertTrusted 1523 * DESCRIPTION: 1524 * 1525 * Checks the Cert specified by "cert" to determine, in a manner that depends 1526 * on the underlying platform, whether it is trusted, and stores the result in 1527 * "pTrusted". If a certificate is trusted it means that a chain built to that 1528 * certificate, and satisfying all the usage, policy, validity, and other 1529 * tests, is a valid chain and the End Entity certificate from which it was 1530 * built can be trusted. 1531 * 1532 * If the Certificate is not intrinsically trustworthy, it still might end up a 1533 * component in a successful chain. 1534 * 1535 * If the Certificate is intrinsically untrustworthy, this function will return 1536 * an error. 1537 * 1538 * PARAMETERS 1539 * "cert" 1540 * Address of Cert whose trustworthiness is to be determined. Must be 1541 * non-NULL. 1542 * "trustAnchorMode" 1543 * A PKIX_PL_TrustAnchorMode that indicates how explicitly defined user 1544 * trust anchors should be handled. 1545 * "pTrusted" 1546 * Address where the Boolean value will be stored. Must be non-NULL. 1547 * "plContext" 1548 * Platform-specific context pointer. 1549 * THREAD SAFETY: 1550 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1551 * RETURNS: 1552 * Returns NULL if the function succeeds. 1553 * Returns a CERT Error if the function fails in a non-fatal way. 1554 * Returns a Fatal Error if the function fails in an unrecoverable way. 1555 */ 1556 PKIX_Error * 1557 PKIX_PL_Cert_IsCertTrusted( 1558 PKIX_PL_Cert *cert, 1559 PKIX_PL_TrustAnchorMode trustAnchorMode, 1560 PKIX_Boolean *pTrusted, 1561 void *plContext); 1562 1563 /* 1564 * FUNCTION: PKIX_PL_Cert_IsLeafCertTrusted 1565 * DESCRIPTION: 1566 * 1567 * Checks the Leaf Cert specified by "cert" to determine, in a manner that 1568 * depends on the underlying platform, whether it is trusted, and stores the 1569 * result in "pTrusted". If a certificate is trusted it means that this 1570 * End Entify certificate has been marked as trusted for the requested usage, 1571 * policy, validity, and other tests. 1572 * 1573 * If the Certificate is not intrinsically trustworthy, we can still try to 1574 * build a successful chain. 1575 * 1576 * If the Certificate is intrinsically untrustworthy, this function will return 1577 * an error. 1578 * 1579 * PARAMETERS 1580 * "cert" 1581 * Address of Cert whose trustworthiness is to be determined. Must be 1582 * non-NULL. 1583 * "pTrusted" 1584 * Address where the Boolean value will be stored. Must be non-NULL. 1585 * "plContext" 1586 * Platform-specific context pointer. 1587 * THREAD SAFETY: 1588 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1589 * RETURNS: 1590 * Returns NULL if the function succeeds. 1591 * Returns a CERT Error if the function fails in a non-fatal way. 1592 * Returns a Fatal Error if the function fails in an unrecoverable way. 1593 */ 1594 PKIX_Error * 1595 PKIX_PL_Cert_IsLeafCertTrusted( 1596 PKIX_PL_Cert *cert, 1597 PKIX_Boolean *pTrusted, 1598 void *plContext); 1599 1600 /* FUNCTION: PKIX_PL_Cert_SetAsTrustAnchor */ 1601 PKIX_Error* 1602 PKIX_PL_Cert_SetAsTrustAnchor(PKIX_PL_Cert *cert, 1603 void *plContext); 1604 1605 /* 1606 * FUNCTION: PKIX_PL_Cert_GetCacheFlag 1607 * DESCRIPTION: 1608 * 1609 * Retrieves the value of the cache flag in "cert" and return it at address 1610 * pointed by "pCacheFlag". The initila cache flag is determined by the 1611 * CertStore this "cert" is fetched from. When CertStore is created, user 1612 * need to specify if the data should be cached. 1613 * 1614 * PARAMETERS: 1615 * "cert" 1616 * Address of Cert whose cache flag is fetched. Must be non-NULL. 1617 * "pCacheFlag" 1618 * Address where PKIX_Boolean will be stored. Must be non-NULL. 1619 * "plContext" 1620 * Platform-specific context pointer. 1621 * THREAD SAFETY: 1622 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1623 * RETURNS: 1624 * Returns NULL if the function succeeds. 1625 * Returns a Cert Error if the function fails in a non-fatal way. 1626 * Returns a Fatal Error if the function fails in an unrecoverable way. 1627 */ 1628 PKIX_Error * 1629 PKIX_PL_Cert_GetCacheFlag( 1630 PKIX_PL_Cert *cert, 1631 PKIX_Boolean *pCacheFlag, 1632 void *plContext); 1633 1634 /* 1635 * FUNCTION: PKIX_PL_Cert_SetCacheFlag 1636 * DESCRIPTION: 1637 * 1638 * Set the value of the cache flag in "cert" base on the boolean value stored 1639 * at "cacheFlag". This function is meant to be used by CertStore after a 1640 * Cert is created. 1641 * 1642 * PARAMETERS: 1643 * "cert" 1644 * Address of Cert where "cacheFlag" is stored. Must be non-NULL. 1645 * "cacheFlag" 1646 * PKIX_Boolean flag for cache flag. 1647 * "plContext" 1648 * Platform-specific context pointer. 1649 * THREAD SAFETY: 1650 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1651 * RETURNS: 1652 * Returns NULL if the function succeeds. 1653 * Returns a Cert Error if the function fails in a non-fatal way. 1654 * Returns a Fatal Error if the function fails in an unrecoverable way. 1655 */ 1656 PKIX_Error * 1657 PKIX_PL_Cert_SetCacheFlag( 1658 PKIX_PL_Cert *cert, 1659 PKIX_Boolean cacheFlag, 1660 void *plContext); 1661 1662 /* 1663 * FUNCTION: PKIX_PL_Cert_GetTrustCertStore 1664 * DESCRIPTION: 1665 * 1666 * Retrieves the value of the CertStore in "cert" and return it at address 1667 * pointed by "pCertStore". 1668 * 1669 * PARAMETERS: 1670 * "cert" 1671 * Address of Cert whose CertStore is fetched. Must be non-NULL. 1672 * "pTrustCertStore" 1673 * Address where CertStore will be stored and returned. Must be non-NULL. 1674 * "plContext" 1675 * Platform-specific context pointer. 1676 * THREAD SAFETY: 1677 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1678 * RETURNS: 1679 * Returns NULL if the function succeeds. 1680 * Returns a Cert Error if the function fails in a non-fatal way. 1681 * Returns a Fatal Error if the function fails in an unrecoverable way. 1682 */ 1683 PKIX_Error * 1684 PKIX_PL_Cert_GetTrustCertStore( 1685 PKIX_PL_Cert *cert, 1686 PKIX_CertStore **pTrustCertStore, 1687 void *plContext); 1688 1689 /* 1690 * FUNCTION: PKIX_PL_Cert_SetTrustCertStore 1691 * DESCRIPTION: 1692 * 1693 * Set the value of the CertStore "certStore" in "cert". 1694 * 1695 * PARAMETERS: 1696 * "cert" 1697 * Address of Cert where "certStore" will be stored. Must be non-NULL. 1698 * "trustCertStore" 1699 * Address where the CertStore is. Must be non-NULL. 1700 * "plContext" 1701 * Platform-specific context pointer. 1702 * THREAD SAFETY: 1703 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1704 * RETURNS: 1705 * Returns NULL if the function succeeds. 1706 * Returns a Cert Error if the function fails in a non-fatal way. 1707 * Returns a Fatal Error if the function fails in an unrecoverable way. 1708 */ 1709 PKIX_Error * 1710 PKIX_PL_Cert_SetTrustCertStore( 1711 PKIX_PL_Cert *cert, 1712 PKIX_CertStore *trustCertStore, 1713 void *plContext); 1714 1715 1716 /* 1717 * FUNCTION: PKIX_PL_Cert_GetAuthorityInfoAccess 1718 * DESCRIPTION: 1719 * 1720 * Retrieves the value(s) of the Authority Information Access in "cert" and 1721 * returns it in a list at address pointed by "pAuthorityInfoAccess". 1722 * 1723 * SubjectInfoAccess ::= 1724 * SEQUENCE SIZE (1..MAX) of AccessDescription 1725 * AccessDescription ::= SEQUENCE { 1726 * accessMethod OBJECT IDENTIFIER, 1727 * accessLocation GeneralName 1728 * } 1729 * 1730 * PARAMETERS: 1731 * "cert" 1732 * Address of Cert whose Authority Information Access is fetched. 1733 * Must be non-NULL. 1734 * "pAuthorityInfoAccess" 1735 * Address where Authority InfoAccess will be stored and returned. 1736 * Must be non-NULL. 1737 * "plContext" 1738 * Platform-specific context pointer. 1739 * THREAD SAFETY: 1740 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1741 * RETURNS: 1742 * Returns NULL if the function succeeds. 1743 * Returns a Cert Error if the function fails in a non-fatal way. 1744 * Returns a Fatal Error if the function fails in an unrecoverable way. 1745 */ 1746 PKIX_Error * 1747 PKIX_PL_Cert_GetAuthorityInfoAccess( 1748 PKIX_PL_Cert *cert, 1749 PKIX_List **pAiaList, /* of PKIX_PL_InfoAccess */ 1750 void *plContext); 1751 1752 1753 /* 1754 * FUNCTION: PKIX_PL_Cert_GetSubjectInfoAccess 1755 * DESCRIPTION: 1756 * 1757 * Retrieves the value(s) of the Subject Information Access in "cert" and 1758 * returns it in a list at address pointed by "pSubjectInfoAccess". 1759 * 1760 * SubjectInfoAccess ::= 1761 * SEQUENCE SIZE (1..MAX) of AccessDescription 1762 * AccessDescription ::= SEQUENCE { 1763 * accessMethod OBJECT IDENTIFIER, 1764 * accessLocation GeneralName 1765 * } 1766 * 1767 * PARAMETERS: 1768 * "cert" 1769 * Address of Cert whose Subject Information Access is fetched. 1770 * Must be non-NULL. 1771 * "pSubjectInfoAccess" 1772 * Address where Subject InfoAccess will be stored and returned. 1773 * Must be non-NULL. 1774 * "plContext" 1775 * Platform-specific context pointer. 1776 * THREAD SAFETY: 1777 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1778 * RETURNS: 1779 * Returns NULL if the function succeeds. 1780 * Returns a Cert Error if the function fails in a non-fatal way. 1781 * Returns a Fatal Error if the function fails in an unrecoverable way. 1782 */ 1783 PKIX_Error * 1784 PKIX_PL_Cert_GetSubjectInfoAccess( 1785 PKIX_PL_Cert *cert, 1786 PKIX_List **pSiaList, /* of PKIX_PL_InfoAccess */ 1787 void *plContext); 1788 1789 1790 1791 /* 1792 * FUNCTION: PKIX_PL_Cert_GetCrlDp 1793 * DESCRIPTION: 1794 * 1795 * Retrieves the value(s) of the CRL Distribution Point Extension and 1796 * returns it in a list at address pointed by "pDpList". 1797 * 1798 * PARAMETERS: 1799 * "cert" 1800 * Address of Cert whose Subject Information Access is fetched. 1801 * Must be non-NULL. 1802 * "pDpList" 1803 * Address where CRL DP will be stored and returned. 1804 * Must be non-NULL. 1805 * "plContext" 1806 * Platform-specific context pointer. 1807 * THREAD SAFETY: 1808 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1809 * RETURNS: 1810 * Returns NULL if the function succeeds. 1811 * Returns a Cert Error if the function fails in a non-fatal way. 1812 * Returns a Fatal Error if the function fails in an unrecoverable way. 1813 */ 1814 PKIX_Error * 1815 PKIX_PL_Cert_GetCrlDp(PKIX_PL_Cert *cert, 1816 PKIX_List **pDpList, 1817 void *plContext); 1818 1819 1820 /* 1821 * InfoAccess 1822 * 1823 * To hold Authority Information Access or Subject Information Access 1824 * retrieved from a Certificate. 1825 */ 1826 1827 #define PKIX_INFOACCESS_OCSP 1 1828 #define PKIX_INFOACCESS_CA_ISSUERS 2 1829 #define PKIX_INFOACCESS_TIMESTAMPING 3 1830 #define PKIX_INFOACCESS_CA_REPOSITORY 5 1831 1832 #define PKIX_INFOACCESS_LOCATION_UNKNOWN 0 1833 #define PKIX_INFOACCESS_LOCATION_HTTP 1 1834 #ifndef NSS_PKIX_NO_LDAP 1835 #define PKIX_INFOACCESS_LOCATION_LDAP 2 1836 #endif 1837 1838 /* 1839 * FUNCTION: PKIX_PL_InfoAccess_GetMethod 1840 * DESCRIPTION: 1841 * 1842 * Stores the method of the Information Access from "infoAccess" and 1843 * returns in "pMethod". 1844 * 1845 * SubjectInfoAccess ::= 1846 * AccessDescription ::= SEQUENCE { 1847 * accessMethod OBJECT IDENTIFIER, 1848 * accessLocation GeneralName 1849 * } 1850 * 1851 * PARAMETERS: 1852 * "infoAccess" 1853 * Address of PKIX_PL_InfoAccess that has the access data. 1854 * Must be non-NULL. 1855 * "pMethod" 1856 * Address where access method will be stored and returned. 1857 * Must be non-NULL. 1858 * "plContext" 1859 * Platform-specific context pointer. 1860 * THREAD SAFETY: 1861 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1862 * RETURNS: 1863 * Returns NULL if the function succeeds. 1864 * Returns a Cert Error if the function fails in a non-fatal way. 1865 * Returns a Fatal Error if the function fails in an unrecoverable way. 1866 */ 1867 PKIX_Error * 1868 PKIX_PL_InfoAccess_GetMethod( 1869 PKIX_PL_InfoAccess *infoAccess, 1870 PKIX_UInt32 *pMethod, 1871 void *plContext); 1872 1873 /* 1874 * FUNCTION: PKIX_PL_InfoAccess_GetLocation 1875 * DESCRIPTION: 1876 * 1877 * Stores the location of the Information Access from "infoAccess" and 1878 * returns in "pLocation". 1879 * 1880 * SubjectInfoAccess ::= 1881 * AccessDescription ::= SEQUENCE { 1882 * accessMethod OBJECT IDENTIFIER, 1883 * accessLocation GeneralName 1884 * } 1885 * 1886 * PARAMETERS: 1887 * "infoAccess" 1888 * Address of PKIX_PL_InfoAccess that has the access data. 1889 * Must be non-NULL. 1890 * "pLocation" 1891 * Address where access location will be stored and returned. 1892 * Must be non-NULL. 1893 * "plContext" 1894 * Platform-specific context pointer. 1895 * THREAD SAFETY: 1896 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1897 * RETURNS: 1898 * Returns NULL if the function succeeds. 1899 * Returns a Cert Error if the function fails in a non-fatal way. 1900 * Returns a Fatal Error if the function fails in an unrecoverable way. 1901 */ 1902 PKIX_Error * 1903 PKIX_PL_InfoAccess_GetLocation( 1904 PKIX_PL_InfoAccess *infoAccess, 1905 PKIX_PL_GeneralName **pLocation, 1906 void *plContext); 1907 1908 /* 1909 * FUNCTION: PKIX_PL_InfoAccess_GetLocationType 1910 * DESCRIPTION: 1911 * 1912 * Stores the type of location of the Information Access from "infoAccess" and 1913 * returns in "pType". 1914 * 1915 * SubjectInfoAccess ::= 1916 * AccessDescription ::= SEQUENCE { 1917 * accessMethod OBJECT IDENTIFIER, 1918 * accessLocation GeneralName 1919 * } 1920 * 1921 * PARAMETERS: 1922 * "infoAccess" 1923 * Address of PKIX_PL_InfoAccess that has the access data. 1924 * Must be non-NULL. 1925 * "pType" 1926 * Address where access location type will be stored and returned. 1927 * Must be non-NULL. 1928 * "plContext" 1929 * Platform-specific context pointer. 1930 * THREAD SAFETY: 1931 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 1932 * RETURNS: 1933 * Returns NULL if the function succeeds. 1934 * Returns a Cert Error if the function fails in a non-fatal way. 1935 * Returns a Fatal Error if the function fails in an unrecoverable way. 1936 */ 1937 PKIX_Error * 1938 PKIX_PL_InfoAccess_GetLocationType( 1939 PKIX_PL_InfoAccess *infoAccess, 1940 PKIX_UInt32 *pType, 1941 void *plContext); 1942 1943 PKIX_Error * 1944 pkix_pl_InfoAccess_GetAIACerts( 1945 PKIX_PL_InfoAccess *ia, 1946 void **pNBIOContext, 1947 void **pHandle, 1948 PKIX_List **pCerts, 1949 void *plContext); 1950 1951 /* 1952 * CRL 1953 * 1954 * A CRL represents an X.509 certificate revocation list. It can be created 1955 * using the bytes of a valid ASN.1 DER encoding. Once created, a CRL is 1956 * immutable. The following functions include accessors (gettors) for the 1957 * various components of an X.509 CRL, as well as a function for signature 1958 * verification. 1959 */ 1960 1961 /* 1962 * FUNCTION: PKIX_PL_CRL_Create 1963 * DESCRIPTION: 1964 * 1965 * Creates a new CRL using the bytes in the ByteArray pointed to by 1966 * "byteArray" and stores it at "pCRL". If the bytes are not a valid ASN.1 1967 * DER encoding of a CRL, a PKIX_Error pointer is returned. Once created, a 1968 * CRL is immutable. 1969 * 1970 * CertificateList ::= SEQUENCE { 1971 * tbsCertList TBSCertList, 1972 * signatureAlgorithm AlgorithmIdentifier, 1973 * signatureValue BIT STRING } 1974 * 1975 * TBSCertList ::= SEQUENCE { 1976 * version Version OPTIONAL, 1977 * -- if present, MUST be v2 1978 * signature AlgorithmIdentifier, 1979 * issuer Name, 1980 * thisUpdate Time, 1981 * nextUpdate Time OPTIONAL, 1982 * revokedCertificates SEQUENCE OF SEQUENCE { 1983 * userCertificate CertificateSerialNumber, 1984 * revocationDate Time, 1985 * crlEntryExtensions Extensions OPTIONAL 1986 * -- if present, MUST be v2 1987 * } OPTIONAL, 1988 * crlExtensions [0] EXPLICIT Extensions OPTIONAL 1989 * -- if present, MUST be v2 1990 * } 1991 * 1992 * PARAMETERS: 1993 * "byteArray" 1994 * Address of ByteArray representing the CRL's DER encoding. 1995 * Must be non-NULL. 1996 * "pCRL" 1997 * Address where object pointer will be stored. Must be non-NULL. 1998 * "plContext" 1999 * Platform-specific context pointer. 2000 * THREAD SAFETY: 2001 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2002 * RETURNS: 2003 * Returns NULL if the function succeeds. 2004 * Returns a CRL Error if the function fails in a non-fatal way. 2005 * Returns a Fatal Error if the function fails in an unrecoverable way. 2006 */ 2007 PKIX_Error * 2008 PKIX_PL_CRL_Create( 2009 PKIX_PL_ByteArray *byteArray, 2010 PKIX_PL_CRL **pCRL, 2011 void *plContext); 2012 2013 /* 2014 * FUNCTION: PKIX_PL_CRL_GetIssuer 2015 * DESCRIPTION: 2016 * 2017 * Retrieves a pointer to the X500Name that represents the issuer of the CRL 2018 * pointed to by "crl" and stores it at "pCRLIssuer". 2019 * 2020 * PARAMETERS: 2021 * "crl" 2022 * Address of CRL whose issuer is to be stored. Must be non-NULL. 2023 * "pCRLIssuer" 2024 * Address where object pointer will be stored. Must be non-NULL. 2025 * "plContext" 2026 * Platform-specific context pointer. 2027 * THREAD SAFETY: 2028 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2029 * RETURNS: 2030 * Returns NULL if the function succeeds. 2031 * Returns a CRL Error if the function fails in a non-fatal way. 2032 * Returns a Fatal Error if the function fails in an unrecoverable way. 2033 */ 2034 PKIX_Error * 2035 PKIX_PL_CRL_GetIssuer( 2036 PKIX_PL_CRL *crl, 2037 PKIX_PL_X500Name **pCRLIssuer, 2038 void *plContext); 2039 2040 /* 2041 * FUNCTION: PKIX_PL_CRL_GetCriticalExtensionOIDs 2042 * DESCRIPTION: 2043 * 2044 * Retrieves a pointer to the List of OIDs (each OID corresponding to a 2045 * critical extension of the CRL pointed to by "crl") and stores it at 2046 * "pExtensions". If "crl" does not have any critical extensions, this 2047 * function stores an empty List at "pExtensions". 2048 * 2049 * Note that the List returned by this function is immutable. 2050 * 2051 * PARAMETERS: 2052 * "crl" 2053 * Address of CRL whose critical extension OIDs are to be stored. 2054 * Must be non-NULL. 2055 * "pExtensions" 2056 * Address where object pointer will be stored. Must be non-NULL. 2057 * "plContext" 2058 * Platform-specific context pointer. 2059 * THREAD SAFETY: 2060 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2061 * RETURNS: 2062 * Returns NULL if the function succeeds. 2063 * Returns a CRL Error if the function fails in a non-fatal way. 2064 * Returns a Fatal Error if the function fails in an unrecoverable way. 2065 */ 2066 PKIX_Error * 2067 PKIX_PL_CRL_GetCriticalExtensionOIDs( 2068 PKIX_PL_CRL *crl, 2069 PKIX_List **pExtensions, /* list of PKIX_PL_OID */ 2070 void *plContext); 2071 2072 /* 2073 * FUNCTION: PKIX_PL_CRL_GetCRLEntryForSerialNumber 2074 * DESCRIPTION: 2075 * 2076 * Retrieves a pointer to the CRLEntry (found in the CRL pointed to by "crl") 2077 * corresponding to the BigInt pointed to by "serialNumber" and stores it at 2078 * "pCRLEntry". If there is no such CRLEntry, this functions stores NULL at 2079 * "pCRLEntry". Once created, a CRLEntry is immutable. 2080 * 2081 * PARAMETERS: 2082 * "crl" 2083 * Address of CRL whose CRL Entries are to be searched. Must be non-NULL. 2084 * "serialNumber" 2085 * Address of BigInt representing serial number of certificate whose 2086 * CRLEntry is to be found. Must be non-NULL. 2087 * "pCRLEntry" 2088 * Address where object pointer will be stored. Must be non-NULL. 2089 * "plContext" 2090 * Platform-specific context pointer. 2091 * THREAD SAFETY: 2092 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2093 * RETURNS: 2094 * Returns NULL if the function succeeds. 2095 * Returns a CRL Error if the function fails in a non-fatal way. 2096 * Returns a Fatal Error if the function fails in an unrecoverable way. 2097 */ 2098 PKIX_Error * 2099 PKIX_PL_CRL_GetCRLEntryForSerialNumber( 2100 PKIX_PL_CRL *crl, 2101 PKIX_PL_BigInt *serialNumber, 2102 PKIX_PL_CRLEntry **pCRLEntry, 2103 void *plContext); 2104 2105 /* 2106 * FUNCTION: PKIX_PL_CRL_GetCRLNumber 2107 * DESCRIPTION: 2108 * Retrieves the CRL Number from extension. This is non-critical extension. 2109 * 2110 * PARAMETERS: 2111 * "crl" 2112 * Address of CRL whose version is to be stored. Must be non-NULL. 2113 * "pCrlNumber" 2114 * Address where a CRL Number will be stored. Must be non-NULL. 2115 * "plContext" 2116 * Platform-specific context pointer. 2117 * THREAD SAFETY: 2118 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2119 * RETURNS: 2120 * Returns NULL if the function succeeds. 2121 * Returns a CRL Error if the function fails in a non-fatal way. 2122 * Returns a Fatal Error if the function fails in an unrecoverable way. 2123 */ 2124 PKIX_Error * 2125 PKIX_PL_CRL_GetCRLNumber( 2126 PKIX_PL_CRL *crl, 2127 PKIX_PL_BigInt **pCrlNumber, 2128 void *plContext); 2129 2130 /* 2131 * FUNCTION: PKIX_PL_CRL_VerifyUpdateTime 2132 * DESCRIPTION: 2133 * 2134 * Checks whether the CRL pointed to by "crl" would be valid at the time 2135 * represented by the Date pointed to by "date" and stores the Boolean result 2136 * at "pResult". This check is done only when NIST policy is enforced. 2137 * 2138 * Time ::= CHOICE { 2139 * utcTime UTCTime, 2140 * generalTime GeneralizedTime } 2141 * 2142 * PARAMETERS: 2143 * "crl" 2144 * Address of CRL whose validity is to be checked. Must be non-NULL. 2145 * "date" 2146 * Address of Date at which the CRL is being checked for validity. 2147 * Must be non-NULL. 2148 * "pResult" 2149 * Address of Boolean result. Must be non-NULL. 2150 * "plContext" 2151 * Platform-specific context pointer. 2152 * THREAD SAFETY: 2153 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2154 * RETURNS: 2155 * Returns NULL if the function succeeds. 2156 * Returns a CRL Error if the function fails in a non-fatal way. 2157 * Returns a Fatal Error if the function fails in an unrecoverable way. 2158 */ 2159 PKIX_Error * 2160 PKIX_PL_CRL_VerifyUpdateTime( 2161 PKIX_PL_CRL *crl, 2162 PKIX_PL_Date *date, 2163 PKIX_Boolean *pResult, 2164 void *plContext); 2165 2166 /* 2167 * FUNCTION: PKIX_PL_CRL_VerifySignature 2168 * DESCRIPTION: 2169 * 2170 * Verifies the signature on the CRL pointed to by "crl" using the PublicKey 2171 * pointed to by "pubKey". If the signature doesn't verify, a PKIX_Error 2172 * pointer is returned. 2173 * 2174 * PARAMETERS: 2175 * "crl" 2176 * Address of CRL whose signature is to be verified. Must be non-NULL. 2177 * "pubKey" 2178 * Address of a Public Key used to verify the signature. Must be non-NULL. 2179 * "plContext" 2180 * Platform-specific context pointer. 2181 * THREAD SAFETY: 2182 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2183 * RETURNS: 2184 * Returns NULL if the function succeeds. 2185 * Returns a CRL Error if the function fails in a non-fatal way. 2186 * Returns a Fatal Error if the function fails in an unrecoverable way. 2187 */ 2188 PKIX_Error * 2189 PKIX_PL_CRL_VerifySignature( 2190 PKIX_PL_CRL *crl, 2191 PKIX_PL_PublicKey *pubKey, 2192 void *plContext); 2193 2194 /* 2195 * FUNCTION: PKIX_PL_CRL_ReleaseDerCrl 2196 * DESCRIPTION: 2197 * 2198 * Relinguish the ownership for the crl der. The operation will succeed if 2199 * a crl owns the der. If the crl was created from existing crl and does not 2200 * own the der, then the function will return null. 2201 * 2202 * PARAMETERS: 2203 * "crl" 2204 * Address of CRL whose signature is to be verified. Must be non-NULL. 2205 * "derCrl" 2206 * Pointer to a SECItem that has der crl. 2207 * "plContext" 2208 * Platform-specific context pointer. 2209 * THREAD SAFETY: 2210 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2211 * RETURNS: 2212 * Returns NULL if the function succeeds. 2213 * Returns a CRL Error if the function fails in a non-fatal way. 2214 * Returns a Fatal Error if the function fails in an unrecoverable way. 2215 */ 2216 PKIX_Error * 2217 PKIX_PL_CRL_ReleaseDerCrl(PKIX_PL_CRL *crl, 2218 SECItem **derCrl, 2219 void *plContext); 2220 /* 2221 * FUNCTION: PKIX_PL_CRL_AdoptDerCrl 2222 * DESCRIPTION: 2223 * 2224 * Adopt memory of the der. The secItem that contains der will be 2225 * freed with destruction of parent pkix crl structure. 2226 * 2227 * * PARAMETERS: 2228 * "crl" 2229 * Address of CRL whose signature is to be verified. Must be non-NULL. 2230 * "derCrl" 2231 * Pointer to a SECItem that has der crl. 2232 * "plContext" 2233 * Platform-specific context pointer. 2234 * THREAD SAFETY: 2235 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2236 * RETURNS: 2237 * Returns NULL if the function succeeds. 2238 * Returns a CRL Error if the function fails in a non-fatal way. 2239 * Returns a Fatal Error if the function fails in an unrecoverable way. 2240 */ 2241 PKIX_Error * 2242 PKIX_PL_CRL_AdoptDerCrl(PKIX_PL_CRL *crl, 2243 SECItem *derCrl, 2244 void *plContext); 2245 2246 /* 2247 * FUNCTION: PKIX_PL_CRLEntry_GetCRLEntryReasonCode 2248 * DESCRIPTION: 2249 * 2250 * Retrieves the value of the reason code extension of the CRLEntry pointed 2251 * to by "crlEntry" and stores it at "pReason". If the "crlEntry" has no 2252 * reason code extension, this function stores -1 at "pReason". 2253 * 2254 * CRLReason ::= ENUMERATED { 2255 * unspecified (0), 2256 * keyCompromise (1), 2257 * cACompromise (2), 2258 * affiliationChanged (3), 2259 * superseded (4), 2260 * cessationOfOperation (5), 2261 * certificateHold (6), 2262 * removeFromCRL (8), 2263 * privilegeWithdrawn (9), 2264 * aACompromise (10) } 2265 * 2266 * PARAMETERS: 2267 * "crlEntry" 2268 * Address of CRLEntry whose reason code bit values are to be returned 2269 * at "pReason". Must be non-NULL. 2270 * "pReason" 2271 * Address of PKIX_Int32 where reason code is stored. Must be non-NULL. 2272 * "plContext" 2273 * Platform-specific context pointer. 2274 * THREAD SAFETY: 2275 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2276 * RETURNS: 2277 * Returns NULL if the function succeeds. 2278 * Returns a CRL Error if the function fails in a non-fatal way. 2279 * Returns a Fatal Error if the function fails in an unrecoverable way. 2280 */ 2281 PKIX_Error * 2282 PKIX_PL_CRLEntry_GetCRLEntryReasonCode( 2283 PKIX_PL_CRLEntry *crlEntry, 2284 PKIX_Int32 *pReason, 2285 void *plContext); 2286 2287 /* 2288 * FUNCTION: PKIX_PL_CRLEntry_GetCriticalExtensionOIDs 2289 * DESCRIPTION: 2290 * 2291 * Retrieves a pointer to the List of OIDs (each OID corresponding to a 2292 * critical extension of the CRLEntry pointed to by "crlEntry") and stores it 2293 * at "pExtensions". If "crlEntry" does not have any critical extensions, this 2294 * function stores an empty List at "pExtensions". 2295 * 2296 * Note that the List returned by this function is immutable. 2297 * 2298 * PARAMETERS: 2299 * "crlEntry" 2300 * Address of CRLEntry whose critical extension OIDs are to be stored. 2301 * Must be non-NULL. 2302 * "pExtensions" 2303 * Address where object pointer will be stored. Must be non-NULL. 2304 * "plContext" 2305 * Platform-specific context pointer. 2306 * THREAD SAFETY: 2307 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2308 * RETURNS: 2309 * Returns NULL if the function succeeds. 2310 * Returns a CRL Error if the function fails in a non-fatal way. 2311 * Returns a Fatal Error if the function fails in an unrecoverable way. 2312 */ 2313 PKIX_Error * 2314 PKIX_PL_CRLEntry_GetCriticalExtensionOIDs( 2315 PKIX_PL_CRLEntry *crlEntry, 2316 PKIX_List **pExtensions, /* list of PKIX_PL_OID */ 2317 void *plContext); 2318 2319 #ifdef BUILD_LIBPKIX_TESTS 2320 /* 2321 * FUNCTION: PKIX_PL_X500Name_Create 2322 * DESCRIPTION: 2323 * 2324 * Creates a new X500Name using the UTF8 string representation pointed to by 2325 * "stringRep" and stores it at "pName". Once created, an X500Name is 2326 * immutable. 2327 * 2328 * Name ::= CHOICE { 2329 * RDNSequence } 2330 * 2331 * RDNSequence ::= SEQUENCE OF RelativeDistinguishedName 2332 * 2333 * RelativeDistinguishedName ::= 2334 * SET OF AttributeTypeAndValue 2335 * 2336 * AttributeTypeAndValue ::= SEQUENCE { 2337 * type AttributeType, 2338 * value AttributeValue } 2339 * 2340 * AttributeType ::= OBJECT IDENTIFIER 2341 * 2342 * AttributeValue ::= ANY DEFINED BY AttributeType 2343 * 2344 * DirectoryString ::= CHOICE { 2345 * teletexString TeletexString (SIZE (1..MAX)), 2346 * printableString PrintableString (SIZE (1..MAX)), 2347 * universalString UniversalString (SIZE (1..MAX)), 2348 * utf8String UTF8String (SIZE (1..MAX)), 2349 * bmpString BMPString (SIZE (1..MAX)) } 2350 * 2351 * PARAMETERS: 2352 * "stringRep" 2353 * Address of UTF8 String representation of X500Name. Must be non-NULL. 2354 * "pName" 2355 * Address where object pointer will be stored. Must be non-NULL. 2356 * "plContext" 2357 * Platform-specific context pointer. 2358 * THREAD SAFETY: 2359 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2360 * RETURNS: 2361 * Returns NULL if the function succeeds. 2362 * Returns an X500Name Error if the function fails in a non-fatal way. 2363 * Returns a Fatal Error if the function fails in an unrecoverable way. 2364 */ 2365 PKIX_Error * 2366 PKIX_PL_X500Name_Create ( 2367 PKIX_PL_String *stringRep, 2368 PKIX_PL_X500Name **pName, 2369 void *plContext); 2370 2371 #endif /* BUILD_LIBPKIX_TESTS */ 2372 2373 /* 2374 * FUNCTION: PKIX_PL_X500Name_CreateFromCERTName 2375 * DESCRIPTION: 2376 * 2377 * The function creates x500Name using der encoded DN and/or pointer to 2378 * CERTName. If arument "name" is NULL, but derName is supplied when 2379 * the function generates nssDN(CERTName type) from der data. If derName 2380 * is not supplied, CERTName *name will not be used to generate DN DER 2381 * encoding. 2382 * 2383 * PARAMETERS: 2384 * "derName" 2385 * Address of DER representation of X500Name. Can be NULL 2386 * "name" 2387 * Address of CERTName representation of X500Name. Can be NULL 2388 * "pName" 2389 * Address where object pointer will be stored. Must be non-NULL. 2390 * "plContext" 2391 * Platform-specific context pointer. 2392 * THREAD SAFETY: 2393 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2394 * RETURNS: 2395 * Returns NULL if the function succeeds. 2396 * Returns an X500Name Error if the function fails in a non-fatal way. 2397 * Returns a Fatal Error if the function fails in an unrecoverable way. 2398 */ 2399 PKIX_Error * 2400 PKIX_PL_X500Name_CreateFromCERTName( 2401 SECItem *derName, 2402 CERTName *name, 2403 PKIX_PL_X500Name **pName, 2404 void *plContext); 2405 2406 2407 /* 2408 * TYPE: PKIX_PL_X500Name_Match 2409 * DESCRIPTION: 2410 * Checks whether the X500Name pointed to by "firstX500Name" MATCHES the 2411 * X500Name pointed to by "secondX500Name" and stores the boolean result at 2412 * "pResult". Two X500Names MATCH if they meet the conditions specified by 2413 * RFC 3280 (section 4.1.2.4). Namely: 2414 * 2415 * "This specification requires only a subset of the name comparison 2416 * functionality specified in the X.500 series of specifications. 2417 * Conforming implementations are REQUIRED to implement the following 2418 * name comparison rules: 2419 * 2420 * (a) attribute values encoded in different types (e.g., PrintableString 2421 * and BMPString) MAY be assumed to represent different strings; 2422 * 2423 * (b) attribute values in types other than PrintableString are case 2424 * sensitive (this permits matching of attribute values as binary objects) 2425 * 2426 * (c) attribute values in PrintableString are not case sensitive 2427 * (e.g., "Marianne Swanson" is the same as "MARIANNE SWANSON"); and 2428 * 2429 * (d) attribute values in PrintableString are compared after removing 2430 * leading and trailing white space and converting internal substrings of 2431 * one or more consecutive white space characters to a single space." 2432 * 2433 * PARAMETERS: 2434 * "firstX500Name" 2435 * Address of first X500Name to compare. Must be non-NULL. 2436 * "secondX500Name" 2437 * Address of second X500Name to compare. Must be non-NULL. 2438 * "pResult" 2439 * Address of Boolean result. Must be non-NULL. 2440 * "plContext" 2441 * Platform-specific context pointer. 2442 * THREAD SAFETY: 2443 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2444 * RETURNS: 2445 * Returns NULL if the function succeeds. 2446 * Returns an X500Name Error if the function fails in a non-fatal way. 2447 * Returns a Fatal Error if the function fails in an unrecoverable way. 2448 */ 2449 PKIX_Error * 2450 PKIX_PL_X500Name_Match( 2451 PKIX_PL_X500Name *firstX500Name, 2452 PKIX_PL_X500Name *secondX500Name, 2453 PKIX_Boolean *pResult, 2454 void *plContext); 2455 2456 /* 2457 * FUNCTION: PKIX_PL_Date_Create_UTCTime 2458 * DESCRIPTION: 2459 * Creates a new Date of type UTCTime using the string representation pointed 2460 * to by "stringRep" and stores it at "pDate". The UTCTime restriction means 2461 * that the year can only be specified by the least significant two digits 2462 * (YY). As such, Only the years 1950-2049 can be represented. If "stringRep" 2463 * is NULL, this function creates a new Date representing the current time 2464 * and stores it at "pDate". Once created, a Date is immutable. 2465 * 2466 * If YY is greater than or equal to 50, the year is interpreted as 19YY. 2467 * If YY is less than 50, the year is interpreted as 20YY. 2468 * 2469 * The string representation of the date must be in the following form: 2470 * "YYMMDDhhmmssZ" where: 2471 * 2472 * YY is the least significant two digits of the year 2473 * MM is the month (01 to 12) 2474 * DD is the day (01 to 31) 2475 * hh is the hour (00 to 23) 2476 * mm are the minutes (00 to 59) 2477 * ss are the seconds (00 to 59) 2478 * Z indicates that local time is GMT 2479 * 2480 * PARAMETERS: 2481 * "stringRep" 2482 * Address of String representation of Date. 2483 * If NULL, current time is used. 2484 * "pDate" 2485 * Address where object pointer will be stored. Must be non-NULL. 2486 * "plContext" 2487 * Platform-specific context pointer. 2488 * THREAD SAFETY: 2489 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2490 * RETURNS: 2491 * Returns NULL if the function succeeds. 2492 * Returns a Date Error if the function fails in a non-fatal way. 2493 * Returns a Fatal Error if the function fails in an unrecoverable way. 2494 */ 2495 PKIX_Error * 2496 PKIX_PL_Date_Create_UTCTime ( 2497 PKIX_PL_String *stringRep, 2498 PKIX_PL_Date **pDate, 2499 void *plContext); 2500 2501 /* 2502 * FUNCTION: PKIX_PL_Date_Create_UTCTime 2503 * DESCRIPTION: 2504 * Creates a new Date from PRTime data. 2505 * 2506 * PARAMETERS: 2507 * "time" 2508 * Represented time in PRTime type. 2509 * "pDate" 2510 * Address where object pointer will be stored. Must be non-NULL. 2511 * "plContext" 2512 * Platform-specific context pointer. 2513 * THREAD SAFETY: 2514 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2515 * RETURNS: 2516 * Returns NULL if the function succeeds. 2517 * Returns a Date Error if the function fails in a non-fatal way. 2518 * Returns a Fatal Error if the function fails in an unrecoverable way. 2519 */ 2520 PKIX_Error * 2521 PKIX_PL_Date_CreateFromPRTime( 2522 PRTime time, 2523 PKIX_PL_Date **pDate, 2524 void *plContext); 2525 2526 /* 2527 * FUNCTION: PKIX_PL_Date_Create_CurrentOffBySeconds 2528 * DESCRIPTION: 2529 * Creates a new Date of type UTCTime for current time with seconds off by 2530 * "secondsOffset" and returns it at "pDate". 2531 * 2532 * PARAMETERS: 2533 * "secondsOffset" 2534 * A PKIX_Int32 indicates the time offset from current. If "secondsOffset" 2535 * is negative, the time is in past. 2536 * "pDate" 2537 * Address where object pointer will be stored. Must be non-NULL. 2538 * "plContext" 2539 * Platform-specific context pointer. 2540 * THREAD SAFETY: 2541 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2542 * RETURNS: 2543 * Returns NULL if the function succeeds. 2544 * Returns a Date Error if the function fails in a non-fatal way. 2545 * Returns a Fatal Error if the function fails in an unrecoverable way. 2546 */ 2547 PKIX_Error * 2548 PKIX_PL_Date_Create_CurrentOffBySeconds( 2549 PKIX_Int32 secondsOffset, 2550 PKIX_PL_Date **pDate, 2551 void *plContext); 2552 2553 #ifdef BUILD_LIBPKIX_TESTS 2554 /* 2555 * FUNCTION: PKIX_PL_GeneralName_Create 2556 * DESCRIPTION: 2557 * 2558 * Creates a new GeneralName of type "nameType" using the string 2559 * representation pointed to by "stringRep" and stores it at "pGName". 2560 * All of the GeneralName type format values specified in pkixt.h are 2561 * supported, with the exception of PKIX_OTHER_NAME, PKIX_EDIPARTY_NAME, 2562 * PKIX_IP_NAME, and PKIX_X400_ADDRESS. A PKIX_ESCASCII string representation 2563 * should be used for all supported nameTypes, with the exception of 2564 * registeredID and directoryName. For registeredID, the string representation 2565 * should be the same as that used by PKIX_PL_OID_Create. For directoryName, 2566 * the string representation should be the same as that used by 2567 * PKIX_PL_X500Name_Create. If an unsupported name type is used, an Error is 2568 * returned. Once created, a GeneralName is immutable. 2569 * 2570 * GeneralName ::= CHOICE { 2571 * otherName [0] OtherName, 2572 * rfc822Name [1] IA5String, 2573 * dNSName [2] IA5String, 2574 * x400Address [3] ORAddress, 2575 * directoryName [4] Name, 2576 * ediPartyName [5] EDIPartyName, 2577 * uniformResourceIdentifier [6] IA5String, 2578 * iPAddress [7] OCTET STRING, 2579 * registeredID [8] OBJECT IDENTIFIER } 2580 * 2581 * 2582 * NOTE: This function is allowed to be called only by pkix tests programs. 2583 * 2584 * PARAMETERS: 2585 * "nameType" 2586 * Type of GeneralName to be created. This must be one of the GeneralName 2587 * type format values specified in pkixt.h 2588 * "stringRep" 2589 * Address of String representation of GeneralName. Must be non-NULL. 2590 * "pGName" 2591 * Address where object pointer will be stored. Must be non-NULL. 2592 * "plContext" 2593 * Platform-specific context pointer. 2594 * THREAD SAFETY: 2595 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2596 * RETURNS: 2597 * Returns NULL if the function succeeds. 2598 * Returns a GeneralName Error if the function fails in a non-fatal way. 2599 * Returns a Fatal Error if the function fails in an unrecoverable way. 2600 */ 2601 PKIX_Error * 2602 PKIX_PL_GeneralName_Create ( 2603 PKIX_UInt32 nameType, 2604 PKIX_PL_String *stringRep, 2605 PKIX_PL_GeneralName **pGName, 2606 void *plContext); 2607 #endif /* BUILD_LIBPKIX_TESTS */ 2608 2609 /* 2610 * FUNCTION: PKIX_PL_CertNameConstraints_CheckNamesInNameSpace 2611 * DESCRIPTION: 2612 * 2613 * This function checks whether names in "nameList" comply with 2614 * "nameConstraints". It stores PKIX_TRUE at "pCheckPass" if the names meet the 2615 * requirement of the NameConstraints, PKIX_FALSE otherwise. 2616 * 2617 * PARAMETERS 2618 * "nameList" 2619 * List of GeneralNames that are checked for compliance. May be empty 2620 * or NULL. 2621 * "nameConstraints" 2622 * Address of CertNameConstraints that provides lists of permitted 2623 * and excluded names. Must be non-NULL. 2624 * "pCheckPass" 2625 * Address where PKIX_TRUE is returned if the all names in "nameList" are 2626 * valid. Must be non-NULL. 2627 * "plContext" - Platform-specific context pointer. 2628 * THREAD SAFETY: 2629 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2630 * RETURNS: 2631 * Returns NULL if the function succeeds. 2632 * Returns a NameConstraints Error if the function fails in a 2633 * non-fatal way. 2634 * Returns a Fatal Error if the function fails in an unrecoverable way. 2635 */ 2636 PKIX_Error * 2637 PKIX_PL_CertNameConstraints_CheckNamesInNameSpace( 2638 PKIX_List *nameList, /* List of PKIX_PL_GeneralName */ 2639 PKIX_PL_CertNameConstraints *nameConstraints, 2640 PKIX_Boolean *pCheckPass, 2641 void *plContext); 2642 2643 /* 2644 * FUNCTION: PKIX_PL_AIAMgr_Create 2645 * DESCRIPTION: 2646 * 2647 * This function creates an AIAMgr to handle retrieval of Certs and CRLs 2648 * from servers given by AIA Certificate extensions. It manages connections 2649 * and caches. The manager created is stored at "pAIAMgr". 2650 * 2651 * PARAMETERS: 2652 * "pAIAMgr" 2653 * The address at which the result is stored. Must be non-NULL. 2654 * THREAD SAFETY: 2655 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2656 * RETURNS: 2657 * Returns NULL if the function succeeds. 2658 * Returns an AIAMgr Error if the function fails in a non-fatal way 2659 * Returns a Fatal Error if the function fails in an unrecoverable way. 2660 */ 2661 PKIX_Error * 2662 PKIX_PL_AIAMgr_Create( 2663 PKIX_PL_AIAMgr **pAIAMgr, 2664 void *plContext); 2665 2666 /* 2667 * FUNCTION: PKIX_PL_AIAMgr_GetAIACerts 2668 * DESCRIPTION: 2669 * 2670 * This function uses the AIAMgr pointed to by "aiaMgr" to retrieve the Certs 2671 * specified by an AIA certificate extension, if any, in the Cert pointed to by 2672 * "prevCert", storing the results at "pCerts". If the certificate has no such 2673 * extension, this function stores NULL at "pCerts". 2674 * 2675 * If the request is suspended for non-blocking I/O, a platform-dependent 2676 * context is stored at "pNBIOContext" and NULL is stored at "pCerts". This 2677 * return is referred to as the WOULDBLOCK state. Note that the caller must 2678 * check for a non-NULL value at "pNBIOContext", to distinguish this state from 2679 * the "no such extension" return described in the first paragraph. (The 2680 * alternative would be to return an empty List, but it seemed wrong to incur 2681 * the overhead of creating and destroying an empty List for the most common 2682 * situation.) 2683 * 2684 * After a WOULDBLOCK return, the user may continue the operation by calling 2685 * pkix_AIAMgr_GetAIACerts (possibly more than once, if the function again 2686 * returns in the WOULDBLOCK state) with the previously-returned non-NULL 2687 * value of "pNBIOContext". When results are complete, NULL is stored at 2688 * "pNBIOContext", and the results (which may be NULL) are stored at "pCerts". 2689 * 2690 * PARAMETERS: 2691 * "aiaMgr" 2692 * The AIAMgr which controls the retrieval of certificates. Must be 2693 * non-NULL. 2694 * "prevCert" 2695 * Address of PKIX_PL_Cert which may provide an AIA or SIA extension. Must 2696 * be non-NULL. 2697 * "pNBIOContext" 2698 * Address at which platform-dependent information is returned if request 2699 * is suspended for non-blocking I/O. Must be non-NULL. 2700 * "pCerts" 2701 * Address at which the returned List is stored. Must be non-NULL. 2702 * "plContext" 2703 * Platform-specific context pointer. 2704 * THREAD SAFETY: 2705 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 2706 * RETURNS: 2707 * Returns NULL if the function succeeds. 2708 * Returns an AIAMgr Error if the function fails in a non-fatal way 2709 * Returns a Fatal Error if the function fails in an unrecoverable way. 2710 */ 2711 PKIX_Error * 2712 PKIX_PL_AIAMgr_GetAIACerts( 2713 PKIX_PL_AIAMgr *aiaMgr, 2714 PKIX_PL_Cert *prevCert, 2715 void **pNBIOContext, 2716 PKIX_List **pCerts, 2717 void *plContext); 2718 2719 typedef PKIX_Error * 2720 (*PKIX_PL_VerifyCallback)( 2721 PKIX_PL_Object *signedObject, 2722 PKIX_PL_Cert *signerCert, /* can be unknown */ 2723 PKIX_PL_Date *producedAt, 2724 PKIX_ProcessingParams *procParams, 2725 void **pNBIOContext, 2726 void **pState, 2727 PKIX_BuildResult **pBuildResult, 2728 PKIX_VerifyNode **pVerifyTree, 2729 void *plContext); 2730 2731 #ifdef __cplusplus 2732 } 2733 #endif 2734 2735 #endif /* _PKIX_PL_PKI_H */ 2736