mozilla/security/nss/lib/crmf/crmf.h

   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
  48 SEC_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  */
  68 extern 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 CRMFEncoderOutputCallback type is
  87  *    defined for information on proper behavior of the function fn.
  88  * RETURN:
  89  *    SECSuccess if encoding was successful.  Any other return value
  90  *    indicates an error occurred during encoding.
  91  */
  92 extern 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 CRMFEncoderOutputCallback type is
 119  *    defined for information on proper behavior of the function 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  */
 126 extern 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  */
 151 extern 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  */
 169 extern 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  */
 192 extern 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  */
 211 extern 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  */
 225 extern 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  */
 253 extern 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  */
 270 extern 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  */
 349 extern 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  */
 371 extern 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  */
 397 extern 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  */
 421 extern 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  */
 442 extern 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  */
 464 extern 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  */
 479 extern 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  */
 505 extern 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  */
 519 extern 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  */
 538 extern 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  */
 557 extern 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  */
 573 extern 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 function 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  */
 628 extern 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 function 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 function 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  */
 686 extern 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 function 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 function 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  */
 735 extern 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  */
 758 extern 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  */
 779 extern 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  */
 791 extern 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  */
 803 extern 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  */
 825 extern 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  */
 844 extern 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  */
 868 extern 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  */
 887 extern 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  */
 905 extern 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  */
 924 extern 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  */
 943 extern 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 function returns SECFailure and the
 958  * value at *destIssuer is unchanged.
 959  */
 960 extern 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  */
 983 extern 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  */
1004 extern 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  */
1022 extern 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  */
1041 extern 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  */
1066 extern 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  */
1090 extern 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  */
1101 extern 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  */
1122 extern 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  */
1134 extern 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  */
1146 extern 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  */
1162 extern 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  */
1182 extern 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  */
1196 extern 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  */
1208 extern 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  */
1223 extern 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  */
1243 extern 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  */
1266 extern 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  */
1291 extern 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  */
1309 extern SECStatus CRMF_DestroyPOPOPrivKey(CRMFPOPOPrivKey *inPrivKey);
1310
1311 /*
1312  * FUNCTION: CRMF_POPOPrivKeyGetChoice
1313  * INPUT:
1314  *    inKey
1315  *        The POPOPrivKey to operate on.
1316  * RETURN:
1317  * Returns which choice was used in constructing the POPPOPrivKey. Look at
1318  * the definition of CRMFPOPOPrivKeyChoice in crmft.h for the possible return
1319  * values.
1320  */
1321 extern CRMFPOPOPrivKeyChoice CRMF_POPOPrivKeyGetChoice(CRMFPOPOPrivKey *inKey);
1322
1323 /*
1324  * FUNCTION: CRMF_POPOPrivKeyGetThisMessage
1325  * INPUTS:
1326  *    inKey
1327  *        The POPOPrivKey to operate on.
1328  *    destString
1329  *        A pointer to where the library can place a copy of the This Message
1330  *        field stored in the POPOPrivKey
1331  *
1332  * RETURN:
1333  * Returns the field thisMessage from the POPOPrivKey.
1334  * If the POPOPrivKey did not use the field thisMessage, the function
1335  * returns SECFailure and the value at *destString is unchanged.
1336  *
1337  * If the POPOPrivKey did use the field thisMessage, the function returns
1338  * SECSuccess and the BIT STRING representing thisMessage is placed
1339  * at *destString. BIT STRING representation means the len field is the
1340  * number of valid bits as opposed to the total number of bytes.
1341  */
1342 extern SECStatus CRMF_POPOPrivKeyGetThisMessage(CRMFPOPOPrivKey  *inKey,
1343                                                 SECItem          *destString);
1344
1345 /*
1346  * FUNCTION: CRMF_POPOPrivKeyGetSubseqMess
1347  * INPUTS:
1348  *    inKey
1349  *        The POPOPrivKey to operate on.
1350  *    destOpt
1351  *        A pointer to where the library can place the value of the
1352  *        Subsequent Message option used by POPOPrivKey.
1353  *
1354  * RETURN:
1355  * Retrieves the field subsequentMessage from the POPOPrivKey.
1356  * If the POPOPrivKey used the subsequentMessage option, the function
1357  * returns SECSuccess and places the appropriate enumerated value at
1358  * *destMessageOption.
1359  *
1360  * If the POPOPrivKey did not use the subsequenMessage option, the function
1361  * returns SECFailure and the value at *destOpt is un-changed.
1362  */
1363 extern SECStatus CRMF_POPOPrivKeyGetSubseqMess(CRMFPOPOPrivKey       *inKey,
1364                                                CRMFSubseqMessOptions *destOpt);
1365
1366 /*
1367  * FUNCTION: CRMF_POPOPrivKeyGetDHMAC
1368  * INPUTS:
1369  *    inKey
1370  *        The POPOPrivKey to operate on.
1371  *    destMAC
1372  *        A pointer to where the library can place a copy of the dhMAC
1373  *        field of the POPOPrivKey.
1374  *
1375  * NOTES:
1376  * Returns the field dhMAC from the POPOPrivKey.  The populated SECItem
1377  * is in BIT STRING format.
1378  *
1379  * RETURN:
1380  * If the POPOPrivKey used the dhMAC option, the function returns SECSuccess
1381  * and the BIT STRING for dhMAC will be placed at *destMAC.  The len field in
1382  * destMAC (ie destMAC->len) will be the valid number of bits as opposed to
1383  * the number of allocated bytes.
1384  *
1385  * If the POPOPrivKey did not use the dhMAC option, the function returns
1386  * SECFailure and the value at *destMAC is unchanged.
1387  *
1388  */
1389 extern SECStatus CRMF_POPOPrivKeyGetDHMAC(CRMFPOPOPrivKey *inKey,
1390                                           SECItem         *destMAC);
1391
1392 /*
1393  * FUNCTION: CRMF_CertRequestGetNumControls
1394  * INPUTS:
1395  *    inCertReq
1396  *        The Certificate Request to operate on.
1397  * RETURN:
1398  * Returns the number of Controls registered with this CertRequest.
1399  */
1400 extern int CRMF_CertRequestGetNumControls (CRMFCertRequest *inCertReq);
1401
1402 /*
1403  * FUNCTION: CRMF_CertRequestGetControlAtIndex
1404  * INPUTS:
1405  *    inCertReq
1406  *        The certificate request to operate on.
1407  *    index
1408  *        The index of the control the user wants a copy of.
1409  * NOTES:
1410  * Function retrieves the Control at located at index.  The Controls
1411  * are numbered like a traditional C array (0 ... numElements-1)
1412  *
1413  * RETURN:
1414  * Returns a copy of the control at the index specified.  This is a copy
1415  * so the user must call CRMF_DestroyControl after the return value is no
1416  * longer needed.  A return value of NULL indicates an error while copying
1417  * the control or that the index was invalid.
1418  */
1419 extern CRMFControl*
1420        CRMF_CertRequestGetControlAtIndex(CRMFCertRequest *inCertReq,
1421                                          int              index);
1422
1423 /*
1424  * FUNCTION: CRMF_DestroyControl
1425  * INPUTS:
1426  *    inControl
1427  *        The Control to destroy.
1428  * NOTES:
1429  * Destroy a CRMFControl allocated by CRMF_GetControlAtIndex.
1430  *
1431  * RETURN:
1432  * SECSuccess if freeing the memory was successful.  Any other return
1433  * value indicates an error while freeing the memory.
1434  */
1435 extern SECStatus CRMF_DestroyControl(CRMFControl *inControl);
1436
1437 /*
1438  * FUNCTION: CRMF_ControlGetControlType
1439  * INPUTS:
1440  *    inControl
1441  *        The control to operate on.
1442  * NOTES:
1443  * The function returns an enumertion which indicates the type of control
1444  * 'inControl'.
1445  *
1446  * RETURN:
1447  * Look in crmft.h at the definition of the enumerated type CRMFControlType
1448  * for the possible return values.
1449  */
1450 extern CRMFControlType CRMF_ControlGetControlType(CRMFControl *inControl);
1451
1452 /*
1453  * FUNCTION: CRMF_ControlGetRegTokenControlValue
1454  * INPUTS:
1455  *    inControl
1456  *        The Control to operate on.
1457  * NOTES:
1458  * The user must call SECITEM_FreeItem passing in the return value
1459  * after the returnvalue is no longer needed.
1460
1461  * RETURN:
1462  * Return the value for a Registration Token Control.
1463  * The SECItem returned should be in UTF8 format.  A NULL
1464  * return value indicates there was no Registration Control associated
1465  * with the Control.
1466  * (This library will not verify format.  It assumes the client properly
1467  * formatted the strings when adding it or the message decoded was properly
1468  * formatted.  The library will just give back the bytes it was given.)
1469  */
1470 extern SECItem* CRMF_ControlGetRegTokenControlValue(CRMFControl *inControl);
1471
1472 /*
1473  * FUNCTION: CRMF_ControlGetAuthenticatorControlValue
1474  * INPUTS:
1475  *    inControl
1476  *        The Control to operate on.
1477  * NOTES:
1478  * The user must call SECITEM_FreeItem passing in the return value
1479  * after the returnvalue is no longer needed.
1480  *
1481  * RETURN:
1482  * Return the value for the Authenticator Control.
1483  * The SECItem returned should be in UTF8 format.  A NULL
1484  * return value indicates there was no Authenticator Control associated
1485  * with the CRMFControl..
1486  * (This library will not verify format.  It assumes the client properly
1487  * formatted the strings when adding it or the message decoded was properly
1488  * formatted.  The library will just give back the bytes it was given.)
1489  */
1490 extern SECItem* CRMF_ControlGetAuthicatorControlValue(CRMFControl *inControl);
1491
1492 /*
1493  * FUNCTION: CRMF_ControlGetPKIArchiveOptions
1494  * INPUTS:inControl
1495  *    The Control tooperate on.
1496  * NOTES:
1497  * This function returns a copy of the PKIArchiveOptions.  The user must call
1498  * the function CRMF_DestroyPKIArchiveOptions when the return value is no
1499  * longer needed.
1500  *
1501  * RETURN:
1502  * Get the PKIArchiveOptions associated with the Control.  A return
1503  * value of NULL indicates the Control was not a PKIArchiveOptions
1504  * Control.
1505  */
1506 extern CRMFPKIArchiveOptions*
1507        CRMF_ControlGetPKIArchiveOptions(CRMFControl *inControl);
1508
1509 /*
1510  * FUNCTION: CMRF_DestroyPKIArchiveOptions
1511  * INPUTS:
1512  *    inOptions
1513  *        The ArchiveOptions to destroy.
1514  * NOTE:
1515  * Destroy the CRMFPKIArchiveOptions structure.
1516  *
1517  * RETURN:
1518  * SECSuccess if successful in freeing all the memory associated with
1519  * the PKIArchiveOptions.  Any other return value indicates an error while
1520  * freeing the PKIArchiveOptions.
1521  */
1522 extern SECStatus
1523        CRMF_DestroyPKIArchiveOptions(CRMFPKIArchiveOptions *inOptions);
1524
1525 /*
1526  * FUNCTION: CRMF_PKIArchiveOptionsGetOptionType
1527  * INPUTS:
1528  *    inOptions
1529  *        The PKIArchiveOptions to operate on.
1530  * RETURN:
1531  * Returns the choice used for the PKIArchiveOptions.  Look at the definition
1532  * of CRMFPKIArchiveOptionsType in crmft.h for possible return values.
1533  */
1534 extern CRMFPKIArchiveOptionsType
1535        CRMF_PKIArchiveOptionsGetOptionType(CRMFPKIArchiveOptions *inOptions);
1536
1537 /*
1538  * FUNCTION: CRMF_PKIArchiveOptionsGetEncryptedPrivKey
1539  * INPUTS:
1540  *    inOpts
1541  *        The PKIArchiveOptions to operate on.
1542  *
1543  * NOTES:
1544  * The user must call CRMF_DestroyEncryptedKey when done using this return
1545  * value.
1546  *
1547  * RETURN:
1548  * Get the encryptedPrivKey field of the PKIArchiveOptions structure.
1549  * A return value of NULL indicates that encryptedPrivKey was not used as
1550  * the choice for this PKIArchiveOptions.
1551  */
1552 extern CRMFEncryptedKey*
1553       CRMF_PKIArchiveOptionsGetEncryptedPrivKey(CRMFPKIArchiveOptions *inOpts);
1554
1555 /*
1556  * FUNCTION: CRMF_EncryptedKeyGetChoice
1557  * INPUTS:
1558  *    inEncrKey
1559  *        The EncryptedKey to operate on.
1560  *
1561  * NOTES:
1562  * Get the choice used for representing the EncryptedKey.
1563  *
1564  * RETURN:
1565  * Returns the Choice used in representing the EncryptedKey.  Look in
1566  * crmft.h at the definition of CRMFEncryptedKeyChoice for possible return
1567  * values.
1568  */
1569 extern CRMFEncryptedKeyChoice
1570        CRMF_EncryptedKeyGetChoice(CRMFEncryptedKey *inEncrKey);
1571
1572
1573 /*
1574  * FUNCTION: CRMF_EncryptedKeyGetEncryptedValue
1575  * INPUTS:
1576  *    inKey
1577  *        The EncryptedKey to operate on.
1578  *
1579  * NOTES:
1580  * The user must call CRMF_DestroyEncryptedValue passing in
1581  * CRMF_GetEncryptedValue's return value.
1582  *
1583  * RETURN:
1584  * A pointer to a copy of the EncryptedValue contained as a member of
1585  * the EncryptedKey.
1586  */
1587 extern CRMFEncryptedValue*
1588        CRMF_EncryptedKeyGetEncryptedValue(CRMFEncryptedKey *inKey);
1589
1590 /*
1591  * FUNCTION: CRMF_DestroyEncryptedValue
1592  * INPUTS:
1593  *    inEncrValue
1594  *        The EncryptedValue to destroy.
1595  *
1596  * NOTES:
1597  * Free up all memory associated with 'inEncrValue'.
1598  *
1599  * RETURN:
1600  * SECSuccess if freeing up the memory associated with the EncryptedValue
1601  * is successful. Any other return value indicates an error while freeing the
1602  * memory.
1603  */
1604 extern SECStatus CRMF_DestroyEncryptedValue(CRMFEncryptedValue *inEncrValue);
1605
1606 /*
1607  * FUNCTION: CRMF_EncryptedValueGetEncValue
1608  * INPUTS:
1609  *    inEncValue
1610  *        The EncryptedValue to operate on.
1611  * NOTES:
1612  * Function retrieves the encValue from an EncryptedValue structure.
1613  *
1614  * RETURN:
1615  * A poiner to a SECItem containing the encValue of the EncryptedValue
1616  * structure.  The return value is in BIT STRING format, meaning the
1617  * len field of the return structure represents the number of valid bits
1618  * as opposed to the allocated number of bytes.
1619  * ANULL return value indicates an error in copying the encValue field.
1620  */
1621 extern SECItem* CRMF_EncryptedValueGetEncValue(CRMFEncryptedValue *inEncValue);
1622
1623 /*
1624  * FUNCTION: CRMF_EncryptedValueGetIntendedAlg
1625  * INPUTS
1626  *    inEncValue
1627  *        The EncryptedValue to operate on.
1628  * NOTES:
1629  * Retrieve the IntendedAlg field from the EncryptedValue structure.
1630  * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
1631  * the return value.  When present, this alogorithm is the alogrithm for
1632  * which the private key will be used.
1633  *
1634  * RETURN:
1635  * A Copy of the intendedAlg field.  A NULL return value indicates the
1636  * optional field was not present in the structure.
1637  */
1638 extern SECAlgorithmID*
1639        CRMF_EncryptedValueGetIntendedAlg(CRMFEncryptedValue  *inEncValue);
1640
1641
1642 /*
1643  * FUNCTION: CRMF_EncryptedValueGetSymmAlg
1644  * INPUTS
1645  *    inEncValue
1646  *        The EncryptedValue to operate on.
1647  * NOTES:
1648  * Retrieve the symmAlg field from the EncryptedValue structure.
1649  * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
1650  * the return value.  When present, this is algorithm used to
1651  * encrypt the encValue of the EncryptedValue.
1652  *
1653  * RETURN:
1654  * A Copy of the symmAlg field.  A NULL return value indicates the
1655  * optional field was not present in the structure.
1656  */
1657 extern SECAlgorithmID*
1658        CRMF_EncryptedValueGetSymmAlg(CRMFEncryptedValue  *inEncValue);
1659
1660
1661 /*
1662  * FUNCTION: CRMF_EncryptedValueGetKeyAlg
1663  * INPUTS
1664  *    inEncValue
1665  *        The EncryptedValue to operate on.
1666  * NOTES:
1667  * Retrieve the keyAlg field from the EncryptedValue structure.
1668  * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
1669  * the return value.  When present, this is the algorithm used to encrypt
1670  * the symmetric key in the encSymmKey field of the EncryptedValue structure.
1671  *
1672  * RETURN:
1673  * A Copy of the keyAlg field.  A NULL return value indicates the
1674  * optional field was not present in the structure.
1675  */
1676 extern SECAlgorithmID*
1677        CRMF_EncryptedValueGetKeyAlg(CRMFEncryptedValue *inEncValue);
1678
1679 /*
1680  * FUNCTION: CRMF_EncryptedValueGetValueHint
1681  * INPUTS:
1682  *    inEncValue
1683  *        The EncryptedValue to operate on.
1684  *
1685  * NOTES:
1686  * Return a copy of the der-encoded value hint.
1687  * User must call SECITEM_FreeItem(retVal, PR_TRUE) when done using the
1688  * return value.  When, present, this is a value that the client which
1689  * originally issued a certificate request can use to reproduce any data
1690  * it wants.  The RA does not know how to interpret this data.
1691  *
1692  * RETURN:
1693  * A copy of the valueHint field of the EncryptedValue.  A NULL return
1694  * value indicates the optional valueHint field is not present in the
1695  * EncryptedValue.
1696  */
1697 extern SECItem*
1698        CRMF_EncryptedValueGetValueHint(CRMFEncryptedValue  *inEncValue);
1699
1700 /*
1701  * FUNCTION: CRMF_EncrypteValueGetEncSymmKey
1702  * INPUTS:
1703  *    inEncValue
1704  *        The EncryptedValue to operate on.
1705  *
1706  * NOTES:
1707  * Return a copy of the encSymmKey field. This field is the encrypted
1708  * symmetric key that the client uses in doing Public Key wrap of a private
1709  * key.  When present, this is the symmetric key that was used to wrap the
1710  * private key.  (The encrypted private key will be stored in encValue
1711  * of the same EncryptedValue structure.)  The user must call
1712  * SECITEM_FreeItem(retVal, PR_TRUE) when the return value is no longer
1713  * needed.
1714  *
1715  * RETURN:
1716  * A copy of the optional encSymmKey field of the EncryptedValue structure.
1717  * The return value will be in BIT STRING format, meaning the len field will
1718  * be the number of valid bits as opposed to the number of bytes. A return
1719  * value of NULL means the optional encSymmKey field was not present in
1720  * the EncryptedValue structure.
1721  */
1722 extern SECItem*
1723        CRMF_EncryptedValueGetEncSymmKey(CRMFEncryptedValue *inEncValue);
1724
1725 /*
1726  * FUNCTION: CRMF_PKIArchiveOptionsGetKeyGenParameters
1727  * INPUTS:
1728  *    inOptions
1729  *        The PKiArchiveOptions to operate on.
1730  *
1731  * NOTES:
1732  * User must call SECITEM_FreeItem(retVal, PR_TRUE) after the return
1733  * value is no longer needed.
1734  *
1735  * RETURN:
1736  * Get the keyGenParameters field of the PKIArchiveOptions.
1737  * A NULL return value indicates that keyGenParameters was not
1738  * used as the choice for this PKIArchiveOptions.
1739  *
1740  * The SECItem returned is in BIT STRING format (ie, the len field indicates
1741  * number of valid bits as opposed to allocated number of bytes.)
1742  */
1743 extern SECItem*
1744    CRMF_PKIArchiveOptionsGetKeyGenParameters(CRMFPKIArchiveOptions *inOptions);
1745
1746 /*
1747  * FUNCTION: CRMF_PKIArchiveOptionsGetArchiveRemGenPrivKey
1748  * INPUTS:
1749  *    inOpt
1750  *        The PKIArchiveOptions to operate on.
1751  *    destVal
1752  *        A pointer to where the library can place the value for
1753  *        arciveRemGenPrivKey
1754  * RETURN:
1755  * If the PKIArchiveOptions used the archiveRemGenPrivKey field, the
1756  * function returns SECSuccess and fills the value at *destValue with either
1757  * PR_TRUE or PR_FALSE, depending on what the PKIArchiveOptions has as a
1758  * value.
1759  *
1760  * If the PKIArchiveOptions does not use the archiveRemGenPrivKey field, the
1761  * function returns SECFailure and the value at *destValue is unchanged.
1762  */
1763 extern SECStatus
1764     CRMF_PKIArchiveOptionsGetArchiveRemGenPrivKey(CRMFPKIArchiveOptions *inOpt,
1765                                                   PRBool             *destVal);
1766
1767 /* Helper functions that can be used by other libraries. */
1768 /*
1769  * A quick helper function to get the best wrap mechanism.
1770  */
1771 extern CK_MECHANISM_TYPE CRMF_GetBestWrapPadMechanism(PK11SlotInfo *slot);
1772
1773 /*
1774  * A helper function to get a randomly generated IV from a mechanism
1775  * type.
1776  */
1777 extern SECItem* CRMF_GetIVFromMechanism(CK_MECHANISM_TYPE mechType);
1778
1779 SEC_END_PROTOS
1780 #endif /*_CRMF_H_*/
1781
1782