sys/man/2/ec

   1 .TH EC 2
   2 .SH NAME
   3 ecassign,
   4 ecadd,
   5 ecmul,
   6 strtoec,
   7 ecgen,
   8 ecverify,
   9 ecpubverify,
  10 ecdsasign,
  11 ecdsaverify \- elliptic curve cryptography
  12 .SH SYNOPSIS
  13 .B #include <u.h>
  14 .br
  15 .B #include <libc.h>
  16 .br
  17 .B #include <mp.h>
  18 .br
  19 .B #include <libsec.h>
  20 .PP
  21 .B
  22 void    ecdominit(ECdomain *dom, void (*init)(mpint *p, mpint *a, mpint *b, mpint *x, mpint *y, mpint *n, mpint *h));
  23 .PP
  24 .B
  25 void    ecdomfree(ECdomain *dom);
  26 .PP
  27 .B
  28 void    ecassign(ECdomain *dom, ECpoint *old, ECpoint *new);
  29 .PP
  30 .B
  31 void    ecadd(ECdomain *dom, ECpoint *a, ECpoint *b, ECpoint *s);
  32 .PP
  33 .B
  34 void    ecmul(ECdomain *dom, ECpoint *a, mpint *k, ECpoint *s);
  35 .PP
  36 .B
  37 ECpoint*        strtoec(ECdomain *dom, char *s, char **rptr, ECpoint *p);
  38 .PP
  39 .B
  40 ECpriv* ecgen(ECdomain *dom, ECpriv *p);
  41 .PP
  42 .B
  43 int     ecverify(ECdomain *dom, ECpoint *p);
  44 .PP
  45 .B
  46 int     ecpubverify(ECdomain *dom, ECpub *p);
  47 .PP
  48 .B
  49 void    ecdsasign(ECdomain *dom, ECpriv *priv, uchar *dig, int dlen, mpint *r, mpint *s);
  50 .PP
  51 .B
  52 int     ecdsaverify(ECdomain *dom, ECpub *pub, uchar *dig, int dlen, mpint *r, mpint *s);
  53 .DT
  54 .SH DESCRIPTION
  55 These functions implement elliptic curve cryptography.
  56 An elliptic curve together with cryptographic parameters are specified using an
  57 .B ECdomain
  58 struct.
  59 Points on the curve are represented by
  60 .B ECpoint
  61 structs.
  62 .PP
  63 .B ecdominit
  64 initializes a
  65 .B ECdomain
  66 struct and calls the
  67 .B init
  68 function such as
  69 .B secp256r1
  70 which fills in the parameters of the curve.
  71 .PP
  72 .B ecdomfree
  73 frees the parameters of the curve and zeros the struct. It does
  74 not free the memory of the struct itself.
  75 .PP
  76 .BR ecassign ", " ecadd " and " ecmul
  77 are analogous to their counterparts in
  78 .IR mp (2).
  79 .PP
  80 .B strtoec
  81 converts a hex string representing an octet string as specified in
  82 .I Standards for Efficient Cryptography (SEC) 1
  83 to an
  84 .B ECpoint
  85 struct. Both uncompressed and compressed formats are supported.
  86 If
  87 .B rptr
  88 is not
  89 .BR nil ,
  90 it is used to return the position in the string where the parser stopped.
  91 If
  92 .BR p " is " nil
  93 space is allocated automatically, else the given struct is used.
  94 .PP
  95 .B ecverify
  96 and
  97 .B ecpubverify
  98 verify that the given point or public key, respectively, is valid.
  99 .PP
 100 .B ecgen
 101 generates a keypair and returns a pointer to it.
 102 If
 103 .BR p " is " nil
 104 space is allocated automatically, else the given struct is used.
 105 .PP
 106 .B ecdsasign
 107 and
 108 .B ecdsaverify
 109 create or verify, respectively, a signature using the ECDSA scheme specified in
 110 .I SEC 1.
 111 It is absolutely vital that
 112 .B dig
 113 is a cryptographic hash to the message.
 114 .B ecdsasign
 115 writes the signature to
 116 .BR r " and " s
 117 which are assumed to be allocated properly.
 118 .SH RETURN VALUE
 119 .B *verify
 120 functions return
 121 .B 1
 122 for a positive result.
 123 Functions returning pointers may return
 124 .B nil
 125 in case of error
 126 .I (e.g.
 127 failing
 128 .IR malloc (2)).
 129 .SH SOURCE
 130 .B /sys/src/libsec/port/ecc.c
 131 .SH SEE ALSO
 132 .I
 133 Standards for Efficient Cryptography (SEC) 1: Elliptic Curve Cryptography
 134 - Certicom Research, 2009
 135 .SH HISTORY
 136 This implementation of elliptic curve cryptography first appeared in 9front (June, 2012).