Back to index

lightning-sunbird  0.9+nobinonly
crmffut.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 /*
00038  * These functions to be implemented in the future if the features
00039  * which these functions would implement wind up being needed.
00040  */
00041 
00042 /*
00043  * Use this functionto create the CRMFSinglePubInfo* variables that will 
00044  * populate the inPubInfoArray paramter for the funciton
00045  * CRMF_CreatePKIPublicationInfo.
00046  *
00047  * "inPubMethod" specifies which publication method will be used
00048  * "pubLocation" is a representation of the location where 
00049  */
00050 extern CRMFSinglePubInfo* 
00051       CRMF_CreateSinglePubInfo(CRMFPublicationMethod  inPubMethod,
00052                             CRMFGeneralName       *pubLocation);
00053 
00054 /*
00055  * Create a PKIPublicationInfo that can later be passed to the function
00056  * CRMFAddPubInfoControl.
00057  */
00058 extern CRMFPKIPublicationInfo *
00059      CRMF_CreatePKIPublicationInfo(CRMFPublicationAction  inAction,
00060                                CRMFSinglePubInfo    **inPubInfoArray,
00061                                int                    numPubInfo);
00062 
00063 /*
00064  * Only call this function on a CRMFPublicationInfo that was created by
00065  * CRMF_CreatePKIPublicationInfo that was passed in NULL for arena.
00066  */
00067 
00068 extern SECStatus 
00069        CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo);
00070 
00071 extern SECStatus CRMF_AddPubInfoControl(CRMFCertRequest        *inCertReq,
00072                                    CRMFPKIPublicationInfo *inPubInfo);
00073 
00074 /*
00075  * This is to create a Cert ID Control which can later be added to 
00076  * a certificate request.
00077  */
00078 extern CRMFCertID* CRMF_CreateCertID(CRMFGeneralName *issuer,
00079                                  long             serialNumber);
00080 
00081 extern SECStatus CRMF_DestroyCertID(CRMFCertID* certID);
00082 
00083 extern SECStatus CRMF_AddCertIDControl(CRMFCertRequest *inCertReq,
00084                                    CRMFCertID      *certID);
00085 
00086 extern SECStatus 
00087        CRMF_AddProtocolEncryptioKeyControl(CRMFCertRequest          *inCertReq,
00088                                       CERTSubjectPublicKeyInfo *spki);
00089 
00090 /*
00091  * Add the ASCII Pairs Registration Info to the Certificate Request.
00092  * The SECItem must be an OCTET string representation.
00093  */
00094 extern SECStatus
00095        CRMF_AddUTF8PairsRegInfo(CRMFCertRequest *inCertReq,
00096                              SECItem         *asciiPairs);
00097 
00098 /*
00099  * This takes a CertRequest and adds it to another CertRequest.  
00100  */
00101 extern SECStatus
00102        CRMF_AddCertReqToRegInfo(CRMFCertRequest *certReqToAddTo,
00103                             CRMFCertRequest *certReqBeingAdded);
00104 
00105 /*
00106  * Returns which option was used for the authInfo field of POPOSigningKeyInput
00107  */
00108 extern CRMFPOPOSkiInputAuthChoice 
00109        CRMF_GetSignKeyInputAuthChoice(CRMFPOPOSigningKeyInput *inKeyInput);
00110 
00111 /*
00112  * Gets the PKMACValue associated with the POPOSigningKeyInput.
00113  * If the POPOSigningKeyInput did not use authInfo.publicKeyMAC 
00114  * the function returns SECFailure and the value at *destValue is unchanged.
00115  *
00116  * If the POPOSigningKeyInput did use authInfo.publicKeyMAC, the function
00117  * returns SECSuccess and places the PKMACValue at *destValue.
00118  */
00119 extern SECStatus 
00120        CRMF_GetSignKeyInputPKMACValue(CRMFPOPOSigningKeyInput *inKeyInput,
00121                                   CRMFPKMACValue          **destValue);
00122 /*
00123  * Gets the SubjectPublicKeyInfo from the POPOSigningKeyInput
00124  */
00125 extern CERTSubjectPublicKeyInfo *
00126        CRMF_GetSignKeyInputPublicKey(CRMFPOPOSigningKeyInput *inKeyInput);
00127 
00128 
00129 /*
00130  * Return the value for the PKIPublicationInfo Control.
00131  * A return value of NULL indicates that the Control was 
00132  * not a PKIPublicationInfo Control.  Call 
00133  * CRMF_DestroyPKIPublicationInfo on the return value when done
00134  * using the pointer.
00135  */
00136 extern CRMFPKIPublicationInfo* CRMF_GetPKIPubInfo(CRMFControl *inControl);
00137 
00138 /*
00139  * Free up a CRMFPKIPublicationInfo structure.
00140  */
00141 extern SECStatus 
00142        CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo);
00143 
00144 /*
00145  * Get the choice used for action in this PKIPublicationInfo.
00146  */
00147 extern CRMFPublicationAction 
00148        CRMF_GetPublicationAction(CRMFPKIPublicationInfo *inPubInfo);
00149 
00150 /*
00151  * Get the number of pubInfos are stored in the PKIPubicationInfo.
00152  */
00153 extern int CRMF_GetNumPubInfos(CRMFPKIPublicationInfo *inPubInfo);
00154 
00155 /*
00156  * Get the pubInfo at index for the given PKIPubicationInfo.
00157  * Indexing is done like a traditional C Array. (0 .. numElements-1)
00158  */
00159 extern CRMFSinglePubInfo* 
00160        CRMF_GetPubInfoAtIndex(CRMFPKIPublicationInfo *inPubInfo,
00161                            int                     index);
00162 
00163 /*
00164  * Destroy the CRMFSinglePubInfo.
00165  */
00166 extern SECStatus CRMF_DestroySinglePubInfo(CRMFSinglePubInfo *inPubInfo);
00167 
00168 /*
00169  * Get the pubMethod used by the SinglePubInfo.
00170  */
00171 extern CRMFPublicationMethod 
00172        CRMF_GetPublicationMethod(CRMFSinglePubInfo *inPubInfo);
00173 
00174 /*
00175  * Get the pubLocation associated with the SinglePubInfo.
00176  * A NULL return value indicates there was no pubLocation associated
00177  * with the SinglePuInfo.
00178  */
00179 extern CRMFGeneralName* CRMF_GetPubLocation(CRMFSinglePubInfo *inPubInfo);
00180 
00181 /*
00182  * Get the authInfo.sender field out of the POPOSigningKeyInput.
00183  * If the POPOSigningKeyInput did not use the authInfo the function
00184  * returns SECFailure and the value at *destName is unchanged.
00185  *
00186  * If the POPOSigningKeyInput did use authInfo.sender, the function returns
00187  * SECSuccess and puts the authInfo.sender at *destName/
00188  */
00189 extern SECStatus CRMF_GetSignKeyInputSender(CRMFPOPOSigningKeyInput *keyInput,
00190                                        CRMFGeneralName        **destName);
00191 
00192 /**************** CMMF Functions that need to be added. **********************/
00193 
00194 /*
00195  * FUNCTION: CMMF_POPODecKeyChallContentSetNextChallenge
00196  * INPUTS:
00197  *    inDecKeyChall
00198  *        The CMMFPOPODecKeyChallContent to operate on.
00199  *    inRandom
00200  *        The random number to use when generating the challenge,
00201  *    inSender
00202  *        The GeneralName representation of the sender of the challenge.
00203  *    inPubKey
00204  *        The public key to use when encrypting the challenge.
00205  * NOTES:
00206  *    This function adds a challenge to the end of the list of challenges
00207  *    contained by 'inDecKeyChall'.  Refer to the CMMF draft on how the
00208  *    the random number passed in and the sender's GeneralName are used
00209  *    to generate the challenge and witness fields of the challenge.  This
00210  *    library will use SHA1 as the one-way function for generating the 
00211  *    witess field of the challenge.
00212  *
00213  * RETURN:
00214  *    SECSuccess if generating the challenge and adding to the end of list
00215  *    of challenges was successful.  Any other return value indicates an error
00216  *    while trying to generate the challenge.
00217  */
00218 extern SECStatus
00219 CMMF_POPODecKeyChallContentSetNextChallenge
00220                                    (CMMFPOPODecKeyChallContent *inDecKeyChall,
00221                                 long                        inRandom,
00222                                 CERTGeneralName            *inSender,
00223                                 SECKEYPublicKey            *inPubKey);
00224 
00225 /*
00226  * FUNCTION: CMMF_POPODecKeyChallContentGetNumChallenges
00227  * INPUTS:
00228  *    inKeyChallCont
00229  *        The CMMFPOPODecKeyChallContent to operate on.
00230  * RETURN:
00231  *    This function returns the number of CMMFChallenges are contained in 
00232  *    the CMMFPOPODecKeyChallContent structure.
00233  */
00234 extern int CMMF_POPODecKeyChallContentGetNumChallenges
00235                                   (CMMFPOPODecKeyChallContent *inKeyChallCont);
00236 
00237 /*
00238  * FUNCTION: CMMF_ChallengeGetRandomNumber
00239  * INPUTS:
00240  *    inChallenge
00241  *        The CMMFChallenge to operate on.
00242  *    inDest
00243  *        A pointer to a user supplied buffer where the library
00244  *        can place a copy of the random integer contatained in the
00245  *        challenge.
00246  * NOTES:
00247  *    This function returns the value held in the decrypted Rand structure
00248  *    corresponding to the random integer.  The user must call 
00249  *    CMMF_ChallengeDecryptWitness before calling this function.  Call 
00250  *    CMMF_ChallengeIsDecrypted to find out if the challenge has been 
00251  *    decrypted.
00252  *
00253  * RETURN:
00254  *    SECSuccess indicates the witness field has been previously decrypted
00255  *    and the value for the random integer was successfully placed at *inDest.
00256  *    Any other return value indicates an error and that the value at *inDest
00257  *    is not a valid value.
00258  */
00259 extern SECStatus CMMF_ChallengeGetRandomNumber(CMMFChallenge *inChallenge,
00260                                           long          *inDest);
00261 
00262 /*
00263  * FUNCTION: CMMF_ChallengeGetSender
00264  * INPUTS:
00265  *    inChallenge
00266  *        the CMMFChallenge to operate on.
00267  * NOTES:
00268  *    This function returns the value held in the decrypted Rand structure
00269  *    corresponding to the sender.  The user must call 
00270  *    CMMF_ChallengeDecryptWitness before calling this function.  Call 
00271  *    CMMF_ChallengeIsDecrypted to find out if the witness field has been
00272  *    decrypted.  The user must call CERT_DestroyGeneralName after the return
00273  *    value is no longer needed.
00274  *
00275  * RETURN:
00276  *    A pointer to a copy of the sender CERTGeneralName.  A return value of
00277  *    NULL indicates an error in trying to copy the information or that the
00278  *    witness field has not been decrypted.
00279  */
00280 extern CERTGeneralName* CMMF_ChallengeGetSender(CMMFChallenge *inChallenge);
00281 
00282 /*
00283  * FUNCTION: CMMF_ChallengeGetAlgId
00284  * INPUTS:
00285  *    inChallenge
00286  *        The CMMFChallenge to operate on.
00287  *    inDestAlgId
00288  *        A pointer to memory where a pointer to a copy of the algorithm
00289  *        id can be placed.
00290  * NOTES:
00291  *    This function retrieves the one way function algorithm identifier 
00292  *    contained within the CMMFChallenge if the optional field is present.
00293  *
00294  * RETURN:
00295  *    SECSucces indicates the function was able to place a pointer to a copy of
00296  *    the alogrithm id at *inAlgId.  If the value at *inDestAlgId is NULL, 
00297  *    that means there was no algorithm identifier present in the 
00298  *    CMMFChallenge.  Any other return value indicates the function was not 
00299  *    able to make a copy of the algorithm identifier.  In this case the value 
00300  *    at *inDestAlgId is not valid.
00301  */
00302 extern SECStatus CMMF_ChallengeGetAlgId(CMMFChallenge  *inChallenge,
00303                                    SECAlgorithmID *inAlgId);
00304 
00305 /*
00306  * FUNCTION: CMMF_DestroyChallenge
00307  * INPUTS:
00308  *    inChallenge
00309  *        The CMMFChallenge to free up.
00310  * NOTES:
00311  *    This function frees up all the memory associated with the CMMFChallenge 
00312  *    passed in.
00313  * RETURN:
00314  *    SECSuccess if freeing all the memory associated with the CMMFChallenge
00315  *    passed in is successful.  Any other return value indicates an error 
00316  *    while freeing the memory.
00317  */
00318 extern SECStatus CMMF_DestroyChallenge (CMMFChallenge *inChallenge);
00319 
00320 /*
00321  * FUNCTION: CMMF_DestroyPOPODecKeyRespContent
00322  * INPUTS:
00323  *    inDecKeyResp
00324  *        The CMMFPOPODecKeyRespContent structure to free.
00325  * NOTES:
00326  *    This function frees up all the memory associate with the 
00327  *    CMMFPOPODecKeyRespContent.
00328  *
00329  * RETURN:
00330  *    SECSuccess if freeint up all the memory associated with the
00331  *    CMMFPOPODecKeyRespContent structure is successful.  Any other
00332  *    return value indicates an error while freeing the memory.
00333  */
00334 extern SECStatus
00335      CMMF_DestroyPOPODecKeyRespContent(CMMFPOPODecKeyRespContent *inDecKeyResp);
00336 
00337 /*
00338  * FUNCTION: CMMF_ChallengeDecryptWitness
00339  * INPUTS:
00340  *    inChallenge
00341  *        The CMMFChallenge to operate on.
00342  *    inPrivKey
00343  *        The private key to use to decrypt the witness field.
00344  * NOTES:
00345  *    This function uses the private key to decrypt the challenge field
00346  *    contained in the CMMFChallenge.  Make sure the private key matches the
00347  *    public key that was used to encrypt the witness.  The creator of 
00348  *    the challenge will most likely be an RA that has the public key
00349  *    from a Cert request.  So the private key should be the private key
00350  *    associated with public key in that request.  This function will also
00351  *    verify the witness field of the challenge.
00352  *
00353  * RETURN:
00354  *    SECSuccess if decrypting the witness field was successful.  This does
00355  *    not indicate that the decrypted data is valid, since the private key 
00356  *    passed in may not be the actual key needed to properly decrypt the 
00357  *    witness field.  Meaning that there is a decrypted structure now, but
00358  *    may be garbage because the private key was incorrect.
00359  *    Any other return value indicates the function could not complete the
00360  *    decryption process.
00361  */
00362 extern SECStatus CMMF_ChallengeDecryptWitness(CMMFChallenge    *inChallenge,
00363                                          SECKEYPrivateKey *inPrivKey);
00364 
00365 /*
00366  * FUNCTION: CMMF_ChallengeIsDecrypted
00367  * INPUTS:
00368  *    inChallenge
00369  *        The CMMFChallenge to operate on.
00370  * RETURN:
00371  *    This is a predicate function that returns PR_TRUE if the decryption 
00372  *    process has already been performed.  The function return PR_FALSE if 
00373  *    the decryption process has not been performed yet.
00374  */
00375 extern PRBool CMMF_ChallengeIsDecrypted(CMMFChallenge *inChallenge);
00376 
00377 /*
00378  * FUNCTION: CMMF_DestroyPOPODecKeyChallContent
00379  * INPUTS:
00380  *    inDecKeyCont
00381  *        The CMMFPOPODecKeyChallContent to free
00382  * NOTES:
00383  *    This function frees up all the memory associated with the 
00384  *    CMMFPOPODecKeyChallContent 
00385  * RETURN:
00386  *    SECSuccess if freeing up all the memory associatd with the 
00387  *    CMMFPOPODecKeyChallContent is successful.  Any other return value
00388  *    indicates an error while freeing the memory.
00389  *
00390  */
00391 extern SECStatus 
00392  CMMF_DestroyPOPODecKeyChallContent (CMMFPOPODecKeyChallContent *inDecKeyCont);
00393