libp2p/crypto/ecnist

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: [], forbids: [].}
Return string representation of EC public key. Source   Edit   
proc `$`(seckey: EcPrivateKey): string {....raises: [], tags: [], forbids: [].}
Return string representation of EC private key. Source   Edit   
proc `$`(sig: EcSignature): string {....raises: [], tags: [], forbids: [].}
Return hexadecimal string representation of EC signature. Source   Edit   
proc `==`(a, b: EcSignature): bool {....raises: [], tags: [], forbids: [].}
Return true if both signatures sig1 and sig2 are equal. Source   Edit   
proc `==`(pubkey1, pubkey2: EcPublicKey): bool {....raises: [], tags: [],
    forbids: [].}
Returns true if both keys pubkey1 and pubkey2 are equal. Source   Edit   
proc `==`(seckey1, seckey2: EcPrivateKey): bool {....raises: [], tags: [],
    forbids: [].}
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: [], forbids: [].}
Generate ephemeral keys used to perform ECDHE. Source   Edit   
proc ephemeral(scheme: string; rng: var HmacDrbgContext): EcResult[EcKeyPair] {.
    ...raises: [], tags: [], forbids: [].}

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

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], forbids: [].}

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], forbids: [].}

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: [], forbids: [].}

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], forbids: [].}

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], forbids: [].}

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: [], forbids: [].}

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], forbids: [].}

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: [], forbids: [].}

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: [], forbids: [].}

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: [], forbids: [].}

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: [], forbids: [].}

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: [], forbids: [].}

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: [], forbids: [].}

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],
    forbids: [].}

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: 2023-10-04 18:27:56 UTC