xref: /freebsd/sys/net80211/ieee80211_crypto.h (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
1 /*-
2  * Copyright (c) 2001 Atsushi Onoe
3  * Copyright (c) 2002-2007 Sam Leffler, Errno Consulting
4  * All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  * 1. Redistributions of source code must retain the above copyright
10  *    notice, this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  *    notice, this list of conditions and the following disclaimer in the
13  *    documentation and/or other materials provided with the distribution.
14  *
15  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
16  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
19  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25  *
26  * $FreeBSD$
27  */
28 #ifndef _NET80211_IEEE80211_CRYPTO_H_
29 #define _NET80211_IEEE80211_CRYPTO_H_
30 
31 /*
32  * 802.11 protocol crypto-related definitions.
33  */
34 #define	IEEE80211_KEYBUF_SIZE	16
35 #define	IEEE80211_MICBUF_SIZE	(8+8)	/* space for both tx+rx keys */
36 
37 /*
38  * Old WEP-style key.  Deprecated.
39  */
40 struct ieee80211_wepkey {
41 	u_int		wk_len;		/* key length in bytes */
42 	uint8_t		wk_key[IEEE80211_KEYBUF_SIZE];
43 };
44 
45 struct ieee80211_cipher;
46 
47 /*
48  * Crypto key state.  There is sufficient room for all supported
49  * ciphers (see below).  The underlying ciphers are handled
50  * separately through loadable cipher modules that register with
51  * the generic crypto support.  A key has a reference to an instance
52  * of the cipher; any per-key state is hung off wk_private by the
53  * cipher when it is attached.  Ciphers are automatically called
54  * to detach and cleanup any such state when the key is deleted.
55  *
56  * The generic crypto support handles encap/decap of cipher-related
57  * frame contents for both hardware- and software-based implementations.
58  * A key requiring software crypto support is automatically flagged and
59  * the cipher is expected to honor this and do the necessary work.
60  * Ciphers such as TKIP may also support mixed hardware/software
61  * encrypt/decrypt and MIC processing.
62  */
63 typedef uint16_t ieee80211_keyix;	/* h/w key index */
64 
65 struct ieee80211_key {
66 	uint8_t		wk_keylen;	/* key length in bytes */
67 	uint8_t		wk_pad;
68 	uint16_t	wk_flags;
69 #define	IEEE80211_KEY_XMIT	0x01	/* key used for xmit */
70 #define	IEEE80211_KEY_RECV	0x02	/* key used for recv */
71 #define	IEEE80211_KEY_GROUP	0x04	/* key used for WPA group operation */
72 #define	IEEE80211_KEY_SWCRYPT	0x10	/* host-based encrypt/decrypt */
73 #define	IEEE80211_KEY_SWMIC	0x20	/* host-based enmic/demic */
74 	ieee80211_keyix	wk_keyix;	/* h/w key index */
75 	ieee80211_keyix	wk_rxkeyix;	/* optional h/w rx key index */
76 	uint8_t		wk_key[IEEE80211_KEYBUF_SIZE+IEEE80211_MICBUF_SIZE];
77 #define	wk_txmic	wk_key+IEEE80211_KEYBUF_SIZE+0	/* XXX can't () right */
78 #define	wk_rxmic	wk_key+IEEE80211_KEYBUF_SIZE+8	/* XXX can't () right */
79 	uint64_t	wk_keyrsc;	/* key receive sequence counter */
80 	uint64_t	wk_keytsc;	/* key transmit sequence counter */
81 	const struct ieee80211_cipher *wk_cipher;
82 	void		*wk_private;	/* private cipher state */
83 };
84 #define	IEEE80211_KEY_COMMON 		/* common flags passed in by apps */\
85 	(IEEE80211_KEY_XMIT | IEEE80211_KEY_RECV | IEEE80211_KEY_GROUP)
86 
87 /*
88  * NB: these values are ordered carefully; there are lots of
89  * of implications in any reordering.  In particular beware
90  * that 4 is not used to avoid conflicting with IEEE80211_F_PRIVACY.
91  */
92 #define	IEEE80211_CIPHER_WEP		0
93 #define	IEEE80211_CIPHER_TKIP		1
94 #define	IEEE80211_CIPHER_AES_OCB	2
95 #define	IEEE80211_CIPHER_AES_CCM	3
96 #define	IEEE80211_CIPHER_CKIP		5
97 #define	IEEE80211_CIPHER_NONE		6	/* pseudo value */
98 
99 #define	IEEE80211_CIPHER_MAX		(IEEE80211_CIPHER_NONE+1)
100 
101 #define	IEEE80211_KEYIX_NONE	((ieee80211_keyix) -1)
102 
103 #if defined(__KERNEL__) || defined(_KERNEL)
104 
105 struct ieee80211com;
106 struct ieee80211_node;
107 struct mbuf;
108 
109 /*
110  * Crypto state kept in each ieee80211com.  Some of this
111  * can/should be shared when virtual AP's are supported.
112  *
113  * XXX save reference to ieee80211com to properly encapsulate state.
114  * XXX split out crypto capabilities from ic_caps
115  */
116 struct ieee80211_crypto_state {
117 	struct ieee80211_key	cs_nw_keys[IEEE80211_WEP_NKID];
118 	ieee80211_keyix		cs_def_txkey;	/* default/group tx key index */
119 	uint16_t		cs_max_keyix;	/* max h/w key index */
120 
121 	int			(*cs_key_alloc)(struct ieee80211com *,
122 					const struct ieee80211_key *,
123 					ieee80211_keyix *, ieee80211_keyix *);
124 	int			(*cs_key_delete)(struct ieee80211com *,
125 					const struct ieee80211_key *);
126 	int			(*cs_key_set)(struct ieee80211com *,
127 					const struct ieee80211_key *,
128 					const uint8_t mac[IEEE80211_ADDR_LEN]);
129 	void			(*cs_key_update_begin)(struct ieee80211com *);
130 	void			(*cs_key_update_end)(struct ieee80211com *);
131 };
132 
133 void	ieee80211_crypto_attach(struct ieee80211com *);
134 void	ieee80211_crypto_detach(struct ieee80211com *);
135 int	ieee80211_crypto_newkey(struct ieee80211com *,
136 		int cipher, int flags, struct ieee80211_key *);
137 int	ieee80211_crypto_delkey(struct ieee80211com *,
138 		struct ieee80211_key *);
139 int	ieee80211_crypto_setkey(struct ieee80211com *,
140 		struct ieee80211_key *, const uint8_t macaddr[IEEE80211_ADDR_LEN]);
141 void	ieee80211_crypto_delglobalkeys(struct ieee80211com *);
142 
143 /*
144  * Template for a supported cipher.  Ciphers register with the
145  * crypto code and are typically loaded as separate modules
146  * (the null cipher is always present).
147  * XXX may need refcnts
148  */
149 struct ieee80211_cipher {
150 	const char *ic_name;		/* printable name */
151 	u_int	ic_cipher;		/* IEEE80211_CIPHER_* */
152 	u_int	ic_header;		/* size of privacy header (bytes) */
153 	u_int	ic_trailer;		/* size of privacy trailer (bytes) */
154 	u_int	ic_miclen;		/* size of mic trailer (bytes) */
155 	void*	(*ic_attach)(struct ieee80211com *, struct ieee80211_key *);
156 	void	(*ic_detach)(struct ieee80211_key *);
157 	int	(*ic_setkey)(struct ieee80211_key *);
158 	int	(*ic_encap)(struct ieee80211_key *, struct mbuf *,
159 			uint8_t keyid);
160 	int	(*ic_decap)(struct ieee80211_key *, struct mbuf *, int);
161 	int	(*ic_enmic)(struct ieee80211_key *, struct mbuf *, int);
162 	int	(*ic_demic)(struct ieee80211_key *, struct mbuf *, int);
163 };
164 extern	const struct ieee80211_cipher ieee80211_cipher_none;
165 
166 #define	IEEE80211_KEY_UNDEFINED(k) \
167 	((k)->wk_cipher == &ieee80211_cipher_none)
168 
169 void	ieee80211_crypto_register(const struct ieee80211_cipher *);
170 void	ieee80211_crypto_unregister(const struct ieee80211_cipher *);
171 int	ieee80211_crypto_available(u_int cipher);
172 
173 struct ieee80211_key *ieee80211_crypto_encap(struct ieee80211com *,
174 		struct ieee80211_node *, struct mbuf *);
175 struct ieee80211_key *ieee80211_crypto_decap(struct ieee80211com *,
176 		struct ieee80211_node *, struct mbuf *, int);
177 
178 /*
179  * Check and remove any MIC.
180  */
181 static __inline int
182 ieee80211_crypto_demic(struct ieee80211com *ic, struct ieee80211_key *k,
183 	struct mbuf *m, int force)
184 {
185 	const struct ieee80211_cipher *cip = k->wk_cipher;
186 	return (cip->ic_miclen > 0 ? cip->ic_demic(k, m, force) : 1);
187 }
188 
189 /*
190  * Add any MIC.
191  */
192 static __inline int
193 ieee80211_crypto_enmic(struct ieee80211com *ic,
194 	struct ieee80211_key *k, struct mbuf *m, int force)
195 {
196 	const struct ieee80211_cipher *cip = k->wk_cipher;
197 	return (cip->ic_miclen > 0 ? cip->ic_enmic(k, m, force) : 1);
198 }
199 
200 /*
201  * Reset key state to an unused state.  The crypto
202  * key allocation mechanism insures other state (e.g.
203  * key data) is properly setup before a key is used.
204  */
205 static __inline void
206 ieee80211_crypto_resetkey(struct ieee80211com *ic,
207 	struct ieee80211_key *k, ieee80211_keyix ix)
208 {
209 	k->wk_cipher = &ieee80211_cipher_none;;
210 	k->wk_private = k->wk_cipher->ic_attach(ic, k);
211 	k->wk_keyix = k->wk_rxkeyix = ix;
212 	k->wk_flags = IEEE80211_KEY_XMIT | IEEE80211_KEY_RECV;
213 }
214 
215 /*
216  * Crypt-related notification methods.
217  */
218 void	ieee80211_notify_replay_failure(struct ieee80211com *,
219 		const struct ieee80211_frame *, const struct ieee80211_key *,
220 		u_int64_t rsc);
221 void	ieee80211_notify_michael_failure(struct ieee80211com *,
222 		const struct ieee80211_frame *, u_int keyix);
223 #endif /* defined(__KERNEL__) || defined(_KERNEL) */
224 #endif /* _NET80211_IEEE80211_CRYPTO_H_ */
225