PageRenderTime 168ms CodeModel.GetById 74ms app.highlight 45ms RepoModel.GetById 35ms app.codeStats 1ms

/gecko_api/include/crmf.h

http://firefox-mac-pdf.googlecode.com/
C++ Header | 1782 lines | 189 code | 91 blank | 1502 comment | 0 complexity | b45cf1fafb5a2c8ffe54e5513c925a8d MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1/* -*- Mode: C; tab-width: 8 -*-*/
   2/* ***** BEGIN LICENSE BLOCK *****
   3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4 *
   5 * The contents of this file are subject to the Mozilla Public License Version
   6 * 1.1 (the "License"); you may not use this file except in compliance with
   7 * the License. You may obtain a copy of the License at
   8 * http://www.mozilla.org/MPL/
   9 *
  10 * Software distributed under the License is distributed on an "AS IS" basis,
  11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12 * for the specific language governing rights and limitations under the
  13 * License.
  14 *
  15 * The Original Code is the Netscape security libraries.
  16 *
  17 * The Initial Developer of the Original Code is
  18 * Netscape Communications Corporation.
  19 * Portions created by the Initial Developer are Copyright (C) 1994-2000
  20 * the Initial Developer. All Rights Reserved.
  21 *
  22 * Contributor(s):
  23 *
  24 * Alternatively, the contents of this file may be used under the terms of
  25 * either the GNU General Public License Version 2 or later (the "GPL"), or
  26 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27 * in which case the provisions of the GPL or the LGPL are applicable instead
  28 * of those above. If you wish to allow use of your version of this file only
  29 * under the terms of either the GPL or the LGPL, and not to allow others to
  30 * use your version of this file under the terms of the MPL, indicate your
  31 * decision by deleting the provisions above and replace them with the notice
  32 * and other provisions required by the GPL or the LGPL. If you do not delete
  33 * the provisions above, a recipient may use your version of this file under
  34 * the terms of any one of the MPL, the GPL or the LGPL.
  35 *
  36 * ***** END LICENSE BLOCK ***** */
  37
  38
  39#ifndef _CRMF_H_
  40#define _CRMF_H_
  41
  42#include "seccomon.h"
  43#include "cert.h"
  44#include "crmft.h"
  45#include "secoid.h"
  46#include "secpkcs7.h"
  47
  48SEC_BEGIN_PROTOS
  49
  50/*
  51 * FUNCTION: CRMF_EncodeCertReqMsg
  52 * INPUTS:
  53 *    inCertReqMsg
  54 *        The Certificate Request Message to be encoded.
  55 *    fn
  56 *        A Callback function that the ASN1 encoder calls whenever
  57 *        the encoder wants to write out some DER encoded bytes.
  58 *    arg
  59 *        An opaque pointer that gets passed to the function fn
  60 * OUTPUT:
  61 *    The function fn will be called multiple times.  Look at the
  62 *    comments in crmft.h where the CRMFEncoderOutputCallback type is 
  63 *    defined for information on proper behavior of the function fn.
  64 * RETURN:
  65 *    SECSuccess if encoding was successful.  Any other return value
  66 *    indicates an error occurred during encoding.
  67 */
  68extern SECStatus 
  69        CRMF_EncodeCertReqMsg (CRMFCertReqMsg            *inCertReqMsg, 
  70			       CRMFEncoderOutputCallback  fn,
  71			       void                      *arg);
  72
  73/*
  74 * FUNCTION: CRMF_EncoderCertRequest
  75 * INPUTS:
  76 *    inCertReq
  77 *        The Certificate Request to be encoded.
  78 *    fn
  79 *        A Callback function that the ASN1 encoder calls whenever
  80 *        the encoder wants to write out some DER encoded bytes.
  81 *    arg
  82 *        An opaque pointer that gets passed to the function fn.
  83 * OUTPUT:
  84 *    The function fn will be called, probably multiple times whenever 
  85 *    the ASN1 encoder wants to write out DER-encoded bytes.  Look at the 
  86 *    comments in crmft.h where the CRMFEncoderOuputCallback type is
  87 *    defined for information on proper behavior of the funciton fn.
  88 * RETURN:
  89 *    SECSuccess if encoding was successful.  Any other return value 
  90 *    indicates an error occured during encoding.
  91 */
  92extern SECStatus CRMF_EncodeCertRequest (CRMFCertRequest           *inCertReq,
  93					 CRMFEncoderOutputCallback  fn,
  94					 void                      *arg);
  95/*
  96 * FUNCTION: CRMF_EncodeCertReqMessages
  97 * INPUTS:
  98 *    inCertReqMsgs
  99 *        An array of pointers to the Certificate Request Messages
 100 *        to encode.  The user must place a NULL pointer in the index
 101 *        after the last message to be encoded.  When the library runs
 102 *        into the NULL pointer, the library assumes there are no more
 103 *        messages to encode.
 104 *    fn
 105 *        A Callback function that the ASN1 encoder calls whenever
 106 *        the encoder wants to write out some DER encoded byts.
 107 *    arg
 108 *        An opaque pointer that gets passed to the function fn.
 109 *
 110 * NOTES:
 111 *    The parameter inCertReqMsgs needs to be an array with a NULL pointer
 112 *    to signal the end of messages.  An array in the form of 
 113 *    {m1, m2, m3, NULL, m4, ...} will only encode the messages m1, m2, and
 114 *    m3.  All messages from m4 on will not be looked at by the library.
 115 *
 116 * OUTPUT:
 117 *    The function fn will be called, probably multiple times.  Look at the 
 118 *    comments in crmft.h where the CRMFEncoderOuputCallback type is
 119 *    defined for information on proper behavior of the funciton fn.
 120 *
 121 * RETURN:
 122 * SECSuccess if encoding the Certificate Request Messages was successful. 
 123 * Any other return value indicates an error occurred while encoding the
 124 * certificate request messages.
 125 */
 126extern SECStatus 
 127       CRMF_EncodeCertReqMessages(CRMFCertReqMsg           **inCertReqMsgs,
 128				  CRMFEncoderOutputCallback  fn,
 129				  void                      *arg);
 130
 131
 132/*
 133 * FUNCTION: CRMF_CreateCertReqMsg
 134 * INPUTS:
 135 *    NONE
 136 * OUTPUT:
 137 *    An empty CRMF Certificate Request Message.
 138 *    Before encoding this message, the user must set
 139 *    the ProofOfPossession field and the certificate 
 140 *    request which are necessary for the full message.
 141 *    After the user no longer needs this CertReqMsg,
 142 *    the user must call CRMF_DestroyCertReqMsg to free
 143 *    all memory associated with the Certificate Request
 144 *    Message.
 145 * RETURN:
 146 *    A pointer to a Certificate Request Message.  The user 
 147 *    must pass the return value of this function to 
 148 *    CRMF_DestroyCertReqMsg after the Certificate Request
 149 *    Message is no longer necessary.
 150 */
 151extern CRMFCertReqMsg* CRMF_CreateCertReqMsg(void);
 152
 153/*
 154 * FUNCTION: CRMF_DestroyCertReqMsg
 155 * INPUTS:
 156 *    inCertReqMsg
 157 *        The Certificate Request Message to destroy.
 158 *  NOTES:
 159 *    This function frees all the memory used for the Certificate
 160 *    Request Message and all the memory used in making copies of
 161 *    fields of elelments of the message, eg. the Proof Of Possession
 162 *    filed and the Cetificate Request.  
 163 * RETURN:
 164 *    SECSuccess if destruction was successful.  Any other return value
 165 *    indicates an error while trying to free the memory associated
 166 *    with inCertReqMsg.
 167 *    
 168 */
 169extern SECStatus CRMF_DestroyCertReqMsg(CRMFCertReqMsg *inCertReqMsg);
 170
 171/*
 172 * FUNCTION: CRMF_CertReqMsgSetCertRequest
 173 * INPUTS:
 174 *    inCertReqMsg
 175 *        The Certificate Request Message that the function will set
 176 *        the certificate request for.
 177 *    inCertReq
 178 *        The Certificate Request that will be added to the Certificate
 179 *        Request Message.
 180 * NOTES:
 181 *    This function will make a copy of the Certificate Request passed in
 182 *    and store it as part of the Certificate Request Message.  Therefore,
 183 *    the user must not call this function until the Certificate Request
 184 *    has been fully built and is ready to be encoded.
 185 * RETURN:
 186 *    SECSuccess 
 187 *        If copying the Certificate as a member of the Certificate
 188 *        request message was successful.
 189 *    Any other return value indicates a failure to copy the Certificate
 190 *    Request and make it a part of the Certificate Request Message.
 191 */
 192extern SECStatus CRMF_CertReqMsgSetCertRequest(CRMFCertReqMsg  *inCertReqMsg, 
 193					       CRMFCertRequest *inCertReq);
 194
 195/*
 196 * FUNCTION: CRMF_CreateCertRequest
 197 * INPUTS:
 198 *    inRequestID
 199 *        The ID that will be associated with this certificate request.
 200 * OUTPUTS:
 201 *    A certificate request which only has the requestID set.
 202 * NOTES:
 203 *    The user must call the function CRMF_DestroyCertRequest when
 204 *    the returned value is no longer needed.  This is usually the
 205 *    case after fully constructing the Certificate Request and then
 206 *    calling the function CRMF_CertReqMsgSetCertRequest.
 207 * RETURN:
 208 *    A pointer to the new Certificate Request.  A NULL return value
 209 *    indicates an error in creating the Certificate Request.
 210 */
 211extern CRMFCertRequest *CRMF_CreateCertRequest (PRUint32 inRequestID);
 212
 213/*
 214 * FUNCTION: CRMF_DestroyCertRequest
 215 * INPUTS:
 216 *    inCertReq
 217 *        The Certificate Request that will be destroyed.
 218 * RETURN:
 219 *    SECSuccess
 220 *        If freeing the memory associated with the certificate request 
 221 *        was successful.
 222 *    Any other return value indicates an error while trying to free the 
 223 *    memory.
 224 */
 225extern SECStatus CRMF_DestroyCertRequest (CRMFCertRequest *inCertReq);
 226
 227/*
 228 * FUNCTION: CRMF_CreateCertExtension
 229 * INPUTS:
 230 *    id
 231 *        The SECOidTag to associate with this CertExtension.  This must
 232 *        correspond to a valid Certificate Extension, if not the function
 233 *        will fail.
 234 *    isCritical
 235 *        A boolean value stating if the extension value is crtical.  PR_TRUE
 236 *        means the value is crtical.  PR_FALSE indicates the value is not 
 237 *        critical.
 238 *    data
 239 *        This is the data associated with the extension.  The user of the
 240 *        library is responsible for making sure the value passed in is a
 241 *        valid interpretation of the certificate extension.
 242 * NOTES:
 243 * Use this function to create CRMFCertExtension Structures which will 
 244 * then be passed to CRMF_AddFieldToCertTemplate as part of the 
 245 * CRMFCertCreationInfo.extensions  The user must call 
 246 * CRMF_DestroyCertExtension after the extension has been added to a certifcate
 247 * and the extension is no longer needed.
 248 *
 249 * RETURN:
 250 * A pointer to a newly created CertExtension.  A return value of NULL
 251 * indicates the id passed in was an invalid certificate extension.
 252 */
 253extern CRMFCertExtension *CRMF_CreateCertExtension(SECOidTag      id, 
 254						   PRBool         isCritical,
 255						   SECItem       *data);
 256
 257/*
 258 * FUNCTION: CMRF_DestroyCertExtension
 259 * INPUTS:
 260 *    inExtension
 261 *        The Cert Extension to destroy
 262 * NOTES:
 263 * Destroy a structure allocated by CRMF_CreateCertExtension.
 264 *
 265 * RETURN:
 266 * SECSuccess if freeing the memory associated with the certificate extension
 267 * was successful.  Any other error indicates an error while freeing the 
 268 * memory.
 269 */
 270extern SECStatus CRMF_DestroyCertExtension(CRMFCertExtension *inExtension);
 271
 272/* 
 273 * FUNCTION: CRMF_CertRequestSetTemplateField
 274 * INPUTS:
 275 *    inCertReq
 276 *        The Certificate Request to operate on.
 277 *    inTemplateField
 278 *        An enumeration that indicates which field of the Certificate
 279 *        template to add.
 280 *    data
 281 *        A generic pointer that will be type cast according to the
 282 *        table under NOTES and used as the key for adding to the
 283 *        certificate template;
 284 * NOTES:
 285 *
 286 * Below is a table that tells what type to pass in as data
 287 * depending on the template field one wants to set.
 288 *
 289 * Look in crmft.h for the definition of CRMFCertTemplateField.
 290 * 
 291 * In all cases, the library makes copies of the data passed in.
 292 *
 293 *   CRMFCertTemplateField    Type of data    What data means
 294 *   ---------------------    ------------    ---------------
 295 *   crmfVersion              long *          The version of
 296 *                                            the certificate
 297 *                                            to be created.
 298 *
 299 *   crmfSerialNumber         long *          The serial number
 300 *                                            for the cert to be
 301 *                                            created.
 302 *   
 303 *   crmfSigningAlg           SECAlgorithm *  The ASN.1 object ID for
 304 *                                            the algorithm used in encoding
 305 *                                            the certificate.
 306 *
 307 *   crmfIssuer               CERTName *      Certificate Library 
 308 *                                            representation of the ASN1 type
 309 *                                            Name from X.509
 310 *
 311 *   crmfValidity     CRMFValidityCreationInfo *  At least one of the two
 312 *                                                fields in the structure must
 313 *                                                be present.  A NULL pointer 
 314 *                                                in the structure indicates
 315 *                                                that member should not be 
 316 *                                                added.
 317 *
 318 *   crmfSubject              CERTName *      Certificate Library 
 319 *                                            representation of the ASN1 type
 320 *                                            Name from X.509
 321 *
 322 *   crmfPublicKey    CERTSubjectPublicKeyInfo *  The public key info for the
 323 *                                                certificate being requested.
 324 *
 325 *   crmfIssuerUID            SECItem *           A bit string representation
 326 *                                                of the issuer UID. NOTE: The
 327 *                                                length is the number of bits
 328 *                                                and not the number of bytes.
 329 *
 330 *   crmfSubjectUID           SECItem*            A bit string representation
 331 *                                                of the subject UID. NOTE: The
 332 *                                                length is the number of bits
 333 *                                                and not the number of bytes.
 334 *
 335 *   crmfExtension   CRMFCertExtCreationInfo *     A pointer to the structure
 336 *                                                 populated with an array of 
 337 *                                                 of certificate extensions
 338 *                                                 and an integer that tells
 339 *                                                 how many elements are in the
 340 *                                                 array. Look in crmft.h for
 341 *                                                 the definition of 
 342 *                                                 CRMFCertExtCreationInfo
 343 * RETURN:
 344 *    SECSuccess if adding the desired field to the template was successful.
 345 *    Any other return value indicates failure when trying to add the field 
 346 *    to the template.
 347 *                                                
 348 */
 349extern SECStatus
 350  CRMF_CertRequestSetTemplateField(CRMFCertRequest       *inCertReq, 
 351				   CRMFCertTemplateField  inTemplateField,
 352				   void                  *data);
 353
 354/*
 355 * FUNCTION: CRMF_CertRequestIsFieldPresent
 356 * INPUTS:
 357 *    inCertReq
 358 *        The certificate request to operate on.
 359 *    inTemplateField
 360 *        The enumeration for the template field the user wants to query
 361 *        about.
 362 * NOTES:
 363 * This function checks to see if the the field associated with inTemplateField
 364 * enumeration is already present in the certificate request passed in.
 365 *
 366 * RETURN:
 367 * The function returns PR_TRUE if the field associated with inTemplateField
 368 * is already present in the certificate request.  If the field is not present
 369 * the function returns PR_FALSE.
 370 */
 371extern PRBool
 372  CRMF_CertRequestIsFieldPresent(CRMFCertRequest       *inCertReq,
 373				 CRMFCertTemplateField  inTemplateField);
 374
 375/*
 376 * FUNCTION: CRMF_CertRequestIsControlPresent
 377 * INPUTS:
 378 *    inCertReq
 379 *        The certificate request to operate on.
 380 *    inControlType
 381 *        The type of control to look for.
 382 * NOTES:
 383 * This function looks at the control present in the certificate request
 384 * and returns PR_TRUE iff a control of type inControlType already exists.
 385 * The CRMF draft does not explicitly state that two controls of the same
 386 * type can not exist within the same request.  So the library will not
 387 * cause an error if you try to add a control and one of the same type
 388 * already exists.  It is up to the application to ensure that multiple
 389 * controls of the same type do not exist, if that is the desired behavior
 390 * by the application.
 391 *
 392 * RETURN:
 393 * The function returns PR_TRUE if a control of type inControlType already
 394 * exists in the certificate request.  If a control of type inControlType
 395 * does not exist, the function will return PR_FALSE.
 396 */
 397extern PRBool
 398  CRMF_CertRequestIsControlPresent(CRMFCertRequest *inCertReq,
 399				   CRMFControlType  inControlType);
 400				   
 401
 402/*
 403 * FUNCTION: CRMF_CertRequestSetRegTokenControl
 404 * INPUTS:
 405 *    inCertReq
 406 *        The Certificate Request to operate on.
 407 *    value
 408 *        The UTF8 value which will be the Registration Token Control
 409 *        for this Certificate Request.
 410 * NOTES:
 411 *    The library does no verification that the value passed in is 
 412 *    a valid UTF8 value.  The caller must make sure of this in order
 413 *    to get an encoding that is valid.  The library will ultimately
 414 *    encode this value as it was passed in.
 415 * RETURN:
 416 *    SECSucces on successful addition of the Registration Token Control.
 417 *    Any other return value indicates an unsuccessful attempt to add the
 418 *    control.
 419 *
 420 */
 421extern SECStatus CRMF_CertRequestSetRegTokenControl(CRMFCertRequest *inCertReq,
 422						    SECItem         *value);
 423
 424/*
 425 * FUNCTION: CRMF_CertRequestSetAuthenticatorControl
 426 * INPUTS:
 427 *    inCertReq
 428 *        The Certificate Request to operate on.
 429 *    value
 430 *        The UTF8 value that will become the Authenticator Control
 431 *        for the passed in Certificate Request.
 432 * NOTES:
 433 *    The library does no verification that the value passed in is 
 434 *    a valid UTF8 value.  The caller must make sure of this in order
 435 *    to get an encoding that is valid.  The library will ultimately
 436 *    encode this value as it was passed in.
 437 * RETURN:
 438 *    SECSucces on successful addition of the Authenticator Control.
 439 *    Any other return value indicates an unsuccessful attempt to add the
 440 *    control.
 441 */
 442extern SECStatus 
 443       CRMF_CertRequestSetAuthenticatorControl (CRMFCertRequest *inCertReq,
 444						SECItem         *value);
 445
 446/*
 447 * FUNCTION: CRMF_CreateEncryptedKeyWithencryptedValue
 448 * INPUTS:
 449 *    inPrivKey
 450 *        This is the private key associated with a certificate that is
 451 *        being requested.  This structure will eventually wind up as 
 452 *        a part of the PKIArchiveOptions Control.  
 453 *    inCACert
 454 *        This is the certificate for the CA that will be receiving the 
 455 *        certificate request for the private key passed in.
 456 * OUTPUT:
 457 *    A CRMFEncryptedKey that can ultimately be used as part of the 
 458 *    PKIArchiveOptions Control.
 459 *
 460 * RETURN:
 461 *    A pointer to a CRMFEncyptedKey.  A NULL return value indicates an erro
 462 *    during the creation of the encrypted key.
 463 */
 464extern CRMFEncryptedKey* 
 465       CRMF_CreateEncryptedKeyWithEncryptedValue(SECKEYPrivateKey *inPrivKey,
 466						 CERTCertificate  *inCACert);
 467
 468/*
 469 * FUNCTION: CRMF_DestroyEncryptedKey
 470 * INPUTS:
 471 *    inEncrKey
 472 *        The CRMFEncryptedKey to be destroyed.
 473 * NOTES:
 474 *    Frees all memory associated with the CRMFEncryptedKey passed in.
 475 * RETURN:
 476 *    SECSuccess if freeing the memory was successful.  Any other return
 477 *    value indicates an error while freeig the memroy.
 478 */
 479extern SECStatus CRMF_DestroyEncryptedKey(CRMFEncryptedKey *inEncrKey);
 480						
 481/*
 482 * FUNCTION: CRMF_CreatePKIArchiveOptions
 483 * INPUTS:
 484 *    inType
 485 *        An enumeration value indicating which option for 
 486 *        PKIArchiveOptions to use.
 487 *    data
 488 *        A pointer that will be type-cast and de-referenced according
 489 *        to the table under NOTES.
 490 * NOTES:
 491 * A table listing what should be passed in as data
 492 * ------------------------------------------------
 493 *
 494 * inType                            data
 495 * ------                            ----
 496 * crmfEncryptedPrivateKey           CRMFEncryptedKey*
 497 * crmfKeyGenParameters              SECItem*(This needs to be an octet string)
 498 * crmfArchiveRemGenPrivKey          PRBool*
 499 *
 500 * RETURN:
 501 *    A pointer the a CRMFPKIArchiveOptions that can be added to a Certificate
 502 *    Request.  A NULL pointer indicates an error occurred while creating
 503 *    the CRMFPKIArchiveOptions Structure.
 504 */
 505extern CRMFPKIArchiveOptions*
 506       CRMF_CreatePKIArchiveOptions(CRMFPKIArchiveOptionsType  inType,
 507				    void                      *data);
 508/*
 509 * FUNCTION: CRMF_DestroyPKIArchiveOptions
 510 * INPUTS:
 511 *    inArchOpt
 512 *        A pointer to the CRMFPKIArchiveOptions structure to free.
 513 * NOTES:
 514 *    Will free all memory associated with 'inArchOpt'.
 515 * RETURN:
 516 *    SECSuccess if successful in freeing the memory used by 'inArchOpt'
 517 *    Any other return value indicates an error while freeing the memory.
 518 */
 519extern SECStatus 
 520       CRMF_DestroyPKIArchiveOptions(CRMFPKIArchiveOptions *inArchOpt);
 521
 522/*
 523 * FUNCTION: CRMF_CertRequestSetPKIArchiveOptions
 524 * INPUTS:
 525 *    inCertReq
 526 *        The Certificate Request to add the the options to.
 527 *    inOptions
 528 *        The Archive Options to add to the Certificate Request.
 529 * NOTES:
 530 *    Adds the PKIArchiveOption to the Certificate Request.  This is what
 531 *    enables Key Escrow to take place through CRMF.  The library makes
 532 *    its own copy of the information.
 533 * RETURN:
 534 *    SECSuccess if successful in adding the ArchiveOptions to the Certificate
 535 *    request.  Any other return value indicates an error when trying to add
 536 *    the Archive Options  to the Certificate Request.
 537 */
 538extern SECStatus 
 539       CRMF_CertRequestSetPKIArchiveOptions(CRMFCertRequest       *inCertReq,
 540					    CRMFPKIArchiveOptions *inOptions);
 541
 542/*
 543 * FUNCTION: CRMF_CertReqMsgGetPOPType
 544 * INPUTS:
 545 *    inCertReqMsg
 546 *        The Certificate Request Message to operate on.
 547 * NOTES:
 548 *    Returns an enumeration value indicating the method of Proof
 549 *    of Possession that was used for the passed in Certificate Request
 550 *    Message.
 551 * RETURN:
 552 *    An enumeration indicating what method for Proof Of Possession is
 553 *    being used in this Certificate Request Message.  Look in the file
 554 *    crmft.h for the definition of CRMFPOPChoice for the possible return
 555 *    values.
 556 */
 557extern CRMFPOPChoice CRMF_CertReqMsgGetPOPType(CRMFCertReqMsg *inCertReqMsg);
 558
 559/*
 560 * FUNCTION: CRMF_CertReqMsgSetRAVerifiedPOP
 561 * INPUT:
 562 *    InCertReqMsg
 563 *        The Certificate Request Message to operate on.
 564 * NOTES:
 565 *    This function will set the method of Proof Of Possession to 
 566 *    crmfRAVerified which means the RA has already verified the 
 567 *    requester does possess the private key.
 568 * RETURN:
 569 *    SECSuccess if adding RAVerified to the message is successful.  
 570 *    Any other message indicates an error while trying to add RAVerified
 571 *    as the Proof of Possession.
 572 */
 573extern SECStatus CRMF_CertReqMsgSetRAVerifiedPOP(CRMFCertReqMsg *inCertReqMsg);
 574
 575/*
 576 * FUNCTION: CRMF_CertReqMsgSetSignaturePOP
 577 * INPUT:
 578 *    inCertReqMsg
 579 *        The Certificate Request Message to add the SignaturePOP to.
 580 *    inPrivKey
 581 *        The Private Key which corresponds to the the Certificate Request
 582 *        Message.
 583 *    inPubKey
 584 *        The Public Key which corresponds to the Private Key passed in.
 585 *    inCertForInput
 586 *        A Certificate that in the future may be used to create 
 587 *        POPOSigningKeyInput.
 588 *    fn
 589 *        A callback for retrieving a password which may be used in the
 590 *       future to generate POPOSigningKeyInput.
 591 *    arg
 592 *        An opaque pointer that would be passed to fn whenever it is
 593 *        called.
 594 * NOTES:
 595 * Adds Proof Of Possession to the CertRequest using the signature field 
 596 * of the ProofOfPossession field.  NOTE: In order to use this option, 
 597 * the certificate template must contain the publicKey at the very minimum.
 598 * 
 599 * If you don't want the function to generate POPOSigningKeyInput, then
 600 * make sure the cert template already contains the subject and public key
 601 * values.  Currently creating POPOSigningKeyInput is not supported, so 
 602 * a Message passed to this function must have the publicKey and the subject
 603 * as part of the template
 604 *
 605 * This will take care of creating the entire POPOSigningKey structure
 606 * that will become part of the message.
 607 *
 608 * inPrivKey is the key to be used in the signing operation when creating
 609 * POPOSigningKey structure.  This should be the key corresponding to
 610 * the certificate being requested.
 611 *
 612 * inCertForInput will be used if POPOSigningKeyInput needs to be generated.
 613 * It will be used in generating the authInfo.sender field.  If the parameter
 614 * is not passed in then authInfo.publicKeyMAC will be generated instead.
 615 * If passed in, this certificate needs to be a valid certificate.
 616 *
 617 * The last 3 arguments are for future compatibility in case we ever want to
 618 * support generating POPOSigningKeyInput.  Pass in NULL for all 3 if you 
 619 * definitely don't want the funciton to even try to generate 
 620 * POPOSigningKeyInput.  If you try to use POPOSigningKeyInput, the function
 621 * will fail.
 622 *
 623 * RETURN:
 624 *    SECSuccess if adding the Signature Proof Of Possession worked.
 625 *    Any other return value indicates an error in trying to add
 626 *    the Signature Proof Of Possession.
 627 */
 628extern SECStatus 
 629       CRMF_CertReqMsgSetSignaturePOP(CRMFCertReqMsg   *inCertReqMsg,
 630				      SECKEYPrivateKey *inPrivKey,
 631				      SECKEYPublicKey  *inPubKey,
 632				      CERTCertificate  *inCertForInput,
 633				      CRMFMACPasswordCallback  fn,
 634				      void                    *arg);
 635
 636/*
 637 * FUNCTION: CRMF_CertReqMsgSetKeyEnciphermentPOP
 638 * INPUTS:
 639 *    inCertReqMsg
 640 *        The Certificate Request Message to operate on.
 641 *    inKeyChoice
 642 *        An enumeration indicating which POPOPrivKey Choice to use
 643 *        in constructing the KeyEnciphermentPOP.
 644 *    subseqMess
 645 *        This parameter must be provided iff inKeyChoice is 
 646 *        crmfSubsequentMessage.  This details how the RA is to respond
 647 *        in order to perform Proof Of Possession.  Look in crmft.h under
 648 *        the definition of CRMFSubseqMessOptions for possible values.
 649 *    encPrivKey
 650 *        This parameter only needs to be provided if inKeyChoice is
 651 *        crmfThisMessage.  The item should contain the encrypted private
 652 *        key.
 653 *        
 654 * NOTES:
 655 * Adds Proof Of Possession using the keyEncipherment field of
 656 * ProofOfPossession.
 657 *
 658 * The funciton looks at the the inKeyChoice parameter and interprets it in
 659 * in the following manner.
 660 *
 661 * If a parameter is not mentioned under interpretation, the funciton will not
 662 * look at its value when implementing that case.
 663 *
 664 * inKeyChoice          Interpretation
 665 * -----------          --------------
 666 * crmfThisMessage      This options requires that the encrypted private key
 667 *                      be included in the thisMessage field of POPOPrivKey.
 668 *                      We don't support this yet, so any clients who want
 669 *                      to use this feature have to implement a wrapping
 670 *                      function and agree with the server on how to properly
 671 *                      wrap the key.  That encrypted key must be passed in
 672 *                      as the encPrivKey parameter.
 673 *
 674 * crmfSubequentMessage Must pass in a value for subseqMess.  The value must
 675 *                      be either CRMFEncrCert or CRMFChallengeResp.  The
 676 *                      parameter encPrivKey will not be looked at in this
 677 *                      case.
 678 *
 679 * crmfDHMAC            This is not a valid option for this function.  Passing
 680 *                      in this value will result in the function returning
 681 *                      SECFailure.
 682 * RETURN:
 683 *    SECSuccess if adding KeyEnciphermentPOP was successful.  Any other return
 684 *    value indicates an error in adding KeyEnciphermentPOP.
 685 */
 686extern SECStatus 
 687      CRMF_CertReqMsgSetKeyEnciphermentPOP(CRMFCertReqMsg        *inCertReqMsg,
 688					   CRMFPOPOPrivKeyChoice  inKeyChoice,
 689					   CRMFSubseqMessOptions  subseqMess,
 690					   SECItem               *encPrivKey);
 691
 692/*
 693 * FUNCTION: CRMF_CertReqMsgSetKeyAgreementPOP
 694 * INPUTS:
 695 *    inCertReqMsg
 696 *        The Certificate Request Message to operate on.
 697 *    inKeyChoice
 698 *        An enumeration indicating which POPOPrivKey Choice to use
 699 *        in constructing the KeyAgreementPOP.
 700 *    subseqMess
 701 *        This parameter must be provided iff inKeyChoice is 
 702 *        crmfSubsequentMessage.  This details how the RA is to respond
 703 *        in order to perform Proof Of Possession.  Look in crmft.h under
 704 *        the definition of CRMFSubseqMessOptions for possible values.
 705 *    encPrivKey
 706 *        This parameter only needs to be provided if inKeyChoice is
 707 *        crmfThisMessage.  The item should contain the encrypted private
 708 *        key.
 709 * Adds Proof Of Possession using the keyAgreement field of
 710 * ProofOfPossession.
 711 *
 712 * The funciton looks at the the inKeyChoice parameter and interprets it in
 713 * in the following manner.
 714 *
 715 * If a parameter is not mentioned under interpretation, the funciton will not
 716 * look at its value when implementing that case.
 717 *
 718 * inKeyChoice          Interpretation
 719 * -----------          --------------
 720 * crmfThisMessage      This options requires that the encrypted private key
 721 *                      be included in the thisMessage field of POPOPrivKey.
 722 *                      We don't support this yet, so any clients who want
 723 *                      to use this feature have to implement a wrapping
 724 *                      function and agree with the server on how to properly
 725 *                      wrap the key.  That encrypted key must be passed in
 726 *                      as the encPrivKey parameter.
 727 *
 728 * crmfSubequentMessage Must pass in a value for subseqMess.  The value must
 729 *                      be either crmfEncrCert or crmfChallengeResp.  The
 730 *                      parameter encPrivKey will not be looked at in this
 731 *                      case.
 732 *
 733 * crmfDHMAC            This option is not supported.
 734 */
 735extern SECStatus 
 736       CRMF_CertReqMsgSetKeyAgreementPOP(CRMFCertReqMsg        *inCertReqMsg,
 737					 CRMFPOPOPrivKeyChoice  inKeyChoice,
 738					 CRMFSubseqMessOptions  subseqMess,
 739					 SECItem               *encPrivKey);
 740
 741/*
 742 * FUNCTION: CRMF_CreateCertReqMsgFromDER
 743 * INPUTS:
 744 *    buf
 745 *        A buffer to the DER-encoded Certificate Request Message.
 746 *    len
 747 *        The length in bytes of the buffer 'buf'
 748 * NOTES:
 749 * This function passes the buffer to the ASN1 decoder and creates a 
 750 * CRMFCertReqMsg structure.  Do not try adding any fields to a message
 751 * returned from this function.  Specifically adding more Controls or 
 752 * Extensions may cause your program to crash.
 753 *
 754 * RETURN:
 755 *    A pointer to the Certificate Request Message structure.  A NULL return
 756 *    value indicates the library was unable to parse the DER.
 757 */
 758extern CRMFCertReqMsg* CRMF_CreateCertReqMsgFromDER(const char *buf, long len);
 759
 760/*
 761 * FUNCTION: CRMF_CreateCertReqMessagesFromDER
 762 * INPUTS:
 763 *    buf
 764 *        A buffer to the DER-encoded Certificate Request Messages.
 765 *    len
 766 *        The length in bytes of buf
 767 * NOTES:
 768 * This function passes the buffer to the ASN1 decoder and creates a 
 769 * CRMFCertReqMessages structure.  Do not try adding any fields to a message
 770 * derived from this function.  Specifically adding more Controls or 
 771 * Extensions may cause your program to crash.
 772 * The user must call CRMF_DestroyCertReqMessages after the return value is 
 773 * no longer needed, ie when all individual messages have been extracted.
 774 *  
 775 * RETURN:
 776 *    A pointer to the Certificate Request Messages structure.  A NULL return
 777 *    value indicates the library was unable to parse the DER.
 778 */ 
 779extern CRMFCertReqMessages*
 780       CRMF_CreateCertReqMessagesFromDER(const char *buf, long len);
 781
 782/*
 783 * FUNCTION: CRMF_DestroyCertReqMessages
 784 * INPUTS
 785 *    inCertReqMsgs
 786 *        The Messages to destroy.
 787 * RETURN:
 788 *    SECSuccess if freeing the memory was done successfully.  Any other
 789 *    return value indicates an error in freeing up memory.
 790 */ 
 791extern SECStatus 
 792       CRMF_DestroyCertReqMessages(CRMFCertReqMessages *inCertReqMsgs);
 793
 794/*
 795 * FUNCTION: CRMF_CertReqMessagesGetNumMessages
 796 * INPUTS:
 797 *    inCertReqMsgs
 798 *        The Request Messages to operate on.
 799 * RETURN:
 800 *    The number of messages contained in the in the Request Messages 
 801 *    strucure.
 802 */
 803extern int 
 804       CRMF_CertReqMessagesGetNumMessages(CRMFCertReqMessages *inCertReqMsgs);
 805
 806/*
 807 * FUNCTION: CRMF_CertReqMessagesGetCertReqMsgAtIndex
 808 * INPUTS:
 809 *    inReqMsgs
 810 *        The Certificate Request Messages to operate on.
 811 *    index
 812 *        The index of the single message the user wants a copy of.
 813 * NOTES:
 814 * This function returns a copy of the request messages stored at the 
 815 * index corresponding to the parameter 'index'.  Indexing of the messages
 816 * is done in the same manner as a C array.  Meaning the valid index are 
 817 * 0...numMessages-1.  User must call CRMF_DestroyCertReqMsg when done using
 818 * the return value of this function.
 819 *
 820 * RETURN:
 821 * SECSuccess if copying the message at the requested index was successful.
 822 * Any other return value indicates an invalid index or error while copying
 823 * the single request message.
 824 */
 825extern CRMFCertReqMsg*
 826       CRMF_CertReqMessagesGetCertReqMsgAtIndex(CRMFCertReqMessages *inReqMsgs,
 827						int                  index);
 828
 829
 830/*
 831 * FUNCTION: CRMF_CertReqMsgGetID
 832 * INPUTS:
 833 *    inCertReqMsg
 834 *        The Certificate Request Message to get the ID from.
 835 *    destID
 836 *        A pointer to where the library can place the ID of the Message.
 837 * RETURN:
 838 *    SECSuccess if the function was able to retrieve the ID and place it
 839 *    at *destID.  Any other return value indicates an error meaning the value
 840 *    in *destId is un-reliable and should not be used by the caller of this 
 841 *    function.
 842 *    
 843 */
 844extern SECStatus CRMF_CertReqMsgGetID(CRMFCertReqMsg *inCertReqMsg, 
 845				      long           *destID);
 846
 847/*
 848 * FUNCTION: CRMF_DoesRequestHaveField
 849 * INPUTS:
 850 *    inCertReq
 851 *        The Certificate Request to operate on.
 852 *    inField
 853 *        An enumeration indicating which filed of the certificate template
 854 *        to look for.
 855 * NOTES:
 856 * All the fields in a certificate template are optional.  This function
 857 * checks to see if the requested field is present.  Look in crmft.h at the
 858 * definition of CRMFCertTemplateField for possible values for possible 
 859 * querying.
 860 *
 861 * RETURN:
 862 * PR_TRUE iff the field corresponding to 'inField' has been specified as part
 863 *         of 'inCertReq'
 864 * PR_FALSE iff the field corresponding to 'inField' has not been speicified
 865 *          as part of 'inCertReq'
 866 *        
 867 */
 868extern PRBool CRMF_DoesRequestHaveField(CRMFCertRequest       *inCertReq,
 869					CRMFCertTemplateField  inField);
 870
 871/*
 872 * FUNCTION: CRMF_CertReqMsgGetCertRequest
 873 * INPUTS:
 874 *    inCertReqMsg
 875 *        The Certificate Request Message to operate on.
 876 * NOTES:
 877 *    This function returns a copy of the Certificate Request to the user.
 878 *    The user can keep adding to this request and then making it a part
 879 *    of another message.  After the user no longer wants to use the
 880 *    returned request, the user must call CRMF_DestroyCertRequest and
 881 *    pass it the request returned by this function.
 882 * RETURN:
 883 *    A pointer to a copy of the certificate request contained by the message.
 884 *    A NULL return value indicates an error occurred while copying the 
 885 *   certificate request.
 886 */
 887extern CRMFCertRequest *
 888       CRMF_CertReqMsgGetCertRequest(CRMFCertReqMsg *inCertReqMsg);
 889
 890/*
 891 * FUNCTION: CRMF_CertRequestGetCertTemplateVersion
 892 * INPUTS:
 893 *    inCertReq
 894 *        The Certificate Request to operate on.
 895 *    version
 896 *        A pointer to where the library can store the version contatined
 897 *        in the certificate template within the certifcate request.
 898 * RETURN:
 899 *    SECSuccess if the Certificate template contains the version field.  In 
 900 *    this case, *version will hold the value of the certificate template 
 901 *    version.
 902 *    SECFailure indicates that version field was not present as part of
 903 *    of the certificate template.
 904 */
 905extern SECStatus 
 906       CRMF_CertRequestGetCertTemplateVersion(CRMFCertRequest *inCertReq, 
 907					      long            *version);
 908
 909/*
 910 * FUNCTION: CRMF_CertRequestGetCertTemplateSerialNumber
 911 * INPUTS:
 912 *    inCertReq
 913 *        The certificate request to operate on.
 914 *    serialNumber
 915 *        A pointer where the library can put the serial number contained
 916 *        in the certificate request's certificate template.
 917 * RETURN:
 918 * If a serial number exists in the CertTemplate of the request, the function 
 919 * returns SECSuccess and the value at *serialNumber contains the serial 
 920 * number.
 921 * If no serial number is present, then the function returns SECFailure and
 922 * the value at *serialNumber is un-changed.
 923 */
 924extern SECStatus 
 925       CRMF_CertRequestGetCertTemplateSerialNumber(CRMFCertRequest *inCertReq, 
 926						   long         *serialNumber);
 927
 928/*
 929 * FUNCTION: CRMF_CertRequestGetCertTemplateSigningAlg
 930 * INPUT:
 931 *    inCertReq
 932 *        The Certificate Request to operate on.
 933 *    destAlg
 934 *        A Pointer to where the library can place a copy of the signing alg
 935 *        used in the cert request's cert template.
 936 * RETURN:
 937 * If the signingAlg is present in the CertRequest's CertTemplate, then
 938 * the function returns SECSuccess and places a copy of sigingAlg in 
 939 * *destAlg.
 940 * If no signingAlg is present, then the function returns SECFailure and
 941 * the value at *destAlg is un-changed
 942 */
 943extern SECStatus 
 944       CRMF_CertRequestGetCertTemplateSigningAlg(CRMFCertRequest *inCertReq,
 945						 SECAlgorithmID  *destAlg);
 946/*
 947 * FUNCTION: CRMF_CertRequestGetCertTemplateIssuer
 948 * INPUTS:
 949 *    inCertReq
 950 *        The Certificate Request to operate on.
 951 *    destIssuer
 952 *        A pointer to where the library can place a copy of the cert
 953 *        request's cert template issuer field.
 954 * RETURN:
 955 * If the issuer is present in the cert request cert template, the function 
 956 * returns SECSuccess and places a  copy of the issuer in *destIssuer.
 957 * If there is no issuer present, the funciton returns SECFailure and the
 958 * value at *destIssuer is unchanged.
 959 */
 960extern SECStatus 
 961       CRMF_CertRequestGetCertTemplateIssuer(CRMFCertRequest *inCertReq,
 962					     CERTName        *destIssuer);
 963
 964/*
 965 * FUNCTION: CRMF_CertRequestGetCertTemplateValidity
 966 * INPUTS:
 967 *    inCertReq
 968 *        The Certificate Request to operate on.
 969 *    destValdity
 970 *        A pointer to where the library can place a copy of the validity
 971 *        info in the cert request cert template.
 972 * NOTES:
 973 * Pass the pointer to 
 974 * RETURN: 
 975 * If there is an OptionalValidity field, the function will return SECSuccess
 976 * and place the appropriate values in *destValidity->notBefore and 
 977 * *destValidity->notAfter. (Each field is optional, but at least one will
 978 * be present if the function returns SECSuccess)
 979 *
 980 * If there is no OptionalValidity field, the function will return SECFailure
 981 * and the values at *destValidity will be un-changed.
 982 */
 983extern SECStatus 
 984       CRMF_CertRequestGetCertTemplateValidity(CRMFCertRequest *inCertReq,
 985					       CRMFGetValidity *destValidity);
 986/*
 987 * FUNCTION: CRMF_DestroyGetValidity
 988 * INPUTS:
 989 *    inValidity
 990 *        A pointer to the memroy to be freed.
 991 * NOTES:
 992 * The function will free the memory allocated by the function 
 993 * CRMF_CertRequestGetCertTemplateValidity.  That means only memory pointed
 994 * to within the CRMFGetValidity structure.  Since 
 995 * CRMF_CertRequestGetCertTemplateValidity does not allocate memory for the
 996 * structure passed into it, it will not free it.  Meaning this function will
 997 * free the memory at inValidity->notBefore and inValidity->notAfter, but not
 998 * the memory directly at inValdity.
 999 *
1000 * RETURN:
1001 * SECSuccess if freeing the memory was successful.  Any other return value
1002 * indicates an error while freeing the memory.
1003 */
1004extern SECStatus 
1005       CRMF_DestroyGetValidity(CRMFGetValidity *inValidity);
1006
1007/*
1008 * FUNCTION: CRMF_CertRequestGetCertTemplateSubject
1009 * INPUTS:
1010 *    inCertReq
1011 *        The Certificate Request to operate on.
1012 *    destSubject
1013 *        A pointer to where the library can place a copy of the subject
1014 *        contained in the request's cert template.
1015 * RETURN:
1016 * If there is a subject in the CertTemplate, then the function returns 
1017 * SECSuccess and a copy of the subject is placed in *destSubject.
1018 *
1019 * If there is no subject, the function returns SECFailure and the values at
1020 * *destSubject is unchanged.
1021 */
1022extern SECStatus 
1023       CRMF_CertRequestGetCertTemplateSubject (CRMFCertRequest *inCertReq,
1024					       CERTName        *destSubject);
1025
1026/*
1027 * FUNCTION: CRMF_CertRequestGetCertTemplatePublicKey
1028 * INPUTS:
1029 *    inCertReq
1030 *        The Cert request to operate on.
1031 *    destPublicKey
1032 *        A pointer to where the library can place a copy of the request's
1033 *        cert template public key.
1034 * RETURN:
1035 * If there is a publicKey parameter in the CertRequest, the function returns
1036 * SECSuccess, and places a copy of the publicKey in *destPublicKey.
1037 *
1038 * If there is no publicKey, the function returns SECFailure and the value
1039 * at *destPublicKey is un-changed.
1040 */
1041extern SECStatus 
1042       CRMF_CertRequestGetCertTemplatePublicKey(CRMFCertRequest *inCertReq,
1043				      CERTSubjectPublicKeyInfo *destPublicKey);
1044
1045/*
1046 * FUNCTION: CRMF_CertRequestGetCertTemplateIssuerUID
1047 * INPUTS:
1048 *    inCertReq
1049 *        The Cert request to operate on.
1050 *    destIssuerUID
1051 *        A pointer to where the library can store a copy of the request's
1052 *        cert template destIssuerUID.
1053 *
1054 * NOTES: 
1055 * destIssuerUID is a bit string and will be returned in a SECItem as
1056 * a bit string.  Meaning the len field contains the number of valid bits as
1057 * opposed to the number of bytes allocated.
1058 *
1059 * RETURN:
1060 * If the CertTemplate has an issuerUID, the function returns SECSuccess and
1061 * places a copy of the issuerUID in *destIssuerUID.
1062 *
1063 * If there is no issuerUID, the function returns SECFailure and the value
1064 * *destIssuerUID is unchanged.
1065 */
1066extern SECStatus 
1067       CRMF_CertRequestGetCertTemplateIssuerUID(CRMFCertRequest *inCertReq,
1068						SECItem        *destIssuerUID);
1069
1070/*
1071 * FUNCTION: CRMF_CertRequestGetCertTemplateSubjectUID
1072 *    inCertReq
1073 *        The Cert request to operate on.
1074 *    destSubjectUID
1075 *        A pointer to where the library can store a copy of the request's
1076 *        cert template destIssuerUID.
1077 *
1078 * NOTES: 
1079 * destSubjectUID is a bit string and will be returned in a SECItem as
1080 * a bit string.  Meaning the len field contains the number of valid bits as
1081 * opposed to the number of bytes allocated.
1082 *
1083 * RETURN:
1084 * If the CertTemplate has an issuerUID, the function returns SECSuccess and
1085 * places a copy of the issuerUID in *destIssuerUID.
1086 *
1087 * If there is no issuerUID, the function returns SECSuccess and the value
1088 * *destIssuerUID is unchanged.
1089 */
1090extern SECStatus CRMF_GetCertTemplateSubjectUID(CRMFCertRequest *inCertReq,
1091						SECItem       *destSubjectUID);
1092
1093/*
1094 * FUNCTION: CRMF_CertRequestGetNumberOfExtensions
1095 * INPUTS:
1096 *    inCertReq
1097 *        The cert request to operate on.
1098 * RETURN:
1099 *    Returns the number of extensions contained by the Cert Request.
1100 */
1101extern int CRMF_CertRequestGetNumberOfExtensions(CRMFCertRequest *inCertReq);
1102
1103/*
1104 * FUNCTION: CRMF_CertRequestGetExtensionAtIndex
1105 * INPUTS:
1106 *    inCertReq
1107 *        The Certificate request to operate on.
1108 *    index
1109 *        The index of the extension array whihc the user wants to access.
1110 * NOTES:
1111 * This function retrieves the extension at the index corresponding to the 
1112 * parameter "index" indicates.  Indexing is done like a C array.  
1113 * (0 ... numElements-1)
1114 *
1115 * Call CRMF_DestroyCertExtension when done using the return value.
1116 *
1117 * RETURN:
1118 *    A pointer to a copy of the extension at the desired index.  A NULL 
1119 *    return value indicates an invalid index or an error while copying 
1120 *    the extension.
1121 */
1122extern CRMFCertExtension *
1123       CRMF_CertRequestGetExtensionAtIndex(CRMFCertRequest *inCertReq,
1124					   int              index);
1125/*
1126 * FUNCTION: CRMF_CertExtensionGetOidTag
1127 * INPUTS:
1128 *    inExtension
1129
1130 *        The extension to operate on.
1131 * RETURN:
1132 *    Returns the SECOidTag associated with the cert extension passed in.
1133 */
1134extern SECOidTag CRMF_CertExtensionGetOidTag(CRMFCertExtension *inExtension);
1135
1136/*
1137 * FUNCTION: CRMF_CertExtensionGetIsCritical
1138 * INPUT:
1139 *    inExt
1140 *        The cert extension to operate on.
1141 *
1142 * RETURN:
1143 * PR_TRUE if the extension is critical.
1144 * PR_FALSE if the extension is not critical.
1145 */
1146extern PRBool CRMF_CertExtensionGetIsCritical(CRMFCertExtension *inExt);
1147             
1148/*
1149 * FUNCTION: CRMF_CertExtensionGetValue
1150 * INPUT:
1151 *    inExtension
1152 *        The extension to operate on.
1153 * NOTES:
1154 * Caller is responsible for freeing the memory associated with the return
1155 * value.  Call SECITEM_FreeItem(retVal, PR_TRUE) when done using the return
1156 * value.
1157 *
1158 * RETURN:
1159 * A pointer to an item containig the value for the certificate extension.
1160 * A NULL return value indicates an error in copying the information.
1161 */
1162extern SECItem*  CRMF_CertExtensionGetValue(CRMFCertExtension *inExtension);
1163
1164/*
1165 * FUNCTION: CRMF_CertReqMsgGetPOPOSigningKey
1166 * INPUTS:
1167 *    inCertReqMsg
1168 *        The certificate request message to operate on.
1169 *    destKey
1170 *        A pointer to where the library can place a pointer to
1171 *        a copy of the Proof Of Possession Signing Key used 
1172 *        by the message.
1173 *
1174 * RETURN:
1175 * Get the POPOSigningKey associated with this CRMFCertReqMsg.  
1176 * If the CertReqMsg does not have a pop, the function returns
1177 * SECFailure and the value at *destKey is un-changed..
1178 *
1179 * If the CertReqMsg does have a pop, then the CertReqMsg's 
1180 * POPOSigningKey will be placed at *destKey.
1181 */
1182extern SECStatus 
1183       CRMF_CertReqMsgGetPOPOSigningKey(CRMFCertReqMsg      *inCertReqMsg,
1184					CRMFPOPOSigningKey **destKey);
1185
1186/*
1187 * FUNCTION: CRMF_DestroyPOPOSigningKey
1188 * INPUTS:
1189 *    inKey
1190 *        The signing key to free.
1191 *
1192 * RETURN:
1193 * SECSuccess if freeing the memory was successful.  Any other return value
1194 * indicates an error while freeing memory.
1195 */
1196extern SECStatus CRMF_DestroyPOPOSigningKey (CRMFPOPOSigningKey *inKey);
1197
1198/*
1199 * FUNCTION: CRMF_POPOSigningKeyGetAlgID
1200 * INPUTS:
1201 *    inSignKey
1202 *        The Signing Key to operate on.
1203 * RETURN:
1204 * Return the algorithmID used by the CRMFPOPOSigningKey.  User must
1205 * call SECOID_DestroyAlgorithmID(destID, PR_TRUE) when done using the
1206 * return value.
1207 */
1208extern SECAlgorithmID* 
1209       CRMF_POPOSigningKeyGetAlgID(CRMFPOPOSigningKey *inSignKey);
1210
1211/*
1212 * FUNCTION: CRMF_POPOSigningKeyGetSignature
1213 * INPUTS:
1214 *    inSignKey
1215 *        The Signing Key to operate on.
1216 *
1217 * RETURN:        
1218 * Get the actual signature stored away in the CRMFPOPOSigningKey.  SECItem
1219 * returned is a BIT STRING, so the len field is the number of bits as opposed
1220 * to the total number of bytes allocatd.  User must call 
1221 * SECITEM_FreeItem(retVal,PR_TRUE) when done using the return value.
1222 */
1223extern SECItem* CRMF_POPOSigningKeyGetSignature(CRMFPOPOSigningKey *inSignKey);
1224
1225/*
1226 * FUNCTION: CRMF_POPOSigningKeyGetInput
1227 * INPUTS:
1228 *    inSignKey
1229 *        The Signing Key to operate on.
1230 * NOTES:
1231 * This function will return the der encoded input that was read in while 
1232 * decoding.  The API does not support this option when creating, so you
1233 * cannot add this field.
1234 *
1235 * RETURN:
1236 * Get the poposkInput that is part of the of the POPOSigningKey. If the
1237 * optional field is not part of the POPOSigningKey, the function returns
1238 * NULL.
1239 *
1240 * If the optional field is part of the POPOSingingKey, the function will
1241 * return a copy of the der encoded poposkInput.
1242 */
1243extern SECItem* CRMF_POPOSigningKeyGetInput(CRMFPOPOSigningKey *inSignKey);
1244
1245/*
1246 * FUNCTION: CRMF_CertReqMsgGetPOPKeyEncipherment
1247 * INPUTS:
1248 *    inCertReqMsg
1249 *        The certificate request message to operate on.
1250 *    destKey
1251 *        A pointer to where the library can place a pointer to a 
1252 *        copy of the POPOPrivKey representing Key Encipherment 
1253 *        Proof of Possession.
1254 *NOTES:
1255 * This function gets the POPOPrivKey associated with this CRMFCertReqMsg 
1256 * for Key Encipherment.  
1257 *
1258 * RETURN:
1259 * If the CertReqMsg did not use Key Encipherment for Proof Of Possession, the
1260 * function returns SECFailure and the value at *destKey is un-changed.
1261 *
1262 * If the CertReqMsg did use Key Encipherment for ProofOfPossession, the
1263 * function returns SECSuccess and places the POPOPrivKey representing the
1264 * Key Encipherment Proof Of Possessin at *destKey.
1265 */
1266extern SECStatus 
1267       CRMF_CertReqMsgGetPOPKeyEncipherment(CRMFCertReqMsg   *inCertReqMsg,
1268					    CRMFPOPOPrivKey **destKey);
1269
1270/*
1271 * FUNCTION: CRMF_CertReqMsgGetPOPKeyAgreement
1272 * INPUTS:
1273 *    inCertReqMsg
1274 *        The certificate request message to operate on.
1275 *    destKey
1276 *        A pointer to where the library can place a pointer to a 
1277 *        copy of the POPOPrivKey representing Key Agreement 
1278 *        Proof of Possession.
1279 * NOTES:
1280 * This function gets the POPOPrivKey associated with this CRMFCertReqMsg for 
1281 * Key Agreement.  
1282 *
1283 * RETURN:
1284 * If the CertReqMsg used Key Agreement for Proof Of Possession, the
1285 * function returns SECSuccess and the POPOPrivKey for Key Agreement
1286 * is placed at *destKey.
1287 *
1288 * If the CertReqMsg did not use Key Agreement for Proof Of Possession, the
1289 * function return SECFailure and the value at *destKey is unchanged.
1290 */
1291extern SECStatus 
1292       CRMF_CertReqMsgGetPOPKeyAgreement(CRMFCertReqMsg   *inCertReqMsg,
1293					 CRMFPOPOPrivKey **destKey);
1294
1295/* 
1296 * FUNCTION: CRMF_DestroyPOPOPrivKey
1297 * INPUTS:
1298 *    inPrivKey
1299 *        The POPOPrivKey to destroy.
1300 * NOTES:
1301 * Destroy a structure allocated by CRMF_GetPOPKeyEncipherment or
1302 * CRMF_GetPOPKeyAgreement.
1303 *
1304 * RETURN:
1305 * SECSuccess on successful destruction of the POPOPrivKey.
1306 * Any other return value indicates an error in freeing the 
1307 * memory.
1308 */
1309extern SECStatus CRMF_DestroyPOPOPrivKey(CRMFPOPOPrivKey *inPrivKey);
1310
1311/* 
1312 * FUNCTION: CRMF_POPOPrivKeyGetChoice
1313 * INPUT:
1314 *    inKey
1315 *        The POPOPrivKey…

Large files files are truncated, but you can click here to view the full file