include/openssl/jpake.h

   1 /*
   2  * Implement J-PAKE, as described in
   3  * http://grouper.ieee.org/groups/1363/Research/contributions/hao-ryan-2008.pdf
   4  *
   5  * With hints from http://www.cl.cam.ac.uk/~fh240/software/JPAKE2.java.
   6  */
   7
   8 #ifndef HEADER_JPAKE_H
   9 # define HEADER_JPAKE_H
  10
  11 # include <openssl/opensslconf.h>
  12
  13 # ifdef OPENSSL_NO_JPAKE
  14 #  error JPAKE is disabled.
  15 # endif
  16
  17 #ifdef  __cplusplus
  18 extern "C" {
  19 #endif
  20
  21 # include <openssl/bn.h>
  22 # include <openssl/sha.h>
  23
  24 typedef struct JPAKE_CTX JPAKE_CTX;
  25
  26 /* Note that "g" in the ZKPs is not necessarily the J-PAKE g. */
  27 typedef struct {
  28     BIGNUM *gr;                 /* g^r (r random) */
  29     BIGNUM *b;                  /* b = r - x*h, h=hash(g, g^r, g^x, name) */
  30 } JPAKE_ZKP;
  31
  32 typedef struct {
  33     BIGNUM *gx;                 /* g^x in step 1, g^(xa + xc + xd) * xb * s
  34                                  * in step 2 */
  35     JPAKE_ZKP zkpx;             /* ZKP(x) or ZKP(xb * s) */
  36 } JPAKE_STEP_PART;
  37
  38 typedef struct {
  39     JPAKE_STEP_PART p1;         /* g^x3, ZKP(x3) or g^x1, ZKP(x1) */
  40     JPAKE_STEP_PART p2;         /* g^x4, ZKP(x4) or g^x2, ZKP(x2) */
  41 } JPAKE_STEP1;
  42
  43 typedef JPAKE_STEP_PART JPAKE_STEP2;
  44
  45 typedef struct {
  46     unsigned char hhk[SHA_DIGEST_LENGTH];
  47 } JPAKE_STEP3A;
  48
  49 typedef struct {
  50     unsigned char hk[SHA_DIGEST_LENGTH];
  51 } JPAKE_STEP3B;
  52
  53 /* Parameters are copied */
  54 JPAKE_CTX *JPAKE_CTX_new(const char *name, const char *peer_name,
  55                          const BIGNUM *p, const BIGNUM *g, const BIGNUM *q,
  56                          const BIGNUM *secret);
  57 void JPAKE_CTX_free(JPAKE_CTX *ctx);
  58
  59 /*
  60  * Note that JPAKE_STEP1 can be used multiple times before release
  61  * without another init.
  62  */
  63 void JPAKE_STEP1_init(JPAKE_STEP1 *s1);
  64 int JPAKE_STEP1_generate(JPAKE_STEP1 *send, JPAKE_CTX *ctx);
  65 int JPAKE_STEP1_process(JPAKE_CTX *ctx, const JPAKE_STEP1 *received);
  66 void JPAKE_STEP1_release(JPAKE_STEP1 *s1);
  67
  68 /*
  69  * Note that JPAKE_STEP2 can be used multiple times before release
  70  * without another init.
  71  */
  72 void JPAKE_STEP2_init(JPAKE_STEP2 *s2);
  73 int JPAKE_STEP2_generate(JPAKE_STEP2 *send, JPAKE_CTX *ctx);
  74 int JPAKE_STEP2_process(JPAKE_CTX *ctx, const JPAKE_STEP2 *received);
  75 void JPAKE_STEP2_release(JPAKE_STEP2 *s2);
  76
  77 /*
  78  * Optionally verify the shared key. If the shared secrets do not
  79  * match, the two ends will disagree about the shared key, but
  80  * otherwise the protocol will succeed.
  81  */
  82 void JPAKE_STEP3A_init(JPAKE_STEP3A *s3a);
  83 int JPAKE_STEP3A_generate(JPAKE_STEP3A *send, JPAKE_CTX *ctx);
  84 int JPAKE_STEP3A_process(JPAKE_CTX *ctx, const JPAKE_STEP3A *received);
  85 void JPAKE_STEP3A_release(JPAKE_STEP3A *s3a);
  86
  87 void JPAKE_STEP3B_init(JPAKE_STEP3B *s3b);
  88 int JPAKE_STEP3B_generate(JPAKE_STEP3B *send, JPAKE_CTX *ctx);
  89 int JPAKE_STEP3B_process(JPAKE_CTX *ctx, const JPAKE_STEP3B *received);
  90 void JPAKE_STEP3B_release(JPAKE_STEP3B *s3b);
  91
  92 /*
  93  * the return value belongs to the library and will be released when
  94  * ctx is released, and will change when a new handshake is performed.
  95  */
  96 const BIGNUM *JPAKE_get_shared_key(JPAKE_CTX *ctx);
  97
  98 /* BEGIN ERROR CODES */
  99 /*
 100  * The following lines are auto generated by the script mkerr.pl. Any changes
 101  * made after this point may be overwritten when the script is next run.
 102  */
 103 void ERR_load_JPAKE_strings(void);
 104
 105 /* Error codes for the JPAKE functions. */
 106
 107 /* Function codes. */
 108 # define JPAKE_F_JPAKE_STEP1_PROCESS                      101
 109 # define JPAKE_F_JPAKE_STEP2_PROCESS                      102
 110 # define JPAKE_F_JPAKE_STEP3A_PROCESS                     103
 111 # define JPAKE_F_JPAKE_STEP3B_PROCESS                     104
 112 # define JPAKE_F_VERIFY_ZKP                               100
 113
 114 /* Reason codes. */
 115 # define JPAKE_R_G_TO_THE_X3_IS_NOT_LEGAL                 108
 116 # define JPAKE_R_G_TO_THE_X4_IS_NOT_LEGAL                 109
 117 # define JPAKE_R_G_TO_THE_X4_IS_ONE                       105
 118 # define JPAKE_R_HASH_OF_HASH_OF_KEY_MISMATCH             106
 119 # define JPAKE_R_HASH_OF_KEY_MISMATCH                     107
 120 # define JPAKE_R_VERIFY_B_FAILED                          102
 121 # define JPAKE_R_VERIFY_X3_FAILED                         103
 122 # define JPAKE_R_VERIFY_X4_FAILED                         104
 123 # define JPAKE_R_ZKP_VERIFY_FAILED                        100
 124
 125 #ifdef  __cplusplus
 126 }
 127 #endif
 128 #endif