src/core/crypto/ecdsa.hpp - third_party/openthread - Git at Google

 /*
  *  Copyright (c) 2018, The OpenThread Authors.
  *  All rights reserved.
  *
  *  Redistribution and use in source and binary forms, with or without
  *  modification, are permitted provided that the following conditions are met:
  *  1. Redistributions of source code must retain the above copyright
  *     notice, this list of conditions and the following disclaimer.
  *  2. 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.
  *  3. Neither the name of the copyright holder 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 HOLDER 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
  *   This file includes definitions for performing ECDSA signing.
  */

 #ifndef ECDSA_HPP_
 #define ECDSA_HPP_

 #include "openthread-core-config.h"

 #if OPENTHREAD_CONFIG_ECDSA_ENABLE

 #include <stdint.h>
 #include <stdlib.h>

 #include "common/error.hpp"
 #include "crypto/sha256.hpp"

 namespace ot {
 namespace Crypto {
 namespace Ecdsa {

 /**
  * @addtogroup core-security
  *
  * @{
  *
  */

 /**
  * This class implements ECDSA key-generation, signing, and verification for NIST P-256 curve using SHA-256 hash.
  *
  * NIST P-256 curve is also known as 256-bit Random ECP Group (RFC 5114 - 2.6), or secp256r1 (RFC 4492 - Appendix A).
  *
  */
 class P256
 {
 public:
     static constexpr uint16_t kFieldBitLength = 256; ///< Prime field bit length used by the P-256 curve.

     /**
      * Max bytes in binary representation of an MPI (multi-precision int).
      *
      */
     static constexpr uint8_t kMpiSize = kFieldBitLength / 8;

     class PublicKey;
     class KeyPair;

     /**
      * This class represents an ECDSA signature.
      *
      * The signature is encoded as the concatenated binary representation of two MPIs `r` and `s` which are calculated
      * during signing (RFC 6605 - section 4).
      *
      */
     OT_TOOL_PACKED_BEGIN
     class Signature
     {
         friend class KeyPair;
         friend class PublicKey;

     public:
         static constexpr uint8_t kSize = 2 * kMpiSize; ///< Signature size in bytes (two times the curve MPI size).

         /**
          * This method returns the signature as a byte array.
          *
          * @returns A pointer to the byte array containing the signature.
          *
          */
         const uint8_t *GetBytes(void) const { return mShared.mKey; }

     private:
         OT_TOOL_PACKED_BEGIN
         struct Mpis
         {
             uint8_t mR[kMpiSize];
             uint8_t mS[kMpiSize];
         } OT_TOOL_PACKED_END;

         union OT_TOOL_PACKED_FIELD
         {
             Mpis    mMpis;
             uint8_t mKey[kSize];
         } mShared;
     } OT_TOOL_PACKED_END;

     /**
      * This class represents a key pair (public and private keys).
      *
      * The key pair is stored using Distinguished Encoding Rules (DER) format (per RFC 5915).
      *
      */
     class KeyPair
     {
     public:
         /**
          * Max buffer size (in bytes) for representing the key-pair in DER format.
          *
          */
         static constexpr uint8_t kMaxDerSize = 125;

         /**
          * This constructor initializes a `KeyPair` as empty (no key).
          *
          */
         KeyPair(void)
             : mDerLength(0)
         {
         }

         /**
          * This method generates and populates the `KeyPair` with a new public/private keys.
          *
          * @retval kErrorNone         A new key pair was generated successfully.
          * @retval kErrorNoBufs       Failed to allocate buffer for key generation.
          * @retval kErrorNotCapable   Feature not supported.
          * @retval kErrorFailed       Failed to generate key.
          *
          */
         Error Generate(void);

         /**
          * This method gets the associated public key from the `KeyPair`.
          *
          * @param[out] aPublicKey     A reference to a `PublicKey` to output the value.
          *
          * @retval kErrorNone      Public key was retrieved successfully, and @p aPublicKey is updated.
          * @retval kErrorParse     The key-pair DER format could not be parsed (invalid format).
          *
          */
         Error GetPublicKey(PublicKey &aPublicKey) const;

         /**
          * This method gets the pointer to start of the buffer containing the key-pair info in DER format.
          *
          * The length (number of bytes) of DER format is given by `GetDerLength()`.
          *
          * @returns The pointer to the start of buffer containing the key-pair in DER format.
          *
          */
         const uint8_t *GetDerBytes(void) const { return mDerBytes; }

         /**
          * This method gets the length of the byte sequence representation of the key-pair in DER format.
          *
          * @returns The length of byte sequence representation of the key-pair in DER format.
          *
          */
         uint8_t GetDerLength(void) const { return mDerLength; }

         /**
          * This method gets the pointer to start of the key-pair buffer in DER format.
          *
          * This method gives non-const pointer to the buffer and is intended for populating the buffer and setting
          * the key-pair (e.g., reading the key-pair from non-volatile settings). The buffer contains `kMaxDerSize`
          * bytes. After populating the buffer, `SetDerLength()` can be used to set the the number of bytes written.
          *
          * @returns The pointer to the start of key-pair buffer in DER format.
          *
          */
         uint8_t *GetDerBytes(void) { return mDerBytes; }

         /**
          * This method sets the length of the byte sequence representation of the key-pair in DER format.
          *
          * @param[in] aDerLength   The length (number of bytes).
          *
          */
         void SetDerLength(uint8_t aDerLength) { mDerLength = aDerLength; }

         /**
          * This method calculates the ECDSA signature for a hashed message using the private key from `KeyPair`.
          *
          * This method uses the deterministic digital signature generation procedure from RFC 6979.
          *
          * @param[in]  aHash               The SHA-256 hash value of the message to use for signature calculation.
          * @param[out] aSignature          A reference to a `Signature` to output the calculated signature value.
          *
          * @retval kErrorNone           The signature was calculated successfully and @p aSignature was updated.
          * @retval kErrorParse          The key-pair DER format could not be parsed (invalid format).
          * @retval kErrorInvalidArgs    The @p aHash is invalid.
          * @retval kErrorNoBufs         Failed to allocate buffer for signature calculation.
          *
          */
         Error Sign(const Sha256::Hash &aHash, Signature &aSignature) const;

     private:
         Error Parse(void *aContext) const;

         uint8_t mDerBytes[kMaxDerSize];
         uint8_t mDerLength;
     };

     /**
      * This class represents a public key.
      *
      * The public key is stored as a byte sequence representation of an uncompressed curve point (RFC 6605 - sec 4).
      *
      */
     OT_TOOL_PACKED_BEGIN
     class PublicKey : public Equatable<PublicKey>
     {
         friend class KeyPair;

     public:
         static constexpr uint8_t kSize = kMpiSize * 2; ///< Size of the public key in bytes.

         /**
          * This method gets the pointer to the buffer containing the public key (as an uncompressed curve point).
          *
          * @return The pointer to the buffer containing the public key (with `kSize` bytes).
          *
          */
         const uint8_t *GetBytes(void) const { return mData; }

         /**
          * This method uses the `PublicKey` to verify the ECDSA signature of a hashed message.
          *
          * @param[in] aHash                The SHA-256 hash value of a message to use for signature verification.
          * @param[in] aSignature           The signature value to verify.
          *
          * @retval kErrorNone          The signature was verified successfully.
          * @retval kErrorSecurity      The signature is invalid.
          * @retval kErrorInvalidArgs   The key or has is invalid.
          * @retval kErrorNoBufs        Failed to allocate buffer for signature verification
          *
          */
         Error Verify(const Sha256::Hash &aHash, const Signature &aSignature) const;

     private:
         uint8_t mData[kSize];
     } OT_TOOL_PACKED_END;
 };

 /**
  * This function creates an ECDSA signature.
  *
  * @param[out]     aOutput            An output buffer where ECDSA sign should be stored.
  * @param[in,out]  aOutputLength      The length of the @p aOutput buffer.
  * @param[in]      aInputHash         An input hash.
  * @param[in]      aInputHashLength   The length of the @p aInputHash buffer.
  * @param[in]      aPrivateKey        A private key in PEM format.
  * @param[in]      aPrivateKeyLength  The length of the @p aPrivateKey buffer.
  *
  * @retval  kErrorNone         ECDSA sign has been created successfully.
  * @retval  kErrorNoBufs       Output buffer is too small.
  * @retval  kErrorInvalidArgs  Private key is not valid EC Private Key.
  * @retval  kErrorFailed       Error during signing.
  *
  */
 Error Sign(uint8_t *      aOutput,
            uint16_t &     aOutputLength,
            const uint8_t *aInputHash,
            uint16_t       aInputHashLength,
            const uint8_t *aPrivateKey,
            uint16_t       aPrivateKeyLength);

 /**
  * @}
  *
  */

 } // namespace Ecdsa
 } // namespace Crypto
 } // namespace ot

 #endif // OPENTHREAD_CONFIG_ECDSA_ENABLE

 #endif // ECDSA_HPP_
	/*
	* Copyright (c) 2018, The OpenThread Authors.
	* All rights reserved.
	*
	* Redistribution and use in source and binary forms, with or without
	* modification, are permitted provided that the following conditions are met:
	* 1. Redistributions of source code must retain the above copyright
	* notice, this list of conditions and the following disclaimer.
	* 2. 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.
	* 3. Neither the name of the copyright holder 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 HOLDER 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
	* This file includes definitions for performing ECDSA signing.
	*/

	#ifndef ECDSA_HPP_
	#define ECDSA_HPP_

	#include "openthread-core-config.h"

	#if OPENTHREAD_CONFIG_ECDSA_ENABLE

	#include <stdint.h>
	#include <stdlib.h>

	#include "common/error.hpp"
	#include "crypto/sha256.hpp"

	namespace ot {
	namespace Crypto {
	namespace Ecdsa {

	/**
	* @addtogroup core-security
	*
	* @{
	*
	*/

	/**
	* This class implements ECDSA key-generation, signing, and verification for NIST P-256 curve using SHA-256 hash.
	*
	* NIST P-256 curve is also known as 256-bit Random ECP Group (RFC 5114 - 2.6), or secp256r1 (RFC 4492 - Appendix A).
	*
	*/
	class P256
	{
	public:
	static constexpr uint16_t kFieldBitLength = 256; ///< Prime field bit length used by the P-256 curve.

	/**
	* Max bytes in binary representation of an MPI (multi-precision int).
	*
	*/
	static constexpr uint8_t kMpiSize = kFieldBitLength / 8;

	class PublicKey;
	class KeyPair;

	/**
	* This class represents an ECDSA signature.
	*
	* The signature is encoded as the concatenated binary representation of two MPIs `r` and `s` which are calculated
	* during signing (RFC 6605 - section 4).
	*
	*/
	OT_TOOL_PACKED_BEGIN
	class Signature
	{
	friend class KeyPair;
	friend class PublicKey;

	public:
	static constexpr uint8_t kSize = 2 * kMpiSize; ///< Signature size in bytes (two times the curve MPI size).

	/**
	* This method returns the signature as a byte array.
	*
	* @returns A pointer to the byte array containing the signature.
	*
	*/
	const uint8_t *GetBytes(void) const { return mShared.mKey; }

	private:
	OT_TOOL_PACKED_BEGIN
	struct Mpis
	{
	uint8_t mR[kMpiSize];
	uint8_t mS[kMpiSize];
	} OT_TOOL_PACKED_END;

	union OT_TOOL_PACKED_FIELD
	{
	Mpis mMpis;
	uint8_t mKey[kSize];
	} mShared;
	} OT_TOOL_PACKED_END;

	/**
	* This class represents a key pair (public and private keys).
	*
	* The key pair is stored using Distinguished Encoding Rules (DER) format (per RFC 5915).
	*
	*/
	class KeyPair
	{
	public:
	/**
	* Max buffer size (in bytes) for representing the key-pair in DER format.
	*
	*/
	static constexpr uint8_t kMaxDerSize = 125;

	/**
	* This constructor initializes a `KeyPair` as empty (no key).
	*
	*/
	KeyPair(void)
	: mDerLength(0)
	{
	}

	/**
	* This method generates and populates the `KeyPair` with a new public/private keys.
	*
	* @retval kErrorNone A new key pair was generated successfully.
	* @retval kErrorNoBufs Failed to allocate buffer for key generation.
	* @retval kErrorNotCapable Feature not supported.
	* @retval kErrorFailed Failed to generate key.
	*
	*/
	Error Generate(void);

	/**
	* This method gets the associated public key from the `KeyPair`.
	*
	* @param[out] aPublicKey A reference to a `PublicKey` to output the value.
	*
	* @retval kErrorNone Public key was retrieved successfully, and @p aPublicKey is updated.
	* @retval kErrorParse The key-pair DER format could not be parsed (invalid format).
	*
	*/
	Error GetPublicKey(PublicKey &aPublicKey) const;

	/**
	* This method gets the pointer to start of the buffer containing the key-pair info in DER format.
	*
	* The length (number of bytes) of DER format is given by `GetDerLength()`.
	*
	* @returns The pointer to the start of buffer containing the key-pair in DER format.
	*
	*/
	const uint8_t *GetDerBytes(void) const { return mDerBytes; }

	/**
	* This method gets the length of the byte sequence representation of the key-pair in DER format.
	*
	* @returns The length of byte sequence representation of the key-pair in DER format.
	*
	*/
	uint8_t GetDerLength(void) const { return mDerLength; }

	/**
	* This method gets the pointer to start of the key-pair buffer in DER format.
	*
	* This method gives non-const pointer to the buffer and is intended for populating the buffer and setting
	* the key-pair (e.g., reading the key-pair from non-volatile settings). The buffer contains `kMaxDerSize`
	* bytes. After populating the buffer, `SetDerLength()` can be used to set the the number of bytes written.
	*
	* @returns The pointer to the start of key-pair buffer in DER format.
	*
	*/
	uint8_t *GetDerBytes(void) { return mDerBytes; }

	/**
	* This method sets the length of the byte sequence representation of the key-pair in DER format.
	*
	* @param[in] aDerLength The length (number of bytes).
	*
	*/
	void SetDerLength(uint8_t aDerLength) { mDerLength = aDerLength; }

	/**
	* This method calculates the ECDSA signature for a hashed message using the private key from `KeyPair`.
	*
	* This method uses the deterministic digital signature generation procedure from RFC 6979.
	*
	* @param[in] aHash The SHA-256 hash value of the message to use for signature calculation.
	* @param[out] aSignature A reference to a `Signature` to output the calculated signature value.
	*
	* @retval kErrorNone The signature was calculated successfully and @p aSignature was updated.
	* @retval kErrorParse The key-pair DER format could not be parsed (invalid format).
	* @retval kErrorInvalidArgs The @p aHash is invalid.
	* @retval kErrorNoBufs Failed to allocate buffer for signature calculation.
	*
	*/
	Error Sign(const Sha256::Hash &aHash, Signature &aSignature) const;

	private:
	Error Parse(void *aContext) const;

	uint8_t mDerBytes[kMaxDerSize];
	uint8_t mDerLength;
	};

	/**
	* This class represents a public key.
	*
	* The public key is stored as a byte sequence representation of an uncompressed curve point (RFC 6605 - sec 4).
	*
	*/
	OT_TOOL_PACKED_BEGIN
	class PublicKey : public Equatable<PublicKey>
	{
	friend class KeyPair;

	public:
	static constexpr uint8_t kSize = kMpiSize * 2; ///< Size of the public key in bytes.

	/**
	* This method gets the pointer to the buffer containing the public key (as an uncompressed curve point).
	*
	* @return The pointer to the buffer containing the public key (with `kSize` bytes).
	*
	*/
	const uint8_t *GetBytes(void) const { return mData; }

	/**
	* This method uses the `PublicKey` to verify the ECDSA signature of a hashed message.
	*
	* @param[in] aHash The SHA-256 hash value of a message to use for signature verification.
	* @param[in] aSignature The signature value to verify.
	*
	* @retval kErrorNone The signature was verified successfully.
	* @retval kErrorSecurity The signature is invalid.
	* @retval kErrorInvalidArgs The key or has is invalid.
	* @retval kErrorNoBufs Failed to allocate buffer for signature verification
	*
	*/
	Error Verify(const Sha256::Hash &aHash, const Signature &aSignature) const;

	private:
	uint8_t mData[kSize];
	} OT_TOOL_PACKED_END;
	};

	/**
	* This function creates an ECDSA signature.
	*
	* @param[out] aOutput An output buffer where ECDSA sign should be stored.
	* @param[in,out] aOutputLength The length of the @p aOutput buffer.
	* @param[in] aInputHash An input hash.
	* @param[in] aInputHashLength The length of the @p aInputHash buffer.
	* @param[in] aPrivateKey A private key in PEM format.
	* @param[in] aPrivateKeyLength The length of the @p aPrivateKey buffer.
	*
	* @retval kErrorNone ECDSA sign has been created successfully.
	* @retval kErrorNoBufs Output buffer is too small.
	* @retval kErrorInvalidArgs Private key is not valid EC Private Key.
	* @retval kErrorFailed Error during signing.
	*
	*/
	Error Sign(uint8_t * aOutput,
	uint16_t & aOutputLength,
	const uint8_t *aInputHash,
	uint16_t aInputHashLength,
	const uint8_t *aPrivateKey,
	uint16_t aPrivateKeyLength);

	/**
	* @}
	*
	*/

	} // namespace Ecdsa
	} // namespace Crypto
	} // namespace ot

	#endif // OPENTHREAD_CONFIG_ECDSA_ENABLE

	#endif // ECDSA_HPP_