ECDSA.h

Go to the documentation of this file.

/*
 * Copyright (c) 2017-2019, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
 * @file ECDSA.h
 *
 * @brief TI Driver for Elliptic Curve Digital Signature Algorithm.
 *
 *
 * @anchor ti_drivers_ECDSA_Overview
 * # Overview #
 *
 * The Elliptic Curve Digital Signature Algorithm (ECDSA) is a message
 * authentication scheme between two parties based on operation on elliptic
 * curves over finite fields.
 *
 * Signing a message with ECDSA proves to the recipient that the sender of
 * the message is in possession of the private key corresponding to the
 * transmitted public key used during verification.
 * For most practical systems, this ensures message authentication and
 * integrity.
 *
 * # Steps involved #
 *  - The sender hashes the message they wish to authenticate and
 *    truncates it to the length of the curve parameters of the
 *    elliptic curve used by both parties.
 *  - The sender generates a per-message secret number (PMSN) where
 *    0 < PMSN < N. This number must (!) be unique for each message and be
 *    kept secret. If a PMSN is reused to authenticate more than one message,
 *    the secret key of the sender can be derived from these two messages
 *    and signatures!
 *  - The sender generates r and s where 0 < r, s < N. These two integers
 *    constitute the actual signature of the message.
 *  - The sender transmits the message, r, s, and the public key to the
 *    recipient.
 *  - The recipient calculates the hash of the message using an agreed
 *    upon hash function and truncates it to the length of the curve
 *    parameters of the elliptic curve used by both parties
 *  - The recipient uses the hash, s, and the sender's public key to
 *    recalculate r.
 *  - The recipient accepts the signature if the received and calculated r
 *    match. Otherwise, they reject the signature.
 *
 * @anchor ti_drivers_ECDSA_Usage
 * # Usage #
 *
 * ## Before starting an ECDSA operation #
 *
 * Before starting an ECDSA operation, the application must do the following:
 *      - Call ECDSA_init() to initialize the driver
 *      - Call ECDSA_Params_init() to initialize the ECDSA_Params to default values.
 *      - Modify the ECDSA_Params as desired
 *      - Call ECDSA_open() to open an instance of the driver
 *
 * ## Signing a message #
 * To sign a message using an agreed upon hash function and elliptic curve, the
 * application must do the following:
 *  - Initialize an ECDSA_OperationSign struct by calling ECDSA_OperationSign_init().
 *  - Generate the keying material for the private key. This keying material must
 *    be an integer in the interval [1, n - 1], where n is the order of the curve.
 *    It should be stored in an array with the least significant byte of the integer
 *    hex representation stored in the lowest address of the array (little-endian).
 *    The array should be the same length as the curve parameters of the curve used.
 *    The driver can be configured to validate public and private keys against the
 *    provided curve.
 *  - Initialize the private key CryptoKey. CryptoKeys are opaque datastructures and representations
 *    of keying material and its storage. Depending on how the keying material
 *    is stored (RAM or flash, key store, key blob), the CryptoKey must be
 *    initialized differently. The ECDSA API can handle all types of CryptoKey.
 *    However, not all device-specific implementions support all types of CryptoKey.
 *    Devices without a key store will not support CryptoKeys with keying material
 *    stored in a key store for example.
 *    All devices support plaintext CryptoKeys.
 *  - Initialize the pmsn CryptoKey. The PMSN itself should be a 0-padded integer of
 *    the same length as the curve parameters of the agreed upon curve and
 *    where 0 < PMSN < N. The driver will enforce this restriction and reject invalid
 *    PMSNs.
 *  - Hash the message using a previously agreed upon hash function and truncate
 *    the hash to the length of the curve parameters of the agreed upon curve.
 *  - Call  ECDSA_sign(). The r and s vectors will be written to the buffers
 *    provided in the function call. Ensure the return value is
 *    ECDSA_STATUS_SUCCESS.
 *
 * ## Verifying a message #
 * After receiving the message, public key, r, and s, the application should
 * do the following to verify the signature:
 *  - Initialize an ECDSA_OperationVerify struct by calling ECDSA_OperationVerify_init().
 *  - Hash the message using a previously agreed upon hash function and truncate
 *    the hash to the length of the curve parameters of the agreed upon curve.
 *  - Initialize a CryptoKey as public key with the keying material received from the other
 *    party.
 *  - Call ECDSA_verify(). Ensure the return value is ECDSA_STATUS_SUCCESS. The
 *    driver will validate the received public key against the provided curve.
 *
 * ## General usage #
 * The API expects elliptic curves as defined in ti/drivers/cryptoutils/ecc/ECCParams.h.
 * Several commonly used curves are provided. Check the device-specific ECDSA documentation
 * for curve type (short Weierstrass, Montgomery, Edwards) support for your device.
 * ECDSA support for a curve type on a device does not imply curve-type support for
 * other ECC schemes.
 *
 * Public keys and shared secrets are points on an elliptic curve. These points can
 * be expressed in several ways. The most common one is in affine coordinates as an
 * X,Y pair.
 * This API uses points expressed in affine coordinates.
 * The point is stored as a concatenated array of X followed by Y in a location
 * described by its CryptoKey.
 *
 * This API accepts and returns the keying material of public keys according
 * to the following table:
 *
 * | Curve Type         | Keying Material Array | Array Length              |
 * |--------------------|-----------------------|---------------------------|
 * | Short Weierstrass  | [X, Y]                | 2 * Curve Param Length    |
 * | Montgomery         | [X, Y]                | 2 * Curve Param Length    |
 * | Edwards            | [X, Y]                | 2 * Curve Param Length    |
 *
 * @anchor ti_drivers_ECDSA_Synopsis
 * ## Synopsis
 * @anchor ti_drivers_ECDSA_Synopsis_Code
 * @code
 * // Import ECDSA Driver definitions
 * #include <ti/drivers/ECDSA.h>
 *
 * // Since we are using default ECDSA_Params, we just pass in NULL for that parameter.
 * ecdsaHandle = ECDSA_open(0, NULL);
 *
 * if (!ecdsaHandle) {
 *     // Handle error
 * }
 *
 * // Initialize myPrivateKey
 * CryptoKeyPlaintext_initKey(&myPrivateKey, myPrivateKeyingMaterial, sizeof(myPrivateKeyingMaterial));
 * CryptoKeyPlaintext_initKey(&pmsnKey, pmsn, sizeof(pmsn));
 *
 * // Initialize the operation
 * ECDSA_OperationSign_init(&operationSign);
 * operationSign.curve             = &ECCParams_NISTP256;
 * operationSign.myPrivateKey      = &myPrivateKey;
 * operationSign.pmsn              = &pmsnKey;
 * operationSign.hash              = messageHash;
 * operationSign.r                 = r;
 * operationSign.s                 = s;
 *
 * // Generate the signature
 * operationResult = ECDSA_sign(ecdsaHandle, &operationSign);
 *
 * // Initialize theirPublicKey
 * CryptoKeyPlaintext_initKey(&theirPublicKey, theirPublicKeyingMaterial, sizeof(theirPublicKeyingMaterial));
 *
 * ECDSA_OperationVerify_init(&operationVerify);
 * operationVerify.curve           = &ECCParams_NISTP256;
 * operationVerify.theirPublicKey  = &theirPublicKey;
 * operationVerify.hash            = messageHash;
 * operationVerify.r               = r;
 * operationVerify.s               = s;
 *
 * // Generate the keying material for myPublicKey and store it in myPublicKeyingMaterial
 * operationResult = ECDSA_verify(ecdsaHandle, &operationVerify);
 *
 * // Close the driver
 * ECDSA_close(ecdsaHandle);
 *
 * @anchor ti_drivers_ECDSA_Examples
 *
 * # Examples #
 *
 * ## ECDSA sign with plaintext CryotoKeys #
 *
 * @code
 *
 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 * #include <ti/drivers/ECDSA.h>
 *
 * ...
 *
 * // This vector is taken from the NIST ST toolkit examples from ECDSA_Prime.pdf
 * uint8_t myPrivateKeyingMaterial[32] = {0x96, 0xBF, 0x85, 0x49, 0xC3, 0x79, 0xE4, 0x04,
 *                                        0xED, 0xA1, 0x08, 0xA5, 0x51, 0xF8, 0x36, 0x23,
 *                                        0x12, 0xD8, 0xD1, 0xB2, 0xA5, 0xFA, 0x57, 0x06,
 *                                        0xE2, 0xCC, 0x22, 0x5C, 0xF6, 0xF9, 0x77, 0xC4};
 * uint8_t messageHashSHA256[32]        = {0xC4, 0xA8, 0xC8, 0x99, 0x28, 0xCF, 0x80, 0xB6,
 *                                         0xE4, 0x42, 0xD5, 0xBD, 0x28, 0x4D, 0xE3, 0xFD,
 *                                         0x3A, 0x13, 0xD8, 0x65, 0x0C, 0x41, 0x1C, 0x21,
 *                                         0x48, 0x95, 0x79, 0x2A, 0xA1, 0x41, 0x1A, 0xA4};
 * uint8_t pmsn[32]                     = {0xAE, 0x50, 0xEE, 0xFA, 0x27, 0xB4, 0xDB, 0x14,
 *                                         0x9F, 0xE1, 0xFB, 0x04, 0xF2, 0x4B, 0x50, 0x58,
 *                                         0x91, 0xE3, 0xAC, 0x4D, 0x2A, 0x5D, 0x43, 0xAA,
 *                                         0xCA, 0xC8, 0x7F, 0x79, 0x52, 0x7E, 0x1A, 0x7A};
 * uint8_t r[32] = {0};
 * uint8_t s[32] = {0};
 *
 *
 * CryptoKey myPrivateKey;
 * CryptoKey pmsnKey;
 *
 * ECDSA_Handle ecdsaHandle;
 *
 * int_fast16_t operationResult;
 *
 * // Since we are using default ECDSA_Params, we just pass in NULL for that parameter.
 * ecdsaHandle = ECDSA_open(0, NULL);
 *
 * if (!ecdsaHandle) {
 *     // Handle error
 * }
 *
 * // Initialize myPrivateKey
 * CryptoKeyPlaintext_initKey(&myPrivateKey, myPrivateKeyingMaterial, sizeof(myPrivateKeyingMaterial));
 * CryptoKeyPlaintext_initKey(&pmsnKey, pmsn, sizeof(pmsn));
 *
 * // Initialize the operation
 * ECDSA_OperationSign_init(&operationSign);
 * operationSign.curve             = &ECCParams_NISTP256;
 * operationSign.myPrivateKey      = &myPrivateKey;
 * operationSign.pmsn              = &pmsnKey;
 * operationSign.hash              = messageHash;
 * operationSign.r                 = r;
 * operationSign.s                 = s;
 *
 * // Generate the signature
 * operationResult = ECDSA_sign(ecdsaHandle, &operationSign);
 *
 * if (operationResult != ECDSA_STATUS_SUCCESS) {
 *     // Handle error
 * }
 *
 * // Send out signature
 * // r should be   0x4F, 0x10, 0x46, 0xCA, 0x9A, 0xB6, 0x25, 0x73,
 * //               0xF5, 0x3E, 0x0B, 0x1F, 0x6F, 0x31, 0x4C, 0xE4,
 * //               0x81, 0x0F, 0x50, 0xB1, 0xF3, 0xD1, 0x65, 0xFF,
 * //               0x65, 0x41, 0x7F, 0xD0, 0x76, 0xF5, 0x42, 0x2B
 * //
 * // s should be   0xF1, 0xFA, 0x63, 0x6B, 0xDB, 0x9B, 0x32, 0x4B,
 * //               0x2C, 0x26, 0x9D, 0xE6, 0x6F, 0x88, 0xC1, 0x98,
 * //               0x81, 0x2A, 0x50, 0x89, 0x3A, 0x99, 0x3A, 0x3E,
 * //               0xCD, 0x92, 0x63, 0x2D, 0x12, 0xC2, 0x42, 0xDC
 *
 * @endcode
 *
 *
 * ## ECDSA verify with plaintext CryotoKeys #
 *
 * @code
 *
 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 * #include <ti/drivers/ECDSA.h>
 *
 * ...
 *
 * // This vector is taken from the NIST ST toolkit examples from ECDSA_Prime.pdf
 * uint8_t theirPublicKeyingMaterial[64] =  {0x19, 0x7A, 0xBC, 0x89, 0x08, 0xCD, 0x01, 0x82,
 *                                           0xA3, 0xA2, 0x9E, 0x1E, 0xAD, 0xA0, 0xB3, 0x62,
 *                                           0x1C, 0xBA, 0x98, 0x47, 0x73, 0x8C, 0xDC, 0xF1,
 *                                           0xD3, 0xBA, 0x94, 0xFE, 0xFD, 0x8A, 0xE0, 0xB7,
 *                                           0x09, 0x5E, 0xCC, 0x06, 0xC6, 0xBB, 0x63, 0xB5,
 *                                           0x61, 0x9E, 0x52, 0x43, 0xAE, 0xC7, 0xAD, 0x63,
 *                                           0x90, 0x72, 0x28, 0x19, 0xE4, 0x26, 0xB2, 0x4B,
 *                                           0x7A, 0xBF, 0x9D, 0x95, 0x47, 0xF7, 0x03, 0x36};
 * uint8_t messageHashSHA256[32] =          {0xC4, 0xA8, 0xC8, 0x99, 0x28, 0xCF, 0x80, 0xB6,
 *                                           0xE4, 0x42, 0xD5, 0xBD, 0x28, 0x4D, 0xE3, 0xFD,
 *                                           0x3A, 0x13, 0xD8, 0x65, 0x0C, 0x41, 0x1C, 0x21,
 *                                           0x48, 0x95, 0x79, 0x2A, 0xA1, 0x41, 0x1A, 0xA4};
 * uint8_t r[32] =                          {0x4F, 0x10, 0x46, 0xCA, 0x9A, 0xB6, 0x25, 0x73,
 *                                           0xF5, 0x3E, 0x0B, 0x1F, 0x6F, 0x31, 0x4C, 0xE4,
 *                                           0x81, 0x0F, 0x50, 0xB1, 0xF3, 0xD1, 0x65, 0xFF,
 *                                           0x65, 0x41, 0x7F, 0xD0, 0x76, 0xF5, 0x42, 0x2B};
 * uint8_t s[32] =                          {0xF1, 0xFA, 0x63, 0x6B, 0xDB, 0x9B, 0x32, 0x4B,
 *                                           0x2C, 0x26, 0x9D, 0xE6, 0x6F, 0x88, 0xC1, 0x98,
 *                                           0x81, 0x2A, 0x50, 0x89, 0x3A, 0x99, 0x3A, 0x3E,
 *                                           0xCD, 0x92, 0x63, 0x2D, 0x12, 0xC2, 0x42, 0xDC};
 *
 *
 * CryptoKey theirPublicKey;
 *
 * ECDSA_Handle ecdsaHandle;
 *
 * int_fast16_t operationResult;
 *
 * ECDSA_OperationVerify operationVerify;
 *
 * // Since we are using default ECDSA_Params, we just pass in NULL for that parameter.
 * ecdsaHandle = ECDSA_open(0, NULL);
 *
 * if (!ecdsaHandle) {
 *     // Handle error
 * }
 *
 * // Initialize theirPublicKey
 * CryptoKeyPlaintext_initKey(&theirPublicKey, theirPublicKeyingMaterial, sizeof(theirPublicKeyingMaterial));
 *
 * ECDSA_OperationVerify_init(&operationVerify);
 * operationVerify.curve           = &ECCParams_NISTP256;
 * operationVerify.theirPublicKey  = &theirPublicKey;
 * operationVerify.hash            = messageHash;
 * operationVerify.r               = r;
 * operationVerify.s               = s;
 *
 * // Generate the keying material for myPublicKey and store it in myPublicKeyingMaterial
 * operationResult = ECDSA_verify(ecdsaHandle, &operationVerify);
 *
 * if (operationResult != ECDSA_STATUS_SUCCESS) {
 *     // Handle error
 * }
 *
 * @endcode
 *
 *
 */


#ifndef ti_drivers_ECDSA__include
#define ti_drivers_ECDSA__include

#ifdef __cplusplus
extern "C" {
#endif

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>
#include <ti/drivers/cryptoutils/ecc/ECCParams.h>

#define ECDSA_STATUS_RESERVED        (-32)

#define ECDSA_STATUS_SUCCESS         (0)

#define ECDSA_STATUS_ERROR           (-1)

#define ECDSA_STATUS_RESOURCE_UNAVAILABLE (-2)

#define ECDSA_STATUS_INVALID_PMSN (-3)

#define ECDSA_STATUS_R_LARGER_THAN_ORDER (-4)

#define ECDSA_STATUS_S_LARGER_THAN_ORDER (-5)

#define ECDSA_STATUS_PUBLIC_KEY_NOT_ON_CURVE (-6)

#define ECDSA_STATUS_PUBLIC_KEY_LARGER_THAN_PRIME (-7)

#define ECDSA_STATUS_POINT_AT_INFINITY (-8)

#define ECDSA_STATUS_CANCELED (-9)

typedef struct ECDSA_Config *ECDSA_Handle;

typedef enum {
    ECDSA_RETURN_BEHAVIOR_CALLBACK = 1,     
    ECDSA_RETURN_BEHAVIOR_BLOCKING = 2,     
    ECDSA_RETURN_BEHAVIOR_POLLING  = 4,     
} ECDSA_ReturnBehavior;

typedef struct ECDSA_Config {
    void               *object;

    void         const *hwAttrs;
} ECDSA_Config;

typedef struct {
    const ECCParams_CurveParams     *curve;                     
    const CryptoKey                 *myPrivateKey;              
    const CryptoKey                 *pmsn;                      
    const uint8_t                   *hash;                      
    uint8_t                         *r;                         
    uint8_t                         *s;                         
} ECDSA_OperationSign;

typedef struct {
    const ECCParams_CurveParams     *curve;             
    const CryptoKey                 *theirPublicKey;    
    const uint8_t                   *hash;              
    const uint8_t                   *r;                 
    const uint8_t                   *s;                 
} ECDSA_OperationVerify;

typedef union {
    ECDSA_OperationSign     *sign;      
    ECDSA_OperationVerify   *verify;    
} ECDSA_Operation;

typedef enum {
    ECDSA_OPERATION_TYPE_SIGN = 1,
    ECDSA_OPERATION_TYPE_VERIFY = 2,
} ECDSA_OperationType;

typedef void (*ECDSA_CallbackFxn) (ECDSA_Handle handle,
                                   int_fast16_t returnStatus,
                                   ECDSA_Operation operation,
                                   ECDSA_OperationType operationType);

typedef struct {
    ECDSA_ReturnBehavior    returnBehavior;             
    ECDSA_CallbackFxn       callbackFxn;                
    uint32_t                timeout;                    
    void                   *custom;                     
} ECDSA_Params;

void ECDSA_init(void);

void ECDSA_close(ECDSA_Handle handle);

ECDSA_Handle ECDSA_open(uint_least8_t index, ECDSA_Params *params);

void ECDSA_Params_init(ECDSA_Params *params);

void ECDSA_OperationSign_init(ECDSA_OperationSign *operation);

void ECDSA_OperationVerify_init(ECDSA_OperationVerify *operation);

int_fast16_t ECDSA_sign(ECDSA_Handle handle, ECDSA_OperationSign *operation);

int_fast16_t ECDSA_verify(ECDSA_Handle handle, ECDSA_OperationVerify *operation);

int_fast16_t ECDSA_cancelOperation(ECDSA_Handle handle);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_ECDSA__include */