libp2p/crypto/ecnist

    Dark Mode
Search:
Group by:
  Source   Edit

This module implements constant-time ECDSA and ECDHE for NIST elliptic curves secp256r1, secp384r1 and secp521r1.

This module uses unmodified parts of code from BearSSL library <https://bearssl.org/> Copyright(C) 2018 Thomas Pornin <pornin@bolet.org>.

Types

EcCurveKind = enum
  Secp256r1 = 23, Secp384r1 = 24, Secp521r1 = 25
  Source   Edit 
EcError = enum
  EcRngError, EcKeyGenError, EcPublicKeyError, EcKeyIncorrectError,
  EcSignatureError
  Source   Edit 
EcKeyPair = object
  seckey*: EcPrivateKey
  pubkey*: EcPublicKey
  Source   Edit 
EcPrivateKey = ref object
  buffer*: array[EC_KBUF_PRIV_MAX_SIZE, byte]
  key*: ec.EcPrivateKey
  Source   Edit 
EcPublicKey = ref object
  buffer*: array[EC_KBUF_PUB_MAX_SIZE, byte]
  key*: ec.EcPublicKey
  Source   Edit 
EcResult[T] = Result[T, EcError]
  Source   Edit 
EcSignature = ref object
  buffer*: seq[byte]
  Source   Edit

Consts

EcSupportedCurvesCint = [23, 24, 25]
  Source   Edit 
PubKey256Length = 65
  Source   Edit 
PubKey384Length = 97
  Source   Edit 
PubKey521Length = 133
  Source   Edit 
SecKey256Length = 32
  Source   Edit 
SecKey384Length = 48
  Source   Edit 
SecKey521Length = 66
  Source   Edit 
Secret256Length = 32
  Source   Edit 
Secret384Length = 48
  Source   Edit 
Secret521Length = 66
  Source   Edit 
Sig256Length = 64
  Source   Edit 
Sig384Length = 96
  Source   Edit 
Sig521Length = 132
  Source   Edit

Procs

proc `$`(pubkey: EcPublicKey): string {....raises: [], tags: [].}
Return string representation of EC public key.   Source   Edit 
proc `$`(seckey: EcPrivateKey): string {....raises: [], tags: [].}
Return string representation of EC private key.   Source   Edit 
proc `$`(sig: EcSignature): string {....raises: [], tags: [].}
Return hexadecimal string representation of EC signature.   Source   Edit 
proc `==`(a, b: EcSignature): bool {....raises: [], tags: [].}
Return true if both signatures sig1 and sig2 are equal.   Source   Edit 
proc `==`(pubkey1, pubkey2: EcPublicKey): bool {....raises: [], tags: [].}
Returns true if both keys pubkey1 and pubkey2 are equal.   Source   Edit 
proc `==`(seckey1, seckey2: EcPrivateKey): bool {....raises: [], tags: [].}
Returns true if both keys seckey1 and seckey2 are equal.   Source   Edit 
proc clear[T: EcPKI | EcKeyPair](pki: var T) {....raises: [].}
Wipe and clear EC private key, public key or signature object.   Source   Edit 
proc copy[T: EcPKI](dst: var T; src: T): bool {....raises: [].}

Copy EC private key, public key or signature src to dst.

Returns true on success, false otherwise.

  Source   Edit 
proc copy[T: EcPKI](src: T): T {.inline, ...raises: [].}
Returns copy of EC private key, public key or signature object src.   Source   Edit 
proc ephemeral(scheme: ECDHEScheme; rng: var HmacDrbgContext): EcResult[
    EcKeyPair] {....raises: [], tags: [].}
Generate ephemeral keys used to perform ECDHE.   Source   Edit 
proc ephemeral(scheme: string; rng: var HmacDrbgContext): EcResult[EcKeyPair] {.
    ...raises: [], tags: [].}

Generate ephemeral keys used to perform ECDHE using string encoding.

Currently supported encoding strings are P-256, P-384, P-521, if encoding string is not supported P-521 key will be generated.

  Source   Edit 
proc getBytes(pubkey: EcPublicKey): EcResult[seq[byte]] {....raises: [], tags: [].}
Serialize EC public key pubkey to ASN.1 DER binary form and return it.   Source   Edit 
proc getBytes(seckey: EcPrivateKey): EcResult[seq[byte]] {....raises: [], tags: [].}
Serialize EC private key seckey to ASN.1 DER binary form and return it.   Source   Edit 
proc getBytes(sig: EcSignature): EcResult[seq[byte]] {....raises: [], tags: [].}
Serialize EC signature sig to ASN.1 DER binary form and return it.   Source   Edit 
proc getPublicKey(seckey: EcPrivateKey): EcResult[EcPublicKey] {....raises: [],
    tags: [].}
Calculate and return EC public key from private key seckey.   Source   Edit 
proc getRawBytes(pubkey: EcPublicKey): EcResult[seq[byte]] {....raises: [],
    tags: [].}
Serialize EC public key pubkey to raw binary form and return it.   Source   Edit 
proc getRawBytes(seckey: EcPrivateKey): EcResult[seq[byte]] {....raises: [],
    tags: [].}
Serialize EC private key seckey to raw binary form and return it.   Source   Edit 
proc getRawBytes(sig: EcSignature): EcResult[seq[byte]] {....raises: [], tags: [].}
Serialize EC signature sig to raw binary form and return it.   Source   Edit 
proc getSecret(pubkey: EcPublicKey; seckey: EcPrivateKey): seq[byte] {.
    ...raises: [], tags: [RootEffect].}

Calculate ECDHE shared secret using Go's elliptic curve approach, using remote public key pubkey and local private key seckey and return shared secret.

If error happens length of result array will be 0.

  Source   Edit 
proc init(key: var EcPrivateKey; data: openArray[byte]): Result[void, Asn1Error] {.
    ...raises: [], tags: [RootEffect].}

Initialize EC private key or signature key from ASN.1 DER binary representation data.

Procedure returns Result[void, Asn1Error].

  Source   Edit 
proc init(pubkey: var EcPublicKey; data: openArray[byte]): Result[void,
    Asn1Error] {....raises: [], tags: [RootEffect].}

Initialize EC public key pubkey from ASN.1 DER binary representation data.

Procedure returns Result[void, Asn1Error].

  Source   Edit 
proc init(sig: var EcSignature; data: openArray[byte]): Result[void, Asn1Error] {.
    ...raises: [], tags: [].}

Initialize EC signature sig from raw binary representation data.

Procedure returns Result[void, Asn1Error].

  Source   Edit 
proc init(t: typedesc[EcPrivateKey]; data: openArray[byte]): EcResult[
    EcPrivateKey] {....raises: [].}
Initialize EC private key from ASN.1 DER binary representation data and return constructed object.   Source   Edit 
proc init(t: typedesc[EcPublicKey]; data: openArray[byte]): EcResult[EcPublicKey] {.
    ...raises: [].}
Initialize EC public key from ASN.1 DER binary representation data and return constructed object.   Source   Edit 
proc init(t: typedesc[EcSignature]; data: openArray[byte]): EcResult[EcSignature] {.
    ...raises: [].}
Initialize EC signature from raw binary representation data and return constructed object.   Source   Edit 
proc init[T: EcPKI](sospk: var T; data: string): Result[void, Asn1Error] {.
    inline, ...raises: [].}

Initialize EC private key, public key or signature sospk from ASN.1 DER hexadecimal string representation data.

Procedure returns Asn1Status.

  Source   Edit 
proc init[T: EcPKI](t: typedesc[T]; data: string): EcResult[T] {....raises: [].}
Initialize EC private key, public key or signature from hexadecimal string representation data and return constructed object.   Source   Edit 
proc initRaw(key: var EcPrivateKey; data: openArray[byte]): bool {....raises: [],
    tags: [RootEffect].}

Initialize EC private key or scalar key from raw binary representation data.

Length of data array must be SecKey256Length, SecKey384Length or SecKey521Length.

Procedure returns true on success, false otherwise.

  Source   Edit 
proc initRaw(pubkey: var EcPublicKey; data: openArray[byte]): bool {....raises: [],
    tags: [RootEffect].}

Initialize EC public key pubkey from raw binary representation data.

Length of data array must be PubKey256Length, PubKey384Length or PubKey521Length.

Procedure returns true on success, false otherwise.

  Source   Edit 
proc initRaw(sig: var EcSignature; data: openArray[byte]): bool {....raises: [],
    tags: [].}

Initialize EC signature sig from raw binary representation data.

Length of data array must be Sig256Length, Sig384Length or Sig521Length.

Procedure returns true on success, false otherwise.

  Source   Edit 
proc initRaw(t: typedesc[EcPrivateKey]; data: openArray[byte]): EcResult[
    EcPrivateKey] {....raises: [].}
Initialize EC private key from raw binary representation data and return constructed object.   Source   Edit 
proc initRaw(t: typedesc[EcPublicKey]; data: openArray[byte]): EcResult[
    EcPublicKey] {....raises: [].}
Initialize EC public key from raw binary representation data and return constructed object.   Source   Edit 
proc initRaw(t: typedesc[EcSignature]; data: openArray[byte]): EcResult[
    EcSignature] {....raises: [].}
Initialize EC signature from raw binary representation data and return constructed object.   Source   Edit 
proc initRaw[T: EcPKI](sospk: var T; data: string): bool {.inline, ...raises: [].}

Initialize EC private key, public key or signature sospk from raw hexadecimal string representation data.

Procedure returns true on success, false otherwise.

  Source   Edit 
proc initRaw[T: EcPKI](t: typedesc[T]; data: string): T {.inline, ...raises: [].}
Initialize EC private key, public key or signature from raw hexadecimal string representation data and return constructed object.   Source   Edit 
proc random(T: typedesc[EcKeyPair]; kind: EcCurveKind; rng: var HmacDrbgContext): EcResult[
    T] {....raises: [].}

Generate new random EC private and public keypair using BearSSL's HMAC-SHA256-DRBG algorithm.

kind elliptic curve kind of your choice (secp256r1, secp384r1 or secp521r1).

  Source   Edit 
proc random(T: typedesc[EcPrivateKey]; kind: EcCurveKind;
            rng: var HmacDrbgContext): EcResult[EcPrivateKey] {....raises: [].}

Generate new random EC private key using BearSSL's HMAC-SHA256-DRBG algorithm.

kind elliptic curve kind of your choice (secp256r1, secp384r1 or secp521r1).

  Source   Edit 
proc scalarMul(pub: EcPublicKey; sec: EcPrivateKey): EcPublicKey {....raises: [],
    tags: [RootEffect].}

Return scalar multiplication of pub and sec.

Returns point in curve as pub * sec or nil otherwise.

  Source   Edit 
proc sign[T: byte | char](seckey: EcPrivateKey; message: openArray[T]): EcResult[
    EcSignature] {....gcsafe, raises: [].}
Get ECDSA signature of data message using private key seckey.   Source   Edit 
proc toBytes(pubkey: EcPublicKey; data: var openArray[byte]): EcResult[int] {.
    ...raises: [], tags: [].}

Serialize EC public key pubkey to ASN.1 DER binary form and store it to data.

Procedure returns number of bytes (octets) needed to store EC public key, or 0 if public key is not in supported curve.

  Source   Edit 
proc toBytes(seckey: EcPrivateKey; data: var openArray[byte]): EcResult[int] {.
    ...raises: [], tags: [].}

Serialize EC private key seckey to ASN.1 DER binary form and store it to data.

Procedure returns number of bytes (octets) needed to store EC private key, or 0 if private key is not in supported curve.

  Source   Edit 
proc toBytes(sig: EcSignature; data: var openArray[byte]): EcResult[int] {.
    ...raises: [], tags: [].}

Serialize EC signature sig to ASN.1 DER binary form and store it to data.

Procedure returns number of bytes (octets) needed to store EC signature, or 0 if signature is not in supported curve.

  Source   Edit 
proc toRawBytes(pubkey: EcPublicKey; data: var openArray[byte]): EcResult[int] {.
    ...raises: [], tags: [].}

Serialize EC public key pubkey to uncompressed form specified in section 4.3.6 of ANSI X9.62.

Returns number of bytes (octets) needed to store EC public key, or 0 if public key is not in supported curve.

  Source   Edit 
proc toRawBytes(seckey: EcPrivateKey; data: var openArray[byte]): EcResult[int] {.
    ...raises: [], tags: [].}

Serialize EC private key seckey to raw binary form and store it to data.

Returns number of bytes (octets) needed to store EC private key, or 0 if private key is not in supported curve.

  Source   Edit 
proc toRawBytes(sig: EcSignature; data: var openArray[byte]): int {....raises: [],
    tags: [].}

Serialize EC signature sig to raw binary form and store it to data.

Returns number of bytes (octets) needed to store EC signature, or 0 if signature is not in supported curve.

  Source   Edit 
proc toSecret(pubkey: EcPublicKey; seckey: EcPrivateKey;
              data: var openArray[byte]): int {....raises: [], tags: [RootEffect].}

Calculate ECDHE shared secret using Go's elliptic/curve approach, using remote public key pubkey and local private key seckey and store shared secret to data.

Returns number of bytes (octets) needed to store shared secret, or 0 on error.

data array length must be at least 32 bytes for secp256r1, 48 bytes for secp384r1 and 66 bytes for secp521r1.

  Source   Edit 
proc verify[T: byte | char](sig: EcSignature; message: openArray[T];
                            pubkey: EcPublicKey): bool {.inline, ...raises: [].}

Verify ECDSA signature sig using public key pubkey and data message.

Return true if message verification succeeded, false if verification failed.

  Source   Edit

Templates

template getPrivateKeyLength(curve: EcCurveKind): int
  Source   Edit 
template getPublicKeyLength(curve: EcCurveKind): int
  Source   Edit

Made with Nim. Generated: 2024-12-21 01:20:54 UTC