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