cmmf.h

来自「支持SSL v2/v3, TLS, PKCS #5, PKCS #7, PKCS」· C头文件 代码 · 共 1,120 行 · 第 1/3 页

 *    User must call CERT_DestroyCertList when the return value is no longer 
 *    needed.  All of these certificates will be placed in the tempoaray
 *    database.
 *
 * RETURN:
 *    A pointer to the list of caCerts contained in the CMMFKeyRecRepContent
 *    structure.  A return value of NULL indicates the library was not able to 
 *    make a copy of the certifcates.  This may be because there are no caCerts
 *    included in the CMMFKeyRecRepContent strucure or an internal error.  Call
 *    CMMF_KeyRecRepContentHasCACerts to find out if there are any caCerts 
 *    included in 'inKeyRecRep'.
 */
extern CERTCertList*
       CMMF_KeyRecRepContentGetCACerts(CMMFKeyRecRepContent *inKeyRecRep);

/*
 * FUNCTION: CMMF_KeyRecRepContentGetNumKeyPairs
 * INPUTS:
 *    inKeyRecRep
 *        The CMMFKeyRecRepContent to operate on.
 * RETURN:
 *    This function returns the number of CMMFCertifiedKeyPair structures that
 *    that are stored in the KeyRecRepContent structure.
 */
extern int 
       CMMF_KeyRecRepContentGetNumKeyPairs(CMMFKeyRecRepContent *inKeyRecRep);

/*
 * FUNCTION: CMMF_KeyRecRepContentGetCertKeyAtIndex
 * INPUTS:
 *    inKeyRecRepContent
 *        The CMMFKeyRecRepContent to operate on.
 *    inIndex
 *        The index of the desired CMMFCertifiedKeyPair
 * NOTES:
 *    This function retrieves the CMMFCertifiedKeyPair structure at the index
 *    'inIndex'.  Valid indexes are 0...(numKeyPairs-1)  The user must call 
 *    CMMF_DestroyCertifiedKeyPair when the return value is no longer needed.
 *
 * RETURN:
 *    A pointer to the Certified Key Pair at the desired index.  A return value
 *    of NULL indicates an error in extracting the Certified Key Pair at the 
 *    desired index.
 */
extern CMMFCertifiedKeyPair*
      CMMF_KeyRecRepContentGetCertKeyAtIndex(CMMFKeyRecRepContent *inKeyRecRep,
					     int                   inIndex);

/*
 * FUNCTION: CMMF_CertifiedKeyPairGetCertificate
 * INPUTS:
 *    inCertKeyPair
 *        The CMMFCertifiedKeyPair to operate on.
 *    inCertdb
 *        The database handle for the database you want this certificate
 *        to wind up in.
 * NOTES:
 *    This function retrieves the certificate at 
 *    CertifiedKeyPair.certOrEncCert.certificate
 *    The user must call CERT_DestroyCertificate when the return value is no
 *    longer needed.  The user must import this certificate as a token object
 *    onto PKCS#11 slot in order to make it a permanent object.  The returned
 *    certificate will be in the temporary database.
 * 
 * RETURN:
 *    A pointer to the certificate contained within the certified key pair.
 *    A return value of NULL indicates an error in creating the copy of the 
 *    certificate.
 */
extern CERTCertificate*
      CMMF_CertifiedKeyPairGetCertificate(CMMFCertifiedKeyPair *inCertKeyPair,
					  CERTCertDBHandle     *inCertdb);

/*
 * 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_POPODecKeyChallContentGetPublicValue
 * ---------------------------------------------------
 * INPUTS:
 *    inKeyChallCont
 *        The CMMFPOPODecKeyChallContent to operate on.
 *    inIndex
 *        The index of the Challenge within inKeyChallCont to operate on.
 *        Indexes start from 0, ie the Nth Challenge corresponds to index
 *        N-1.
 * NOTES:
 * This function retrieves the public value stored away in the Challenge at
 * index inIndex of inKeyChallCont.
 * RETURN:
 * A pointer to a SECItem containing the public value.  User must call 
 * SECITEM_FreeItem on the return value when the value is no longer necessary.
 * A return value of NULL indicates an error while retrieving the public value.
 */
extern SECItem* CMMF_POPODecKeyChallContentGetPublicValue
                                   (CMMFPOPODecKeyChallContent *inKeyChallCont,
				    int                         inIndex);


/*
 * FUNCTION: CMMF_POPODecKeyChallContentGetRandomNumber
 * INPUTS:
 *    inChallContent
 *        The CMMFPOPODecKeyChallContent to operate on.
 *    inIndex
 *        The index of the challenge to look at.  Valid indexes are 0 through
 *        (CMMF_POPODecKeyChallContentGetNumChallenges(inChallContent) - 1).
 *    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_POPODecKeyChallContentDecryptChallenge 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_POPODecKeyChallContentGetRandomNumber
                                      (CMMFPOPODecKeyChallContent *inKeyChallCont,
				       int                          inIndex,
				       long                        *inDest);

/*
 * FUNCTION: CMMF_POPODecKeyRespContentGetNumResponses
 * INPUTS:
 *    inRespCont
 *        The POPODecKeyRespContent to operate on.
 * RETURN:
 * This function returns the number of responses contained in inRespContent.
 */
extern int 
 CMMF_POPODecKeyRespContentGetNumResponses(CMMFPOPODecKeyRespContent *inRespCont);

/*
 * FUNCTION: CMMF_POPODecKeyRespContentGetResponse
 * INPUTS:
 *    inRespCont
 *        The POPODecKeyRespContent to operate on.
 *    inIndex
 *        The index of the response to retrieve.
 *        The Nth response is at index N-1, ie the 1st response is at index 0,
 *        the 2nd response is at index 1, and so on.
 *    inDest
 *        A pointer to a pre-allocated buffer where the library can put the 
 *        value of the response located at inIndex.
 * NOTES:
 * The function returns the response contained at index inIndex.  
 * CMMFPOPODecKeyRespContent is a structure that the server will generally 
 * get in response to a CMMFPOPODecKeyChallContent.  The server will expect
 * to see the responses in the same order as it constructed them in 
 * the CMMFPOPODecKeyChallContent structure.
 * RETURN:
 * SECSuccess if getting the response at the desired index was successful.  Any
 * other return value indicates an errror.
 */
extern SECStatus
     CMMF_POPODecKeyRespContentGetResponse (CMMFPOPODecKeyRespContent *inRespCont,
					    int                        inIndex,
					    long                      *inDest);

/************************* Destructor Functions ******************************/

/*
 * FUNCTION: CMMF_DestroyCertResponse
 * INPUTS:
 *    inCertResp
 *        The CMMFCertResponse to destroy.
 * NOTES:
 *    This function frees all the memory associated with the CMMFCertResponse
 *    passed in.
 * RETURN:
 *    SECSuccess if freeing the memory was successful.  Any other return value
 *    indicates an error while freeing the memory.
 */
extern SECStatus CMMF_DestroyCertResponse(CMMFCertResponse *inCertResp);

/*
 * FUNCTION: CMMF_DestroyCertRepContent
 * INPUTS:
 *    inCertRepContent
 *        The CMMFCertRepContent to destroy
 * NOTES:
 *    This function frees the memory associated with the CMMFCertRepContent
 *    passed in.
 * RETURN:
 *    SECSuccess if freeing all the memory associated with the 
 *    CMMFCertRepContent passed in is successful.  Any other return value 
 *    indicates an error while freeing the memory.
 */
extern SECStatus 
       CMMF_DestroyCertRepContent (CMMFCertRepContent *inCertRepContent);

/*
 * FUNCTION: CMMF_DestroyKeyRecRepContent
 * INPUTS:
 *    inKeyRecRep
 *        The CMMFKeyRecRepContent to destroy.
 * NOTES:
 *    This function destroys all the memory associated with the 
 *    CMMFKeyRecRepContent passed in.
 *
 * RETURN:
 *    SECSuccess if freeing all the memory is successful.  Any other return 
 *    value indicates an error in freeing the memory.
 */
extern SECStatus 
       CMMF_DestroyKeyRecRepContent(CMMFKeyRecRepContent *inKeyRecRep);

/*
 * FUNCTION: CMMF_DestroyCertifiedKeyPair
 * INPUTS:
 *    inCertKeyPair
 *        The CMMFCertifiedKeyPair to operate on.
 * NOTES: 
 *    This function frees up all the memory associated with 'inCertKeyPair'
 *
 * RETURN:
 *    SECSuccess if freeing all the memory associated with 'inCertKeyPair'
 *    is successful.  Any other return value indicates an error while trying
 *    to free the memory.
 */
extern SECStatus 
       CMMF_DestroyCertifiedKeyPair(CMMFCertifiedKeyPair *inCertKeyPair);

/*
 * 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 freeing 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);


/************************** Miscellaneous Functions *************************/
 
/*
 * FUNCTION: CMMF_CertifiedKeyPairUnwrapPrivKey
 * INPUTS:
 *    inCertKeyPair
 *        The CMMFCertifiedKeyPair to operate on.
 *    inPrivKey
 *        The private key to use to un-wrap the private key
 *    inNickName
 *        This is the nickname that will be associated with the private key
 *        to be unwrapped.
 *    inSlot
 *        The PKCS11 slot where the unwrapped private key should end up.
 *    inCertdb
 *        The Certificate database with which the new key will be associated.
 *    destPrivKey
 *        A pointer to memory where the library can place a pointer to the
 *        private key after importing the key onto the specified slot.
 *    wincx
 *        An opaque pointer that the library will use in a callback function
 *        to get the password if necessary.
 *    
 * NOTES:
 *    This function uses the private key passed in to unwrap the private key
 *    contained within the CMMFCertifiedKeyPair structure. After this 
 *    function successfully returns, the private key has been unwrapped and
 *    placed in the specified slot. 
 *
 * RETURN:
 *    SECSuccess if unwrapping the private key was successful.  Any other 
 *    return value indicates an error while trying to un-wrap the private key.
 */
extern SECStatus 
       CMMF_CertifiedKeyPairUnwrapPrivKey(CMMFCertifiedKeyPair *inKeyPair,
					  SECKEYPrivateKey     *inPrivKey,
					  SECItem              *inNickName,
					  PK11SlotInfo         *inSlot,
                                          CERTCertDBHandle     *inCertdb,
					  SECKEYPrivateKey    **destPrivKey,
					  void                 *wincx);

/*
 * FUNCTION: CMMF_KeyRecRepContentHasCACerts
 * INPUTS:
 *    inKeyRecRecp
 *        The CMMFKeyRecRepContent to operate on.
 * RETURN:
 *    This function returns PR_TRUE if there are one or more certificates in 
 *    the sequence KeyRecRepContent.caCerts within the CMMFKeyRecRepContent
 *    structure.  The function will return PR_FALSE if there are 0 certificate
 *    in the above mentioned sequence.
 */
extern PRBool 
       CMMF_KeyRecRepContentHasCACerts(CMMFKeyRecRepContent *inKeyRecRep);

/*
 * FUNCTION: CMMF_POPODecKeyChallContDecryptChallenge
 * INPUTS:
 *    inChalCont
 *        The CMMFPOPODecKeyChallContent to operate on.
 *    inIndex
 *        The index of the Challenge to operate on.  The 1st Challenge is
 *        at index 0, the second at index 1 and so forth.
 *    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 appropriate challenge.  Make sure the private key matches 
 *    the public key that was used to encrypt the witness.  Use 
 *    CMMF_POPODecKeyChallContentGetPublicValue to get the public value of
 *    the key used to encrypt the witness and then use that to determine the
 *    appropriate private key.  This can be done by calling PK11_MakeIDFromPubKey
 *    and then passing that return value to PK11_FindKeyByKeyID.  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.  This function also verifies
 *    that the sender and witness hashes match within 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_POPODecKeyChallContDecryptChallenge(CMMFPOPODecKeyChallContent *inChalCont,
					   int                         inIndex,
					   SECKEYPrivateKey           *inPrivKey);

/*
 * 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);

SEC_END_PROTOS
#endif /* _CMMF_H_ */