cmtcmn.h

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

 * SSM_FID_P7CINFO_IS_ENCRYPTED     Numeric   If non-zero, then the content
 *                                            info is encrypted.
 *
 * SSM_FID_P7CINFO_SIGNER_CERT      Numeric   The resource ID of the 
 *                                            certificate used to sign the 
 *                                            content info.
 *
 * RETURN
 * A return value of CMTSuccess indicates the PKCS7 Decoder Context was 
 * properly shutdown and that a resource for the Content Info exists on 
 * the psm server.  Any other return  value indicates an error.  The library
 * will have tried to shutdown the PKCS7 decoder context, but may have failed.
 * The Content Info will not exist on the psm server in this case.
 */
CMTStatus CMT_PKCS7DecoderFinish(PCMT_CONTROL control, CMUint32 connectionID, 
                                 CMUint32 * resourceID);

/*
 * FUNCTION: CMT_PKCS7DestroyContentInfo
 * -------------------------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    resourceID
 *        The resource ID of content info returned via the function 
 *        CMT_PKCS7DecoderFinish or CMT_CreateSigned.
 * NOTES
 * This function destroys the content info on the psm server.
 * 
 * RETURN
 * A return value of CMTSuccess indicates the content info was successfully
 * destroyed.  Any other return value indicates an error and that the 
 * resource with the resource ID passed in was not destroyed.
 */
CMTStatus CMT_PKCS7DestroyContentInfo(PCMT_CONTROL control, 
                                      CMUint32 resourceID);

/*
 * FUNCTION: CMT_PKCS7VerifyDetachedSignature
 * ------------------------------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    resourceID
 *        The resource ID of content info returned via the function 
 *        CMT_PKCS7DecoderFinish or CMT_CreateSigned.
 *    certUsage
 *        How the certificate that were used to sign should be interpretted.
 *    hashAlgID
 *        An identifier which tells the psm server which hash algorithm was
 *        to produce the signature.
 *    keepCerts
 *        If non-zero, the psm server will store any new certificates in
 *        content info into the local certificate database.
 *    digest
 *        A pre-calculated digest of the input.
 *    result
 *        A pointer to a pre-allocated chunk of memory where the library
 *        can place the result code of the verfication process.
 * NOTES
 * This function requests the psm server verify a signature within a 
 * Content Info.  
 *
 * Valid values for certUsage:
 * Use              Value
 * ---              -----
 * Email Signer     4
 * Object Signer    6
 *
 * Valid values for hashAlgID:
 * Hash Algorithm           Value
 * --------------           -----
 * MD2                      1
 * MD5                      2
 * SHA1                     3
 *
 * RETURN
 * If the function returns CMTSuccess, then psm server completed the operation
 * of verifying the signature and the result is located at *result.  If 
 * *result is non-zero, then the signature did not verify.  If the result is
 * zero, then the signature did verify.  Any other return value indicates
 * an error and the value at *result should be ignored.
 */
CMTStatus CMT_PKCS7VerifyDetachedSignature(PCMT_CONTROL control, 
                                           CMUint32     resourceID, 
                                           CMUint32     certUsage, 
                                           CMUint32     hashAlgID, 
                                           CMUint32     keepCerts, 
                                           CMTItem     *digest, 
                                           CMInt32     *result);

/*
 * FUNCTION: CMT_CreateSigned
 * --------------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    scertID
 *        The resource ID of the certificate to use for signing data.
 *    ecertID
 *        The resource ID of the encryption cert associated with scertID.
 *        If the certificates are different, then the encryption cert
 *        will also be included in the signed message so that the recipient
 *        can save it for future encryption.
 *    dig_alg
 *        A representation of what algorithm to use for generating the 
 *        digest.
 *    digest
 *        The actual digest of the data.  
 *    ciRID
 *        A pointer to a pre-allocated chunk of memory where the library
 *        can place the resource ID of the content info created by the psm
 *        server.
 *    errCode
 *        A pointer to a pre-allocated chunk of memory where the library 
 *        can place the error code returned by the psm server in case of
 *        error. NOTE: The error codes need to be documented.
 * NOTES
 * This function creates a PKCS7 Content Info on the psm server that will
 * be used to sign the digest.  After creating this content info the 
 * application must use CMT_PKCS7Encoder{Start|Update|Finish} function
 * calls to encode the content info.
 * Currently there is only one supported value for digest algorithm:
 * Digest Algorithm     Value
 * ----------------     -----
 * SHA1                 4
 *
 * RETURN
 * A return value of CMTSuccess indicates the content info was successfully
 * created on the psm server and the application can proceed to encode the
 * content info with CMT_PKCS7Encoder* function calls.  Any other return
 * value indicates an error and the content info was not created.
 */
CMTStatus CMT_CreateSigned(PCMT_CONTROL control, CMUint32 scertID,
                           CMUint32 ecertID, CMUint32 dig_alg, 
                           CMTItem *digest,CMUint32 *ciRID,CMInt32 *errCode);

/*
 * FUNCTION: CMT_PKCS7EncoderStart
 * ------------------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    ciRID
 *        The resource ID of the content info to encode.
 *    connectionID
 *        A pointer to a pre-allocated chunk of memory where the library can
 *        place the resource ID of the resulting PKCS7 Encoder Context.
 *    cb
 *        A callback function that will get called as the content info
 *        is encoded.
 *    cb_arg
 *        An opaque pointer that will get passed to cb every time cb is
 *        called.
 *
 * NOTES
 * This function creates a PKCS7 encoder context on the psm server which
 * the application can use to encode a data as a PKCS7 content info.  The 
 * function cb will be used to pass back encoded buffers to the application.
 * The applicaton should concatenate the buffer passed in to cb to any buffer
 * previously passed in to the function cb.  The concatenation of all the
 * buffers passed in to cb will be the final product of the encoding 
 * procedure.
 *
 * RETURN
 * A return value of CMTSuccess indicates successful creation of a PKCS7
 * encoder context on the psm server.  Any other return value indicates 
 * an error and that no encoder context was created on the psm server.
 */
CMTStatus CMT_PKCS7EncoderStart(PCMT_CONTROL control, CMUint32 ciRID,
                                CMUint32 *connectionID, 
                                CMTP7ContentCallback cb,
                                void *cb_arg);

/*
 * FUNCTION: CMT_PKCS7EncoderUpdate
 * --------------------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    connectionID
 *        The resource ID of a PKCS7 Encoder context returned by the function
 *        CMT_PKCS7EncoderStart
 *    buf
 *        The next chunk of buffer to set as the data of the content info.
 *    len
 *        The length of the buffer passed in.
 * 
 * NOTES
 * This function sets the next buffer to include as part of the content to
 * encode.  The application can repeatedly call this function until all the
 * data has been fed to the encoder context.
 *
 * RETURN
 * A return value of CMTSuccess indicates the the encoder context on the psm
 * server successfully added the data to the encoder context.  Any other 
 * return value indicates an error.
 * 
 */
CMTStatus CMT_PKCS7EncoderUpdate(PCMT_CONTROL control, CMUint32 connectionID,
                                 const char *buf, CMUint32 len);

/*
 * FUNCTION: CMT_PKCS7EncoderFinish
 * --------------------------------
 * INPUTS:
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    connectionID
 *        The resource ID of a PKCS7 Encoder context returned by the function
 *        CMT_PKCS7EncoderStart
 *
 * NOTES
 * This function destroys the PKCS7 encoder context with the resource ID of
 * connectionID on the psm server.
 *
 * RETURN
 * A return value of CMTSuccess indicates the PKCS7 encoder context was 
 * successfully destroyed.  Any other return value indcates an error while
 * trying to destroy the PKCS7 encoder context.
 */
CMTStatus CMT_PKCS7EncoderFinish(PCMT_CONTROL control, 
                                 CMUint32 connectionID);


/* Hash functions */
/*
 * FUNCTION: CMT_HashCreate
 * ------------------------
 * INPUTS:
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    algID 
 *        A numeric value representing what kind of hash to perform.
 *    connID
 *        A pointer to a pre-allocated chunk of memory where the library
 *        can place a copy of the resource ID associated with the hashing
 *        context created by this function.
 * NOTES
 * This function sends a message to the psm server requesting a context be
 * created for performing a hashing operation.  The type of hashing operation
 * performed depends on the parameter passed in for algID.  The valid values
 * are:
 *
 * Hash Algorithm    Value
 * --------------    -----
 * MD2               1
 * MD5               2
 * SHA1              3
 *
 * RETURN
 * A return value of CMTSuccess indicates successful creation of a hashing
 * context ont he psm server.  The resource ID of the hashing context is 
 * located at *connID.  Any other return value indicates an error and the
 * value at *connID should be ignored.
 */
CMTStatus CMT_HashCreate(PCMT_CONTROL control, CMUint32 algID, 
                         CMUint32 * connID);

/*
 * FUNCTION: CMT_HASH_Destroy
 * --------------------------
 * INPUTS:
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    connectionID
 *        The resource ID of the Hash context on psm to destroy.
 * NOTES
 * This function sends a message to the psm server requesting that the hashing
 * context with the resource ID of "connectionID" be destroyed.  This function
 * should be called after the hashing context is no longe needed.
 *
 * RETURN
 * A return value of CMTSuccess indicates the hashing context was successfully
 * destroyed.  Any other return value indicates an error while destroying
 * the resource with resource ID connectionID.
 */
CMTStatus CMT_HASH_Destroy(PCMT_CONTROL control, CMUint32 connectionID);

/*
 * FUNCTION: CMT_HASH_Begin
 * ------------------------
 * INPUTS:
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    connectionID
 *        The resource ID of a hashing context on the psm server.
 * NOTES
 * This function will send a message to the psm server requesting the hashing
 * context initialize its internal state before beginning the process of hasing
 * data.
 *
 * RETURN
 * A return value of CMTSuccess indicates the state of the hashing context 
 * successfully initialized its state and that the application can start 
 * feeding the data to hash via the CMT_HASH_Update function.  Any other return
 * value indicates an error and the hashing context should not be used after
 * this function call.
 */
CMTStatus CMT_HASH_Begin(PCMT_CONTROL control, CMUint32 connectionID);

/*
 * FUNCTION: CMT_HASH_Update
 * -------------------------
 * INPUTS:
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    connectionID
 *        The resource ID of a hashing context on the psm server.
 *    buf
 *        The data to feed to the hashing context.
 *    len
 *        The length of the buffer passed in as data.
 *
 * NOTES
 * This function sends the next buffer of data to be hashed as part
 * of the hash context associated with the parameter connecionID.  The 
 * application may call this function multiple times each time feeding
 * in the next chunk of data to be hashed.  The end result will be the hash
 * of the concatenation of the data passed into each successive call to 
 * CMT_HASH_Update.  To get the final hash of the data call CMT_HASH_End
 * after feeding all of the data to the context via this function.
 *
 * RETURN
 * A return value of CMTSuccess indicates the hash context on the psm server