404 lines
18 KiB
C
404 lines
18 KiB
C
|
/**
|
||
|
Copyright (c) Certicom Corp. 1996-2008. All rights reserved.
|
||
|
|
||
|
This software contains trade secrets, confidential information, and
|
||
|
other intellectual property of Certicom Corp. and its licensors.
|
||
|
This software cannot be used, reproduced, or distributed in whole or
|
||
|
in part by any means without the explicit prior consent of Certicom
|
||
|
Corp.
|
||
|
Such consent must arise from a separate license agreement from
|
||
|
Certicom or its licensees, as appropriate. This software implements
|
||
|
Canadian, U.S., and other nations' patents, both registered and
|
||
|
pending (see the readme file included in this distribution).
|
||
|
|
||
|
Warning: U.S. Federal and state laws and international treaties
|
||
|
provide severe civil and criminal penalties for the unauthorized
|
||
|
reproduction in any form of these copyrighted materials.
|
||
|
Criminal copyright infringement constitutes a felony and is
|
||
|
punishable by a $250,000 fine and up to 5 years in prison.
|
||
|
|
||
|
Certicom, Certicom Security Architecture, Certicom CodeSign, Security
|
||
|
Builder, Security Builder BSP, Security Builder API, Security
|
||
|
Builder Crypto, Security Builder SSL, Security Builder PKI, Security
|
||
|
Builder NSE and Security Builder GSE are trademarks or registered
|
||
|
trademarks of Certicom Corp.
|
||
|
|
||
|
All other trademarks or registered trademarks listed herein are
|
||
|
property of their respective owners.
|
||
|
|
||
|
Certicom Corp. has intellectual property rights relating to
|
||
|
technology embodied in this product.
|
||
|
In particular, and without limitation, these intellectual property
|
||
|
rights may include one or more of the U.S. and non-U.S. patents listed
|
||
|
at www.certicom.com/patents
|
||
|
and one or more additional patents or pending patent applications in
|
||
|
the U.S. and in other countries.
|
||
|
|
||
|
Information subject to change without notice.
|
||
|
|
||
|
|
||
|
|
||
|
Certicom Corp. Technical Support
|
||
|
Email: support@certicom.com
|
||
|
Vox: 1-800-511-8011
|
||
|
Fax: 1-800-474-3877
|
||
|
*/
|
||
|
/*****************************************************************************
|
||
|
*
|
||
|
* eccapi.h
|
||
|
*
|
||
|
*****************************************************************************/
|
||
|
|
||
|
#ifndef ECCAPI_H
|
||
|
#define ECCAPI_H
|
||
|
|
||
|
#ifdef __cplusplus
|
||
|
extern "C" {
|
||
|
#endif
|
||
|
|
||
|
#define ZSE_MAJOR 1
|
||
|
#define ZSE_MINOR 0
|
||
|
#define ZSE_PATCH 1
|
||
|
#define ZSE_BUILD 6
|
||
|
#define ZSE_VERSION ((unsigned long)(ZSE_MAJOR & 0x0F)<< 28 | (unsigned long)(ZSE_MINOR & 0x0F) << 24 | (unsigned long)(ZSE_PATCH & 0x0FFF) << 12 | (unsigned long)(ZSE_BUILD & 0x0FFF))
|
||
|
|
||
|
|
||
|
#define SECT163K1_COMPRESSED_PUBLIC_KEY_SIZE (22)
|
||
|
#define SECT163K1_UNCOMPRESSED_PUBLIC_KEY_SIZE (43)
|
||
|
#define SECT163K1_PRIVATE_KEY_SIZE (21)
|
||
|
#define SECT163K1_CERTIFICATE_SIZE (48)
|
||
|
#define SECT163K1_SHARED_SECRET_SIZE (21)
|
||
|
#define SECT163K1_POINT_ORDER_SIZE (21)
|
||
|
#define AES_MMO_HASH_SIZE (16)
|
||
|
|
||
|
/******************************************************************************
|
||
|
* Return Codes
|
||
|
*****************************************************************************/
|
||
|
|
||
|
#define MCE_SUCCESS 0x00
|
||
|
#define MCE_ERR_FAIL_VERIFY 0x01
|
||
|
#define MCE_ERR_NULL_PRIVATE_KEY 0x02
|
||
|
#define MCE_ERR_NULL_PUBLIC_KEY 0x03
|
||
|
#define MCE_ERR_NULL_INPUT_BUF 0x04
|
||
|
#define MCE_ERR_NULL_OUTPUT_BUF 0x05
|
||
|
#define MCE_ERR_NULL_FUNC_PTR 0x06
|
||
|
#define MCE_ERR_NULL_EPHEM_PRI_KEY 0x07
|
||
|
#define MCE_ERR_NULL_EPHEM_PUB_KEY 0x08
|
||
|
#define MCE_ERR_BAD_INPUT 0x09
|
||
|
|
||
|
/** This is a prototype of a user-provided callback function that generates
|
||
|
* random seeds of the specified length.
|
||
|
|
||
|
This function should copy <tt>sz</tt> bytes of random data into
|
||
|
<tt>buffer</tt>.
|
||
|
|
||
|
@param[out] buffer This is an unsigned char array of size at least
|
||
|
<tt>sz</tt> to hold the random data.
|
||
|
@param[in] sz The number of bytes of random data to compute and store.
|
||
|
|
||
|
@retval MCE_SUCCESS Indicates successful completion.
|
||
|
*/
|
||
|
|
||
|
typedef int GetRandomDataFunc(unsigned char *buffer, unsigned long sz);
|
||
|
|
||
|
/** This is a prototype of a user-provided callback function that computes an
|
||
|
* AES MMO message digest of the <tt>data</tt> of given size, <tt>sz</tt>.
|
||
|
*
|
||
|
This function should compute the hash of the <tt>data</tt> parameter of size
|
||
|
<tt>sz</tt>, and store the result in the <tt>digest</tt> buffer parameter.
|
||
|
|
||
|
@param[out] digest This is an unsigned char buffer to hold the message digest.
|
||
|
The length of the digest must be <tt>AES_MMO_HASH_SIZE</tt> bytes.
|
||
|
@param[in] sz The size in bytes of the message to be hashed.
|
||
|
@param[in] data This is an unsigned char buffer of data to be hashed.
|
||
|
|
||
|
@retval MCE_SUCCESS Indicates successful completion.
|
||
|
*/
|
||
|
typedef int HashFunc(unsigned char *digest, unsigned long sz, unsigned char *data);
|
||
|
|
||
|
|
||
|
/** This is a prototype of a user-provided callback function to process information
|
||
|
during a long computation inside the library.
|
||
|
|
||
|
@retval - This user-provided function should return MCE_SUCCESS to indicate
|
||
|
successful completion.
|
||
|
*/
|
||
|
|
||
|
|
||
|
typedef int YieldFunc(void);
|
||
|
|
||
|
|
||
|
/**
|
||
|
|
||
|
This is a sample implementation of the <tt>HashFunc</tt> callback used by the
|
||
|
Security Builder MCE toolkit. Please note that this is not an optimized
|
||
|
implementation and is provided for testing purposes.
|
||
|
|
||
|
This function computes the AES MMO digest of the <tt>data</tt> parameter of
|
||
|
length <tt>sz</tt>, and stores the result in <tt>digest</tt>.
|
||
|
|
||
|
@param[out] digest This is an unsigned char buffer to hold the message digest.
|
||
|
The length of the digest must be <tt>AES_MMO_HASH_SIZE</tt> bytes.
|
||
|
@param[in] sz The size in bytes of the message to be hashed.
|
||
|
@param[in] data This is an unsigned char buffer of data to be hashed.
|
||
|
|
||
|
@retval MCE_ERR_NULL_OUTPUT_BUF <tt>digest</tt> is <tt>NULL</tt>
|
||
|
@retval MCE_ERR_NULL_INPUT_BUF <tt>data</tt> is <tt>NULL</tt>
|
||
|
@retval MCE_SUCCESS indicates successful completion.
|
||
|
|
||
|
*/
|
||
|
int aesMmoHash(unsigned char *digest, unsigned long sz, unsigned char *data);
|
||
|
|
||
|
/**
|
||
|
|
||
|
Creates an ECDSA signature of a message digest.
|
||
|
The outputs are the r and s components of the signature.
|
||
|
|
||
|
@param[in] privateKey The private key. This is an unsigned char buffer of size
|
||
|
<tt>SECT163K1_PRIVATE_KEY_SIZE</tt>.
|
||
|
@param[in] msgDigest The hash of the message to be signed. This is an unsigned
|
||
|
char buffer of size <tt>AES_MMO_HASH_SIZE</tt>.
|
||
|
@param[in] GetRandomData Pointer to a function to get random data for
|
||
|
generating ephemeral keys.
|
||
|
@param[in] yieldLevel The yield level determines how often the user defined yield
|
||
|
function will be called. This is a number from <tt>0</tt> to <tt>10</tt>.
|
||
|
<tt>0</tt> will never yield.
|
||
|
<tt>1</tt> will yield the most often.
|
||
|
<tt>10</tt> will yield the least often.
|
||
|
@param[in] YieldFunc Pointer to a function to allow user defined yielding.
|
||
|
@param[out] r The r component of the signature. This is an unsigned char buffer
|
||
|
of size <tt>SECT163K1_POINT_ORDER_SIZE</tt>.
|
||
|
@param[out] s The s component of the signature. This is an unsigned char buffer
|
||
|
of size <tt>SECT163K1_POINT_ORDER_SIZE</tt>.
|
||
|
|
||
|
@retval MCE_ERR_NULL_PRIVATE_KEY <tt>privateKey</tt> is <tt>NULL</tt>.
|
||
|
@retval MCE_ERR_NULL_OUTPUT_BUF <tt>msgDigest</tt>, <tt>r</tt> or
|
||
|
<tt>s</tt> are <tt>NULL</tt>.
|
||
|
@retval MCE_ERR_NULL_FUNC_PTR <tt>GetRandomData</tt> is <tt>NULL</tt> or
|
||
|
<tt>YieldFunc</tt> is <tt>NULL</tt> and
|
||
|
<tt>YieldLevel</tt> is not <tt>0</tt>.
|
||
|
@retval MCE_ERR_BAD_INPUT <tt>YieldLevel</tt> is greater than <tt>10</tt>.
|
||
|
@retval MCE_SUCCESS Success.
|
||
|
*/
|
||
|
|
||
|
int ZSE_ECDSASign(unsigned char *privateKey,
|
||
|
unsigned char *msgDigest,
|
||
|
GetRandomDataFunc *GetRandomData,
|
||
|
unsigned char *r,
|
||
|
unsigned char *s,
|
||
|
YieldFunc *yield,
|
||
|
unsigned long yieldLevel );
|
||
|
|
||
|
|
||
|
|
||
|
/**
|
||
|
|
||
|
Verifies an ECDSA signature created using a private signing key by using
|
||
|
the associated public key, the digest and the signature components.
|
||
|
|
||
|
@param[in] publicKey The public key. This is an unsigned char buffer of size
|
||
|
<tt>SECT163K1_COMPRESSED_PUBLIC_KEY_SIZE</tt>.
|
||
|
@param[in] msgDigest The hash of the message to be verified. This is an
|
||
|
unsigned char buffer of size <tt>AES_MMO_HASH_SIZE</tt>.
|
||
|
@param[in] r The r component of the signature. This is an unsigned char
|
||
|
buffer of size <tt>SECT163K1_POINT_ORDER_SIZE</tt>.
|
||
|
@param[in] s The s component of the signature. This is an unsigned char
|
||
|
buffer of size <tt>SECT163K1_POINT_ORDER_SIZE</tt>.
|
||
|
@param[in] yieldLevel The yield level determines how often the user defined yield
|
||
|
function will be called. This is a number from <tt>0</tt> to <tt>10</tt>.
|
||
|
<tt>0</tt> will never yield.
|
||
|
<tt>1</tt> will yield the most often.
|
||
|
<tt>10</tt> will yield the least often.
|
||
|
@param[in] YieldFunc Pointer to a function to allow user defined yielding.
|
||
|
<tt>YieldFunc</tt> may be <tt>NULL</tt> if <tt>yieldLevel</tt> is <tt>0</tt>.
|
||
|
|
||
|
@retval MCE_ERR_FAIL_VERIFY The signature verification failed.
|
||
|
@retval MCE_ERR_NULL_PUBLIC_KEY <tt>publicKey</tt> is <tt>NULL</tt>.
|
||
|
@retval MCE_ERR_NULL_INPUT_BUF <tt>msgDigest</tt>, <tt>r</tt> or
|
||
|
<tt>s</tt> are <tt>NULL</tt>.
|
||
|
@retval MCE_ERR_NULL_FUNC_PTR <tt>YieldFunc</tt> is <tt>NULL</tt> and
|
||
|
<tt>YieldLevel</tt> is not <tt>0</tt>.
|
||
|
@retval MCE_ERR_BAD_INPUT <tt>YieldLevel</tt> is greater than <tt>10</tt>.
|
||
|
@retval MCE_SUCCESS Success.
|
||
|
*/
|
||
|
|
||
|
int ZSE_ECDSAVerify(unsigned char *publicKey,
|
||
|
unsigned char *msgDigest,
|
||
|
unsigned char *r,
|
||
|
unsigned char *s,
|
||
|
YieldFunc *yield,
|
||
|
unsigned long yieldLevel);
|
||
|
|
||
|
|
||
|
/**
|
||
|
|
||
|
Generates an ephemeral key pair using the specified random data generation
|
||
|
function. Normally, the public key is sent to the remote party as part of the
|
||
|
key agreement protocol.
|
||
|
|
||
|
@param[out] privateKey The generated private key. This is an unsigned char
|
||
|
buffer of size <tt>SECT163K1_PRIVATE_KEY_SIZE</tt>.
|
||
|
@param[out] publicKey The generated public key. This is an unsigned char
|
||
|
buffer of size
|
||
|
<tt>SECT163K1_COMPRESSED_PUBLIC_KEY_SIZE</tt>.
|
||
|
@param[in] GetRandomData Pointer to a function to get random data for
|
||
|
generating the ephemeral key pair.
|
||
|
@param[in] yieldLevel The yield level determines how often the user defined yield
|
||
|
function will be called. This is a number from <tt>0</tt> to <tt>10</tt>.
|
||
|
<tt>0</tt> will never yield.
|
||
|
<tt>1</tt> will yield the most often.
|
||
|
<tt>10</tt> will yield the least often.
|
||
|
@param[in] YieldFunc Pointer to a function to allow user defined yielding.
|
||
|
<tt>YieldFunc</tt> may be <tt>NULL</tt> if <tt>yieldLevel</tt> is <tt>0</tt>.
|
||
|
|
||
|
@retval MCE_ERR_NULL_OUTPUT_BUF <tt>privateKey</tt> or <tt>publicKey</tt>
|
||
|
are <tt>NULL</tt>.
|
||
|
@retval MCE_ERR_NULL_FUNC_PTR <tt>GetRandomData</tt> is <tt>NULL</tt> or
|
||
|
<tt>YieldFunc</tt> is <tt>NULL</tt> and
|
||
|
<tt>YieldLevel</tt> is not <tt>0</tt>.
|
||
|
@retval MCE_ERR_BAD_INPUT <tt>YieldLevel</tt> is greater than <tt>10</tt>.
|
||
|
@retval MCE_SUCCESS Success.
|
||
|
*/
|
||
|
|
||
|
int ZSE_ECCGenerateKey(unsigned char *privateKey,
|
||
|
unsigned char *publicKey,
|
||
|
GetRandomDataFunc *GetRandomData,
|
||
|
YieldFunc *yield,
|
||
|
unsigned long yieldLevel);
|
||
|
|
||
|
|
||
|
/**
|
||
|
|
||
|
Derives a shared secret using the ECMQV algorithm. The public key of the
|
||
|
remote party is reconstructed using its implicit certificate and the CA
|
||
|
public key.
|
||
|
|
||
|
@param[in] privateKey The static private key of the local entity. This is an
|
||
|
unsigned char buffer of size
|
||
|
<tt>SECT163K1_PRIVATE_KEY_SIZE</tt>.
|
||
|
@param[in] ephemeralPrivateKey The ephemeral private key of the local entity.
|
||
|
It should be generated using a previous call
|
||
|
to the function <tt>ECCGenerateKey</tt>. An
|
||
|
unsigned char buffer of size
|
||
|
<tt>SECT163K1_PRIVATE_KEY_SIZE</tt>.
|
||
|
@param[in] ephemeralPublicKey The ephemeral public key of the local entity.
|
||
|
It should be generated using a previous call
|
||
|
to the function <tt>ECCGenerateKey</tt>. An
|
||
|
unsigned char buffer of size
|
||
|
<tt>SECT163K1_COMPRESSED_PUBLIC_KEY_SIZE</tt>.
|
||
|
@param[in] remoteCertificate Implicit certificate of the remote party.
|
||
|
This is an unsigned char buffer of size
|
||
|
<tt>SECT163K1_CERTIFICATE_SIZE</tt>. The
|
||
|
static public key of the remote party is
|
||
|
derived from the certificate using the CA's
|
||
|
public key.
|
||
|
@param[in] remoteEphemeralPublicKey Ephemeral public key received from the
|
||
|
remote party. This is an unsigned char
|
||
|
buffer of size
|
||
|
<tt>SECT163K1_COMPRESSED_PUBLIC_KEY_SIZE</tt>.
|
||
|
@param[in] caPublicKey Public key of the certificate authority. The static
|
||
|
public key for the remote party is derived from the
|
||
|
certificate using the CA's public key.
|
||
|
@param[out] keyBits The derived shared secret. This is an unsigned char
|
||
|
buffer of size <tt>SECT163K1_SHARED_SECRET_SIZE</tt>.
|
||
|
@param[in] Hash Pointer to a function to hash the certificate data.
|
||
|
@param[in] yieldLevel The yield level determines how often the user defined yield
|
||
|
function will be called. This is a number from <tt>0</tt> to <tt>10</tt>.
|
||
|
<tt>0</tt> will never yield.
|
||
|
<tt>1</tt> will yield the most often.
|
||
|
<tt>10</tt> will yield the least often.
|
||
|
@param[in] YieldFunc Pointer to a function to allow user defined yielding.
|
||
|
<tt>YieldFunc</tt> may be <tt>NULL</tt> if <tt>yieldLevel</tt> is <tt>0</tt>.
|
||
|
|
||
|
@retval MCE_ERR_NULL_PRIVATE_KEY <tt>privateKey</tt> is <tt>NULL</tt>.
|
||
|
@retval MCE_ERR_NULL_EPHEM_PRI_KEY <tt>ephemeralPrivateKey</tt> is
|
||
|
<tt>NULL</tt>
|
||
|
@retval MCE_ERR_NULL_EPHEM_PUB_KEY <tt>ephemeralPublicKey</tt> or
|
||
|
<tt>remoteEphemeralPublicKey</tt> are
|
||
|
<tt>NULL</tt>.
|
||
|
@retval MCE_ERR_NULL_INPUT_BUF <tt>remoteCertificate</tt> is
|
||
|
<tt>NULL</tt>.
|
||
|
@retval MCE_ERR_NULL_PUBLIC_KEY <tt>caPublicKey</tt> is <tt>NULL</tt>.
|
||
|
@retval MCE_ERR_NULL_OUTPUT_BUF <tt>keyBits</tt> is <tt>NULL</tt>.
|
||
|
@retval MCE_ERR_NULL_FUNC_PTR <tt>Hash</tt> is <tt>NULL</tt> or
|
||
|
<tt>YieldFunc</tt> is <tt>NULL</tt> and
|
||
|
<tt>YieldLevel</tt> is not <tt>0</tt>.
|
||
|
@retval MCE_ERR_BAD_INPUT <tt>YieldLevel</tt> is greater than <tt>10</tt>.
|
||
|
@retval MCE_SUCCESS Success.
|
||
|
*/
|
||
|
|
||
|
int ZSE_ECCKeyBitGenerate(unsigned char *privateKey,
|
||
|
unsigned char *ephemeralPrivateKey,
|
||
|
unsigned char *ephemeralPublicKey,
|
||
|
unsigned char *remoteCertificate,
|
||
|
unsigned char *remoteEphemeralPublicKey,
|
||
|
unsigned char *caPublicKey,
|
||
|
unsigned char *keyBits,
|
||
|
HashFunc *Hash,
|
||
|
YieldFunc *yield,
|
||
|
unsigned long yieldLevel);
|
||
|
|
||
|
|
||
|
/**
|
||
|
|
||
|
Reconstructs the remote party's public key using its implicit certificate
|
||
|
and the CA public key.
|
||
|
|
||
|
@param[in] certificate Implicit certificate of the remote party. This is an unsigned
|
||
|
char buffer of size
|
||
|
<tt>SECT163K1_CERTIFICATE_SIZE</tt>. The static public
|
||
|
key of the remote party is derived from the certificate
|
||
|
using the CA's public key.
|
||
|
@param[in] caPublicKey Public key of the certificate authority. The static
|
||
|
public key of the remote party is derived from the
|
||
|
certificate using the CA's public key.
|
||
|
@param[out] publicKey The derived public key. This is an unsigned char buffer
|
||
|
of size
|
||
|
<tt>SECT163K1_COMPRESSED_PUBLIC_KEY_SIZE</tt>.
|
||
|
@param[in] Hash Pointer to a function to hash the certificate data.
|
||
|
@param[in] yieldLevel The yield level determines how often the user defined
|
||
|
yield function will be called. This is a number from
|
||
|
<tt>0</tt> to <tt>10</tt>.
|
||
|
<tt>0</tt> will never yield.
|
||
|
<tt>1</tt> will yield the most often.
|
||
|
<tt>10</tt> will yield the least often.
|
||
|
@param[in] YieldFunc Pointer to a function to allow user defined yielding.
|
||
|
<tt>YieldFunc</tt> may be <tt>NULL</tt> if
|
||
|
<tt>yieldLevel</tt> is <tt>0</tt>.
|
||
|
|
||
|
|
||
|
|
||
|
@retval MCE_ERR_NULL_INPUT_BUF <tt>certificate</tt> is <tt>NULL</tt>.
|
||
|
@retval MCE_ERR_NULL_PUBLIC_KEY <tt>caPublicKey</tt> is <tt>NULL</tt>.
|
||
|
@retval MCE_ERR_NULL_OUTPUT_BUF <tt>publicKey</tt> is <tt>NULL</tt>.
|
||
|
@retval MCE_ERR_NULL_FUNC_PTR <tt>Hash</tt> is <tt>NULL</tt> or
|
||
|
<tt>YieldFunc</tt> is <tt>NULL</tt> and
|
||
|
<tt>YieldLevel</tt> is not <tt>0</tt>.
|
||
|
@retval MCE_ERR_BAD_INPUT <tt>YieldLevel</tt> is greater than <tt>10</tt>.
|
||
|
*/
|
||
|
|
||
|
int ZSE_ECQVReconstructPublicKey(unsigned char* certificate,
|
||
|
unsigned char* caPublicKey,
|
||
|
unsigned char* publicKey,
|
||
|
HashFunc *Hash,
|
||
|
YieldFunc *yield,
|
||
|
unsigned long yieldLevel);
|
||
|
|
||
|
|
||
|
|
||
|
/**
|
||
|
|
||
|
Returns the version number for the product.
|
||
|
|
||
|
@retval ZSE_VERSION The product version number.
|
||
|
*/
|
||
|
|
||
|
unsigned long ZSE_GetVersion(void);
|
||
|
|
||
|
|
||
|
#ifdef __cplusplus
|
||
|
}
|
||
|
#endif
|
||
|
|
||
|
#endif
|