cmtjs.h

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

 *    control
 *        The Control Connection that has already established a connection
 *        with the psm server.
 *    resType
 *        The enumeration representing the resource type to create.
 *    params
 *        A resource dependent binary string that will be sent to the psm 
 *        server. Each resource will expect a binary string it defines.
 *    rsrcId
 *        A pointer to a pre-allocated chunk of memory where the library
 *        can place the resource ID of the newly created resource.
 *    errorCode
 *        A pointer to a pre-allocated chunk of memory where the library
 *        can place the errorCode returned by the psm server after creating
 *        the resource.
 * NOTES:
 * This function sends a message to the psm server requesting that a new 
 * resource be created.  The params parameter depends on the type of resource
 * being created.  Below is a table detailing the format of the params for 
 * a given resource type. Only the resource types listed below can be created
 * by calling this function.
 *
 * Resource Type constant                  Value for params
 * ------------------------------          ----------------
 * SSM_RESTYPE_KEYGEN_CONTEXT              NULL
 * SSM_RESTYPE_SECADVISOR_CONTEXT          NULL
 * SSM_RESTYPE_SIGNTEXT                    NULL
 *
 * RETURN
 * A return value of CMTSuccess means the psm server received the request and
 * processed the create resource create. If the value at *errorCode is zero,
 * then the value at *rsrcId is the resource ID of the newly created resource.
 * Otherwise, creating the new resource failed and *errorCode contains the
 * error code returned by the psm server. ???What are the return values and
 * what do they mean. Any other return value indicates there was an error 
 * in the communication with the psm server and the values at *rsrcId and 
 * *errorCode should be ignored.
 */
CMTStatus
CMT_CreateResource(PCMT_CONTROL control, SSMResourceType resType,
		   CMTItem *params, CMUint32 *rsrcId, CMUint32 *errorCode);

/*
 * FUNCTION: CMT_SignText
 * ----------------------
 * INPUTS:
 *    control
 *        The Control Connection that has already established a connection
 *        with the psm server.
 *    resID
 *        The resource ID of an SSMSignTextResource.
 *    stringToSign
 *        The string that the psm server should sign.
 *    hostName
 *        The host name of the site that is requesting a string to be
 *        signed.  This is used for displaying the UI that tells the user
 *        a web site has requested the use sign some text.
 *    caOption
 *        If the value is "auto" then psm will select the certificate
 *        to use for signing automatically.
 *        If the value is "ask" then psm will display a list of 
 *        certificates for signing.
 *    numCAs
 *        The number of CA names included in the array caNames passed in as
 *        the last parameter to this function.
 *    caNames
 *        An array of CA Names to use for filtering the user certs to use
 *        for signing the text.
 * NOTES
 * This function will sign the text passed via the parameter stringToSign.
 * The function will also cause the psm server to send some UI notifying the
 * user that a site has requested the user sign some text.  The hostName 
 * parameter is used in the UI to inform the user which site is requesting
 * the signed text.  The caOption is used to determine if the psm server 
 * should automatically select which personal cert to use in signing the
 * text.  The caNames array is ussed to narrow down the field of personal
 * certs to use when signing the text. In other words, only personal certs 
 * trusted by the CA's passed in will be used.
 *
 * RETURN
 * If the function returns CMTSuccess, that indicates the psm server 
 * successfully signed the text.  The signed text can be retrieved by 
 * calling CMT_GetStringResource and passing in SSM_FID_SIGNTEXT_RESULT
 * as the field ID. Any other return value indicates an error meaning the
 * string was not signed successfully.
 */
CMTStatus
CMT_SignText(PCMT_CONTROL control, CMUint32 resID, char* stringToSign,
             char* hostName, char *caOption, CMInt32 numCAs, char** caNames);

/*
 * FUNCTION: CMT_ProcessChallengeResponse
 * --------------------------------------
 * INPUTS:
 *    control
 *        The Control Connection that has already established a connection
 *        with the psm server.
 *    challengeString
 *        The base64 encoded Challenge string received as the 
 *        Proof-Of-Possession Challenge in response to CRMF request that
 *        specified Challenge-Reponse as the method for Proof-Of-Possession.
 *    responseString
 *        A pointer to pre-allocated char* where the library can place a
 *        copy of the bas64 encoded response to the challenge presented.
 * NOTES
 * This function takes the a challenge--that is encrypted with the public key
 * of a certificate we created--and decrypts it with the private key we 
 * generated.  The format of the challenge is as follows:
 *
 * Challenge ::= SEQUENCE { 
 *      owf                 AlgorithmIdentifier  OPTIONAL, 
 *      -- MUST be present in the first Challenge; MAY be omitted in any 
 *      -- subsequent Challenge in POPODecKeyChallContent (if omitted, 
 *      -- then the owf used in the immediately preceding Challenge is 
 *      -- to be used). 
 *      witness             OCTET STRING, 
 *      -- the result of applying the one-way function (owf) to a 
 *      -- randomly-generated INTEGER, A.  [Note that a different 
 *      -- INTEGER MUST be used for each Challenge.] 
 *      sender              GeneralName, 
 *      -- the name of the sender. 
 *      key                 OCTET STRING, 
 *      -- the public key used to encrypt the challenge.  This will allow 
 *      -- the client to find the appropriate key to do the decryption. 
 *      challenge           OCTET STRING 
 *      -- the encryption (under the public key for which the cert. 
 *      -- request is being made) of Rand, where Rand is specified as 
 *      --   Rand ::= SEQUENCE { 
 *      --      int      INTEGER, 
 *      --       - the randomly-generated INTEGER A (above) 
 *      --      senderHash  OCTET STRING 
 *      --       - the result of applying the one-way function (owf) to 
 *      --       - the sender's general name 
 *      --   } 
 *      -- the size of "int" must be small enough such that "Rand" can be 
 *      -- contained within a single PKCS #1 encryption block. 
 *  } 
 * This challenge is based on the Challenge initially defined in the CMMF
 * internet draft, but differs in that this structure includes the sender
 * as part of the challenge along with the public key and includes a has
 * of the sender in the encrypted Rand structure.  The reason for including
 * the key is to facilitate looking up the key that should be used to 
 * decipher the challenge.  Including the hash of the sender in the encrypted
 * Rand structure makes the challenge smaller and allows it to fit in 
 * one RSA block. 
 *
 * The response is of the type POPODecKeyRespContent as defined in the CMMF
 * internet draft.
 *
 * RETURN
 * A return value of CMTSuccess indicates psm successfully parsed and processed
 * the challenge and created a response.  The base64 encoded response to the
 * challenge is placed at *responseString.  Any other return value indicates
 * an error and the value at *responseString should be ignored.
 */
CMTStatus
CMT_ProcessChallengeResponse(PCMT_CONTROL control, char *challengeString,
			     char **responseString);

/*
 * FUNCTION: CMT_GetLocalizedString
 * --------------------------------
 * INPUTS:
 *    control
 *        The Control Connection that has already established a connection
 *        with the psm server.
 *    whichString
 *        The enumerated value corresponding to the localized string to 
 *        retrieve from the psm server
 *    localizedString
 *        A pointer to a pre-allocated char* where the library can place 
 *        copy of the localized string retrieved from the psm server.
 * NOTES
 * This function retrieves a localized string from the psm server.  These 
 * strings are useful for strings that aren't localized in the client 
 * making use of the psm server, but need to be displayed by the user. Look
 * in protocol.h for the enumerations of the localized strings that can 
 * be fetched from psm via this method.
 *
 * RETURN
 * A return value of CMTSuccess indicates the localized string was retrieved
 * successfully and the localized value is located at *localizedString.  Any
 * other return value indicates an error and the value at *localizedString
 * should be ignored.
 */
CMTStatus 
CMT_GetLocalizedString(PCMT_CONTROL        control, 
                       SSMLocalizedString  whichString,
                       char              **localizedString); 

/*
 * FUNCTION: CMT_DeleteModule
 * --------------------------
 * INPUTS:
 *    control
 *        The Control Connection that has already established a connection
 *        with the psm server.
 *    moduleName
 *        The name of the PKCS11 module to delete.
 *    moduleType
 *        A pointer to a pre-allocated integer where the library can place
 *        a value that tells what the type of module was deleted.
 * NOTES
 * This function will send a message to the psm server requesting the server 
 * delete a PKCS-11 module stored in psm's security module database. moduleName
 * is the value passed in as moduleName when the module was added to the 
 * security module database of psm.
 * The values that may be returned by psm for moduleType are:
 *
 *    0      The module was an external module developped by a third party
 *           that was added to the psm security module.
 *
 *    1      The module deleted was the internal PKCS-11 module that comes
 *           built in with the psm server.
 *
 *    2      The module that was deleted was the FIPS  internal module.
 *
 * RETURN
 * A return value of CMTSuccess indicates the security module was successfully
 * delete from the psm security module database and the value at *moduleType
 * will tell what type of module was deleted.
 * Any other return value indicates an error and the value at *moduleType 
 * should be ignored.
 */
CMTStatus
CMT_DeleteModule(PCMT_CONTROL  control,
                 char         *moduleName,
                 int          *moduleType);


/*
 * FUNCTION: CMT_AddNewModule
 * --------------------------
 * INPUTS:
 *    control
 *        The Control Connection that has already established a connection
 *        with the psm server.
 *    moduleName
 *        The name to be associated with the module once it is added to 
 *        the psm security module database.
 *    libraryPath
 *        The path to the library to be  loaded.  The library should be 
 *        loadable at run-time.
 *    pubMechFlags
 *        A bit vector indicating all cryptographic mechanisms that should
 *        be turned on by default.  This module will become the default 
 *        handler for the mechanisms that are set by this bit vector.
 *    pubCipherFlags
 *        A bit vector indicating all SSL or S/MIME cipher functions
 *        supported by the module. Most modules will pas in 0x0 for this
 *        parameter.
 * NOTES:
 * This function sends a message to the psm server and requests the .so
 * file on UNIX or .dll file on Windows be loaded as a PKCS11 module and 
 * be stored in the psm security module database.  The module will be stored
 * with the name moduleName that is passed in and will always expect the 
 * library to live at the path passed in via the parameter libraryPath.
 * The pubMechFlags tell the psm server how this module should be used.
 * Valid values are the #define constants defined at the beginning of
 * this file.
 * 
 * RETURN
 * A return value of CMTSuccess indicates the module was successfully loaded
 * and placed in the security module database of psm.  Any other return value
 * indicates an error and means the module was not loaded successfully and
 * not stored in the psm server's security module database.
 */
CMTStatus
CMT_AddNewModule(PCMT_CONTROL  control,
                 char         *moduleName,
                 char         *libraryPath,
                 unsigned long pubMechFlags,
                 unsigned long pubCipherFlags);

CMT_END_EXTERN_C

#endif /*_CMTJS_H_*/