cmtcmn.h

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

 * NOTES:
 * This function returns the string representing the version of the psm
 * server that was sent as part of the hello reply.  This string originated
 * in the psm server.
 *
 * RETURN
 * A string.  A NULL return value indicates an error.  The user must not free
 * this memory since it is memory owned by the control connection.
 */
char* CMT_GetServerStringVersion(PCMT_CONTROL control);

/* SSL functions */
/*
 * FUNCTION: CMT_OpenSSLConnection
 * -------------------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    sock
 *        The file descriptor of the socket to use for feeding the data
 *        back to the application.
 *    requestType
 *        The type of SSL connection to establish.  View ssmdefs.h for
 *        the possible Connection types to pass in.
 *    port
 *        The port which the psm server should connect to.
 *    hostIP
 *        The IP address of the server with which to establish an SSL
 *        connection.
 *    hostName
 *        The host name of the site to connect to.
 *    forceHandshake
 *        Indicates whether forced handshakes are required.
 *    clientContext
 *        Client supplied data pointer that is returned to the client during UI.
 * NOTES:
 * This function sends a message to the psm server requesting an SSL connection
 * be established.  The parameter "sock" is a file descriptor to use for
 * reading the decrypted data the psm server has fetched.  Afte all of the
 * contents have been read from the socket, the application should call 
 * CMT_DestroyDataConnection passing in the 2 parameters "control" and
 * "sock" that were passed into this function.
 *
 * RETURN
 * A return value of CMTSuccess indicates the psm server has established an 
 * SSL connection with the site passed in.  Any other return value indicates
 * an error setting up the connection and the application should not try 
 * to read any data from the socket "sock" passed in.
 */
CMTStatus CMT_OpenSSLConnection(PCMT_CONTROL control, CMTSocket sock,
                                SSMSSLConnectionRequestType requestType, 
                                CMUint32 port, char * hostIP, 
                                char * hostName, CMBool forceHandshake, void* clientContext);

CMTStatus CMT_GetSSLDataErrorCode(PCMT_CONTROL control, CMTSocket sock,
                                  CMInt32* errorCode);

/*
 * FUNCTION: CMT_GetSSLSocketStatus
 * --------------------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    sock
 *        The socket which was passed into CMT_OpenSSLConnection as the file
 *        descriptor for the application to read data from.
 *    pickledStatus
 *        On return, filled with data blob that contains pickled socket 
 *        status.
 *    level
 *        On return, filled with the security level indicator.
 * NOTES
 * This function requests socket status information that is relevant to the
 * client.
 *
 * RETURN
 * A return value of CMTSuccess indicates retrieving the Socket Status 
 * resource on the psm server was successful.  Any other return value 
 * indicates an error in getting the socket status resource.
 */
CMTStatus CMT_GetSSLSocketStatus(PCMT_CONTROL control, CMTSocket sock, 
                                 CMTItem* pickledStatus, CMInt32* level);

/*
 * FUNCTION: CMT_OpenTLSConnection
 * -------------------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the
 *        PSM server.
 *    sock
 *        The file descriptor of the socket to use for feeding the data
 *        back to the application.
 *    port
 *        The port which the PSM server should connect to.
 *    hostIP
 *        The IP address of the server with which to establish a TLS
 *        connection.
 *    hostName
 *        The host name of the site to connect to.
 *
 * NOTES:
 * This function sends a message to the PSM server requesting a TLS connection
 * to be established.  A TLS connection is the one that starts out as a regular
 * TCP socket but later turns into a secure connection upon request.  The
 * parameter "sock" is a file descriptor to use for reading data from the PSM
 * server.  After all of the contents have been read from the socket, the
 * application should call CMT_DestroyDataConnection passing in the two
 * parameters "control" and "sock" that were passed into this function.
 *
 * RETURN
 * A return value of CMTSuccess indicates the PSM server has established a
 * TLS connection with the site passed in.  Any other return value indicates
 * an error setting up the connection and the application should not try
 * to read any data from the socket "sock" passed in.
 */
CMTStatus CMT_OpenTLSConnection(PCMT_CONTROL control, CMTSocket sock,
                                CMUint32 port, char* hostIP, char* hostName);

/*
 * FUNCTION: CMT_TLSStepUp
 * -----------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the PSM
 *        server.
 *    sock
 *        The file descriptor to use for exchanging data with the PSM server.
 *    clientContext
 *        The client context that is to be saved.
 *
 * RETURN
 * A return value of CMTSuccess indicates that the PSM server successfully
 * upgraded the connection to a secure one.  Any other return value indicates
 * the TLS step-up did not succeed.
 */
CMTStatus CMT_TLSStepUp(PCMT_CONTROL control, CMTSocket sock, 
                        void* clientContext);

/* PKCS 7 Functions */
/*
 * FUNCTION: CMT_PKCS7DecoderStart
 * -------------------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    connectionID
 *        A pointer to a pre-allocated block of memory where the library
 *        can place the resource ID of the data connection associated with
 *        this PKCS7 decode process.
 *    cb
 *        A pointer to a function that will receive the content bytes as
 *        they are recovered while decoding.
 *    cb_arg
 *        An opaque pointer that will get passed to the callback function 
 *        "cb" when "cb" is invoked.
 *
 * NOTES
 * This function sends a message to the psm server requesting a context with
 * which to decode a PKCS7 stream.  The contents of the decoded stream will
 * be passed to the function cb.
 *
 * RETURN
 * A return value of CMTSuccess indicates a context for decoding a PKCS7 
 * stream was created on the psm server and is ready to process a PKCS stream.
 * Any other return value indicates an error and that no context for decoding
 * a PKCS7 stream was created.
 */
CMTStatus CMT_PKCS7DecoderStart(PCMT_CONTROL control, void * clientContext, CMUint32 * connectionID, CMInt32 * result,
                                CMTP7ContentCallback cb, void *cb_arg);

/*
 * FUNCTION: CMT_PKCS7DecoderUpdate
 * --------------------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    connectionID
 *        The resource ID of a PKCS Decoder Context returned by the 
 *        function CMT_PKCS7DecoderStart.
 *    buf
 *        The next section of a PKCS7 stream to feed to the PKCS7 decoder
 *        context.
 *    len
 *        The length of the buffer "buff" passed in.
 * NOTES
 * This function sends a buffer to a PKCS7 decoder context.  The context then
 * parses the data and updates its internal state.
 *
 * RETURN
 * A return value of CMTSuccess indicates the PKCS7 decoder context 
 * successfully read and parsed the buffer passed in as a PKCS7 buffer.
 * Any other return value indicates an error while processing the buffer.
 */
CMTStatus CMT_PKCS7DecoderUpdate(PCMT_CONTROL control, CMUint32 connectionID, 
                                 const char * buf, CMUint32 len);

/*
 * FUNCTION: CMT_PKCS7DecoderFinish
 * --------------------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    connectionID
 *        The resource ID of a PKCS Decoder Context returned by the 
 *        function CMT_PKCS7DecoderStart.
 *    resourceID
 *        A pointer to a pre-allocated chunk of memory where the library
 *        can place a copy of the resource ID associated with the content
 *        info produced while the decoder context existed.
 * NOTES:
 * This function shuts down a PKCS7 decoder context on the psm server and
 * returns the resource ID of the content info that was decoded from the
 * PKCS7 stream passed in to the decoder context via CMT_PKCS7DecoderUpdate 
 * calls.  The attributes you can retrieve from the Content Info via the 
 * functions CMT_GetNumericAttribute or CMT_GetStringAttribute are as
 * follows:
 *
 * Attribute                        Type      What it means
 * ---------                        ----      -------------
 * SSM_FID_P7CINFO_IS_SIGNED        Numeric   If non-zero, then the content
 *                                            info is signed.
 *
 * 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