crmfres.h

安全开发库。含客户端建立ssl连接、签名、证书验证、证书发布和撤销等。编译用到nss

 *        destroyed.
 *    doFree
 *        Until the day when someone creates a sub-class of SSMCRMFRequest,
 *        this value should always be PR_TRUE.
 * 
 * NOTES:
 * This function takes of freeing up all memory associated with the
 * SSMCRMFRequest.  First the function will release the reference obtained
 * for the member mKeyPair in the function SSMCRMFRequest_Init.  The function
 * then calls CRMF_DestroyCertRequest to free the memory used by mCRMFRequest.
 * Finally, the function calls SSMResource_Destroy to free up the SSMResource
 * member before calling free on the pointer passed in.
 *
 * RETURN:
 * Function returns PR_SUCCESS upon successful destruction of the object. Any
 * other return value should be interpreted as an error.
 */
SSMStatus SSMCRMFRequest_Destroy(SSMResource *inRequest, PRBool doFree);

/*
 * FUNCTION: SSMCRMFRequest_SetAttr
 * --------------------------------
 * INPUTS:
 *    res
 *        A pointer to a SSMResource of type SSM_RESTYPE_CRMFREQ
 *    attrID
 *        The attribute to set in the request.
 *    value
 *        The data to use when setting the desired attribute.
 *
 * NOTES:
 * This function over-rides SSMResource_SetAttr which all classes inherit
 * from the SSMResource class.  This function will set the following 
 * attributes (these attributes are defined in 
 * ns/security/ssm/lib/protocol/rsrcids.h):
 *
 *    SSMAttributeID                SSMResourceAttrType     Value(s)
 *    --------------                -------------------     --------
 *    SSM_FID_CRMFREQ_KEY_TYPE      SSM_NUMERIC_ATTRIBUTE   A pointer to any
 *                                                          enumerated value 
 *                                                          with type of
 *                                                          SSMKeyGenType.
 *
 *    SSM_FID_CRMFREQ_DN            SSM_STRING_ATTRIBUTE    An RFC1485 
 *                                                          formatted DN.
 *    
 *    SSM_FID_REGTOKEN              SSM_STRING_ATTRIBUTE    A string to place
 *                                                          as the Registration
 *                                                          token for the 
 *                                                          request.
 *
 *    SSM_FID_AUTHENTICATOR         SSM_STRING_ATTRIBUTE    A string to place
 *                                                          as the 
 *                                                          Authenticator token
 *                                                          in the request.
 *
 *    SSM_FID_CRMFREQ_ESCROW_AUTHORITY SSM_STRING_ATTRIBUTE A base64 encoded 
 *                                                          DER cert to use for
 *                                                          creating the 
 *                                                          PKIArchiveOptions
 *                                                          control.
 *
 * NOTES:
 * The function return PR_SUCCESS if setting the field with the given data
 * was successful.  Any other return value should be considered an error.
 *    
 */

SSMStatus SSMCRMFRequest_SetAttr(SSMResource         *res,
                                SSMAttributeID      attrID,
                                SSMAttributeValue   *value);

/*
 * FUNCTION: SSMCRMFRequest_SetEscrowAuthority
 * -------------------------------------------
 * INPUTS:
 *    crmfReq
 *        The CRMFRequest resource to add the escrow authority to.
 *    eaCert
 *        The Certificate that belongs to the CA that wants to 
 *        escrow the private key associated with the request.
 * NOTES:
 * This function will wrap the private key in an EncryptedKey type
 * defined by CRMF and include in the CRMF request that is generated.
 *
 * RETURN:
 * PR_SUCCESS indicates the private key associated with the requested
 * was successfully wrapped and made a part of the CRMF request.  Any
 * other return value indicates an error in trying to wrap the private
 * and include it in the CRMF request.
 */
SSMStatus SSMCRMFRequest_SetEscrowAuthority(SSMCRMFRequest  *crmfReq,
                                           CERTCertificate *eaCert);

/*
 * FUNCTION: SSM_EncodeCRMFRequests
 * --------------------------------
 * INPUTS:
 *    msg
 *        The message received from the client requesting CRMF messages to 
 *        be encoded.
 *    destDER
 *        Pointer to a pre-allocated chunk of memory where the function can 
 *        place a pointer to the base64 encoded CRMF CertReqMessages
 *    destLen
 *        Pointer to a pre-allocated piece of memory where the function can
 *        place the length of the string returned in *destDER.
 *
 * NOTES:
 * This function takes a message request from the client to encode CRMF 
 * requests.  The output will be base64 DER-formatted bytes of the type
 * CertReqMessages as defined by the CRMF Internet Draft.  The function 
 * will allocate a buffer in memory to store the DER using PORT_Alloc and
 * place a pointer to the buffer at *destDER.
 *
 * RETURN:
 * The function will return PR_SUCCESS if encoding the requests was successful.
 * Any other return value should be treated as an error and the values at 
 * *destDER and *destLen should be ignored.
 */

SSMStatus SSM_EncodeCRMFRequests(SSMControlConnection * ctrl, SECItem *msg, 
                                char **destDER, SSMPRUint32 *destLen);

/*
 * FUNCTION: SSM_ProcessCMMFCertResponse
 * -------------------------------------
 * INPUTS:
 *    msg
 *        The message received from the client requesting PSM to 
 *        process a CMMF response.
 *    connection
 *        The control connection associated with the CMMF response.
 *        The connection is necessary so that the function can find
 *        the appropriate cetificate database for placing the decoded
 *        certificates.
 *
 * NOTES:
 * This function serves as the back-end for the JavaScript method
 * crypto.importUserCertificates.  It will decode the base64 DER blob passed
 * in and process it.  Eventually this function will also start the process
 * of backing up the certificate when PSM supports that feature.  
 * View the document at http://warp/hardcore/library/arch/cert-issue.html
 * to see a detailed explanation for what this function doess.
 * 
 */
SSMStatus SSM_ProcessCMMFCertResponse(SECItem              *msg, 
                                     SSMControlConnection *connection);

/*
 * FUNCTION: SSM_RespondToPOPChallenge
 * -----------------------------------
 * INPUTS:
 *    msg
 *        The message received from the client requesting that PSM
 *        respond to a challenge.
 *    ctrl
 *        The Control Connection associated with the message to process.
 *    challengeResponse
 *        A pointer to a pre-allocated pointer where the function can place
 *        a copy of the base64 encoded response to the challenge.  The 
 *        response will be a POPODecKeyRespContent defined in the CMMF 
 *        internet draft.
 *    responseLen
 *        A pointer to a pre-allocated PRUint32 where the function can place
 *        the length of the response returned via the challengeResponse input
 *        parameter.
 *
 * NOTES:
 * This function servers as the back-end for the JavaScript method
 * crypto.popChallengeRespone.  The function will decode the base64 DER blob
 * passed in and process it.
 */
SSMStatus SSM_RespondToPOPChallenge(SECItem                *msg, 
                                   SSMControlConnection   *ctrl,
                                   char                  **challengeResponse, 
                                   PRUint32               *responseLen);

typedef struct SSMCRMFThreadArgStr {
    SSMControlConnection *ctrl;
    SECItem              *msg;
} SSMCRMFThreadArg;

/*
 * FUNCTION: SSM_CRMFEncodeThread
 * ------------------------------
 * INPUTS:
 *    arg
 *        A pointer to a structure of type SSMCRMFThreadArg which the function
 *        will use to encode a CRMF request.
 * NOTES:
 * This function is intended to encode a CRMF request taking a message from
 * the client as its argument along with the associated control thread.  This
 * function will send the reply back to the client in case of success or 
 * failure so the client may proceed with its operations.
 * RETURN:
 * No return value.
 */
void SSM_CRMFEncodeThread(void *arg);
#endif /* _CRMFRES_H_ */