J-PAKE is not experimental in HEAD.
[openssl.git] / crypto / jpake / 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  __cplusplus
14 extern "C" {
15 #endif
16
17 #include <openssl/bn.h>
18 #include <openssl/sha.h>
19
20 typedef struct JPAKE_CTX JPAKE_CTX;
21
22 /* Note that "g" in the ZKPs is not necessarily the J-PAKE g. */
23 typedef struct
24     {
25     BIGNUM *gr; /* g^r (r random) */
26     BIGNUM *b;  /* b = r - x*h, h=hash(g, g^r, g^x, name) */
27     } JPAKE_ZKP;
28
29 typedef struct
30     {
31     BIGNUM *gx;       /* g^x in step 1, g^(xa + xc + xd) * xb * s in step 2 */
32     JPAKE_ZKP zkpx;   /* ZKP(x) or ZKP(xb * s) */
33     } JPAKE_STEP_PART;
34
35 typedef struct
36     {
37     JPAKE_STEP_PART p1;   /* g^x3, ZKP(x3) or g^x1, ZKP(x1) */
38     JPAKE_STEP_PART p2;   /* g^x4, ZKP(x4) or g^x2, ZKP(x2) */
39     } JPAKE_STEP1;
40
41 typedef JPAKE_STEP_PART JPAKE_STEP2;
42
43 typedef struct
44     {
45     unsigned char hhk[SHA_DIGEST_LENGTH];
46     } JPAKE_STEP3A;
47
48 typedef struct
49     {
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 /* The following lines are auto generated by the script mkerr.pl. Any changes
100  * made after this point may be overwritten when the script is next run.
101  */
102 void ERR_load_JPAKE_strings(void);
103
104 /* Error codes for the JPAKE functions. */
105
106 /* Function codes. */
107 #define JPAKE_F_JPAKE_STEP1_PROCESS                      101
108 #define JPAKE_F_JPAKE_STEP2_PROCESS                      102
109 #define JPAKE_F_JPAKE_STEP3A_PROCESS                     103
110 #define JPAKE_F_JPAKE_STEP3B_PROCESS                     104
111 #define JPAKE_F_VERIFY_ZKP                               100
112
113 /* Reason codes. */
114 #define JPAKE_R_G_TO_THE_X4_IS_ONE                       105
115 #define JPAKE_R_HASH_OF_HASH_OF_KEY_MISMATCH             106
116 #define JPAKE_R_HASH_OF_KEY_MISMATCH                     107
117 #define JPAKE_R_VERIFY_B_FAILED                          102
118 #define JPAKE_R_VERIFY_X3_FAILED                         103
119 #define JPAKE_R_VERIFY_X4_FAILED                         104
120 #define JPAKE_R_ZKP_VERIFY_FAILED                        100
121
122 #ifdef  __cplusplus
123 }
124 #endif
125 #endif