security/nss/lib/crmf/crmffut.h

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is the Netscape security libraries.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Netscape Communications Corporation.
  18  * Portions created by the Initial Developer are Copyright (C) 1994-2000
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *
  23  * Alternatively, the contents of this file may be used under the terms of
  24  * either the GNU General Public License Version 2 or later (the "GPL"), or
  25  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  26  * in which case the provisions of the GPL or the LGPL are applicable instead
  27  * of those above. If you wish to allow use of your version of this file only
  28  * under the terms of either the GPL or the LGPL, and not to allow others to
  29  * use your version of this file under the terms of the MPL, indicate your
  30  * decision by deleting the provisions above and replace them with the notice
  31  * and other provisions required by the GPL or the LGPL. If you do not delete
  32  * the provisions above, a recipient may use your version of this file under
  33  * the terms of any one of the MPL, the GPL or the LGPL.
  34  *
  35  * ***** END LICENSE BLOCK ***** */
  36
  37 /*
  38  * These functions to be implemented in the future if the features
  39  * which these functions would implement wind up being needed.
  40  */
  41
  42 /*
  43  * Use this functionto create the CRMFSinglePubInfo* variables that will
  44  * populate the inPubInfoArray paramter for the funciton
  45  * CRMF_CreatePKIPublicationInfo.
  46  *
  47  * "inPubMethod" specifies which publication method will be used
  48  * "pubLocation" is a representation of the location where
  49  */
  50 extern CRMFSinglePubInfo*
  51       CRMF_CreateSinglePubInfo(CRMFPublicationMethod  inPubMethod,
  52                                CRMFGeneralName       *pubLocation);
  53
  54 /*
  55  * Create a PKIPublicationInfo that can later be passed to the function
  56  * CRMFAddPubInfoControl.
  57  */
  58 extern CRMFPKIPublicationInfo *
  59      CRMF_CreatePKIPublicationInfo(CRMFPublicationAction  inAction,
  60                                    CRMFSinglePubInfo    **inPubInfoArray,
  61                                    int                    numPubInfo);
  62
  63 /*
  64  * Only call this function on a CRMFPublicationInfo that was created by
  65  * CRMF_CreatePKIPublicationInfo that was passed in NULL for arena.
  66  */
  67
  68 extern SECStatus
  69        CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo);
  70
  71 extern SECStatus CRMF_AddPubInfoControl(CRMFCertRequest        *inCertReq,
  72                                         CRMFPKIPublicationInfo *inPubInfo);
  73
  74 /*
  75  * This is to create a Cert ID Control which can later be added to
  76  * a certificate request.
  77  */
  78 extern CRMFCertID* CRMF_CreateCertID(CRMFGeneralName *issuer,
  79                                      long             serialNumber);
  80
  81 extern SECStatus CRMF_DestroyCertID(CRMFCertID* certID);
  82
  83 extern SECStatus CRMF_AddCertIDControl(CRMFCertRequest *inCertReq,
  84                                        CRMFCertID      *certID);
  85
  86 extern SECStatus
  87        CRMF_AddProtocolEncryptioKeyControl(CRMFCertRequest          *inCertReq,
  88                                            CERTSubjectPublicKeyInfo *spki);
  89
  90 /*
  91  * Add the ASCII Pairs Registration Info to the Certificate Request.
  92  * The SECItem must be an OCTET string representation.
  93  */
  94 extern SECStatus
  95        CRMF_AddUTF8PairsRegInfo(CRMFCertRequest *inCertReq,
  96                                  SECItem         *asciiPairs);
  97
  98 /*
  99  * This takes a CertRequest and adds it to another CertRequest.
 100  */
 101 extern SECStatus
 102        CRMF_AddCertReqToRegInfo(CRMFCertRequest *certReqToAddTo,
 103                                 CRMFCertRequest *certReqBeingAdded);
 104
 105 /*
 106  * Returns which option was used for the authInfo field of POPOSigningKeyInput
 107  */
 108 extern CRMFPOPOSkiInputAuthChoice
 109        CRMF_GetSignKeyInputAuthChoice(CRMFPOPOSigningKeyInput *inKeyInput);
 110
 111 /*
 112  * Gets the PKMACValue associated with the POPOSigningKeyInput.
 113  * If the POPOSigningKeyInput did not use authInfo.publicKeyMAC
 114  * the function returns SECFailure and the value at *destValue is unchanged.
 115  *
 116  * If the POPOSigningKeyInput did use authInfo.publicKeyMAC, the function
 117  * returns SECSuccess and places the PKMACValue at *destValue.
 118  */
 119 extern SECStatus
 120        CRMF_GetSignKeyInputPKMACValue(CRMFPOPOSigningKeyInput *inKeyInput,
 121                                       CRMFPKMACValue          **destValue);
 122 /*
 123  * Gets the SubjectPublicKeyInfo from the POPOSigningKeyInput
 124  */
 125 extern CERTSubjectPublicKeyInfo *
 126        CRMF_GetSignKeyInputPublicKey(CRMFPOPOSigningKeyInput *inKeyInput);
 127
 128
 129 /*
 130  * Return the value for the PKIPublicationInfo Control.
 131  * A return value of NULL indicates that the Control was
 132  * not a PKIPublicationInfo Control.  Call
 133  * CRMF_DestroyPKIPublicationInfo on the return value when done
 134  * using the pointer.
 135  */
 136 extern CRMFPKIPublicationInfo* CRMF_GetPKIPubInfo(CRMFControl *inControl);
 137
 138 /*
 139  * Free up a CRMFPKIPublicationInfo structure.
 140  */
 141 extern SECStatus
 142        CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo);
 143
 144 /*
 145  * Get the choice used for action in this PKIPublicationInfo.
 146  */
 147 extern CRMFPublicationAction
 148        CRMF_GetPublicationAction(CRMFPKIPublicationInfo *inPubInfo);
 149
 150 /*
 151  * Get the number of pubInfos are stored in the PKIPubicationInfo.
 152  */
 153 extern int CRMF_GetNumPubInfos(CRMFPKIPublicationInfo *inPubInfo);
 154
 155 /*
 156  * Get the pubInfo at index for the given PKIPubicationInfo.
 157  * Indexing is done like a traditional C Array. (0 .. numElements-1)
 158  */
 159 extern CRMFSinglePubInfo*
 160        CRMF_GetPubInfoAtIndex(CRMFPKIPublicationInfo *inPubInfo,
 161                               int                     index);
 162
 163 /*
 164  * Destroy the CRMFSinglePubInfo.
 165  */
 166 extern SECStatus CRMF_DestroySinglePubInfo(CRMFSinglePubInfo *inPubInfo);
 167
 168 /*
 169  * Get the pubMethod used by the SinglePubInfo.
 170  */
 171 extern CRMFPublicationMethod
 172        CRMF_GetPublicationMethod(CRMFSinglePubInfo *inPubInfo);
 173
 174 /*
 175  * Get the pubLocation associated with the SinglePubInfo.
 176  * A NULL return value indicates there was no pubLocation associated
 177  * with the SinglePuInfo.
 178  */
 179 extern CRMFGeneralName* CRMF_GetPubLocation(CRMFSinglePubInfo *inPubInfo);
 180
 181 /*
 182  * Get the authInfo.sender field out of the POPOSigningKeyInput.
 183  * If the POPOSigningKeyInput did not use the authInfo the function
 184  * returns SECFailure and the value at *destName is unchanged.
 185  *
 186  * If the POPOSigningKeyInput did use authInfo.sender, the function returns
 187  * SECSuccess and puts the authInfo.sender at *destName/
 188  */
 189 extern SECStatus CRMF_GetSignKeyInputSender(CRMFPOPOSigningKeyInput *keyInput,
 190                                             CRMFGeneralName        **destName);
 191
 192 /**************** CMMF Functions that need to be added. **********************/
 193
 194 /*
 195  * FUNCTION: CMMF_POPODecKeyChallContentSetNextChallenge
 196  * INPUTS:
 197  *    inDecKeyChall
 198  *        The CMMFPOPODecKeyChallContent to operate on.
 199  *    inRandom
 200  *        The random number to use when generating the challenge,
 201  *    inSender
 202  *        The GeneralName representation of the sender of the challenge.
 203  *    inPubKey
 204  *        The public key to use when encrypting the challenge.
 205  * NOTES:
 206  *    This function adds a challenge to the end of the list of challenges
 207  *    contained by 'inDecKeyChall'.  Refer to the CMMF draft on how the
 208  *    the random number passed in and the sender's GeneralName are used
 209  *    to generate the challenge and witness fields of the challenge.  This
 210  *    library will use SHA1 as the one-way function for generating the
 211  *    witess field of the challenge.
 212  *
 213  * RETURN:
 214  *    SECSuccess if generating the challenge and adding to the end of list
 215  *    of challenges was successful.  Any other return value indicates an error
 216  *    while trying to generate the challenge.
 217  */
 218 extern SECStatus
 219 CMMF_POPODecKeyChallContentSetNextChallenge
 220                                    (CMMFPOPODecKeyChallContent *inDecKeyChall,
 221                                     long                        inRandom,
 222                                     CERTGeneralName            *inSender,
 223                                     SECKEYPublicKey            *inPubKey);
 224
 225 /*
 226  * FUNCTION: CMMF_POPODecKeyChallContentGetNumChallenges
 227  * INPUTS:
 228  *    inKeyChallCont
 229  *        The CMMFPOPODecKeyChallContent to operate on.
 230  * RETURN:
 231  *    This function returns the number of CMMFChallenges are contained in
 232  *    the CMMFPOPODecKeyChallContent structure.
 233  */
 234 extern int CMMF_POPODecKeyChallContentGetNumChallenges
 235                                   (CMMFPOPODecKeyChallContent *inKeyChallCont);
 236
 237 /*
 238  * FUNCTION: CMMF_ChallengeGetRandomNumber
 239  * INPUTS:
 240  *    inChallenge
 241  *        The CMMFChallenge to operate on.
 242  *    inDest
 243  *        A pointer to a user supplied buffer where the library
 244  *        can place a copy of the random integer contatained in the
 245  *        challenge.
 246  * NOTES:
 247  *    This function returns the value held in the decrypted Rand structure
 248  *    corresponding to the random integer.  The user must call
 249  *    CMMF_ChallengeDecryptWitness before calling this function.  Call
 250  *    CMMF_ChallengeIsDecrypted to find out if the challenge has been
 251  *    decrypted.
 252  *
 253  * RETURN:
 254  *    SECSuccess indicates the witness field has been previously decrypted
 255  *    and the value for the random integer was successfully placed at *inDest.
 256  *    Any other return value indicates an error and that the value at *inDest
 257  *    is not a valid value.
 258  */
 259 extern SECStatus CMMF_ChallengeGetRandomNumber(CMMFChallenge *inChallenge,
 260                                                long          *inDest);
 261
 262 /*
 263  * FUNCTION: CMMF_ChallengeGetSender
 264  * INPUTS:
 265  *    inChallenge
 266  *        the CMMFChallenge to operate on.
 267  * NOTES:
 268  *    This function returns the value held in the decrypted Rand structure
 269  *    corresponding to the sender.  The user must call
 270  *    CMMF_ChallengeDecryptWitness before calling this function.  Call
 271  *    CMMF_ChallengeIsDecrypted to find out if the witness field has been
 272  *    decrypted.  The user must call CERT_DestroyGeneralName after the return
 273  *    value is no longer needed.
 274  *
 275  * RETURN:
 276  *    A pointer to a copy of the sender CERTGeneralName.  A return value of
 277  *    NULL indicates an error in trying to copy the information or that the
 278  *    witness field has not been decrypted.
 279  */
 280 extern CERTGeneralName* CMMF_ChallengeGetSender(CMMFChallenge *inChallenge);
 281
 282 /*
 283  * FUNCTION: CMMF_ChallengeGetAlgId
 284  * INPUTS:
 285  *    inChallenge
 286  *        The CMMFChallenge to operate on.
 287  *    inDestAlgId
 288  *        A pointer to memory where a pointer to a copy of the algorithm
 289  *        id can be placed.
 290  * NOTES:
 291  *    This function retrieves the one way function algorithm identifier
 292  *    contained within the CMMFChallenge if the optional field is present.
 293  *
 294  * RETURN:
 295  *    SECSucces indicates the function was able to place a pointer to a copy of
 296  *    the alogrithm id at *inAlgId.  If the value at *inDestAlgId is NULL,
 297  *    that means there was no algorithm identifier present in the
 298  *    CMMFChallenge.  Any other return value indicates the function was not
 299  *    able to make a copy of the algorithm identifier.  In this case the value
 300  *    at *inDestAlgId is not valid.
 301  */
 302 extern SECStatus CMMF_ChallengeGetAlgId(CMMFChallenge  *inChallenge,
 303                                         SECAlgorithmID *inAlgId);
 304
 305 /*
 306  * FUNCTION: CMMF_DestroyChallenge
 307  * INPUTS:
 308  *    inChallenge
 309  *        The CMMFChallenge to free up.
 310  * NOTES:
 311  *    This function frees up all the memory associated with the CMMFChallenge
 312  *    passed in.
 313  * RETURN:
 314  *    SECSuccess if freeing all the memory associated with the CMMFChallenge
 315  *    passed in is successful.  Any other return value indicates an error
 316  *    while freeing the memory.
 317  */
 318 extern SECStatus CMMF_DestroyChallenge (CMMFChallenge *inChallenge);
 319
 320 /*
 321  * FUNCTION: CMMF_DestroyPOPODecKeyRespContent
 322  * INPUTS:
 323  *    inDecKeyResp
 324  *        The CMMFPOPODecKeyRespContent structure to free.
 325  * NOTES:
 326  *    This function frees up all the memory associate with the
 327  *    CMMFPOPODecKeyRespContent.
 328  *
 329  * RETURN:
 330  *    SECSuccess if freeint up all the memory associated with the
 331  *    CMMFPOPODecKeyRespContent structure is successful.  Any other
 332  *    return value indicates an error while freeing the memory.
 333  */
 334 extern SECStatus
 335      CMMF_DestroyPOPODecKeyRespContent(CMMFPOPODecKeyRespContent *inDecKeyResp);
 336
 337 /*
 338  * FUNCTION: CMMF_ChallengeDecryptWitness
 339  * INPUTS:
 340  *    inChallenge
 341  *        The CMMFChallenge to operate on.
 342  *    inPrivKey
 343  *        The private key to use to decrypt the witness field.
 344  * NOTES:
 345  *    This function uses the private key to decrypt the challenge field
 346  *    contained in the CMMFChallenge.  Make sure the private key matches the
 347  *    public key that was used to encrypt the witness.  The creator of
 348  *    the challenge will most likely be an RA that has the public key
 349  *    from a Cert request.  So the private key should be the private key
 350  *    associated with public key in that request.  This function will also
 351  *    verify the witness field of the challenge.
 352  *
 353  * RETURN:
 354  *    SECSuccess if decrypting the witness field was successful.  This does
 355  *    not indicate that the decrypted data is valid, since the private key
 356  *    passed in may not be the actual key needed to properly decrypt the
 357  *    witness field.  Meaning that there is a decrypted structure now, but
 358  *    may be garbage because the private key was incorrect.
 359  *    Any other return value indicates the function could not complete the
 360  *    decryption process.
 361  */
 362 extern SECStatus CMMF_ChallengeDecryptWitness(CMMFChallenge    *inChallenge,
 363                                               SECKEYPrivateKey *inPrivKey);
 364
 365 /*
 366  * FUNCTION: CMMF_ChallengeIsDecrypted
 367  * INPUTS:
 368  *    inChallenge
 369  *        The CMMFChallenge to operate on.
 370  * RETURN:
 371  *    This is a predicate function that returns PR_TRUE if the decryption
 372  *    process has already been performed.  The function return PR_FALSE if
 373  *    the decryption process has not been performed yet.
 374  */
 375 extern PRBool CMMF_ChallengeIsDecrypted(CMMFChallenge *inChallenge);
 376
 377 /*
 378  * FUNCTION: CMMF_DestroyPOPODecKeyChallContent
 379  * INPUTS:
 380  *    inDecKeyCont
 381  *        The CMMFPOPODecKeyChallContent to free
 382  * NOTES:
 383  *    This function frees up all the memory associated with the
 384  *    CMMFPOPODecKeyChallContent
 385  * RETURN:
 386  *    SECSuccess if freeing up all the memory associatd with the
 387  *    CMMFPOPODecKeyChallContent is successful.  Any other return value
 388  *    indicates an error while freeing the memory.
 389  *
 390  */
 391 extern SECStatus
 392  CMMF_DestroyPOPODecKeyChallContent (CMMFPOPODecKeyChallContent *inDecKeyCont);
 393