Back to index

lightning-sunbird  0.9+nobinonly
crmf.h
Go to the documentation of this file.
00001 /* -*- Mode: C; tab-width: 8 -*-*/
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is the Netscape security libraries.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 
00039 #ifndef _CRMF_H_
00040 #define _CRMF_H_
00041 
00042 #include "seccomon.h"
00043 #include "cert.h"
00044 #include "crmft.h"
00045 #include "secoid.h"
00046 #include "secpkcs7.h"
00047 
00048 SEC_BEGIN_PROTOS
00049 
00050 /*
00051  * FUNCTION: CRMF_EncodeCertReqMsg
00052  * INPUTS:
00053  *    inCertReqMsg
00054  *        The Certificate Request Message to be encoded.
00055  *    fn
00056  *        A Callback function that the ASN1 encoder calls whenever
00057  *        the encoder wants to write out some DER encoded bytes.
00058  *    arg
00059  *        An opaque pointer that gets passed to the function fn
00060  * OUTPUT:
00061  *    The function fn will be called multiple times.  Look at the
00062  *    comments in crmft.h where the CRMFEncoderOutputCallback type is 
00063  *    defined for information on proper behavior of the function fn.
00064  * RETURN:
00065  *    SECSuccess if encoding was successful.  Any other return value
00066  *    indicates an error occurred during encoding.
00067  */
00068 extern SECStatus 
00069         CRMF_EncodeCertReqMsg (CRMFCertReqMsg            *inCertReqMsg, 
00070                             CRMFEncoderOutputCallback  fn,
00071                             void                      *arg);
00072 
00073 /*
00074  * FUNCTION: CRMF_EncoderCertRequest
00075  * INPUTS:
00076  *    inCertReq
00077  *        The Certificate Request to be encoded.
00078  *    fn
00079  *        A Callback function that the ASN1 encoder calls whenever
00080  *        the encoder wants to write out some DER encoded bytes.
00081  *    arg
00082  *        An opaque pointer that gets passed to the function fn.
00083  * OUTPUT:
00084  *    The function fn will be called, probably multiple times whenever 
00085  *    the ASN1 encoder wants to write out DER-encoded bytes.  Look at the 
00086  *    comments in crmft.h where the CRMFEncoderOuputCallback type is
00087  *    defined for information on proper behavior of the funciton fn.
00088  * RETURN:
00089  *    SECSuccess if encoding was successful.  Any other return value 
00090  *    indicates an error occured during encoding.
00091  */
00092 extern SECStatus CRMF_EncodeCertRequest (CRMFCertRequest           *inCertReq,
00093                                     CRMFEncoderOutputCallback  fn,
00094                                     void                      *arg);
00095 /*
00096  * FUNCTION: CRMF_EncodeCertReqMessages
00097  * INPUTS:
00098  *    inCertReqMsgs
00099  *        An array of pointers to the Certificate Request Messages
00100  *        to encode.  The user must place a NULL pointer in the index
00101  *        after the last message to be encoded.  When the library runs
00102  *        into the NULL pointer, the library assumes there are no more
00103  *        messages to encode.
00104  *    fn
00105  *        A Callback function that the ASN1 encoder calls whenever
00106  *        the encoder wants to write out some DER encoded byts.
00107  *    arg
00108  *        An opaque pointer that gets passed to the function fn.
00109  *
00110  * NOTES:
00111  *    The parameter inCertReqMsgs needs to be an array with a NULL pointer
00112  *    to signal the end of messages.  An array in the form of 
00113  *    {m1, m2, m3, NULL, m4, ...} will only encode the messages m1, m2, and
00114  *    m3.  All messages from m4 on will not be looked at by the library.
00115  *
00116  * OUTPUT:
00117  *    The function fn will be called, probably multiple times.  Look at the 
00118  *    comments in crmft.h where the CRMFEncoderOuputCallback type is
00119  *    defined for information on proper behavior of the funciton fn.
00120  *
00121  * RETURN:
00122  * SECSuccess if encoding the Certificate Request Messages was successful. 
00123  * Any other return value indicates an error occurred while encoding the
00124  * certificate request messages.
00125  */
00126 extern SECStatus 
00127        CRMF_EncodeCertReqMessages(CRMFCertReqMsg           **inCertReqMsgs,
00128                               CRMFEncoderOutputCallback  fn,
00129                               void                      *arg);
00130 
00131 
00132 /*
00133  * FUNCTION: CRMF_CreateCertReqMsg
00134  * INPUTS:
00135  *    NONE
00136  * OUTPUT:
00137  *    An empty CRMF Certificate Request Message.
00138  *    Before encoding this message, the user must set
00139  *    the ProofOfPossession field and the certificate 
00140  *    request which are necessary for the full message.
00141  *    After the user no longer needs this CertReqMsg,
00142  *    the user must call CRMF_DestroyCertReqMsg to free
00143  *    all memory associated with the Certificate Request
00144  *    Message.
00145  * RETURN:
00146  *    A pointer to a Certificate Request Message.  The user 
00147  *    must pass the return value of this function to 
00148  *    CRMF_DestroyCertReqMsg after the Certificate Request
00149  *    Message is no longer necessary.
00150  */
00151 extern CRMFCertReqMsg* CRMF_CreateCertReqMsg(void);
00152 
00153 /*
00154  * FUNCTION: CRMF_DestroyCertReqMsg
00155  * INPUTS:
00156  *    inCertReqMsg
00157  *        The Certificate Request Message to destroy.
00158  *  NOTES:
00159  *    This function frees all the memory used for the Certificate
00160  *    Request Message and all the memory used in making copies of
00161  *    fields of elelments of the message, eg. the Proof Of Possession
00162  *    filed and the Cetificate Request.  
00163  * RETURN:
00164  *    SECSuccess if destruction was successful.  Any other return value
00165  *    indicates an error while trying to free the memory associated
00166  *    with inCertReqMsg.
00167  *    
00168  */
00169 extern SECStatus CRMF_DestroyCertReqMsg(CRMFCertReqMsg *inCertReqMsg);
00170 
00171 /*
00172  * FUNCTION: CRMF_CertReqMsgSetCertRequest
00173  * INPUTS:
00174  *    inCertReqMsg
00175  *        The Certificate Request Message that the function will set
00176  *        the certificate request for.
00177  *    inCertReq
00178  *        The Certificate Request that will be added to the Certificate
00179  *        Request Message.
00180  * NOTES:
00181  *    This function will make a copy of the Certificate Request passed in
00182  *    and store it as part of the Certificate Request Message.  Therefore,
00183  *    the user must not call this function until the Certificate Request
00184  *    has been fully built and is ready to be encoded.
00185  * RETURN:
00186  *    SECSuccess 
00187  *        If copying the Certificate as a member of the Certificate
00188  *        request message was successful.
00189  *    Any other return value indicates a failure to copy the Certificate
00190  *    Request and make it a part of the Certificate Request Message.
00191  */
00192 extern SECStatus CRMF_CertReqMsgSetCertRequest(CRMFCertReqMsg  *inCertReqMsg, 
00193                                           CRMFCertRequest *inCertReq);
00194 
00195 /*
00196  * FUNCTION: CRMF_CreateCertRequest
00197  * INPUTS:
00198  *    inRequestID
00199  *        The ID that will be associated with this certificate request.
00200  * OUTPUTS:
00201  *    A certificate request which only has the requestID set.
00202  * NOTES:
00203  *    The user must call the function CRMF_DestroyCertRequest when
00204  *    the returned value is no longer needed.  This is usually the
00205  *    case after fully constructing the Certificate Request and then
00206  *    calling the function CRMF_CertReqMsgSetCertRequest.
00207  * RETURN:
00208  *    A pointer to the new Certificate Request.  A NULL return value
00209  *    indicates an error in creating the Certificate Request.
00210  */
00211 extern CRMFCertRequest *CRMF_CreateCertRequest (PRUint32 inRequestID);
00212 
00213 /*
00214  * FUNCTION: CRMF_DestroyCertRequest
00215  * INPUTS:
00216  *    inCertReq
00217  *        The Certificate Request that will be destroyed.
00218  * RETURN:
00219  *    SECSuccess
00220  *        If freeing the memory associated with the certificate request 
00221  *        was successful.
00222  *    Any other return value indicates an error while trying to free the 
00223  *    memory.
00224  */
00225 extern SECStatus CRMF_DestroyCertRequest (CRMFCertRequest *inCertReq);
00226 
00227 /*
00228  * FUNCTION: CRMF_CreateCertExtension
00229  * INPUTS:
00230  *    id
00231  *        The SECOidTag to associate with this CertExtension.  This must
00232  *        correspond to a valid Certificate Extension, if not the function
00233  *        will fail.
00234  *    isCritical
00235  *        A boolean value stating if the extension value is crtical.  PR_TRUE
00236  *        means the value is crtical.  PR_FALSE indicates the value is not 
00237  *        critical.
00238  *    data
00239  *        This is the data associated with the extension.  The user of the
00240  *        library is responsible for making sure the value passed in is a
00241  *        valid interpretation of the certificate extension.
00242  * NOTES:
00243  * Use this function to create CRMFCertExtension Structures which will 
00244  * then be passed to CRMF_AddFieldToCertTemplate as part of the 
00245  * CRMFCertCreationInfo.extensions  The user must call 
00246  * CRMF_DestroyCertExtension after the extension has been added to a certifcate
00247  * and the extension is no longer needed.
00248  *
00249  * RETURN:
00250  * A pointer to a newly created CertExtension.  A return value of NULL
00251  * indicates the id passed in was an invalid certificate extension.
00252  */
00253 extern CRMFCertExtension *CRMF_CreateCertExtension(SECOidTag      id, 
00254                                              PRBool         isCritical,
00255                                              SECItem       *data);
00256 
00257 /*
00258  * FUNCTION: CMRF_DestroyCertExtension
00259  * INPUTS:
00260  *    inExtension
00261  *        The Cert Extension to destroy
00262  * NOTES:
00263  * Destroy a structure allocated by CRMF_CreateCertExtension.
00264  *
00265  * RETURN:
00266  * SECSuccess if freeing the memory associated with the certificate extension
00267  * was successful.  Any other error indicates an error while freeing the 
00268  * memory.
00269  */
00270 extern SECStatus CRMF_DestroyCertExtension(CRMFCertExtension *inExtension);
00271 
00272 /* 
00273  * FUNCTION: CRMF_CertRequestSetTemplateField
00274  * INPUTS:
00275  *    inCertReq
00276  *        The Certificate Request to operate on.
00277  *    inTemplateField
00278  *        An enumeration that indicates which field of the Certificate
00279  *        template to add.
00280  *    data
00281  *        A generic pointer that will be type cast according to the
00282  *        table under NOTES and used as the key for adding to the
00283  *        certificate template;
00284  * NOTES:
00285  *
00286  * Below is a table that tells what type to pass in as data
00287  * depending on the template field one wants to set.
00288  *
00289  * Look in crmft.h for the definition of CRMFCertTemplateField.
00290  * 
00291  * In all cases, the library makes copies of the data passed in.
00292  *
00293  *   CRMFCertTemplateField    Type of data    What data means
00294  *   ---------------------    ------------    ---------------
00295  *   crmfVersion              long *          The version of
00296  *                                            the certificate
00297  *                                            to be created.
00298  *
00299  *   crmfSerialNumber         long *          The serial number
00300  *                                            for the cert to be
00301  *                                            created.
00302  *   
00303  *   crmfSigningAlg           SECAlgorithm *  The ASN.1 object ID for
00304  *                                            the algorithm used in encoding
00305  *                                            the certificate.
00306  *
00307  *   crmfIssuer               CERTName *      Certificate Library 
00308  *                                            representation of the ASN1 type
00309  *                                            Name from X.509
00310  *
00311  *   crmfValidity     CRMFValidityCreationInfo *  At least one of the two
00312  *                                                fields in the structure must
00313  *                                                be present.  A NULL pointer 
00314  *                                                in the structure indicates
00315  *                                                that member should not be 
00316  *                                                added.
00317  *
00318  *   crmfSubject              CERTName *      Certificate Library 
00319  *                                            representation of the ASN1 type
00320  *                                            Name from X.509
00321  *
00322  *   crmfPublicKey    CERTSubjectPublicKeyInfo *  The public key info for the
00323  *                                                certificate being requested.
00324  *
00325  *   crmfIssuerUID            SECItem *           A bit string representation
00326  *                                                of the issuer UID. NOTE: The
00327  *                                                length is the number of bits
00328  *                                                and not the number of bytes.
00329  *
00330  *   crmfSubjectUID           SECItem*            A bit string representation
00331  *                                                of the subject UID. NOTE: The
00332  *                                                length is the number of bits
00333  *                                                and not the number of bytes.
00334  *
00335  *   crmfExtension   CRMFCertExtCreationInfo *     A pointer to the structure
00336  *                                                 populated with an array of 
00337  *                                                 of certificate extensions
00338  *                                                 and an integer that tells
00339  *                                                 how many elements are in the
00340  *                                                 array. Look in crmft.h for
00341  *                                                 the definition of 
00342  *                                                 CRMFCertExtCreationInfo
00343  * RETURN:
00344  *    SECSuccess if adding the desired field to the template was successful.
00345  *    Any other return value indicates failure when trying to add the field 
00346  *    to the template.
00347  *                                                
00348  */
00349 extern SECStatus
00350   CRMF_CertRequestSetTemplateField(CRMFCertRequest       *inCertReq, 
00351                                CRMFCertTemplateField  inTemplateField,
00352                                void                  *data);
00353 
00354 /*
00355  * FUNCTION: CRMF_CertRequestIsFieldPresent
00356  * INPUTS:
00357  *    inCertReq
00358  *        The certificate request to operate on.
00359  *    inTemplateField
00360  *        The enumeration for the template field the user wants to query
00361  *        about.
00362  * NOTES:
00363  * This function checks to see if the the field associated with inTemplateField
00364  * enumeration is already present in the certificate request passed in.
00365  *
00366  * RETURN:
00367  * The function returns PR_TRUE if the field associated with inTemplateField
00368  * is already present in the certificate request.  If the field is not present
00369  * the function returns PR_FALSE.
00370  */
00371 extern PRBool
00372   CRMF_CertRequestIsFieldPresent(CRMFCertRequest       *inCertReq,
00373                              CRMFCertTemplateField  inTemplateField);
00374 
00375 /*
00376  * FUNCTION: CRMF_CertRequestIsControlPresent
00377  * INPUTS:
00378  *    inCertReq
00379  *        The certificate request to operate on.
00380  *    inControlType
00381  *        The type of control to look for.
00382  * NOTES:
00383  * This function looks at the control present in the certificate request
00384  * and returns PR_TRUE iff a control of type inControlType already exists.
00385  * The CRMF draft does not explicitly state that two controls of the same
00386  * type can not exist within the same request.  So the library will not
00387  * cause an error if you try to add a control and one of the same type
00388  * already exists.  It is up to the application to ensure that multiple
00389  * controls of the same type do not exist, if that is the desired behavior
00390  * by the application.
00391  *
00392  * RETURN:
00393  * The function returns PR_TRUE if a control of type inControlType already
00394  * exists in the certificate request.  If a control of type inControlType
00395  * does not exist, the function will return PR_FALSE.
00396  */
00397 extern PRBool
00398   CRMF_CertRequestIsControlPresent(CRMFCertRequest *inCertReq,
00399                                CRMFControlType  inControlType);
00400                                
00401 
00402 /*
00403  * FUNCTION: CRMF_CertRequestSetRegTokenControl
00404  * INPUTS:
00405  *    inCertReq
00406  *        The Certificate Request to operate on.
00407  *    value
00408  *        The UTF8 value which will be the Registration Token Control
00409  *        for this Certificate Request.
00410  * NOTES:
00411  *    The library does no verification that the value passed in is 
00412  *    a valid UTF8 value.  The caller must make sure of this in order
00413  *    to get an encoding that is valid.  The library will ultimately
00414  *    encode this value as it was passed in.
00415  * RETURN:
00416  *    SECSucces on successful addition of the Registration Token Control.
00417  *    Any other return value indicates an unsuccessful attempt to add the
00418  *    control.
00419  *
00420  */
00421 extern SECStatus CRMF_CertRequestSetRegTokenControl(CRMFCertRequest *inCertReq,
00422                                               SECItem         *value);
00423 
00424 /*
00425  * FUNCTION: CRMF_CertRequestSetAuthenticatorControl
00426  * INPUTS:
00427  *    inCertReq
00428  *        The Certificate Request to operate on.
00429  *    value
00430  *        The UTF8 value that will become the Authenticator Control
00431  *        for the passed in Certificate Request.
00432  * NOTES:
00433  *    The library does no verification that the value passed in is 
00434  *    a valid UTF8 value.  The caller must make sure of this in order
00435  *    to get an encoding that is valid.  The library will ultimately
00436  *    encode this value as it was passed in.
00437  * RETURN:
00438  *    SECSucces on successful addition of the Authenticator Control.
00439  *    Any other return value indicates an unsuccessful attempt to add the
00440  *    control.
00441  */
00442 extern SECStatus 
00443        CRMF_CertRequestSetAuthenticatorControl (CRMFCertRequest *inCertReq,
00444                                           SECItem         *value);
00445 
00446 /*
00447  * FUNCTION: CRMF_CreateEncryptedKeyWithencryptedValue
00448  * INPUTS:
00449  *    inPrivKey
00450  *        This is the private key associated with a certificate that is
00451  *        being requested.  This structure will eventually wind up as 
00452  *        a part of the PKIArchiveOptions Control.  
00453  *    inCACert
00454  *        This is the certificate for the CA that will be receiving the 
00455  *        certificate request for the private key passed in.
00456  * OUTPUT:
00457  *    A CRMFEncryptedKey that can ultimately be used as part of the 
00458  *    PKIArchiveOptions Control.
00459  *
00460  * RETURN:
00461  *    A pointer to a CRMFEncyptedKey.  A NULL return value indicates an erro
00462  *    during the creation of the encrypted key.
00463  */
00464 extern CRMFEncryptedKey* 
00465        CRMF_CreateEncryptedKeyWithEncryptedValue(SECKEYPrivateKey *inPrivKey,
00466                                            CERTCertificate  *inCACert);
00467 
00468 /*
00469  * FUNCTION: CRMF_DestroyEncryptedKey
00470  * INPUTS:
00471  *    inEncrKey
00472  *        The CRMFEncryptedKey to be destroyed.
00473  * NOTES:
00474  *    Frees all memory associated with the CRMFEncryptedKey passed in.
00475  * RETURN:
00476  *    SECSuccess if freeing the memory was successful.  Any other return
00477  *    value indicates an error while freeig the memroy.
00478  */
00479 extern SECStatus CRMF_DestroyEncryptedKey(CRMFEncryptedKey *inEncrKey);
00480                                           
00481 /*
00482  * FUNCTION: CRMF_CreatePKIArchiveOptions
00483  * INPUTS:
00484  *    inType
00485  *        An enumeration value indicating which option for 
00486  *        PKIArchiveOptions to use.
00487  *    data
00488  *        A pointer that will be type-cast and de-referenced according
00489  *        to the table under NOTES.
00490  * NOTES:
00491  * A table listing what should be passed in as data
00492  * ------------------------------------------------
00493  *
00494  * inType                            data
00495  * ------                            ----
00496  * crmfEncryptedPrivateKey           CRMFEncryptedKey*
00497  * crmfKeyGenParameters              SECItem*(This needs to be an octet string)
00498  * crmfArchiveRemGenPrivKey          PRBool*
00499  *
00500  * RETURN:
00501  *    A pointer the a CRMFPKIArchiveOptions that can be added to a Certificate
00502  *    Request.  A NULL pointer indicates an error occurred while creating
00503  *    the CRMFPKIArchiveOptions Structure.
00504  */
00505 extern CRMFPKIArchiveOptions*
00506        CRMF_CreatePKIArchiveOptions(CRMFPKIArchiveOptionsType  inType,
00507                                 void                      *data);
00508 /*
00509  * FUNCTION: CRMF_DestroyPKIArchiveOptions
00510  * INPUTS:
00511  *    inArchOpt
00512  *        A pointer to the CRMFPKIArchiveOptions structure to free.
00513  * NOTES:
00514  *    Will free all memory associated with 'inArchOpt'.
00515  * RETURN:
00516  *    SECSuccess if successful in freeing the memory used by 'inArchOpt'
00517  *    Any other return value indicates an error while freeing the memory.
00518  */
00519 extern SECStatus 
00520        CRMF_DestroyPKIArchiveOptions(CRMFPKIArchiveOptions *inArchOpt);
00521 
00522 /*
00523  * FUNCTION: CRMF_CertRequestSetPKIArchiveOptions
00524  * INPUTS:
00525  *    inCertReq
00526  *        The Certificate Request to add the the options to.
00527  *    inOptions
00528  *        The Archive Options to add to the Certificate Request.
00529  * NOTES:
00530  *    Adds the PKIArchiveOption to the Certificate Request.  This is what
00531  *    enables Key Escrow to take place through CRMF.  The library makes
00532  *    its own copy of the information.
00533  * RETURN:
00534  *    SECSuccess if successful in adding the ArchiveOptions to the Certificate
00535  *    request.  Any other return value indicates an error when trying to add
00536  *    the Archive Options  to the Certificate Request.
00537  */
00538 extern SECStatus 
00539        CRMF_CertRequestSetPKIArchiveOptions(CRMFCertRequest       *inCertReq,
00540                                        CRMFPKIArchiveOptions *inOptions);
00541 
00542 /*
00543  * FUNCTION: CRMF_CertReqMsgGetPOPType
00544  * INPUTS:
00545  *    inCertReqMsg
00546  *        The Certificate Request Message to operate on.
00547  * NOTES:
00548  *    Returns an enumeration value indicating the method of Proof
00549  *    of Possession that was used for the passed in Certificate Request
00550  *    Message.
00551  * RETURN:
00552  *    An enumeration indicating what method for Proof Of Possession is
00553  *    being used in this Certificate Request Message.  Look in the file
00554  *    crmft.h for the definition of CRMFPOPChoice for the possible return
00555  *    values.
00556  */
00557 extern CRMFPOPChoice CRMF_CertReqMsgGetPOPType(CRMFCertReqMsg *inCertReqMsg);
00558 
00559 /*
00560  * FUNCTION: CRMF_CertReqMsgSetRAVerifiedPOP
00561  * INPUT:
00562  *    InCertReqMsg
00563  *        The Certificate Request Message to operate on.
00564  * NOTES:
00565  *    This function will set the method of Proof Of Possession to 
00566  *    crmfRAVerified which means the RA has already verified the 
00567  *    requester does possess the private key.
00568  * RETURN:
00569  *    SECSuccess if adding RAVerified to the message is successful.  
00570  *    Any other message indicates an error while trying to add RAVerified
00571  *    as the Proof of Possession.
00572  */
00573 extern SECStatus CRMF_CertReqMsgSetRAVerifiedPOP(CRMFCertReqMsg *inCertReqMsg);
00574 
00575 /*
00576  * FUNCTION: CRMF_CertReqMsgSetSignaturePOP
00577  * INPUT:
00578  *    inCertReqMsg
00579  *        The Certificate Request Message to add the SignaturePOP to.
00580  *    inPrivKey
00581  *        The Private Key which corresponds to the the Certificate Request
00582  *        Message.
00583  *    inPubKey
00584  *        The Public Key which corresponds to the Private Key passed in.
00585  *    inCertForInput
00586  *        A Certificate that in the future may be used to create 
00587  *        POPOSigningKeyInput.
00588  *    fn
00589  *        A callback for retrieving a password which may be used in the
00590  *       future to generate POPOSigningKeyInput.
00591  *    arg
00592  *        An opaque pointer that would be passed to fn whenever it is
00593  *        called.
00594  * NOTES:
00595  * Adds Proof Of Possession to the CertRequest using the signature field 
00596  * of the ProofOfPossession field.  NOTE: In order to use this option, 
00597  * the certificate template must contain the publicKey at the very minimum.
00598  * 
00599  * If you don't want the function to generate POPOSigningKeyInput, then
00600  * make sure the cert template already contains the subject and public key
00601  * values.  Currently creating POPOSigningKeyInput is not supported, so 
00602  * a Message passed to this function must have the publicKey and the subject
00603  * as part of the template
00604  *
00605  * This will take care of creating the entire POPOSigningKey structure
00606  * that will become part of the message.
00607  *
00608  * inPrivKey is the key to be used in the signing operation when creating
00609  * POPOSigningKey structure.  This should be the key corresponding to
00610  * the certificate being requested.
00611  *
00612  * inCertForInput will be used if POPOSigningKeyInput needs to be generated.
00613  * It will be used in generating the authInfo.sender field.  If the parameter
00614  * is not passed in then authInfo.publicKeyMAC will be generated instead.
00615  * If passed in, this certificate needs to be a valid certificate.
00616  *
00617  * The last 3 arguments are for future compatibility in case we ever want to
00618  * support generating POPOSigningKeyInput.  Pass in NULL for all 3 if you 
00619  * definitely don't want the funciton to even try to generate 
00620  * POPOSigningKeyInput.  If you try to use POPOSigningKeyInput, the function
00621  * will fail.
00622  *
00623  * RETURN:
00624  *    SECSuccess if adding the Signature Proof Of Possession worked.
00625  *    Any other return value indicates an error in trying to add
00626  *    the Signature Proof Of Possession.
00627  */
00628 extern SECStatus 
00629        CRMF_CertReqMsgSetSignaturePOP(CRMFCertReqMsg   *inCertReqMsg,
00630                                   SECKEYPrivateKey *inPrivKey,
00631                                   SECKEYPublicKey  *inPubKey,
00632                                   CERTCertificate  *inCertForInput,
00633                                   CRMFMACPasswordCallback  fn,
00634                                   void                    *arg);
00635 
00636 /*
00637  * FUNCTION: CRMF_CertReqMsgSetKeyEnciphermentPOP
00638  * INPUTS:
00639  *    inCertReqMsg
00640  *        The Certificate Request Message to operate on.
00641  *    inKeyChoice
00642  *        An enumeration indicating which POPOPrivKey Choice to use
00643  *        in constructing the KeyEnciphermentPOP.
00644  *    subseqMess
00645  *        This parameter must be provided iff inKeyChoice is 
00646  *        crmfSubsequentMessage.  This details how the RA is to respond
00647  *        in order to perform Proof Of Possession.  Look in crmft.h under
00648  *        the definition of CRMFSubseqMessOptions for possible values.
00649  *    encPrivKey
00650  *        This parameter only needs to be provided if inKeyChoice is
00651  *        crmfThisMessage.  The item should contain the encrypted private
00652  *        key.
00653  *        
00654  * NOTES:
00655  * Adds Proof Of Possession using the keyEncipherment field of
00656  * ProofOfPossession.
00657  *
00658  * The funciton looks at the the inKeyChoice parameter and interprets it in
00659  * in the following manner.
00660  *
00661  * If a parameter is not mentioned under interpretation, the funciton will not
00662  * look at its value when implementing that case.
00663  *
00664  * inKeyChoice          Interpretation
00665  * -----------          --------------
00666  * crmfThisMessage      This options requires that the encrypted private key
00667  *                      be included in the thisMessage field of POPOPrivKey.
00668  *                      We don't support this yet, so any clients who want
00669  *                      to use this feature have to implement a wrapping
00670  *                      function and agree with the server on how to properly
00671  *                      wrap the key.  That encrypted key must be passed in
00672  *                      as the encPrivKey parameter.
00673  *
00674  * crmfSubequentMessage Must pass in a value for subseqMess.  The value must
00675  *                      be either CRMFEncrCert or CRMFChallengeResp.  The
00676  *                      parameter encPrivKey will not be looked at in this
00677  *                      case.
00678  *
00679  * crmfDHMAC            This is not a valid option for this function.  Passing
00680  *                      in this value will result in the function returning
00681  *                      SECFailure.
00682  * RETURN:
00683  *    SECSuccess if adding KeyEnciphermentPOP was successful.  Any other return
00684  *    value indicates an error in adding KeyEnciphermentPOP.
00685  */
00686 extern SECStatus 
00687       CRMF_CertReqMsgSetKeyEnciphermentPOP(CRMFCertReqMsg        *inCertReqMsg,
00688                                       CRMFPOPOPrivKeyChoice  inKeyChoice,
00689                                       CRMFSubseqMessOptions  subseqMess,
00690                                       SECItem               *encPrivKey);
00691 
00692 /*
00693  * FUNCTION: CRMF_CertReqMsgSetKeyAgreementPOP
00694  * INPUTS:
00695  *    inCertReqMsg
00696  *        The Certificate Request Message to operate on.
00697  *    inKeyChoice
00698  *        An enumeration indicating which POPOPrivKey Choice to use
00699  *        in constructing the KeyAgreementPOP.
00700  *    subseqMess
00701  *        This parameter must be provided iff inKeyChoice is 
00702  *        crmfSubsequentMessage.  This details how the RA is to respond
00703  *        in order to perform Proof Of Possession.  Look in crmft.h under
00704  *        the definition of CRMFSubseqMessOptions for possible values.
00705  *    encPrivKey
00706  *        This parameter only needs to be provided if inKeyChoice is
00707  *        crmfThisMessage.  The item should contain the encrypted private
00708  *        key.
00709  * Adds Proof Of Possession using the keyAgreement field of
00710  * ProofOfPossession.
00711  *
00712  * The funciton looks at the the inKeyChoice parameter and interprets it in
00713  * in the following manner.
00714  *
00715  * If a parameter is not mentioned under interpretation, the funciton will not
00716  * look at its value when implementing that case.
00717  *
00718  * inKeyChoice          Interpretation
00719  * -----------          --------------
00720  * crmfThisMessage      This options requires that the encrypted private key
00721  *                      be included in the thisMessage field of POPOPrivKey.
00722  *                      We don't support this yet, so any clients who want
00723  *                      to use this feature have to implement a wrapping
00724  *                      function and agree with the server on how to properly
00725  *                      wrap the key.  That encrypted key must be passed in
00726  *                      as the encPrivKey parameter.
00727  *
00728  * crmfSubequentMessage Must pass in a value for subseqMess.  The value must
00729  *                      be either crmfEncrCert or crmfChallengeResp.  The
00730  *                      parameter encPrivKey will not be looked at in this
00731  *                      case.
00732  *
00733  * crmfDHMAC            This option is not supported.
00734  */
00735 extern SECStatus 
00736        CRMF_CertReqMsgSetKeyAgreementPOP(CRMFCertReqMsg        *inCertReqMsg,
00737                                     CRMFPOPOPrivKeyChoice  inKeyChoice,
00738                                     CRMFSubseqMessOptions  subseqMess,
00739                                     SECItem               *encPrivKey);
00740 
00741 /*
00742  * FUNCTION: CRMF_CreateCertReqMsgFromDER
00743  * INPUTS:
00744  *    buf
00745  *        A buffer to the DER-encoded Certificate Request Message.
00746  *    len
00747  *        The length in bytes of the buffer 'buf'
00748  * NOTES:
00749  * This function passes the buffer to the ASN1 decoder and creates a 
00750  * CRMFCertReqMsg structure.  Do not try adding any fields to a message
00751  * returned from this function.  Specifically adding more Controls or 
00752  * Extensions may cause your program to crash.
00753  *
00754  * RETURN:
00755  *    A pointer to the Certificate Request Message structure.  A NULL return
00756  *    value indicates the library was unable to parse the DER.
00757  */
00758 extern CRMFCertReqMsg* CRMF_CreateCertReqMsgFromDER(const char *buf, long len);
00759 
00760 /*
00761  * FUNCTION: CRMF_CreateCertReqMessagesFromDER
00762  * INPUTS:
00763  *    buf
00764  *        A buffer to the DER-encoded Certificate Request Messages.
00765  *    len
00766  *        The length in bytes of buf
00767  * NOTES:
00768  * This function passes the buffer to the ASN1 decoder and creates a 
00769  * CRMFCertReqMessages structure.  Do not try adding any fields to a message
00770  * derived from this function.  Specifically adding more Controls or 
00771  * Extensions may cause your program to crash.
00772  * The user must call CRMF_DestroyCertReqMessages after the return value is 
00773  * no longer needed, ie when all individual messages have been extracted.
00774  *  
00775  * RETURN:
00776  *    A pointer to the Certificate Request Messages structure.  A NULL return
00777  *    value indicates the library was unable to parse the DER.
00778  */ 
00779 extern CRMFCertReqMessages*
00780        CRMF_CreateCertReqMessagesFromDER(const char *buf, long len);
00781 
00782 /*
00783  * FUNCTION: CRMF_DestroyCertReqMessages
00784  * INPUTS
00785  *    inCertReqMsgs
00786  *        The Messages to destroy.
00787  * RETURN:
00788  *    SECSuccess if freeing the memory was done successfully.  Any other
00789  *    return value indicates an error in freeing up memory.
00790  */ 
00791 extern SECStatus 
00792        CRMF_DestroyCertReqMessages(CRMFCertReqMessages *inCertReqMsgs);
00793 
00794 /*
00795  * FUNCTION: CRMF_CertReqMessagesGetNumMessages
00796  * INPUTS:
00797  *    inCertReqMsgs
00798  *        The Request Messages to operate on.
00799  * RETURN:
00800  *    The number of messages contained in the in the Request Messages 
00801  *    strucure.
00802  */
00803 extern int 
00804        CRMF_CertReqMessagesGetNumMessages(CRMFCertReqMessages *inCertReqMsgs);
00805 
00806 /*
00807  * FUNCTION: CRMF_CertReqMessagesGetCertReqMsgAtIndex
00808  * INPUTS:
00809  *    inReqMsgs
00810  *        The Certificate Request Messages to operate on.
00811  *    index
00812  *        The index of the single message the user wants a copy of.
00813  * NOTES:
00814  * This function returns a copy of the request messages stored at the 
00815  * index corresponding to the parameter 'index'.  Indexing of the messages
00816  * is done in the same manner as a C array.  Meaning the valid index are 
00817  * 0...numMessages-1.  User must call CRMF_DestroyCertReqMsg when done using
00818  * the return value of this function.
00819  *
00820  * RETURN:
00821  * SECSuccess if copying the message at the requested index was successful.
00822  * Any other return value indicates an invalid index or error while copying
00823  * the single request message.
00824  */
00825 extern CRMFCertReqMsg*
00826        CRMF_CertReqMessagesGetCertReqMsgAtIndex(CRMFCertReqMessages *inReqMsgs,
00827                                           int                  index);
00828 
00829 
00830 /*
00831  * FUNCTION: CRMF_CertReqMsgGetID
00832  * INPUTS:
00833  *    inCertReqMsg
00834  *        The Certificate Request Message to get the ID from.
00835  *    destID
00836  *        A pointer to where the library can place the ID of the Message.
00837  * RETURN:
00838  *    SECSuccess if the function was able to retrieve the ID and place it
00839  *    at *destID.  Any other return value indicates an error meaning the value
00840  *    in *destId is un-reliable and should not be used by the caller of this 
00841  *    function.
00842  *    
00843  */
00844 extern SECStatus CRMF_CertReqMsgGetID(CRMFCertReqMsg *inCertReqMsg, 
00845                                   long           *destID);
00846 
00847 /*
00848  * FUNCTION: CRMF_DoesRequestHaveField
00849  * INPUTS:
00850  *    inCertReq
00851  *        The Certificate Request to operate on.
00852  *    inField
00853  *        An enumeration indicating which filed of the certificate template
00854  *        to look for.
00855  * NOTES:
00856  * All the fields in a certificate template are optional.  This function
00857  * checks to see if the requested field is present.  Look in crmft.h at the
00858  * definition of CRMFCertTemplateField for possible values for possible 
00859  * querying.
00860  *
00861  * RETURN:
00862  * PR_TRUE iff the field corresponding to 'inField' has been specified as part
00863  *         of 'inCertReq'
00864  * PR_FALSE iff the field corresponding to 'inField' has not been speicified
00865  *          as part of 'inCertReq'
00866  *        
00867  */
00868 extern PRBool CRMF_DoesRequestHaveField(CRMFCertRequest       *inCertReq,
00869                                    CRMFCertTemplateField  inField);
00870 
00871 /*
00872  * FUNCTION: CRMF_CertReqMsgGetCertRequest
00873  * INPUTS:
00874  *    inCertReqMsg
00875  *        The Certificate Request Message to operate on.
00876  * NOTES:
00877  *    This function returns a copy of the Certificate Request to the user.
00878  *    The user can keep adding to this request and then making it a part
00879  *    of another message.  After the user no longer wants to use the
00880  *    returned request, the user must call CRMF_DestroyCertRequest and
00881  *    pass it the request returned by this function.
00882  * RETURN:
00883  *    A pointer to a copy of the certificate request contained by the message.
00884  *    A NULL return value indicates an error occurred while copying the 
00885  *   certificate request.
00886  */
00887 extern CRMFCertRequest *
00888        CRMF_CertReqMsgGetCertRequest(CRMFCertReqMsg *inCertReqMsg);
00889 
00890 /*
00891  * FUNCTION: CRMF_CertRequestGetCertTemplateVersion
00892  * INPUTS:
00893  *    inCertReq
00894  *        The Certificate Request to operate on.
00895  *    version
00896  *        A pointer to where the library can store the version contatined
00897  *        in the certificate template within the certifcate request.
00898  * RETURN:
00899  *    SECSuccess if the Certificate template contains the version field.  In 
00900  *    this case, *version will hold the value of the certificate template 
00901  *    version.
00902  *    SECFailure indicates that version field was not present as part of
00903  *    of the certificate template.
00904  */
00905 extern SECStatus 
00906        CRMF_CertRequestGetCertTemplateVersion(CRMFCertRequest *inCertReq, 
00907                                          long            *version);
00908 
00909 /*
00910  * FUNCTION: CRMF_CertRequestGetCertTemplateSerialNumber
00911  * INPUTS:
00912  *    inCertReq
00913  *        The certificate request to operate on.
00914  *    serialNumber
00915  *        A pointer where the library can put the serial number contained
00916  *        in the certificate request's certificate template.
00917  * RETURN:
00918  * If a serial number exists in the CertTemplate of the request, the function 
00919  * returns SECSuccess and the value at *serialNumber contains the serial 
00920  * number.
00921  * If no serial number is present, then the function returns SECFailure and
00922  * the value at *serialNumber is un-changed.
00923  */
00924 extern SECStatus 
00925        CRMF_CertRequestGetCertTemplateSerialNumber(CRMFCertRequest *inCertReq, 
00926                                              long         *serialNumber);
00927 
00928 /*
00929  * FUNCTION: CRMF_CertRequestGetCertTemplateSigningAlg
00930  * INPUT:
00931  *    inCertReq
00932  *        The Certificate Request to operate on.
00933  *    destAlg
00934  *        A Pointer to where the library can place a copy of the signing alg
00935  *        used in the cert request's cert template.
00936  * RETURN:
00937  * If the signingAlg is present in the CertRequest's CertTemplate, then
00938  * the function returns SECSuccess and places a copy of sigingAlg in 
00939  * *destAlg.
00940  * If no signingAlg is present, then the function returns SECFailure and
00941  * the value at *destAlg is un-changed
00942  */
00943 extern SECStatus 
00944        CRMF_CertRequestGetCertTemplateSigningAlg(CRMFCertRequest *inCertReq,
00945                                            SECAlgorithmID  *destAlg);
00946 /*
00947  * FUNCTION: CRMF_CertRequestGetCertTemplateIssuer
00948  * INPUTS:
00949  *    inCertReq
00950  *        The Certificate Request to operate on.
00951  *    destIssuer
00952  *        A pointer to where the library can place a copy of the cert
00953  *        request's cert template issuer field.
00954  * RETURN:
00955  * If the issuer is present in the cert request cert template, the function 
00956  * returns SECSuccess and places a  copy of the issuer in *destIssuer.
00957  * If there is no issuer present, the funciton returns SECFailure and the
00958  * value at *destIssuer is unchanged.
00959  */
00960 extern SECStatus 
00961        CRMF_CertRequestGetCertTemplateIssuer(CRMFCertRequest *inCertReq,
00962                                         CERTName        *destIssuer);
00963 
00964 /*
00965  * FUNCTION: CRMF_CertRequestGetCertTemplateValidity
00966  * INPUTS:
00967  *    inCertReq
00968  *        The Certificate Request to operate on.
00969  *    destValdity
00970  *        A pointer to where the library can place a copy of the validity
00971  *        info in the cert request cert template.
00972  * NOTES:
00973  * Pass the pointer to 
00974  * RETURN: 
00975  * If there is an OptionalValidity field, the function will return SECSuccess
00976  * and place the appropriate values in *destValidity->notBefore and 
00977  * *destValidity->notAfter. (Each field is optional, but at least one will
00978  * be present if the function returns SECSuccess)
00979  *
00980  * If there is no OptionalValidity field, the function will return SECFailure
00981  * and the values at *destValidity will be un-changed.
00982  */
00983 extern SECStatus 
00984        CRMF_CertRequestGetCertTemplateValidity(CRMFCertRequest *inCertReq,
00985                                           CRMFGetValidity *destValidity);
00986 /*
00987  * FUNCTION: CRMF_DestroyGetValidity
00988  * INPUTS:
00989  *    inValidity
00990  *        A pointer to the memroy to be freed.
00991  * NOTES:
00992  * The function will free the memory allocated by the function 
00993  * CRMF_CertRequestGetCertTemplateValidity.  That means only memory pointed
00994  * to within the CRMFGetValidity structure.  Since 
00995  * CRMF_CertRequestGetCertTemplateValidity does not allocate memory for the
00996  * structure passed into it, it will not free it.  Meaning this function will
00997  * free the memory at inValidity->notBefore and inValidity->notAfter, but not
00998  * the memory directly at inValdity.
00999  *
01000  * RETURN:
01001  * SECSuccess if freeing the memory was successful.  Any other return value
01002  * indicates an error while freeing the memory.
01003  */
01004 extern SECStatus 
01005        CRMF_DestroyGetValidity(CRMFGetValidity *inValidity);
01006 
01007 /*
01008  * FUNCTION: CRMF_CertRequestGetCertTemplateSubject
01009  * INPUTS:
01010  *    inCertReq
01011  *        The Certificate Request to operate on.
01012  *    destSubject
01013  *        A pointer to where the library can place a copy of the subject
01014  *        contained in the request's cert template.
01015  * RETURN:
01016  * If there is a subject in the CertTemplate, then the function returns 
01017  * SECSuccess and a copy of the subject is placed in *destSubject.
01018  *
01019  * If there is no subject, the function returns SECFailure and the values at
01020  * *destSubject is unchanged.
01021  */
01022 extern SECStatus 
01023        CRMF_CertRequestGetCertTemplateSubject (CRMFCertRequest *inCertReq,
01024                                           CERTName        *destSubject);
01025 
01026 /*
01027  * FUNCTION: CRMF_CertRequestGetCertTemplatePublicKey
01028  * INPUTS:
01029  *    inCertReq
01030  *        The Cert request to operate on.
01031  *    destPublicKey
01032  *        A pointer to where the library can place a copy of the request's
01033  *        cert template public key.
01034  * RETURN:
01035  * If there is a publicKey parameter in the CertRequest, the function returns
01036  * SECSuccess, and places a copy of the publicKey in *destPublicKey.
01037  *
01038  * If there is no publicKey, the function returns SECFailure and the value
01039  * at *destPublicKey is un-changed.
01040  */
01041 extern SECStatus 
01042        CRMF_CertRequestGetCertTemplatePublicKey(CRMFCertRequest *inCertReq,
01043                                   CERTSubjectPublicKeyInfo *destPublicKey);
01044 
01045 /*
01046  * FUNCTION: CRMF_CertRequestGetCertTemplateIssuerUID
01047  * INPUTS:
01048  *    inCertReq
01049  *        The Cert request to operate on.
01050  *    destIssuerUID
01051  *        A pointer to where the library can store a copy of the request's
01052  *        cert template destIssuerUID.
01053  *
01054  * NOTES: 
01055  * destIssuerUID is a bit string and will be returned in a SECItem as
01056  * a bit string.  Meaning the len field contains the number of valid bits as
01057  * opposed to the number of bytes allocated.
01058  *
01059  * RETURN:
01060  * If the CertTemplate has an issuerUID, the function returns SECSuccess and
01061  * places a copy of the issuerUID in *destIssuerUID.
01062  *
01063  * If there is no issuerUID, the function returns SECFailure and the value
01064  * *destIssuerUID is unchanged.
01065  */
01066 extern SECStatus 
01067        CRMF_CertRequestGetCertTemplateIssuerUID(CRMFCertRequest *inCertReq,
01068                                           SECItem        *destIssuerUID);
01069 
01070 /*
01071  * FUNCTION: CRMF_CertRequestGetCertTemplateSubjectUID
01072  *    inCertReq
01073  *        The Cert request to operate on.
01074  *    destSubjectUID
01075  *        A pointer to where the library can store a copy of the request's
01076  *        cert template destIssuerUID.
01077  *
01078  * NOTES: 
01079  * destSubjectUID is a bit string and will be returned in a SECItem as
01080  * a bit string.  Meaning the len field contains the number of valid bits as
01081  * opposed to the number of bytes allocated.
01082  *
01083  * RETURN:
01084  * If the CertTemplate has an issuerUID, the function returns SECSuccess and
01085  * places a copy of the issuerUID in *destIssuerUID.
01086  *
01087  * If there is no issuerUID, the function returns SECSuccess and the value
01088  * *destIssuerUID is unchanged.
01089  */
01090 extern SECStatus CRMF_GetCertTemplateSubjectUID(CRMFCertRequest *inCertReq,
01091                                           SECItem       *destSubjectUID);
01092 
01093 /*
01094  * FUNCTION: CRMF_CertRequestGetNumberOfExtensions
01095  * INPUTS:
01096  *    inCertReq
01097  *        The cert request to operate on.
01098  * RETURN:
01099  *    Returns the number of extensions contained by the Cert Request.
01100  */
01101 extern int CRMF_CertRequestGetNumberOfExtensions(CRMFCertRequest *inCertReq);
01102 
01103 /*
01104  * FUNCTION: CRMF_CertRequestGetExtensionAtIndex
01105  * INPUTS:
01106  *    inCertReq
01107  *        The Certificate request to operate on.
01108  *    index
01109  *        The index of the extension array whihc the user wants to access.
01110  * NOTES:
01111  * This function retrieves the extension at the index corresponding to the 
01112  * parameter "index" indicates.  Indexing is done like a C array.  
01113  * (0 ... numElements-1)
01114  *
01115  * Call CRMF_DestroyCertExtension when done using the return value.
01116  *
01117  * RETURN:
01118  *    A pointer to a copy of the extension at the desired index.  A NULL 
01119  *    return value indicates an invalid index or an error while copying 
01120  *    the extension.
01121  */
01122 extern CRMFCertExtension *
01123        CRMF_CertRequestGetExtensionAtIndex(CRMFCertRequest *inCertReq,
01124                                       int              index);
01125 /*
01126  * FUNCTION: CRMF_CertExtensionGetOidTag
01127  * INPUTS:
01128  *    inExtension
01129 
01130  *        The extension to operate on.
01131  * RETURN:
01132  *    Returns the SECOidTag associated with the cert extension passed in.
01133  */
01134 extern SECOidTag CRMF_CertExtensionGetOidTag(CRMFCertExtension *inExtension);
01135 
01136 /*
01137  * FUNCTION: CRMF_CertExtensionGetIsCritical
01138  * INPUT:
01139  *    inExt
01140  *        The cert extension to operate on.
01141  *
01142  * RETURN:
01143  * PR_TRUE if the extension is critical.
01144  * PR_FALSE if the extension is not critical.
01145  */
01146 extern PRBool CRMF_CertExtensionGetIsCritical(CRMFCertExtension *inExt);
01147              
01148 /*
01149  * FUNCTION: CRMF_CertExtensionGetValue
01150  * INPUT:
01151  *    inExtension
01152  *        The extension to operate on.
01153  * NOTES:
01154  * Caller is responsible for freeing the memory associated with the return
01155  * value.  Call SECITEM_FreeItem(retVal, PR_TRUE) when done using the return
01156  * value.
01157  *
01158  * RETURN:
01159  * A pointer to an item containig the value for the certificate extension.
01160  * A NULL return value indicates an error in copying the information.
01161  */
01162 extern SECItem*  CRMF_CertExtensionGetValue(CRMFCertExtension *inExtension);
01163 
01164 /*
01165  * FUNCTION: CRMF_CertReqMsgGetPOPOSigningKey
01166  * INPUTS:
01167  *    inCertReqMsg
01168  *        The certificate request message to operate on.
01169  *    destKey
01170  *        A pointer to where the library can place a pointer to
01171  *        a copy of the Proof Of Possession Signing Key used 
01172  *        by the message.
01173  *
01174  * RETURN:
01175  * Get the POPOSigningKey associated with this CRMFCertReqMsg.  
01176  * If the CertReqMsg does not have a pop, the function returns
01177  * SECFailure and the value at *destKey is un-changed..
01178  *
01179  * If the CertReqMsg does have a pop, then the CertReqMsg's 
01180  * POPOSigningKey will be placed at *destKey.
01181  */
01182 extern SECStatus 
01183        CRMF_CertReqMsgGetPOPOSigningKey(CRMFCertReqMsg      *inCertReqMsg,
01184                                    CRMFPOPOSigningKey **destKey);
01185 
01186 /*
01187  * FUNCTION: CRMF_DestroyPOPOSigningKey
01188  * INPUTS:
01189  *    inKey
01190  *        The signing key to free.
01191  *
01192  * RETURN:
01193  * SECSuccess if freeing the memory was successful.  Any other return value
01194  * indicates an error while freeing memory.
01195  */
01196 extern SECStatus CRMF_DestroyPOPOSigningKey (CRMFPOPOSigningKey *inKey);
01197 
01198 /*
01199  * FUNCTION: CRMF_POPOSigningKeyGetAlgID
01200  * INPUTS:
01201  *    inSignKey
01202  *        The Signing Key to operate on.
01203  * RETURN:
01204  * Return the algorithmID used by the CRMFPOPOSigningKey.  User must
01205  * call SECOID_DestroyAlgorithmID(destID, PR_TRUE) when done using the
01206  * return value.
01207  */
01208 extern SECAlgorithmID* 
01209        CRMF_POPOSigningKeyGetAlgID(CRMFPOPOSigningKey *inSignKey);
01210 
01211 /*
01212  * FUNCTION: CRMF_POPOSigningKeyGetSignature
01213  * INPUTS:
01214  *    inSignKey
01215  *        The Signing Key to operate on.
01216  *
01217  * RETURN:        
01218  * Get the actual signature stored away in the CRMFPOPOSigningKey.  SECItem
01219  * returned is a BIT STRING, so the len field is the number of bits as opposed
01220  * to the total number of bytes allocatd.  User must call 
01221  * SECITEM_FreeItem(retVal,PR_TRUE) when done using the return value.
01222  */
01223 extern SECItem* CRMF_POPOSigningKeyGetSignature(CRMFPOPOSigningKey *inSignKey);
01224 
01225 /*
01226  * FUNCTION: CRMF_POPOSigningKeyGetInput
01227  * INPUTS:
01228  *    inSignKey
01229  *        The Signing Key to operate on.
01230  * NOTES:
01231  * This function will return the der encoded input that was read in while 
01232  * decoding.  The API does not support this option when creating, so you
01233  * cannot add this field.
01234  *
01235  * RETURN:
01236  * Get the poposkInput that is part of the of the POPOSigningKey. If the
01237  * optional field is not part of the POPOSigningKey, the function returns
01238  * NULL.
01239  *
01240  * If the optional field is part of the POPOSingingKey, the function will
01241  * return a copy of the der encoded poposkInput.
01242  */
01243 extern SECItem* CRMF_POPOSigningKeyGetInput(CRMFPOPOSigningKey *inSignKey);
01244 
01245 /*
01246  * FUNCTION: CRMF_CertReqMsgGetPOPKeyEncipherment
01247  * INPUTS:
01248  *    inCertReqMsg
01249  *        The certificate request message to operate on.
01250  *    destKey
01251  *        A pointer to where the library can place a pointer to a 
01252  *        copy of the POPOPrivKey representing Key Encipherment 
01253  *        Proof of Possession.
01254  *NOTES:
01255  * This function gets the POPOPrivKey associated with this CRMFCertReqMsg 
01256  * for Key Encipherment.  
01257  *
01258  * RETURN:
01259  * If the CertReqMsg did not use Key Encipherment for Proof Of Possession, the
01260  * function returns SECFailure and the value at *destKey is un-changed.
01261  *
01262  * If the CertReqMsg did use Key Encipherment for ProofOfPossession, the
01263  * function returns SECSuccess and places the POPOPrivKey representing the
01264  * Key Encipherment Proof Of Possessin at *destKey.
01265  */
01266 extern SECStatus 
01267        CRMF_CertReqMsgGetPOPKeyEncipherment(CRMFCertReqMsg   *inCertReqMsg,
01268                                        CRMFPOPOPrivKey **destKey);
01269 
01270 /*
01271  * FUNCTION: CRMF_CertReqMsgGetPOPKeyAgreement
01272  * INPUTS:
01273  *    inCertReqMsg
01274  *        The certificate request message to operate on.
01275  *    destKey
01276  *        A pointer to where the library can place a pointer to a 
01277  *        copy of the POPOPrivKey representing Key Agreement 
01278  *        Proof of Possession.
01279  * NOTES:
01280  * This function gets the POPOPrivKey associated with this CRMFCertReqMsg for 
01281  * Key Agreement.  
01282  *
01283  * RETURN:
01284  * If the CertReqMsg used Key Agreement for Proof Of Possession, the
01285  * function returns SECSuccess and the POPOPrivKey for Key Agreement
01286  * is placed at *destKey.
01287  *
01288  * If the CertReqMsg did not use Key Agreement for Proof Of Possession, the
01289  * function return SECFailure and the value at *destKey is unchanged.
01290  */
01291 extern SECStatus 
01292        CRMF_CertReqMsgGetPOPKeyAgreement(CRMFCertReqMsg   *inCertReqMsg,
01293                                     CRMFPOPOPrivKey **destKey);
01294 
01295 /* 
01296  * FUNCTION: CRMF_DestroyPOPOPrivKey
01297  * INPUTS:
01298  *    inPrivKey
01299  *        The POPOPrivKey to destroy.
01300  * NOTES:
01301  * Destroy a structure allocated by CRMF_GetPOPKeyEncipherment or
01302  * CRMF_GetPOPKeyAgreement.
01303  *
01304  * RETURN:
01305  * SECSuccess on successful destruction of the POPOPrivKey.
01306  * Any other return value indicates an error in freeing the 
01307  * memory.
01308  */
01309 extern SECStatus CRMF_DestroyPOPOPrivKey(CRMFPOPOPrivKey *inPrivKey);
01310 
01311 /* 
01312  * FUNCTION: CRMF_POPOPrivKeyGetChoice
01313  * INPUT:
01314  *    inKey
01315  *        The POPOPrivKey to operate on.
01316  * RETURN:
01317  * Returns which choice was used in constructing the POPPOPrivKey. Look at
01318  * the definition of CRMFPOPOPrivKeyChoice in crmft.h for the possible return
01319  * values.
01320  */
01321 extern CRMFPOPOPrivKeyChoice CRMF_POPOPrivKeyGetChoice(CRMFPOPOPrivKey *inKey);
01322 
01323 /*
01324  * FUNCTION: CRMF_POPOPrivKeyGetThisMessage
01325  * INPUTS:
01326  *    inKey
01327  *        The POPOPrivKey to operate on.
01328  *    destString
01329  *        A pointer to where the library can place a copy of the This Message
01330  *        field stored in the POPOPrivKey
01331  *
01332  * RETURN:
01333  * Returns the field thisMessage from the POPOPrivKey.  
01334  * If the POPOPrivKey did not use the field thisMessage, the function
01335  * returns SECFailure and the value at *destString is unchanged.
01336  *
01337  * If the POPOPrivKey did use the field thisMessage, the function returns
01338  * SECSuccess and the BIT STRING representing thisMessage is placed
01339  * at *destString. BIT STRING representation means the len field is the
01340  * number of valid bits as opposed to the total number of bytes.
01341  */
01342 extern SECStatus CRMF_POPOPrivKeyGetThisMessage(CRMFPOPOPrivKey  *inKey,
01343                                           SECItem          *destString);
01344 
01345 /*
01346  * FUNCTION: CRMF_POPOPrivKeyGetSubseqMess
01347  * INPUTS:
01348  *    inKey
01349  *        The POPOPrivKey to operate on.
01350  *    destOpt
01351  *        A pointer to where the library can place the value of the 
01352  *        Subsequent Message option used by POPOPrivKey.
01353  *
01354  * RETURN:
01355  * Retrieves the field subsequentMessage from the POPOPrivKey.  
01356  * If the POPOPrivKey used the subsequentMessage option, the function 
01357  * returns SECSuccess and places the appropriate enumerated value at
01358  * *destMessageOption.
01359  *
01360  * If the POPOPrivKey did not use the subsequenMessage option, the function
01361  * returns SECFailure and the value at *destOpt is un-changed.
01362  */
01363 extern SECStatus CRMF_POPOPrivKeyGetSubseqMess(CRMFPOPOPrivKey       *inKey,
01364                                           CRMFSubseqMessOptions *destOpt);
01365 
01366 /*
01367  * FUNCTION: CRMF_POPOPrivKeyGetDHMAC
01368  * INPUTS:
01369  *    inKey
01370  *        The POPOPrivKey to operate on.
01371  *    destMAC
01372  *        A pointer to where the library can place a copy of the dhMAC
01373  *        field of the POPOPrivKey.
01374  *        
01375  * NOTES:
01376  * Returns the field dhMAC from the POPOPrivKey.  The populated SECItem 
01377  * is in BIT STRING format.
01378  *
01379  * RETURN:
01380  * If the POPOPrivKey used the dhMAC option, the function returns SECSuccess
01381  * and the BIT STRING for dhMAC will be placed at *destMAC.  The len field in
01382  * destMAC (ie destMAC->len) will be the valid number of bits as opposed to
01383  * the number of allocated bytes.
01384  *
01385  * If the POPOPrivKey did not use the dhMAC option, the function returns
01386  * SECFailure and the value at *destMAC is unchanged.
01387  * 
01388  */
01389 extern SECStatus CRMF_POPOPrivKeyGetDHMAC(CRMFPOPOPrivKey *inKey,
01390                                      SECItem         *destMAC);
01391 
01392 /*
01393  * FUNCTION: CRMF_CertRequestGetNumControls
01394  * INPUTS: 
01395  *    inCertReq
01396  *        The Certificate Request to operate on.
01397  * RETURN:
01398  * Returns the number of Controls registered with this CertRequest.
01399  */
01400 extern int CRMF_CertRequestGetNumControls (CRMFCertRequest *inCertReq);
01401 
01402 /*
01403  * FUNCTION: CRMF_CertRequestGetControlAtIndex
01404  * INPUTS:
01405  *    inCertReq
01406  *        The certificate request to operate on.
01407  *    index
01408  *        The index of the control the user wants a copy of.
01409  * NOTES:
01410  * Function retrieves the Control at located at index.  The Controls 
01411  * are numbered like a traditional C array (0 ... numElements-1)
01412  *
01413  * RETURN:
01414  * Returns a copy of the control at the index specified.  This is a copy
01415  * so the user must call CRMF_DestroyControl after the return value is no 
01416  * longer needed.  A return value of NULL indicates an error while copying
01417  * the control or that the index was invalid.
01418  */
01419 extern CRMFControl* 
01420        CRMF_CertRequestGetControlAtIndex(CRMFCertRequest *inCertReq, 
01421                                     int              index);
01422 
01423 /*
01424  * FUNCTION: CRMF_DestroyControl
01425  * INPUTS:
01426  *    inControl
01427  *        The Control to destroy.
01428  * NOTES:
01429  * Destroy a CRMFControl allocated by CRMF_GetControlAtIndex.
01430  *
01431  * RETURN:
01432  * SECSuccess if freeing the memory was successful.  Any other return
01433  * value indicates an error while freeing the memory.
01434  */
01435 extern SECStatus CRMF_DestroyControl(CRMFControl *inControl);
01436 
01437 /*
01438  * FUNCTION: CRMF_ControlGetControlType
01439  * INPUTS:
01440  *    inControl
01441  *        The control to operate on.
01442  * NOTES:
01443  * The function returns an enumertion which indicates the type of control
01444  * 'inControl'.
01445  *
01446  * RETURN:
01447  * Look in crmft.h at the definition of the enumerated type CRMFControlType
01448  * for the possible return values.
01449  */
01450 extern CRMFControlType CRMF_ControlGetControlType(CRMFControl *inControl);
01451 
01452 /*
01453  * FUNCTION: CRMF_ControlGetRegTokenControlValue
01454  * INPUTS:
01455  *    inControl
01456  *        The Control to operate on.
01457  * NOTES:
01458  * The user must call SECITEM_FreeItem passing in the return value
01459  * after the returnvalue is no longer needed.
01460 
01461  * RETURN:
01462  * Return the value for a Registration Token Control.
01463  * The SECItem returned should be in UTF8 format.  A NULL
01464  * return value indicates there was no Registration Control associated
01465  * with the Control.
01466  * (This library will not verify format.  It assumes the client properly 
01467  * formatted the strings when adding it or the message decoded was properly 
01468  * formatted.  The library will just give back the bytes it was given.)
01469  */
01470 extern SECItem* CRMF_ControlGetRegTokenControlValue(CRMFControl *inControl);
01471 
01472 /*
01473  * FUNCTION: CRMF_ControlGetAuthenticatorControlValue
01474  * INPUTS:
01475  *    inControl
01476  *        The Control to operate on.
01477  * NOTES:
01478  * The user must call SECITEM_FreeItem passing in the return value
01479  * after the returnvalue is no longer needed.
01480  *
01481  * RETURN:
01482  * Return the value for the Authenticator Control.
01483  * The SECItem returned should be in UTF8 format.  A NULL
01484  * return value indicates there was no Authenticator Control associated
01485  * with the CRMFControl..
01486  * (This library will not verify format.  It assumes the client properly 
01487  * formatted the strings when adding it or the message decoded was properly 
01488  * formatted.  The library will just give back the bytes it was given.)
01489  */
01490 extern SECItem* CRMF_ControlGetAuthicatorControlValue(CRMFControl *inControl);
01491 
01492 /*
01493  * FUNCTION: CRMF_ControlGetPKIArchiveOptions
01494  * INPUTS:inControl
01495  *    The Control tooperate on.
01496  * NOTES:
01497  * This function returns a copy of the PKIArchiveOptions.  The user must call
01498  * the function CRMF_DestroyPKIArchiveOptions when the return value is no
01499  * longer needed.
01500  *
01501  * RETURN:
01502  * Get the PKIArchiveOptions associated with the Control.  A return
01503  * value of NULL indicates the Control was not a PKIArchiveOptions 
01504  * Control.
01505  */
01506 extern CRMFPKIArchiveOptions* 
01507        CRMF_ControlGetPKIArchiveOptions(CRMFControl *inControl);
01508   
01509 /*
01510  * FUNCTION: CMRF_DestroyPKIArchiveOptions
01511  * INPUTS:
01512  *    inOptions
01513  *        The ArchiveOptions to destroy.
01514  * NOTE:
01515  * Destroy the CRMFPKIArchiveOptions structure.
01516  *
01517  * RETURN:
01518  * SECSuccess if successful in freeing all the memory associated with 
01519  * the PKIArchiveOptions.  Any other return value indicates an error while
01520  * freeing the PKIArchiveOptions.
01521  */
01522 extern SECStatus 
01523        CRMF_DestroyPKIArchiveOptions(CRMFPKIArchiveOptions *inOptions);
01524 
01525 /*
01526  * FUNCTION: CRMF_PKIArchiveOptionsGetOptionType
01527  * INPUTS:
01528  *    inOptions
01529  *        The PKIArchiveOptions to operate on.
01530  * RETURN:
01531  * Returns the choice used for the PKIArchiveOptions.  Look at the definition
01532  * of CRMFPKIArchiveOptionsType in crmft.h for possible return values.
01533  */
01534 extern CRMFPKIArchiveOptionsType
01535        CRMF_PKIArchiveOptionsGetOptionType(CRMFPKIArchiveOptions *inOptions);
01536 
01537 /*
01538  * FUNCTION: CRMF_PKIArchiveOptionsGetEncryptedPrivKey
01539  * INPUTS:
01540  *    inOpts
01541  *        The PKIArchiveOptions to operate on.
01542  * 
01543  * NOTES:
01544  * The user must call CRMF_DestroyEncryptedKey when done using this return
01545  * value.
01546  *
01547  * RETURN:
01548  * Get the encryptedPrivKey field of the PKIArchiveOptions structure.
01549  * A return value of NULL indicates that encryptedPrivKey was not used as
01550  * the choice for this PKIArchiveOptions.
01551  */
01552 extern CRMFEncryptedKey*
01553       CRMF_PKIArchiveOptionsGetEncryptedPrivKey(CRMFPKIArchiveOptions *inOpts);
01554 
01555 /*
01556  * FUNCTION: CRMF_EncryptedKeyGetChoice
01557  * INPUTS:
01558  *    inEncrKey
01559  *        The EncryptedKey to operate on.
01560  *
01561  * NOTES:
01562  * Get the choice used for representing the EncryptedKey.
01563  *
01564  * RETURN:
01565  * Returns the Choice used in representing the EncryptedKey.  Look in 
01566  * crmft.h at the definition of CRMFEncryptedKeyChoice for possible return
01567  * values.
01568  */
01569 extern CRMFEncryptedKeyChoice 
01570        CRMF_EncryptedKeyGetChoice(CRMFEncryptedKey *inEncrKey);
01571 
01572 
01573 /*
01574  * FUNCTION: CRMF_EncryptedKeyGetEncryptedValue
01575  * INPUTS:
01576  *    inKey
01577  *        The EncryptedKey to operate on.
01578  *
01579  * NOTES:
01580  * The user must call CRMF_DestroyEncryptedValue passing in 
01581  * CRMF_GetEncryptedValue's return value.
01582  *
01583  * RETURN:
01584  * A pointer to a copy of the EncryptedValue contained as a member of
01585  * the EncryptedKey.
01586  */
01587 extern CRMFEncryptedValue* 
01588        CRMF_EncryptedKeyGetEncryptedValue(CRMFEncryptedKey *inKey);
01589 
01590 /*
01591  * FUNCTION: CRMF_DestroyEncryptedValue
01592  * INPUTS:
01593  *    inEncrValue
01594  *        The EncryptedValue to destroy.
01595  *
01596  * NOTES:
01597  * Free up all memory associated with 'inEncrValue'.
01598  *
01599  * RETURN:
01600  * SECSuccess if freeing up the memory associated with the EncryptedValue
01601  * is successful. Any other return value indicates an error while freeing the
01602  * memory.
01603  */
01604 extern SECStatus CRMF_DestroyEncryptedValue(CRMFEncryptedValue *inEncrValue);
01605 
01606 /*
01607  * FUNCTION: CRMF_EncryptedValueGetEncValue
01608  * INPUTS:
01609  *    inEncValue
01610  *        The EncryptedValue to operate on.
01611  * NOTES:
01612  * Function retrieves the encValue from an EncryptedValue structure.
01613  *
01614  * RETURN:
01615  * A poiner to a SECItem containing the encValue of the EncryptedValue
01616  * structure.  The return value is in BIT STRING format, meaning the
01617  * len field of the return structure represents the number of valid bits
01618  * as opposed to the allocated number of bytes.
01619  * ANULL return value indicates an error in copying the encValue field.
01620  */
01621 extern SECItem* CRMF_EncryptedValueGetEncValue(CRMFEncryptedValue *inEncValue);
01622 
01623 /*
01624  * FUNCTION: CRMF_EncryptedValueGetIntendedAlg
01625  * INPUTS
01626  *    inEncValue
01627  *        The EncryptedValue to operate on.
01628  * NOTES:
01629  * Retrieve the IntendedAlg field from the EncryptedValue structure.
01630  * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
01631  * the return value.  When present, this alogorithm is the alogrithm for
01632  * which the private key will be used.
01633  *
01634  * RETURN:
01635  * A Copy of the intendedAlg field.  A NULL return value indicates the
01636  * optional field was not present in the structure.
01637  */
01638 extern SECAlgorithmID* 
01639        CRMF_EncryptedValueGetIntendedAlg(CRMFEncryptedValue  *inEncValue);
01640 
01641 
01642 /*
01643  * FUNCTION: CRMF_EncryptedValueGetSymmAlg
01644  * INPUTS
01645  *    inEncValue
01646  *        The EncryptedValue to operate on.
01647  * NOTES:
01648  * Retrieve the symmAlg field from the EncryptedValue structure.
01649  * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
01650  * the return value.  When present, this is algorithm used to
01651  * encrypt the encValue of the EncryptedValue.
01652  *
01653  * RETURN:
01654  * A Copy of the symmAlg field.  A NULL return value indicates the
01655  * optional field was not present in the structure.
01656  */
01657 extern SECAlgorithmID* 
01658        CRMF_EncryptedValueGetSymmAlg(CRMFEncryptedValue  *inEncValue);
01659 
01660 
01661 /*
01662  * FUNCTION: CRMF_EncryptedValueGetKeyAlg
01663  * INPUTS
01664  *    inEncValue
01665  *        The EncryptedValue to operate on.
01666  * NOTES:
01667  * Retrieve the keyAlg field from the EncryptedValue structure.
01668  * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
01669  * the return value.  When present, this is the algorithm used to encrypt
01670  * the symmetric key in the encSymmKey field of the EncryptedValue structure.
01671  *
01672  * RETURN:
01673  * A Copy of the keyAlg field.  A NULL return value indicates the
01674  * optional field was not present in the structure.
01675  */
01676 extern SECAlgorithmID* 
01677        CRMF_EncryptedValueGetKeyAlg(CRMFEncryptedValue *inEncValue);
01678 
01679 /*
01680  * FUNCTION: CRMF_EncryptedValueGetValueHint
01681  * INPUTS:
01682  *    inEncValue
01683  *        The EncryptedValue to operate on.
01684  *
01685  * NOTES:
01686  * Return a copy of the der-encoded value hint.
01687  * User must call SECITEM_FreeItem(retVal, PR_TRUE) when done using the
01688  * return value.  When, present, this is a value that the client which
01689  * originally issued a certificate request can use to reproduce any data
01690  * it wants.  The RA does not know how to interpret this data.
01691  *
01692  * RETURN:
01693  * A copy of the valueHint field of the EncryptedValue.  A NULL return
01694  * value indicates the optional valueHint field is not present in the
01695  * EncryptedValue.
01696  */
01697 extern SECItem* 
01698        CRMF_EncryptedValueGetValueHint(CRMFEncryptedValue  *inEncValue);
01699 
01700 /*
01701  * FUNCTION: CRMF_EncrypteValueGetEncSymmKey
01702  * INPUTS: 
01703  *    inEncValue
01704  *        The EncryptedValue to operate on.
01705  *
01706  * NOTES:
01707  * Return a copy of the encSymmKey field. This field is the encrypted
01708  * symmetric key that the client uses in doing Public Key wrap of a private
01709  * key.  When present, this is the symmetric key that was used to wrap the
01710  * private key.  (The encrypted private key will be stored in encValue
01711  * of the same EncryptedValue structure.)  The user must call 
01712  * SECITEM_FreeItem(retVal, PR_TRUE) when the return value is no longer
01713  * needed.
01714  *
01715  * RETURN:
01716  * A copy of the optional encSymmKey field of the EncryptedValue structure.
01717  * The return value will be in BIT STRING format, meaning the len field will
01718  * be the number of valid bits as opposed to the number of bytes. A return 
01719  * value of NULL means the optional encSymmKey field was not present in
01720  * the EncryptedValue structure.
01721  */
01722 extern SECItem* 
01723        CRMF_EncryptedValueGetEncSymmKey(CRMFEncryptedValue *inEncValue);
01724 
01725 /*
01726  * FUNCTION: CRMF_PKIArchiveOptionsGetKeyGenParameters
01727  * INPUTS:
01728  *    inOptions
01729  *        The PKiArchiveOptions to operate on.
01730  *
01731  * NOTES:
01732  * User must call SECITEM_FreeItem(retVal, PR_TRUE) after the return 
01733  * value is no longer needed.
01734  *
01735  * RETURN:
01736  * Get the keyGenParameters field of the PKIArchiveOptions.
01737  * A NULL return value indicates that keyGenParameters was not 
01738  * used as the choice for this PKIArchiveOptions.
01739  *
01740  * The SECItem returned is in BIT STRING format (ie, the len field indicates
01741  * number of valid bits as opposed to allocated number of bytes.)
01742  */
01743 extern SECItem* 
01744    CRMF_PKIArchiveOptionsGetKeyGenParameters(CRMFPKIArchiveOptions *inOptions);
01745 
01746 /*
01747  * FUNCTION: CRMF_PKIArchiveOptionsGetArchiveRemGenPrivKey
01748  * INPUTS:
01749  *    inOpt
01750  *        The PKIArchiveOptions to operate on.
01751  *    destVal
01752  *        A pointer to where the library can place the value for 
01753  *        arciveRemGenPrivKey
01754  * RETURN:
01755  * If the PKIArchiveOptions used the archiveRemGenPrivKey field, the
01756  * function returns SECSuccess and fills the value at *destValue with either
01757  * PR_TRUE or PR_FALSE, depending on what the PKIArchiveOptions has as a 
01758  * value. 
01759  *
01760  * If the PKIArchiveOptions does not use the archiveRemGenPrivKey field, the
01761  * function returns SECFailure and the value at *destValue is unchanged.
01762  */
01763 extern SECStatus 
01764     CRMF_PKIArchiveOptionsGetArchiveRemGenPrivKey(CRMFPKIArchiveOptions *inOpt,
01765                                             PRBool             *destVal);
01766 
01767 /* Helper functions that can be used by other libraries. */
01768 /*
01769  * A quick helper funciton to get the best wrap mechanism.
01770  */
01771 extern CK_MECHANISM_TYPE CRMF_GetBestWrapPadMechanism(PK11SlotInfo *slot); 
01772 
01773 /*
01774  * A helper function to get a randomly generated IV from a mechanism 
01775  * type.
01776  */
01777 extern SECItem* CRMF_GetIVFromMechanism(CK_MECHANISM_TYPE mechType);
01778  
01779 SEC_END_PROTOS
01780 #endif /*_CRMF_H_*/
01781 
01782