aapicrpt.h

是一个手机功能的模拟程序

/*
 * Initialize a hash operation.
 * "alg" is the hash algorithm to use, and on return "handleptr"
 * will point to a new handle to be used in subsequent operations.
 * After calling CRYPTa_hashInit, one calls CRYPTa_hashUpdate zero or
 * more times, followed by CRYPTa_hashFinal, to digest data in
 * multiple parts. The hash operation is active until one makes
 * a call to CRYPTa_hashFinal to actually obtain
 * the final piece of ciphertext. To process additional data
 * (in single or multiple parts), one must call CRYPTa_hashInit again.
 */
INT16
CRYPTa_hashInit (HashAlgorithm alg,
                 HashHandle *handleptr);

/*
 * Continue a multiple-part hash operation, processing another data part.
 * "handle" is the handle of the hash operation, "part" points to the
 * data part, and "partLen" is the length of the data part.
 * The hash operation must have been initialized with CRYPTa_hashInit.
 * A call to CRYPTa_hashUpdate which results in an error terminates
 * the current hash operation.
 */
INT16
CRYPTa_hashUpdate (HashHandle handle,
                   BYTE *part, UINT16 partLen);

/*
 * Finish a multiple-part hash operation.
 * "handle" is the handle of the hash operation, and "digest" is the location
 * that receives the computed message digest.
 * The hash operation must have been initialized with CRYPTa_hashInit.
 * A call to CRYPTa_hashFinal always terminates the active hash operation.
 */
INT16
CRYPTa_hashFinal (HashHandle handle,
                  BYTE *digest);


/***********************************************************************
 * Key exchange
 ***********************************************************************/

/*
 * Perform key exchange, using one of the methods previously
 * reported to be available.
 * Derives the master secret using the pre-master secret produced
 * by the key exchange algorithm, and the 32 random bytes
 * (ClientHello.random + ServerHello.random) supplied
 * as a parameter to this call. The master secret is kept internally in
 * the crypto library, to be used in subsequent operations.
 * The parameter "alg" is the secure hash algorithm to be used.
 * The response should be delivered by a call to the connector function
 * CRYPTc_keyExchangeResponse. The first parameter, "id",
 * should be passed back in this response.
 *
 * RSA:
 * The public key to use is either given explicitly in the parameters,
 * or must be retrieved from a certificate passed to this routine.
 * This function generates a 20-byte value consisting of the given
 * "additionalData" and 19 random bytes. It encrypts the value with
 * the given public key, and stores the result in publicValue.
 * The pre-master secret is the 20-byte value appended with the
 * given public key.
 *
 * Diffie-Hellman: calculate a pre-master secret and a public value
 * to be sent to the server side.
 * The public key to use is given explicitly in the parameters.
 * This function performs a DH calculation based on the given
 * public key and a private key kept in the crypto library.
 *
 * ECDH: calculate a pre-master secret and a public value
 * to be sent to the server side.
 * The public key to use is either given explicitly in the parameters,
 * or must be retrieved from a certificate passed to this routine.
 * This function performs an ECDH calculation based on the given
 * public key and a private key kept in the crypto library.
 *
 * Shared secret: set the pre-master secret to be a pre-defined secret key.
 * Note, that if the library attempts to support the Shared Secret
 * key exchange method, it is required that the routine
 * CRYPTa_getClientKeyExchangeIds pair the method indicator
 * (KEY_EXCH_SHARED_SECRET) with a suitable identifier. That is,
 * an identifier that the gateway can use to retrieve the correct
 * secret key. "identifier" is a copy of that same identifying string.
 * The Crypto Library uses this parameter to select the appropriate
 * secret key.
 *
 * Null: set the pre-master secret to be the empty string.
 *
 */
void
CRYPTa_keyExchange (UINT16 id, KeyExchangeParameters param,
                    HashAlgorithm alg,
                    const BYTE *randval);

/***********************************************************************
 * Key generation
 ***********************************************************************/

/*
 * Calculate the Pseudo-Random Function defined in section
 * 11.3.2 in the WTLS spec.
 * If the master secret is to be used as first parameter,
 * then "secret" is NULL, and "masterSecretID" indicates which
 * master secret to use. Otherwise, "secret" is provided explicitly.
 * The parameter "label" is a null-terminated character string.
 * The parameter "alg" is the secure hash algorithm to be used,
 * and "outputLen" is the number of bytes of output to produce.
 * The response should be delivered by a call to the connector function
 * CRYPTc_PRFResponse. The first parameter, "id", should be
 * passed back in this response.
 */
void
CRYPTa_PRF (UINT16 id, HashAlgorithm alg,
            UINT8 masterSecretID,
            BYTE *secret, UINT16 seclen,
            BYTE *label,
            BYTE *seed, UINT16 seedLen,
            UINT16 outputLen);


/***********************************************************************
 * Certificates
 ***********************************************************************/

/*
 * Verify a chain of certificates.
 * The buffer, "buf", contains a chain of certificates. See section
 * 10.5.2 in the WTLS specification.
 * The parameter "addr" holds the address of the server in the format
 * defined in section 7.5.2 of the WCMP specification.
 * If "domain" is not NULL, it holds the domain name of the server.
 *
 * If possible, this routine should verify that the given address/domainname
 * matches the "common name" field of the certificate. In case the
 * certificate does not have a common name field, or the common name
 * field holds a domain name and the "domain" parameter is NULL,
 * then the checking of the common name field is omitted.
 *
 * The response should be delivered by a call to the connector function
 * CRYPTc_verifyCertificateChainResponse. The first parameter, "id",
 * should be passed back in this response.
 */
void
CRYPTa_verifyCertificateChain (UINT16 id,
                               const BYTE *buf, UINT16 bufLen,
                               const BYTE *addr, UINT16 addrLen,
                               const CHAR *domain, UINT16 domainLen);

/*
 * Retrieve a client certificate.
 * The buffer, "buf", contains a list of acceptable certificate
 * authorities, as byte encoded KeyExchangeId:s. See section 10.5.4
 * in the WTLS specification.
 * The response should be delivered by a call to the connector function
 * CRYPTc_getClientCertificateResponse. The first parameter, "id",
 * should be passed back in this response.
 */
void
CRYPTa_getClientCertificate (UINT16 id, const BYTE *buf, UINT16 bufLen);

/*
 * Compute a digital signature.
 * The buffer, "buf", contains the data to be signed, and the key
 * identifier, "keyId", contains a byte-encoded Identifier.
 * This latter value is either fetched from the Key Exchange Ids
 * passed back in CRYPTc_getMethodsResponse, or is the value
 * passed back in CRYPTc_getClientCertificateResponse (provided that
 * this function has been used). The keyId value indicates
 * which key must be used for signing.
 * The response should be delivered by a call to the connector function
 * CRYPTc_computeSignatureResponse. The first parameter, "id",
 * should be passed back in this response.
 */
void
CRYPTa_computeSignature (UINT16 id,
                         const BYTE *keyId, UINT16 keyIdLen,
                         const BYTE *buf, UINT16 bufLen);

/***********************************************************************
 * Random number generation
 ***********************************************************************/

/*
 * Generate random (or pseudo-random) data. "randomData" points to
 * the location that receives the data and "randomLen" is the number
 * of bytes of data to be generated.
 */
INT16
CRYPTa_generateRandom (BYTE *randomData, UINT16 randomLen);


/***********************************************************************
 * Session cache
 ***********************************************************************/

/*
 * General assumptions about the handling of the session store:
 *
 * The master secret store should be maintained in parallell with
 * the session store. This means, that the same indexes or slot
 * numbers are used both in the master secret store and the session store.
 * New slots in the master secret store are selected by the
 * key exchange routine. If no empty slots are available, the
 * old slot to be evicted should be selected using the following
 * strategy: Select a slot where the session is
 *   1) NON-resumable and NOT active
 *   2) resumable and NOT active
 *   3) NON-resumable and active
 *   4) resumable and active
 *
 * Preferably, the size of the store should be large enough that
 * cases 3 and 4 are never used. This can be accomplished by giving
 * the store one slot more than the maximum number of simultaneous
 * WTLS connections. If there are two or more candidates from
 * the same category, they should be ranked according to creation
 * time. That is, the older slot will be reused first.
 *
 * After the key exchange routine has delivered a new master secret
 * index (mid) to WTLS, it is the responsibility of WTLS to call
 * the routines
 *     CRYPTa_sessionInvalidate (mid);
 *     CRYPTa_peerDeleteLinks (mid);
 *
 */


#define SESSION_OPTIONS_RESUMABLE       0x80
#define SESSION_OPTIONS_SERVER_AUTH     0x20
#define SESSION_OPTIONS_CLIENT_AUTH     0x10


/************************************************************
 * 'Peers' methods
 ************************************************************/

/*
 * Delete all peer entries that link to the indicated
 * master secret.
 */
void
CRYPTa_peerDeleteLinks (UINT8 masterSecretIndex);

/*
 * Add a peer entry that links to the given master secret.
 * If such an entry already exists, overwite it.
 */
void
CRYPTa_peerLinkToSession (BYTE *address, UINT16 addrlen,
                          UINT16 portnum,
                          UINT8 masterSecretIndex);
/*
 * Find a peer with matching address and port number.
 * If none exists, try matching just the address.
 * The result, a master secret index, is returned in
 * CRYPTc_peerLookupResponse.
 */
void
CRYPTa_peerLookup (UINT16 id,
                   BYTE *address, UINT16 addrlen,
                   UINT16 portnum);

/************************************************************
 * 'Sessions' methods
 ************************************************************/

/*
 * If "isActive" != 0, then mark the indicated session slot
 * as being "active". Otherwise, mark it as not active.
 * A session slot that is "active", SHOULD NOT be reused.
 * WTLS will keep a session marked as "active" as long as
 * any WTLS connection that is based upon that session is active.
 */
void
CRYPTa_sessionActive (UINT8 masterSecretIndex, UINT8 isActive);

/*
 * Mark a session entry as non-resumable.
 */
void
CRYPTa_sessionInvalidate (UINT8 masterSecretIndex);

/*
 * Mark all entries in 'Sessions' as non-resumable.
 */
void
CRYPTa_sessionClear (void);

/*
 * Fetch the contents of the indicated session entry.
 * The result is returned in CRYPTc_sessionFetchResponse.
 */
void
CRYPTa_sessionFetch (UINT16 id, UINT8 masterSecretIndex);

/*
 * Store new values for a session entry.
 */
void
CRYPTa_sessionUpdate (UINT8 masterSecretIndex,
                      UINT8 sessionOptions,
                      BYTE *sessionId, UINT8 sessionIdLen,
                      UINT8 macAlg,
                      UINT8 cipherAlg,
                      UINT8 compressionAlg,
                      BYTE *privateKeyId,
                      UINT32 creationTime);

#endif