OSX/libsecurity_cryptkit/lib/ByteRep.txt

   1        FEE Portable Byte Representation of Public Key Strings and Signatures
   2                                                 Last Modified 15 March 2001
   3
   4 This defines portable data formats shared by the C and Java implementation of FEE. This definition supercedes formats used prior to 20 Feb 2001.
   5
   6
   7 Primitive Data Types
   8 --------------------
   9
  10     int, unsigned int:
  11         4 bytes, M.S. byte first
  12
  13     short, feeUnichar, Java char:
  14         2 bytes, M.S. byte first
  15
  16     giant, GiantInteger:
  17
  18         type     contents       comment
  19     ------       --------       ---------------------------------------
  20         int              numBytes       abs(numBytes) indicates size of n[] to
  21                                                         follow, in BYTES
  22                                                         sign of numBytes is sign bit of result
  23         byte     data           n[0], MSB first for each element
  24
  25
  26 Curve Parameters (curveParams, Java CurveParams)
  27 ------------------------------------------------
  28
  29     CURVE_PARAM_VERSION = 1:
  30
  31         type     contents
  32         ------   --------
  33         int              CURVE_PARAM_VERSION = 1
  34         int      minVersion of code to parse this struct = 1
  35         unsigned q
  36         int              k
  37         int              spare
  38         giant    a
  39         giant    b
  40         giant    c
  41         giant    x1Plus
  42         giant    x1Minus
  43         giant    cOrderPlus
  44         giant    cOrderMinus
  45         giant    x1OrderPlus
  46         giant    x1OrderMinus
  47
  48         The last four fields are not always known; a value of (giant)0
  49         indicates a "not known" condition. In this case, 4 bytes of
  50         zero are written, indicating a giant with a length of zero.
  51
  52     CURVE_PARAM_VERSION = 2 (20 Jan 1998)
  53
  54         type     contents
  55         ------   --------
  56         int              CURVE_PARAM_VERSION = 2
  57         int      minVersion of code to parse this struct = 2
  58         byte     primeType      /* new for version 2 */
  59         unsigned q
  60         int              k
  61         unsigned m              /* new for version 2 */
  62         int              spare
  63         giant    a
  64         giant    b
  65         giant    c
  66         giant    x1Plus
  67         giant    x1Minus
  68         giant    cOrderPlus
  69         giant    cOrderMinus
  70         giant    x1OrderPlus
  71         giant    x1OrderMinus
  72         giant    basePrime, if primeType == PT_GENERAL  /* new */
  73
  74         Note that as of version 2, the cOrder* and x1Order* fields are always
  75         known.
  76
  77     CURVE_PARAM_VERSION = 3 (1 Sep 1998)
  78
  79         type     contents
  80         ------   --------
  81         int              CURVE_PARAM_VERSION = 3
  82         int      minVersion of code to parse this struct = 3
  83         byte     primeType
  84         byte     curveType      /* new for version 3 */
  85         unsigned q
  86         int              k
  87         unsigned m
  88         int              spare
  89         giant    a
  90         giant    b
  91         giant    c
  92         giant    x1Plus
  93         giant    x1Minus
  94         giant    cOrderPlus
  95         giant    cOrderMinus
  96         giant    x1OrderPlus
  97         giant    x1OrderMinus
  98         giant    basePrime, if primeType == PT_GENERAL
  99
 100
 101 Public Key String
 102 -----------------
 103
 104         PUBLIC_KEY_STRING_VERSION = 3:
 105
 106         A public key string is always encoded via enc64(); the raw data before
 107         enc64() is as follows.
 108
 109         type            contents
 110     ------              --------
 111         int                     PUBLIC_KEY_STRING_MAGIC (0xfeeddeef)
 112         int             PUBLIC_KEY_STRING_VERSION = 3
 113         int             minVersion of code to parse this key = 3
 114         int                     spare
 115         curveParams     curve parameters
 116         giant           plusX (public key, plus curve)
 117         giant           minusX (public key, minus curve)
 118         int                     usageName length in unichars
 119         feeUnichar[] usageName as array of unichars
 120
 121         PUBLIC_KEY_BLOB_VERSION = 4 (23 Mar 1998)
 122
 123         New for version 4 - exported blobs for both public and private keys.
 124         Public key strings are merely enc64() encoded versions of public
 125         key blobs and are identical to PUBLIC_KEY_STRING_VERSION 3 public
 126         key strings.
 127
 128     PUBLIC_KEY_BLOB_MAGIC : 0xfeeddeef - public
 129                             0xfeeddeed - private
 130     minVersion : 3 for public, 4 for private
 131
 132         type            contents
 133     ------              --------
 134         int                     PUBLIC_KEY_BLOB_MAGIC
 135         int             PUBLIC_KEY_BLOB_VERSION = 4
 136         int             minVersion of code to parse this key = 3 or 4
 137         int                     spare
 138         curveParams     curve parameters
 139
 140         public key blob:
 141           giant         plusX (public key, plus curve)
 142           giant         minusX (public key, minus curve)
 143         private key blob:
 144           int           privDataLen
 145           unsigned char privData[]
 146
 147         both private and public:
 148
 149         int                             usageName length in unichars
 150         feeUnichar[]    usageName as array of unichars
 151
 152         PUBLIC_KEY_BLOB_VERSION = 5 (2 Sep 1998)
 153
 154         Added plusY.
 155         minVersion = 5.
 156
 157         type            contents
 158     ------              --------
 159         int                     PUBLIC_KEY_BLOB_MAGIC_{PRIV,PUB}
 160         int             PUBLIC_KEY_BLOB_VERSION = 5
 161         int             minVersion of code to parse this key = 5
 162         int                     spare
 163         curveParams     curve parameters
 164
 165         public key blob:
 166           giant         plusX (public key, plus curve)
 167           giant         plusY (y-coord of public key, plus curve, may be zero)
 168           giant         minusX (public key, minus curve)
 169         private key blob:
 170           giant         privGiant
 171
 172         both private and public:
 173
 174         int                             usageName length in unichars
 175         feeUnichar[]    usageName as array of unichars
 176
 177         PUBLIC_KEY_BLOB_VERSION = 6 (14 Mar 2001)
 178
 179     Deleted usageName.
 180
 181         type            contents
 182     ------              --------
 183         int                     PUBLIC_KEY_BLOB_MAGIC_{PRIV,PUB}
 184         int             PUBLIC_KEY_BLOB_VERSION = 5
 185         int             minVersion of code to parse this key = 5
 186         int                     spare
 187         curveParams     curve parameters
 188
 189         public key blob:
 190           giant         plusX (public key, plus curve)
 191           giant         plusY (y-coord of public key, plus curve, may be zero)
 192           giant         minusX (public key, minus curve)
 193         private key blob:
 194           giant         privGiant
 195
 196
 197 Digital Signature, ElGamal style
 198 --------------------------------
 199
 200         type                    contents
 201         ------                  --------
 202         int             FEE_SIG_MAGIC (0xfee00516)
 203         int             FEE_SIG_VERSION = 3
 204         int             minVersion of code to parse this signature = 3
 205         int             spare
 206         int                             signer length in unichars (DELETED 2/20/01)
 207         feeUnichar[]    signer as array of unichars (DELETED 2/20/01)
 208         giant                   u
 209         giant                   Pm.x
 210
 211         FEE_SIG_VERSION = 4 (15 March 2001)
 212         Deleted signer.
 213
 214         type                    contents
 215         ------                  --------
 216         int             FEE_SIG_MAGIC (0xfee00516)
 217         int             FEE_SIG_VERSION = 4
 218         int             minVersion of code to parse this signature = 4
 219         int             spare
 220         giant                   u
 221         giant                   Pm.x
 222
 223 Digital Signature, ECDSA style
 224 --------------------------------
 225
 226         type            contents
 227     ------              --------
 228         int         FEE_ECDSA_MAGIC (0xfee00517)
 229         int         FEE_ECDSA_VERSION = 1
 230         int         minVersion of code to parse this signature = 1
 231         int         spare
 232         int                     signer length in unichars (DELETED 2/20/01)
 233         feeUnichar[] signer as array of unichars (DELETED 2/20/01)
 234         giant           s
 235         giant           x0
 236
 237         FEE_ECDSA_VERSION = 2 (15 March 2001)
 238         Deleted signer.
 239
 240         type            contents
 241     ------              --------
 242         int         FEE_ECDSA_MAGIC (0xfee00517)
 243         int         FEE_ECDSA_VERSION = 2
 244         int         minVersion of code to parse this signature = 2
 245         int         spare
 246         giant           s
 247         giant           x0
 248
 249
 250
 251 FEED (2:1) CipherText
 252 ---------------------
 253
 254 This data type uses an optimized form of Giants in that the sign, and hence
 255 the number of 16-bit shorts (i.e., the size of n[]), is implied by the size
 256 of p used in encryption and decryption. For a given curve parameter q (as
 257 in p = 2**q - k), the number of shorts per giant transmitted is ((q/8 + 1)/2).
 258 As in normal giants, the n[] array is transmitted m.s. byte first. During
 259 encoding, unused elements in n[] - i.e., those appearing after
 260 n[abs(sign) - 1] - are zero. Upon decoding, the sign of an incoming n[]
 261 array can be inferred from the number of non-zero shorts.
 262
 263 One block of ciphertext is formatted as follows. See "Fast Elliptic
 264 Encryption (FEE) Algorithms", by Richard E. Crandall, July 1996, for
 265 descriptions of Xm, Xc, and g.
 266
 267         type                      contents
 268         ---------------   -----------------
 269         optimized giant   Xm
 270         optimized giant   Xc
 271         byte                      g
 272
 273
 274 FEED (1:1) CipherText
 275 ---------------------
 276
 277 The first cipherblock is a FEED(2:1) encrypted copy of the initial
 278 R and S arrays; this is basically a bunch of random bytes which are
 279 used to cook up the giants R and S at both encrypt and decrypt time.
 280 In 1:1 FEED ciphertext, this is encrypted with the recipient's public
 281 key; the result is padded out to one 1:1 FEED Cipherblock.
 282
 283 Subsequent cipherblocks are:
 284
 285         type                      contents
 286         ---------------   -----------------
 287         optimized giant   Xm
 288         byte                      clueByte
 289
 290         clueByte contents:
 291             bit 0 : 0 ==> minus
 292                     1 ==> plus
 293             bit 1 : 's' arg to elliptic_add()