cmtcmn.h

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

/*
 * FUNCTION: CMT_GetServerStringVersion
 * ------------------------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *
 * 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.  Should be CM_TRUE
 *        for protocols in which the server initiates the data transfer
 *        (e.g. IMAP over SSL or NNTP over SSL).  Otherwise, always set to
 *        CM_FALSE.
 *    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.
 *
 * Each SSL connection has a socket status variable associated with it.  The 
 * ssl data connection structure on the PSM server will exist, ie the memory
 * associated with it will not be freed, until the application tells the
 * PSM server what to do with socket status structure.  The application 
 * should call either CMT_ReleaseSSLSocketStatus or CMT_GetSSLSocketStatus
 * (but never both) so that the memory associated with the ssl connection
 * can be disposed of properly.
 *
 * 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_ReleaseSSLSocketStatus
 * ------------------------------------
 * 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.
 * NOTES
 * This function instructs the SSL connection to discard the Socket Status
 * variable associated with it.
 *
 * RETURN
 * A return value of CMTSuccess indicates the socket status structure was
 * successfully discarded.  Any other return value indicates an error.
 */
CMTStatus CMT_ReleaseSSLSocketStatus(PCMT_CONTROL control, CMTSocket sock);

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

/*
 * FUNCTION: CMT_OpenSSLProxyConnection
 * ------------------------------------
 * 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.
 *     port
 *         The port which the PSM server should connect to.
 *     hostIP
 *         The IP address of the server with which to establish a proxy
 *         connection.
 *     hostName
 *         The host name of the server to connect to.
 *
 * NOTES
 * This function opens a connection to an SSL proxy server in the clear.  It 
 * is almost identical to the role of CMT_OpenTLSConnection(), but is offered 
 * to be clear of the fact that it is opening a connection to a proxy server.
 * Consult the usage of CMT_OpenTLSConnection() for more information.  Also,
 * note that this by itself does not carry out any authorization (or 
 * authentication) other than simply connecting to the port.  Further exchange
 * is left to the client.  Moreover, once it is ready to transmit actual data, 
 * the client is required to call CMT_ProxyStepUp() to turn on security on the
 * connection.
 *
 * RETURN
 * A return value of CMTSuccess indicates the PSM server has established a
 * connection with the SSL proxy server.  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_OpenSSLProxyConnection(PCMT_CONTROL control, CMTSocket sock,
                                     CMUint32 port, char* hostIP, 
                                     char* hostName);

/*
 * FUNCTION: CMT_ProxyStepUp
 * -------------------------
 * 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.
 *     remoteUrl
 *         The URL of the remote host.
 *
 * NOTES
 * This function instructs PSM to turn on security on the connection.  Once it
 * returns, the connection is ready for SSL data exchange.  The remoteUrl
 * argument is used in validating the SSL connection for the man-in-the-middle
 * attack during the SSL handshake.
 *
 * RETURN
 * A return value of CMTSuccess indicates that the PSM server has turned on
 * security on the connection.  Any other return value indicates an error
 * setting up the connection and the application should not try to read/write
 * data from the socket.
 */
CMTStatus CMT_ProxyStepUp(PCMT_CONTROL control, CMTSocket sock,
                          void* clientContext, char* remoteUrl);

/* 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.
 *