libp2p/crypto/crypto

    Dark Mode
Search:
Group by:
  Source   Edit

Nim-Libp2p Copyright (c) 2018 Status Research & Development GmbH

Licensed under either of

at your option. This file may not be copied, modified, or distributed except according to those terms.

This module implements Public Key and Private Key interface for libp2p.Serialization/Deserialization helpers

Types

CryptoError = enum
  KeyError, SigError, HashError, SchemeError
  Source   Edit 
CryptoResult[T] = Result[T, CryptoError]
  Source   Edit 
DigestSheme = enum
  Sha256, Sha512
  Source   Edit 
KeyPair = object
  seckey*: PrivateKey
  pubkey*: PublicKey
  Source   Edit 
PKScheme = enum
  RSA = 0, Ed25519, Secp256k1, ECDSA
  Source   Edit 
PrivateKey = object
  case scheme*: PKScheme
  of PKScheme.RSA:
      when supported(RSA):
          rsakey*: rsa.RsaPrivateKey

      else:
          nil

    
  of PKScheme.Ed25519:
      when supported(Ed25519):
          edkey*: EdPrivateKey

      else:
          nil

    
  of PKScheme.Secp256k1:
      when supported(Secp256k1):
          skkey*: SkPrivateKey

      else:
          nil

    
  of PKScheme.ECDSA:
      when supported(ECDSA):
          eckey*: ecnist.EcPrivateKey

      else:
          nil
  Source   Edit 
PublicKey = object
  case scheme*: PKScheme
  of PKScheme.RSA:
      when PKScheme.RSA in SupportedSchemes:
          rsakey*: rsa.RsaPublicKey

      else:
          nil

    
  of PKScheme.Ed25519:
      when supported(Ed25519):
          edkey*: EdPublicKey

      else:
          nil

    
  of PKScheme.Secp256k1:
      when supported(Secp256k1):
          skkey*: SkPublicKey

      else:
          nil

    
  of PKScheme.ECDSA:
      when supported(ECDSA):
          eckey*: ecnist.EcPublicKey

      else:
          nil
  Source   Edit 
Secret = object
  ivsize*: int
  keysize*: int
  macsize*: int
  data*: seq[byte]
  Source   Edit 
Signature = object
  data*: seq[byte]
  Source   Edit

Consts

libp2p_pki_schemes = "rsa,ed25519,secp256k1,ecnist"
  Source   Edit 
RsaDefaultKeySize = 3072
  Source   Edit 
SupportedSchemes = {RSA, Ed25519, Secp256k1, ECDSA}
  Source   Edit 
SupportedSchemesInt = {0, 1, 2, 3}
  Source   Edit

Procs

proc `$`(key: PrivateKey | PublicKey): string {....raises: [Defect].}
Get string representation of private/public key key.   Source   Edit 
proc `$`(sig: Signature): string {....raises: [Defect], tags: [].}
Get string representation of signature sig.   Source   Edit 
proc `==`(key1, key2: PrivateKey): bool {....raises: [Defect], tags: [].}
Return true if two private keys key1 and key2 of the same scheme and equal.   Source   Edit 
proc `==`(key1, key2: PublicKey): bool {.inline, ...raises: [Defect], tags: [].}
Return true if two public keys key1 and key2 of the same scheme and equal.   Source   Edit 
proc createExchange(epubkey, signature: openArray[byte]): seq[byte] {.
    ...raises: [Defect], tags: [].}
Create SecIO exchange message using ephemeral public key epubkey and signature of proposal blocks signature.   Source   Edit 
proc createProposal(nonce, pubkey: openArray[byte];
                    exchanges, ciphers, hashes: string): seq[byte] {.
    ...raises: [Defect], tags: [].}
Create SecIO proposal message using random nonce, local public key pubkey, comma-delimieted list of supported exchange schemes exchanges, comma-delimeted list of supported ciphers ciphers and comma-delimeted list of supported hashes hashes.   Source   Edit 
proc decodeExchange(message: seq[byte]; pubkey, signature: var seq[byte]): bool {.
    ...raises: [Defect], tags: [].}

Parse incoming exchange message and decode remote ephemeral public key pubkey and signature signature.

Procedure returns true on success and false on error.

  Source   Edit 
proc decodeProposal(message: seq[byte]; nonce, pubkey: var seq[byte];
                    exchanges, ciphers, hashes: var string): bool {.
    ...raises: [Defect], tags: [].}

Parse incoming proposal message and decode remote random nonce nonce, remote public key pubkey, comma-delimieted list of supported exchange schemes exchanges, comma-delimeted list of supported ciphers ciphers and comma-delimeted list of supported hashes hashes.

Procedure returns true on success and false on error.

  Source   Edit 
proc ephemeral(scheme: ECDHEScheme; rng: var BrHmacDrbgContext): CryptoResult[
    EcKeyPair] {....raises: [Defect], tags: [].}
Generate ephemeral keys used to perform ECDHE.   Source   Edit 
proc ephemeral(scheme: string; rng: var BrHmacDrbgContext): CryptoResult[
    EcKeyPair] {....raises: [Defect], 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(key: PrivateKey): CryptoResult[seq[byte]] {....raises: [Defect],
    tags: [].}
Return private key key in binary form (using libp2p's protobuf serialization).   Source   Edit 
proc getBytes(key: PublicKey): CryptoResult[seq[byte]] {....raises: [Defect],
    tags: [].}
Return public key key in binary form (using libp2p's protobuf serialization).   Source   Edit 
proc getBytes(sig: Signature): seq[byte] {....raises: [Defect], tags: [].}
Return signature sig in binary form.   Source   Edit 
proc getField(pb: ProtoBuffer; field: int; value: var Signature): ProtoResult[
    bool] {....raises: [Defect], tags: [].}

Deserialize signature from protobuf's message pb using field index field.

On success deserialized signature will be stored in value.

  Source   Edit 
proc getField[T: PublicKey | PrivateKey](pb: ProtoBuffer; field: int;
    value: var T): ProtoResult[bool] {....raises: [Defect].}

Deserialize public/private key from protobuf's message pb using field index field.

On success deserialized key will be stored in value.

  Source   Edit 
proc getOrder(remotePubkey, localNonce: openArray[byte];
              localPubkey, remoteNonce: openArray[byte]): CryptoResult[int] {.
    ...raises: [Defect], tags: [].}
Compare values and calculate order parameter.   Source   Edit 
proc getPublicKey(key: PrivateKey): CryptoResult[PublicKey] {....raises: [Defect],
    tags: [].}
Get public key from corresponding private key key.   Source   Edit 
proc getRawBytes(key: PrivateKey | PublicKey): CryptoResult[seq[byte]] {.
    ...raises: [Defect].}
Return private key key in binary form (using scheme's own serialization).   Source   Edit 
proc init(sig: var Signature; data: openArray[byte]): bool {....raises: [Defect],
    tags: [].}

Initialize signature sig from raw binary form.

Returns true on success.

  Source   Edit 
proc init(sig: var Signature; data: string): bool {....raises: [Defect], tags: [].}

Initialize signature sig from serialized hexadecimal string representation.

Returns true on success.

  Source   Edit 
proc init(t: typedesc[PrivateKey]; data: openArray[byte]): CryptoResult[
    PrivateKey] {....raises: [Defect].}
Create new private key from libp2p's protobuf serialized binary form.   Source   Edit 
proc init(t: typedesc[PrivateKey]; data: string): CryptoResult[PrivateKey] {.
    ...raises: [Defect].}
Create new private key from libp2p's protobuf serialized hexadecimal string form.   Source   Edit 
proc init(t: typedesc[PrivateKey]; key: ecnist.EcPrivateKey): PrivateKey {.
    ...raises: [Defect].}
  Source   Edit 
proc init(t: typedesc[PrivateKey]; key: EdPrivateKey): PrivateKey {.
    ...raises: [Defect].}
  Source   Edit 
proc init(t: typedesc[PrivateKey]; key: rsa.RsaPrivateKey): PrivateKey {.
    ...raises: [Defect].}
  Source   Edit 
proc init(t: typedesc[PrivateKey]; key: SkPrivateKey): PrivateKey {.
    ...raises: [Defect].}
  Source   Edit 
proc init(t: typedesc[PublicKey]; data: openArray[byte]): CryptoResult[PublicKey] {.
    ...raises: [Defect].}
Create new public key from libp2p's protobuf serialized binary form.   Source   Edit 
proc init(t: typedesc[PublicKey]; data: string): CryptoResult[PublicKey] {.
    ...raises: [Defect].}
Create new public key from libp2p's protobuf serialized hexadecimal string form.   Source   Edit 
proc init(t: typedesc[PublicKey]; key: ecnist.EcPublicKey): PublicKey {.
    ...raises: [Defect].}
  Source   Edit 
proc init(t: typedesc[PublicKey]; key: EdPublicKey): PublicKey {.
    ...raises: [Defect].}
  Source   Edit 
proc init(t: typedesc[PublicKey]; key: rsa.RsaPublicKey): PublicKey {.
    ...raises: [Defect].}
  Source   Edit 
proc init(t: typedesc[PublicKey]; key: SkPublicKey): PublicKey {.
    ...raises: [Defect].}
  Source   Edit 
proc init(t: typedesc[Signature]; data: openArray[byte]): CryptoResult[Signature] {.
    ...raises: [Defect].}
Create new public key from libp2p's protobuf serialized binary form.   Source   Edit 
proc init(t: typedesc[Signature]; data: string): CryptoResult[Signature] {.
    ...raises: [Defect].}
Create new signature from serialized hexadecimal string form.   Source   Edit 
proc init[T: PrivateKey | PublicKey](key: var T; data: openArray[byte]): bool {.
    ...raises: [Defect].}

Initialize private key key from libp2p's protobuf serialized raw binary form.

Returns true on success.

  Source   Edit 
proc init[T: PrivateKey | PublicKey](key: var T; data: string): bool {.
    ...raises: [Defect].}

Initialize private/public key key from libp2p's protobuf serialized hexadecimal string representation.

Returns true on success.

  Source   Edit 
proc iv(secret: Secret; id: int): seq[byte] {.inline, ...raises: [Defect], tags: [].}
Get array of bytes with with initial vector.   Source   Edit 
proc key(secret: Secret; id: int): seq[byte] {.inline, ...raises: [Defect],
    tags: [].}
  Source   Edit 
proc mac(secret: Secret; id: int): seq[byte] {.inline, ...raises: [Defect],
    tags: [].}
  Source   Edit 
proc newRng(): ref BrHmacDrbgContext {....raises: [Defect], tags: [RootEffect].}
  Source   Edit 
proc random(T: typedesc[KeyPair]; rng: var BrHmacDrbgContext;
            bits = RsaDefaultKeySize): CryptoResult[KeyPair] {....raises: [Defect].}

Generate random private pair of keys using default public-key cryptography scheme.

Default public-key cryptography schemes are following order: ed25519, secp256k1, RSA, secp256r1.

So will be used first available (supported) method.

  Source   Edit 
proc random(T: typedesc[KeyPair]; scheme: PKScheme; rng: var BrHmacDrbgContext;
            bits = RsaDefaultKeySize): CryptoResult[KeyPair] {....raises: [Defect].}

Generate random key pair for scheme scheme.

bits is number of bits for RSA key, bits value must be in [512, 4096], default value is 2048 bits.

  Source   Edit 
proc random(T: typedesc[PrivateKey]; rng: var BrHmacDrbgContext;
            bits = RsaDefaultKeySize): CryptoResult[PrivateKey] {.
    ...raises: [Defect].}

Generate random private key using default public-key cryptography scheme.

Default public-key cryptography schemes are following order: ed25519, secp256k1, RSA, secp256r1.

So will be used first available (supported) method.

  Source   Edit 
proc random(T: typedesc[PrivateKey]; scheme: PKScheme;
            rng: var BrHmacDrbgContext; bits = RsaDefaultKeySize): CryptoResult[
    PrivateKey] {....raises: [Defect].}

Generate random private key for scheme scheme.

bits is number of bits for RSA key, bits value must be in [2048, 4096], default value is 3072 bits.

  Source   Edit 
proc selectBest(order: int; p1, p2: string): string {....raises: [Defect], tags: [].}

Determines which algorithm to use from list p1 and p2.

Returns empty string if there no algorithms in common.

  Source   Edit 
func shortLog(key: PrivateKey | PublicKey): string {....raises: [Defect].}
Get short string representation of private/public key key.   Source   Edit 
proc shuffle[T](rng: ref BrHmacDrbgContext; x: var openArray[T]) {.
    ...raises: [Defect].}
  Source   Edit 
proc sign(key: PrivateKey; data: openArray[byte]): CryptoResult[Signature] {.
    ...gcsafe, raises: [Defect], tags: [RootEffect].}
Sign message data using private key key and return generated signature in raw binary form.   Source   Edit 
proc stretchKeys(cipherType: string; hashType: string; sharedSecret: seq[byte]): Secret {.
    ...raises: [Defect], tags: [].}
Expand shared secret to cryptographic keys.   Source   Edit 
proc toBytes(key: PrivateKey; data: var openArray[byte]): CryptoResult[int] {.
    ...raises: [Defect], tags: [].}

Serialize private key key (using libp2p protobuf scheme) and store it to data.

Returns number of bytes (octets) needed to store private key key.

  Source   Edit 
proc toBytes(key: PublicKey; data: var openArray[byte]): CryptoResult[int] {.
    ...raises: [Defect], tags: [].}

Serialize public key key (using libp2p protobuf scheme) and store it to data.

Returns number of bytes (octets) needed to store public key key.

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

Serialize signature sig and store it to data.

Returns number of bytes (octets) needed to store signature sig.

  Source   Edit 
proc toRawBytes(key: PrivateKey | PublicKey; data: var openArray[byte]): CryptoResult[
    int] {....raises: [Defect].}

Serialize private key key (using scheme's own serialization) and store it to data.

Returns number of bytes (octets) needed to store private key key.

  Source   Edit 
proc verify(sig: Signature; message: openArray[byte]; key: PublicKey): bool {.
    ...raises: [Defect], tags: [RootEffect].}
Verify signature sig using message message and public key key. Return true if message signature is valid.   Source   Edit 
proc write(pb: var ProtoBuffer; field: int; sig: Signature) {.inline,
    ...raises: [Defect], raises: [Defect], tags: [].}
  Source   Edit 
proc write(vb: var VBuffer; pubkey: PublicKey) {.inline,
    ...raises: [Defect, ResultError[CryptoError]], raises: [Defect], tags: [].}
Write PublicKey value pubkey to buffer vb.   Source   Edit 
proc write(vb: var VBuffer; seckey: PrivateKey) {.inline,
    ...raises: [Defect, ResultError[CryptoError]], raises: [Defect], tags: [].}
Write PrivateKey value seckey to buffer vb.   Source   Edit 
proc write(vb: var VBuffer; sig: PrivateKey) {.inline,
    ...raises: [Defect, ResultError[CryptoError]], raises: [Defect], tags: [].}
Write Signature value sig to buffer vb.   Source   Edit 
proc write[T: PublicKey | PrivateKey](pb: var ProtoBuffer; field: int; key: T) {.
    inline, ...raises: [Defect, ResultError[CryptoError]], raises: [Defect].}
  Source   Edit

Templates

template goffset(secret, id, o: untyped): untyped
  Source   Edit 
template ivOpenArray(secret: Secret; id: int): untyped
  Source   Edit 
template keyOpenArray(secret: Secret; id: int): untyped
  Source   Edit 
template macOpenArray(secret: Secret; id: int): untyped
  Source   Edit 
template orError(exp: untyped; err: untyped): untyped
  Source   Edit 
template supported(scheme: PKScheme): bool
Returns true if specified scheme is currently available.   Source   Edit

Made with Nim. Generated: 2022-05-09 15:17:42 UTC