cmtcmn.h

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

 * CMTSetPrefElement structure.
 */
#define CMT_PREF_STRING 0
#define CMT_PREF_BOOL   1
#define CMT_PREF_INT    2

/* structs to pack each preference item to pass between the psm server and 
 * the plugin
 */
typedef struct _CMTSetPrefElement {
    char* key;
    char* value;
    CMInt32 type;
} CMTSetPrefElement;

typedef struct _CMTGetPrefElement {
    char* key;
    CMInt32 type;
} CMTGetPrefElement;

/*
 * FUNCTION TYPE: savePrefsCallback_fn
 * -----------------------------------
 * INPUTS
 *    number
 *        The number of pref items to save.
 *    list
 *        The list of pref items delivered from the PSM server.
 *
 * NOTES
 * This defines the prototype for a function callback used for saving pref
 * changes passed from the PSM server.  Each preference item has a type
 * (string, boolean, or integer) so that the value string may be converted 
 * appropriately according to type.  The callback is not responsible for
 * freeing pref elements (keys and values).
 *
 * RETURN
 * None.
 */
typedef void (*savePrefsCallback_fn)(int number, CMTSetPrefElement* list);

typedef struct CMT_UserCallbacks {
    filePathPromptCallback_fn promptFilePath;
    void *filePromptArg;
    promptCallback_fn promptCallback;
    void *promptArg;
    applicationFreeCallback_fn userFree;
    savePrefsCallback_fn savePrefs;
} CMT_UserCallbacks;

#define RNG_OUT_BUFFER_LEN 4096
#define RNG_IN_BUFFER_LEN 4096

typedef struct CMT_RNGState
{
    char *outBuf;                     /* Outgoing random data cache */
    CMUint32 validOutBytes;            /* #bytes of random data to PSM */
    char *out_cur;                     /* Next CMT_RandomUpdate writes
                                          data here. */
    char *out_end;                         /* End of buffer */

    char *inBuf;                     /* Incoming random data cache */
    CMUint32 validInBytes;             /* #bytes of random data from PSM */
    char *in_cur;                    /* Next CMT_GenerateRandomBytes reads
                                        from here. */

} CMT_RNGState;

typedef struct _CMT_CONTROL {
    CMTSocket sock;
    CMUint32 sessionID;
    CMUint32 protocolVersion;
    CMUint32 port;
    CMTItem nonce;
    PCMT_DATA cmtDataConnections;
    PCMT_EVENT cmtEventHandlers;
    CMUint32 policy;
    CMInt32 refCount;
    CMT_MUTEX* mutex;
    SSMObscureObject *obscureObj;
    char *serverStringVersion;
    CMT_SocketFuncs  sockFuncs;
    CMT_UserCallbacks userFuncs;
    CMT_RNGState rng;
} CMT_CONTROL, *PCMT_CONTROL;

/* Cert list structure */
typedef struct _CMT_CERT_LIST {
    CMTCList certs;
    CMInt32 count;
} CMT_CERT_LIST;

typedef struct _CMT_CERT_LIST_ELEMENT {
    CMTCList links;
    CMUint32 certResID;
} CMT_CERT_LIST_ELEMENT;

/* information required to pack the security advisor request */
typedef struct _CMTSecurityAdvisorData {
    CMInt32 infoContext;
    CMUint32 resID;
    char *hostname;
	char *senderAddr;
    CMUint32 encryptedP7CInfo;
    CMUint32 signedP7CInfo;
    CMInt32 decodeError;
    CMInt32 verifyError;
	CMBool encryptthis;
	CMBool signthis;
	int numRecipients;
	char **recipients;
} CMTSecurityAdvisorData;

CMT_BEGIN_EXTERN_C

/*
 * FUNCTION: CMT_ReferenceControlConnection
 * ----------------------------------------
 * INPUTS:
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 * NOTES:
 * This function bumps up the reference count on the control connection
 * Each thread that has a pointer to the control connection should get
 * its own reference on the control connection to avoid having another thread
 * free up the memory associated with the control connection.
 *
 * RETURN:
 * A return value of CMTSuccess indicates the reference count of the 
 * control connection was successfully achieved.  Any other return value
 * indicates an error.
 */
CMTStatus CMT_ReferenceControlConnection(PCMT_CONTROL control);

/*
 * FUNCTION: CMT_EstablishControlConnection
 * ----------------------------------------
 * INPUTS
 *    path
 *        The full path to the psm server. (Including the psm executable.)
 *    sockFuncs
 *        A structure containing pointers to functions that implement
 *        socket functions using the applications I/O model.  These 
 *        functions will be used by the cmt library to communicate
 *        with the psm server.
 *    mutex
 *        A structure containig a pointer to a mutex defined by the 
 *        implementation.
 * NOTES:
 * This function will establish a control connection to a psm server.
 * First the function will attempt to connect to a psm server that 
 * is already running by calling CMT_ControlConnect.  If that function
 * call succeeds, then the function will return an established control
 * connection to a psm process that is already running.  If 
 * CMT_ControlConnect fails, then this function will launch the psm server
 * that resides in the directory passed in by path and establish a control
 * connection to it.  Read comments on the CMT_MUTEX structure for proper
 * semantics of the lock and un-lock functions.  If you pass in NULL for 
 * the mutex parameter, access to the control connection will not be 
 * thread safe.  If the application using this library is multi-threaded,
 * then it is highly recommended that the application provide a locking 
 * mutex to this function.  Before performing any other actions, the 
 * applicatin must call CMT_Hello to send the psm server a hello message 
 * which will fully establish a port for communication between the psm server
 * and the application.
 *
 * The application may choose to launch the psm server itself and then
 * just call CMT_ControlConnect, but when doing so the application must
 * launch the psm executable with the directory psm lives in as the working
 * directory when launching the psm server.
 *
 * RETURN
 * This function will return a pointer to an established control connection
 * with the psm server upon successful connection.  If the return value
 * is NULL, that means the function was not able to establish a connection
 * to the process created by invoking the parameter "path".  Make sure
 * the path is correct.  Another common reason for failure is not initializing
 * the network libraries.
 */
PCMT_CONTROL CMT_EstablishControlConnection(char            *path, 
                                            CMT_SocketFuncs *sockFuncs,
                                            CMT_MUTEX       *mutex);

/*
 * FUNCTION: CMT_ControlConnect
 * ----------------------------
 * INPUTS:
 *    mutex
 *        A structure containig a pointer to a mutex defined by the 
 *        implementation.
 *    sockFuncs
 *        A structure containing pointers to functions that implement
 *        socket functions using the applications I/O model
 * NOTES
 * This function tries to connect to the psm server establishing a
 * control connection between an already running  psm server and the client 
 * library.
 *
 * The mutex should contain an application defined mutex and corresponding
 * functions for locking and unlocking the mutex.  Read comments on the
 * CMT_MUTEX structure for the proper semantics of the lock and un-lock
 * functions. If you pass in NULL for the mutex parameter, access to the
 * control connection will not be thread safe.  If the application using this 
 * library is multi-threaded, then it is highly recommended that
 * the application provid a locking mutex to this function.  Before 
 * performing any other actions, the application must call CMT_Hello
 * to send the psm server a hello message which will fully establish
 * a port for communication between the psm server and the application.
 *
 * RETURN
 * This function will return a pointer to an established control connection
 * with the psm server upon successful connection.  If the return value is
 * NULL, that means the psm server is not running and that the application
 * must start the psm server before calling this function again.
 */
PCMT_CONTROL CMT_ControlConnect(CMT_MUTEX* mutex, CMT_SocketFuncs *sockFuncs);

/*
 * FUNCTION: CMT_CloseControlConnection
 * ------------------------------------
 * INPUTS:
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 * NOTES:
 * This function closes down the control connection and frees the memory
 * associated with the passed in control connection.
 *
 * RETURN
 * A return value of CMTSuccess indicates successful destruction of the 
 * control connection.  Any other return value indicates an error and the
 * state of the connection betwenn the library and the psm server is 
 * undefined.
 */
CMTStatus CMT_CloseControlConnection(PCMT_CONTROL control);

/*
 * FUNCTION: CMT_Hello
 * ------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    data
 *        Data needed for the Hello message.  It has following subfields.
 *    version
 *        The version of the psm protocol.  For this release, the version
 *        should always be 1.
 *    profile
 *        << This value is currently not used by PSM, but passing in a >>
 *        << proper profile name is recommended for consistency.       >>
 *        The Communicator profile to use when initializing the crypto engine
 *        in the psm server.  If Communicator doesn't support profiles on
 *        the platform you are running on, pass in the empty string for
 *        this parameter.
 *    profileDir
 *        The full absolute path to the profile directory that corresponds
 *        to the profile.  If the application wants to use a default profile,
 *        an empty string is passed.
 * NOTES:
 * This function sends a hello message to the psm server which establishes 
 * the nonce for communication between the application and the psm server 
 * and initializes the crypto engine on the psm server.  After calling this
 * function, the applicatior can successfully call any other function that 
 * talks to the psm server.
 *
 * RETURN
 * A return value of CMTSuccess indicates the hello message was received and 
 * correctly processed by the psm server.  Any other return value indicates
 * a connection to the psm server was not established.
 */
CMTStatus CMT_Hello(PCMT_CONTROL control, CMUint32 version, char* profile,
                    char* profileDir);


/*
 * FUNCTION: CMT_PassAllPrefs
 * --------------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *    num
 *        Number of items that are passed to the psm server.
 *    list
 *        The list of actual preference items.
 *        - key: string for the preference key.
 *        - value: string for the preference value.
 *        - type: preference type (0: string, 1: boolean, 2: integer).
 * NOTES:
 * This function passes in all necessary preferences the psm server uses,
 * including necessary application-specific preferences.  This function must
 * be called after CMT_Hello() returns and before any crypto operations
 * to ensure a correct behavior.  Here is a description of some important 
 * preference items.
 *
 * - KEY                              VALUE                           TYPE 
 *   (DESCRIPTION)
 * --------------------------------------------------------------------------
 * - "security.enable_ssl2"           "true" | "false"                boolean 
 *   (whether to enable SSL2 cipher families)
 * - "security.enable_ssl3"           "true" | "false"                boolean 
 *   (whether to enable SSL3 cipher families)
 * - "security.default_personal_cert" "Select Automatically" | 
 *                                    "Ask Every Time"                string
 *   (whether to select automatically a personal certificate for client 
 *    authentication)
 * - "security.default_mail_cert"     [certificate's nickname] | NULL string
 *   (default certificate to be used for signing email messages)
 * - "security.ask_for_password"      "0" | "1" | "2"                 integer
 *   (mode for prompting the user for the certificate store password:
 *    0: ask for password initially and password does not expire,
 *    1: always ask for password,
 *    2: ask for password initially and stay logged on until the password
 *       expires)
 * - "security.password_lifetime"     [number of minutes]             integer
 *   (number of minutes for password expiration: used only if 
 *    ask_for_password == 2)
 *
 * One can add more application-specific items to the list.
 *
 * RETURN
 * A return value of CMTSuccess indicates successful transmission of the 
 * preference values.  Any other return value indicates an error.
 */
CMTStatus CMT_PassAllPrefs(PCMT_CONTROL control, int num, 
                           CMTSetPrefElement* list);

/*
 * FUNCTION: CMT_GetServerStringVersion
 * ------------------------------------
 * INPUTS
 *    control
 *        A control connection that has established a connection with the
 *        psm server.
 *