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