crys_ecpki_ecdsa.h

00001 /**************************************************************************************
00002 * Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved         *
00003 *                                                                                     *
00004 * This file and the related binary are licensed under the following license:          *
00005 *                                                                                     *
00006 * ARM Object Code and Header Files License, v1.0 Redistribution.                      *
00007 *                                                                                     *
00008 * Redistribution and use of object code, header files, and documentation, without     *
00009 * modification, are permitted provided that the following conditions are met:         *
00010 *                                                                                     *
00011 * 1) Redistributions must reproduce the above copyright notice and the                *
00012 *    following disclaimer in the documentation and/or other materials                 *
00013 *    provided with the distribution.                                                  *
00014 *                                                                                     *
00015 * 2) Unless to the extent explicitly permitted by law, no reverse                     *
00016 *    engineering, decompilation, or disassembly of is permitted.                      *
00017 *                                                                                     *
00018 * 3) Redistribution and use is permitted solely for the purpose of                    *
00019 *    developing or executing applications that are targeted for use                   *
00020 *    on an ARM-based product.                                                         *
00021 *                                                                                     *
00022 * DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND                  *
00023 * CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT             *
00024 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT,        *
00025 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE          *
00026 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,   *
00027 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED            *
00028 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR              *
00029 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF              *
00030 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING                *
00031 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS                  *
00032 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                        *
00033 **************************************************************************************/
00034 
00035 
00036 
00037 #ifndef CRYS_ECPKI_ECDSA_H
00038 #define CRYS_ECPKI_ECDSA_H
00039 
00040 /*!
00041 @file
00042 @brief Defines the APIs that support the ECDSA functions.
00043 @defgroup crys_ecpki_ecdsa CryptoCell ECDSA APIs
00044 @{
00045 @ingroup cryptocell_ecpki
00046 */
00047 
00048 #include "crys_error.h"
00049 #include "crys_ecpki_types.h"
00050 #include "crys_hash.h"
00051 #include "crys_rnd.h"
00052 
00053 #ifdef __cplusplus
00054 extern "C"
00055 {
00056 #endif
00057 
00058 
00059 
00060 /**************************************************************************
00061  *                CRYS_ECDSA_Sign - integrated function
00062  **************************************************************************/
00063 /*!
00064 @brief This function performs an ECDSA sign operation in integrated form.
00065 
00066 \note
00067 Using of HASH functions with HASH size greater than EC modulus size, is not recommended!.
00068 Algorithm according [ANS X9.62] standard.
00069 
00070 The message data may be either a non-hashed data or a digest of a hash function.
00071 For a non-hashed data, the message data will be hashed using the hash function indicated by ::CRYS_ECPKI_HASH_OpMode_t.
00072 For a digest, ::CRYS_ECPKI_HASH_OpMode_t should indicate the hash function that the message data was created by, and it will not be hashed.
00073 
00074 @return CRYS_OK on success.
00075 @return A non-zero value on failure as defined crys_ecpki_error.h, crys_hash_error.h or crys_rnd_error.h.
00076 **/
00077 CIMPORT_C CRYSError_t  CRYS_ECDSA_Sign(
00078                      void           *rndState_ptr,        /*!< [in/out] Pointer to the RND state structure. */
00079                      SaSiRndGenerateVectWorkFunc_t    rndGenerateVectFunc, /*!< [in] Pointer to the random vector generation function. */
00080                      CRYS_ECDSA_SignUserContext_t    *pSignUserContext,   /*!< [in/out] Pointer to the user buffer for signing the database. */
00081                      CRYS_ECPKI_UserPrivKey_t        *pSignerPrivKey,     /*!< [in]  A pointer to a user private key structure. */
00082                      CRYS_ECPKI_HASH_OpMode_t         hashMode,           /*!< [in]  One of the supported SHA-x HASH modes, as defined in
00083                                                     ::CRYS_ECPKI_HASH_OpMode_t.
00084                                                     \note MD5 is not supported. */
00085                      uint8_t                         *pMessageDataIn,    /*!< [in] Pointer to the input data to be signed.
00086                                                    The size of the scatter/gather list representing the data buffer
00087                                                    is limited to 128 entries, and the size of each entry is limited
00088                                                    to 64KB (fragments larger than 64KB are broken into
00089                                                    fragments <= 64KB). */
00090                      uint32_t                        messageSizeInBytes, /*!< [in]  Size of message data in bytes. */
00091                      uint8_t                        *pSignatureOut,      /*!< [in]  Pointer to a buffer for output of signature. */
00092                      uint32_t                       *pSignatureOutSize   /*!< [in/out] Pointer to the signature size. Used to pass the size of
00093                                                        the SignatureOut buffer (in), which must be >= 2
00094                                                        * OrderSizeInBytes. When the API returns,
00095                                                        it is replaced with the size of the actual signature (out). */
00096                      );
00097 
00098 
00099 
00100 /**************************************************************************
00101  *                CRYS_ECDSA_Verify integrated function
00102  **************************************************************************/
00103 /*!
00104 @brief This function performs an ECDSA verify operation in integrated form.
00105 Algorithm according [ANS X9.62] standard.
00106 
00107 The message data may be either a non-hashed data or a digest of a hash function.
00108 For a non-hashed data, the message data will be hashed using the hash function indicated by ::CRYS_ECPKI_HASH_OpMode_t.
00109 For a digest, ::CRYS_ECPKI_HASH_OpMode_t should indicate the hash function that the message data was created by, and it will not be hashed.
00110 
00111 @return CRYS_OK on success.
00112 @return A non-zero value on failure as defined crys_ecpki_error.h or crys_hash_error.h.
00113 */
00114 CIMPORT_C CRYSError_t  CRYS_ECDSA_Verify (
00115                     CRYS_ECDSA_VerifyUserContext_t  *pVerifyUserContext, /*!< [in] Pointer to the user buffer for signing the database. */
00116                     CRYS_ECPKI_UserPublKey_t        *pUserPublKey,       /*!< [in] Pointer to a user public key structure. */
00117                     CRYS_ECPKI_HASH_OpMode_t         hashMode,           /*!< [in] One of the supported SHA-x HASH modes, as defined in
00118                                                       ::CRYS_ECPKI_HASH_OpMode_t.
00119                                                       \note MD5 is not supported. */
00120                     uint8_t                        *pSignatureIn,       /*!< [in] Pointer to the signature to be verified. */
00121                     uint32_t                        SignatureSizeBytes, /*!< [in] Size of the signature (in bytes).  */
00122                     uint8_t                        *pMessageDataIn,     /*!< [in] Pointer to the input data that was signed (same as given to
00123                                                       the signing function). The size of the scatter/gather list representing
00124                                                       the data buffer is limited to 128 entries, and the size of each entry is
00125                                                       limited to 64KB (fragments larger than 64KB are broken into fragments <= 64KB). */
00126                     uint32_t                        messageSizeInBytes  /*!< [in] Size of the input data (in bytes). */
00127                     );
00128 
00129 
00130 /**********************************************************************************************************/
00131 
00132 
00133 #ifdef __cplusplus
00134 }
00135 #endif
00136 /**
00137 @}
00138  */
00139 #endif