Cryptographic authentication support for the d0_blind_id library available on http...
[divverent/darkplaces.git] / crypto.h
1 #ifndef CRYPTO_H
2 #define CRYPTO_H
3
4 extern cvar_t crypto_developer;
5 extern cvar_t crypto_aeslevel;
6 #define ENCRYPTION_REQUIRED (crypto_aeslevel.integer >= 3)
7
8 extern int crypto_keyfp_recommended_length; // applies to LOCAL IDs, and to ALL keys
9
10 #define CRYPTO_HEADERSIZE 31
11 // AES case causes 16 to 31 bytes overhead
12 // SHA256 case causes 16 bytes overhead as we truncate to 128bit
13
14 #include "lhnet.h"
15
16 #define FP64_SIZE 44
17 #define DHKEY_SIZE 16
18
19 typedef struct
20 {
21         unsigned char dhkey[DHKEY_SIZE]; // shared key, not NUL terminated
22         char client_idfp[FP64_SIZE+1];
23         char client_keyfp[FP64_SIZE+1]; // NULL if signature fail
24         char server_idfp[FP64_SIZE+1];
25         char server_keyfp[FP64_SIZE+1]; // NULL if signature fail
26         qboolean authenticated;
27         qboolean use_aes;
28         void *data;
29 }
30 crypto_t;
31
32 void Crypto_Init(void);
33 void Crypto_Init_Commands(void);
34 void Crypto_Shutdown(void);
35 const void *Crypto_EncryptPacket(crypto_t *crypto, const void *data_src, size_t len_src, void *data_dst, size_t *len_dst, size_t len);
36 const void *Crypto_DecryptPacket(crypto_t *crypto, const void *data_src, size_t len_src, void *data_dst, size_t *len_dst, size_t len);
37 #define CRYPTO_NOMATCH 0        // process as usual (packet was not used)
38 #define CRYPTO_MATCH 1          // process as usual (packet was used)
39 #define CRYPTO_DISCARD 2        // discard this packet
40 #define CRYPTO_REPLACE 3        // make the buffer the current packet
41 int Crypto_ClientParsePacket(const char *data_in, size_t len_in, char *data_out, size_t *len_out, lhnetaddress_t *peeraddress);
42 int Crypto_ServerParsePacket(const char *data_in, size_t len_in, char *data_out, size_t *len_out, lhnetaddress_t *peeraddress);
43
44 // if len_out is nonzero, the packet is to be sent to the client
45
46 qboolean Crypto_ServerAppendToChallenge(const char *data_in, size_t len_in, char *data_out, size_t *len_out, size_t maxlen);
47 crypto_t *Crypto_ServerGetInstance(lhnetaddress_t *peeraddress);
48 qboolean Crypto_ServerFinishInstance(crypto_t *out, crypto_t *in); // also clears allocated memory
49 const char *Crypto_GetInfoResponseDataString(void);
50
51 // retrieves a host key for an address (can be exposed to menuqc, or used by the engine to look up stored keys e.g. for server bookmarking)
52 // pointers may be NULL
53 qboolean Crypto_RetrieveHostKey(lhnetaddress_t *peeraddress, int *keyid, char *keyfp, size_t keyfplen, char *idfp, size_t idfplen, int *aeslevel);
54 int Crypto_RetrieveLocalKey(int keyid, char *keyfp, size_t keyfplen, char *idfp, size_t idfplen); // return value: -1 if more to come, +1 if valid, 0 if end of list
55
56 // netconn protocol:
57 //   non-crypto:
58 //     getchallenge                                            >
59 //                                                             < challenge
60 //     connect                                                 >
61 //                                                             < accept (or: reject)
62 //   crypto:
63 //     getchallenge                                            >
64 //                                                             < challenge SP <challenge> NUL vlen <size> d0pk <fingerprints I can auth to> NUL NUL <other fingerprints I accept>
65 //
66 //     IF serverfp:
67 //     d0pk\cnt\0\challenge\<challenge>\aeslevel\<level> NUL <serverfp> NUL <clientfp>
68 //                                                             >
69 //                                                               check if client would get accepted; if not, do "reject" now
70 //     require non-control packets to be encrypted               require non-control packets to be encrypted
71 //     do not send anything yet                                  do not send anything yet
72 //     RESET to serverfp                                         RESET to serverfp
73 //                                                               d0_blind_id_authenticate_with_private_id_start() = 1
74 //                                                             < d0pk\cnt\1\aes\<aesenabled> NUL *startdata*
75 //     d0_blind_id_authenticate_with_private_id_challenge() = 1
76 //     d0pk\cnt\2 NUL *challengedata*                          >
77 //                                                               d0_blind_id_authenticate_with_private_id_response() = 0
78 //                                                             < d0pk\cnt\3 NUL *responsedata*
79 //     d0_blind_id_authenticate_with_private_id_verify() = 1
80 //     store server's fingerprint NOW
81 //     d0_blind_id_sessionkey_public_id() = 1                    d0_blind_id_sessionkey_public_id() = 1
82 //
83 //     IF clientfp AND NOT serverfp:
84 //     RESET to clientfp                                         RESET to clientfp
85 //     d0_blind_id_authenticate_with_private_id_start() = 1
86 //     d0pk\cnt\0\challenge\<challenge>\aeslevel\<level> NUL NUL <clientfp> NUL *startdata*
87 //                                                             >
88 //                                                               check if client would get accepted; if not, do "reject" now
89 //     require non-control packets to be encrypted               require non-control packets to be encrypted
90 //                                                               d0_blind_id_authenticate_with_private_id_challenge() = 1
91 //                                                             < d0pk\cnt\5\aes\<aesenabled> NUL *challengedata*
92 //
93 //     IF clientfp AND serverfp:
94 //     RESET to clientfp                                         RESET to clientfp
95 //     d0_blind_id_authenticate_with_private_id_start() = 1
96 //     d0pk\cnt\4 NUL *startdata*                              >
97 //                                                               d0_blind_id_authenticate_with_private_id_challenge() = 1
98 //                                                             < d0pk\cnt\5 NUL *challengedata*
99 //
100 //     IF clientfp:
101 //     d0_blind_id_authenticate_with_private_id_response() = 0
102 //     d0pk\cnt\6 NUL *responsedata*                           >
103 //                                                               d0_blind_id_authenticate_with_private_id_verify() = 1
104 //                                                               store client's fingerprint NOW
105 //     d0_blind_id_sessionkey_public_id() = 1                    d0_blind_id_sessionkey_public_id() = 1
106 //     note: the ... is the "connect" message, except without the challenge. Reinterpret as regular connect message on server side
107 //
108 //     enforce encrypted transmission (key is XOR of the two DH keys)
109 //
110 //     IF clientfp:
111 //                                                             < challenge (mere sync message)
112 //
113 //     connect\...                                             >
114 //                                                             < accept (ALWAYS accept if connection is encrypted, ignore challenge as it had been checked before)
115 //
116 //     commence with ingame protocol
117
118 // in short:
119 //   server:
120 //     getchallenge NUL d0_blind_id: reply with challenge with added fingerprints
121 //     cnt=0: IF server will auth, cnt=1, ELSE cnt=5
122 //     cnt=2: cnt=3
123 //     cnt=4: cnt=5
124 //     cnt=6: send "challenge"
125 //   client:
126 //     challenge with added fingerprints: cnt=0; if client will auth but not server, append client auth start
127 //     cnt=1: cnt=2
128 //     cnt=3: IF client will auth, cnt=4, ELSE rewrite as "challenge"
129 //     cnt=5: cnt=6, server will continue by sending "challenge" (let's avoid sending two packets as response to one)
130 // other change:
131 //   accept empty "challenge", and challenge-less connect in case crypto protocol has executed and finished
132 //   statusResponse and infoResponse get an added d0_blind_id key that lists
133 //   the keys the server can auth with and to in key@ca SPACE key@ca notation
134 //   any d0pk\ message has an appended "id" parameter; messages with an unexpected "id" are ignored to prevent errors from multiple concurrent auth runs
135
136
137 // comparison to OTR:
138 // - encryption: yes
139 // - authentication: yes
140 // - deniability: no (attacker requires the temporary session key to prove you
141 //   have sent a specific message, the private key itself does not suffice), no
142 //   measures are taken to provide forgeability to even provide deniability
143 //   against an attacker who knows the temporary session key, as using CTR mode
144 //   for the encryption - which, together with deriving the MAC key from the
145 //   encryption key, and MACing the ciphertexts instead of the plaintexts,
146 //   would provide forgeability and thus deniability - requires longer
147 //   encrypted packets and deniability was not a goal of this, as we may e.g.
148 //   reserve the right to capture packet dumps + extra state info to prove a
149 //   client/server has sent specific packets to prove cheating)
150 // - perfect forward secrecy: yes (session key is derived via DH key exchange)
151
152 #endif