sys/man/2/ec

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