The Tor Browser: security/nss/lib/crmf/crmffut.h@6474c204b198 (annotated)

security/nss/lib/crmf/crmffut.h@6474c204b198 (annotated)

security/nss/lib/crmf/crmffut.h

Wed, 31 Dec 2014 06:09:35 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:09:35 +0100
changeset 0: 6474c204b198
permissions: -rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 /*
  * These functions to be implemented in the future if the features
  * which these functions would implement wind up being needed.
  */
 /*
  * Use this function to create the CRMFSinglePubInfo* variables that will
  * populate the inPubInfoArray parameter for the function
  * CRMF_CreatePKIPublicationInfo.
  *
  * "inPubMethod" specifies which publication method will be used
  * "pubLocation" is a representation of the location where
  */
 extern CRMFSinglePubInfo*
       CRMF_CreateSinglePubInfo(CRMFPublicationMethod  inPubMethod,
 			       CRMFGeneralName       *pubLocation);
 /*
  * Create a PKIPublicationInfo that can later be passed to the function
  * CRMFAddPubInfoControl.
  */
 extern CRMFPKIPublicationInfo *
      CRMF_CreatePKIPublicationInfo(CRMFPublicationAction  inAction,
 				   CRMFSinglePubInfo    **inPubInfoArray,
 				   int                    numPubInfo);
 /*
  * Only call this function on a CRMFPublicationInfo that was created by
  * CRMF_CreatePKIPublicationInfo that was passed in NULL for arena.
  */
 extern SECStatus
        CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo);
 extern SECStatus CRMF_AddPubInfoControl(CRMFCertRequest        *inCertReq,
 					CRMFPKIPublicationInfo *inPubInfo);
 /*
  * This is to create a Cert ID Control which can later be added to
  * a certificate request.
  */
 extern CRMFCertID* CRMF_CreateCertID(CRMFGeneralName *issuer,
 				     long             serialNumber);
 extern SECStatus CRMF_DestroyCertID(CRMFCertID* certID);
 extern SECStatus CRMF_AddCertIDControl(CRMFCertRequest *inCertReq,
 				       CRMFCertID      *certID);
 extern SECStatus
        CRMF_AddProtocolEncryptioKeyControl(CRMFCertRequest          *inCertReq,
 					   CERTSubjectPublicKeyInfo *spki);
 /*
  * Add the ASCII Pairs Registration Info to the Certificate Request.
  * The SECItem must be an OCTET string representation.
  */
 extern SECStatus
        CRMF_AddUTF8PairsRegInfo(CRMFCertRequest *inCertReq,
 				 SECItem         *asciiPairs);
 /*
  * This takes a CertRequest and adds it to another CertRequest.
  */
 extern SECStatus
        CRMF_AddCertReqToRegInfo(CRMFCertRequest *certReqToAddTo,
 				CRMFCertRequest *certReqBeingAdded);
 /*
  * Returns which option was used for the authInfo field of POPOSigningKeyInput
  */
 extern CRMFPOPOSkiInputAuthChoice
        CRMF_GetSignKeyInputAuthChoice(CRMFPOPOSigningKeyInput *inKeyInput);
 /*
  * Gets the PKMACValue associated with the POPOSigningKeyInput.
  * If the POPOSigningKeyInput did not use authInfo.publicKeyMAC
  * the function returns SECFailure and the value at *destValue is unchanged.
  *
  * If the POPOSigningKeyInput did use authInfo.publicKeyMAC, the function
  * returns SECSuccess and places the PKMACValue at *destValue.
  */
 extern SECStatus
        CRMF_GetSignKeyInputPKMACValue(CRMFPOPOSigningKeyInput *inKeyInput,
 				      CRMFPKMACValue          **destValue);
 /*
  * Gets the SubjectPublicKeyInfo from the POPOSigningKeyInput
  */
 extern CERTSubjectPublicKeyInfo *
        CRMF_GetSignKeyInputPublicKey(CRMFPOPOSigningKeyInput *inKeyInput);
 /*
  * Return the value for the PKIPublicationInfo Control.
  * A return value of NULL indicates that the Control was
  * not a PKIPublicationInfo Control.  Call
  * CRMF_DestroyPKIPublicationInfo on the return value when done
  * using the pointer.
  */
 extern CRMFPKIPublicationInfo* CRMF_GetPKIPubInfo(CRMFControl *inControl);
 /*
  * Free up a CRMFPKIPublicationInfo structure.
  */
 extern SECStatus
        CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo);
 /*
  * Get the choice used for action in this PKIPublicationInfo.
  */
 extern CRMFPublicationAction
        CRMF_GetPublicationAction(CRMFPKIPublicationInfo *inPubInfo);
 /*
  * Get the number of pubInfos are stored in the PKIPubicationInfo.
  */
 extern int CRMF_GetNumPubInfos(CRMFPKIPublicationInfo *inPubInfo);
 /*
  * Get the pubInfo at index for the given PKIPubicationInfo.
  * Indexing is done like a traditional C Array. (0 .. numElements-1)
  */
 extern CRMFSinglePubInfo*
        CRMF_GetPubInfoAtIndex(CRMFPKIPublicationInfo *inPubInfo,
 			      int                     index);
 /*
  * Destroy the CRMFSinglePubInfo.
  */
 extern SECStatus CRMF_DestroySinglePubInfo(CRMFSinglePubInfo *inPubInfo);
 /*
  * Get the pubMethod used by the SinglePubInfo.
  */
 extern CRMFPublicationMethod
        CRMF_GetPublicationMethod(CRMFSinglePubInfo *inPubInfo);
 /*
  * Get the pubLocation associated with the SinglePubInfo.
  * A NULL return value indicates there was no pubLocation associated
  * with the SinglePuInfo.
  */
 extern CRMFGeneralName* CRMF_GetPubLocation(CRMFSinglePubInfo *inPubInfo);
 /*
  * Get the authInfo.sender field out of the POPOSigningKeyInput.
  * If the POPOSigningKeyInput did not use the authInfo the function
  * returns SECFailure and the value at *destName is unchanged.
  *
  * If the POPOSigningKeyInput did use authInfo.sender, the function returns
  * SECSuccess and puts the authInfo.sender at *destName/
  */
 extern SECStatus CRMF_GetSignKeyInputSender(CRMFPOPOSigningKeyInput *keyInput,
 					    CRMFGeneralName        **destName);
 /**************** CMMF Functions that need to be added. **********************/
 /*
  * FUNCTION: CMMF_POPODecKeyChallContentSetNextChallenge
  * INPUTS:
  *    inDecKeyChall
  *        The CMMFPOPODecKeyChallContent to operate on.
  *    inRandom
  *        The random number to use when generating the challenge,
  *    inSender
  *        The GeneralName representation of the sender of the challenge.
  *    inPubKey
  *        The public key to use when encrypting the challenge.
  * NOTES:
  *    This function adds a challenge to the end of the list of challenges
  *    contained by 'inDecKeyChall'.  Refer to the CMMF draft on how the
  *    the random number passed in and the sender's GeneralName are used
  *    to generate the challenge and witness fields of the challenge.  This
  *    library will use SHA1 as the one-way function for generating the
  *    witess field of the challenge.
  *
  * RETURN:
  *    SECSuccess if generating the challenge and adding to the end of list
  *    of challenges was successful.  Any other return value indicates an error
  *    while trying to generate the challenge.
  */
 extern SECStatus
 CMMF_POPODecKeyChallContentSetNextChallenge
                                    (CMMFPOPODecKeyChallContent *inDecKeyChall,
 				    long                        inRandom,
 				    CERTGeneralName            *inSender,
 				    SECKEYPublicKey            *inPubKey);
 /*
  * FUNCTION: CMMF_POPODecKeyChallContentGetNumChallenges
  * INPUTS:
  *    inKeyChallCont
  *        The CMMFPOPODecKeyChallContent to operate on.
  * RETURN:
  *    This function returns the number of CMMFChallenges are contained in
  *    the CMMFPOPODecKeyChallContent structure.
  */
 extern int CMMF_POPODecKeyChallContentGetNumChallenges
                                   (CMMFPOPODecKeyChallContent *inKeyChallCont);
 /*
  * FUNCTION: CMMF_ChallengeGetRandomNumber
  * INPUTS:
  *    inChallenge
  *        The CMMFChallenge to operate on.
  *    inDest
  *        A pointer to a user supplied buffer where the library
  *        can place a copy of the random integer contatained in the
  *        challenge.
  * NOTES:
  *    This function returns the value held in the decrypted Rand structure
  *    corresponding to the random integer.  The user must call
  *    CMMF_ChallengeDecryptWitness before calling this function.  Call
  *    CMMF_ChallengeIsDecrypted to find out if the challenge has been
  *    decrypted.
  *
  * RETURN:
  *    SECSuccess indicates the witness field has been previously decrypted
  *    and the value for the random integer was successfully placed at *inDest.
  *    Any other return value indicates an error and that the value at *inDest
  *    is not a valid value.
  */
 extern SECStatus CMMF_ChallengeGetRandomNumber(CMMFChallenge *inChallenge,
 					       long          *inDest);
 /*
  * FUNCTION: CMMF_ChallengeGetSender
  * INPUTS:
  *    inChallenge
  *        the CMMFChallenge to operate on.
  * NOTES:
  *    This function returns the value held in the decrypted Rand structure
  *    corresponding to the sender.  The user must call
  *    CMMF_ChallengeDecryptWitness before calling this function.  Call
  *    CMMF_ChallengeIsDecrypted to find out if the witness field has been
  *    decrypted.  The user must call CERT_DestroyGeneralName after the return
  *    value is no longer needed.
  *
  * RETURN:
  *    A pointer to a copy of the sender CERTGeneralName.  A return value of
  *    NULL indicates an error in trying to copy the information or that the
  *    witness field has not been decrypted.
  */
 extern CERTGeneralName* CMMF_ChallengeGetSender(CMMFChallenge *inChallenge);
 /*
  * FUNCTION: CMMF_ChallengeGetAlgId
  * INPUTS:
  *    inChallenge
  *        The CMMFChallenge to operate on.
  *    inDestAlgId
  *        A pointer to memory where a pointer to a copy of the algorithm
  *        id can be placed.
  * NOTES:
  *    This function retrieves the one way function algorithm identifier
  *    contained within the CMMFChallenge if the optional field is present.
  *
  * RETURN:
  *    SECSucces indicates the function was able to place a pointer to a copy of
  *    the alogrithm id at *inAlgId.  If the value at *inDestAlgId is NULL,
  *    that means there was no algorithm identifier present in the
  *    CMMFChallenge.  Any other return value indicates the function was not
  *    able to make a copy of the algorithm identifier.  In this case the value
  *    at *inDestAlgId is not valid.
  */
 extern SECStatus CMMF_ChallengeGetAlgId(CMMFChallenge  *inChallenge,
 					SECAlgorithmID *inAlgId);
 /*
  * FUNCTION: CMMF_DestroyChallenge
  * INPUTS:
  *    inChallenge
  *        The CMMFChallenge to free up.
  * NOTES:
  *    This function frees up all the memory associated with the CMMFChallenge
  *    passed in.
  * RETURN:
  *    SECSuccess if freeing all the memory associated with the CMMFChallenge
  *    passed in is successful.  Any other return value indicates an error
  *    while freeing the memory.
  */
 extern SECStatus CMMF_DestroyChallenge (CMMFChallenge *inChallenge);
 /*
  * FUNCTION: CMMF_DestroyPOPODecKeyRespContent
  * INPUTS:
  *    inDecKeyResp
  *        The CMMFPOPODecKeyRespContent structure to free.
  * NOTES:
  *    This function frees up all the memory associate with the
  *    CMMFPOPODecKeyRespContent.
  *
  * RETURN:
  *    SECSuccess if freeint up all the memory associated with the
  *    CMMFPOPODecKeyRespContent structure is successful.  Any other
  *    return value indicates an error while freeing the memory.
  */
 extern SECStatus
      CMMF_DestroyPOPODecKeyRespContent(CMMFPOPODecKeyRespContent *inDecKeyResp);
 /*
  * FUNCTION: CMMF_ChallengeDecryptWitness
  * INPUTS:
  *    inChallenge
  *        The CMMFChallenge to operate on.
  *    inPrivKey
  *        The private key to use to decrypt the witness field.
  * NOTES:
  *    This function uses the private key to decrypt the challenge field
  *    contained in the CMMFChallenge.  Make sure the private key matches the
  *    public key that was used to encrypt the witness.  The creator of
  *    the challenge will most likely be an RA that has the public key
  *    from a Cert request.  So the private key should be the private key
  *    associated with public key in that request.  This function will also
  *    verify the witness field of the challenge.
  *
  * RETURN:
  *    SECSuccess if decrypting the witness field was successful.  This does
  *    not indicate that the decrypted data is valid, since the private key
  *    passed in may not be the actual key needed to properly decrypt the
  *    witness field.  Meaning that there is a decrypted structure now, but
  *    may be garbage because the private key was incorrect.
  *    Any other return value indicates the function could not complete the
  *    decryption process.
  */
 extern SECStatus CMMF_ChallengeDecryptWitness(CMMFChallenge    *inChallenge,
 					      SECKEYPrivateKey *inPrivKey);
 /*
  * FUNCTION: CMMF_ChallengeIsDecrypted
  * INPUTS:
  *    inChallenge
  *        The CMMFChallenge to operate on.
  * RETURN:
  *    This is a predicate function that returns PR_TRUE if the decryption
  *    process has already been performed.  The function return PR_FALSE if
  *    the decryption process has not been performed yet.
  */
 extern PRBool CMMF_ChallengeIsDecrypted(CMMFChallenge *inChallenge);
 /*
  * FUNCTION: CMMF_DestroyPOPODecKeyChallContent
  * INPUTS:
  *    inDecKeyCont
  *        The CMMFPOPODecKeyChallContent to free
  * NOTES:
  *    This function frees up all the memory associated with the
  *    CMMFPOPODecKeyChallContent
  * RETURN:
  *    SECSuccess if freeing up all the memory associatd with the
  *    CMMFPOPODecKeyChallContent is successful.  Any other return value
  *    indicates an error while freeing the memory.
  *
  */
 extern SECStatus
  CMMF_DestroyPOPODecKeyChallContent (CMMFPOPODecKeyChallContent *inDecKeyCont);

The Tor Browser / annotate

security/nss/lib/crmf/crmffut.h@6474c204b198 (annotated)

security/nss/lib/crmf/crmffut.h