IBR-DTNSuite  0.12
gcm.h
Go to the documentation of this file.
1 /*
2  ---------------------------------------------------------------------------
3  Copyright (c) 1998-2006, Brian Gladman, Worcester, UK. All rights reserved.
4 
5  LICENSE TERMS
6 
7  The free distribution and use of this software in both source and binary
8  form is allowed (with or without changes) provided that:
9 
10  1. distributions of this source code include the above copyright
11  notice, this list of conditions and the following disclaimer;
12 
13  2. distributions in binary form include the above copyright
14  notice, this list of conditions and the following disclaimer
15  in the documentation and/or other associated materials;
16 
17  3. the copyright holder's name is not used to endorse products
18  built using this software without specific written permission.
19 
20  ALTERNATIVELY, provided that this notice is retained in full, this product
21  may be distributed under the terms of the GNU General Public License (GPL),
22  in which case the provisions of the GPL apply INSTEAD OF those given above.
23 
24  DISCLAIMER
25 
26  This software is provided 'as is' with no explicit or implied warranties
27  in respect of its properties, including, but not limited to, correctness
28  and/or fitness for purpose.
29  ---------------------------------------------------------------------------
30  Issue Date: 13/10/2006
31 */
32 
33 /* This file changed 5 June 2007 to reflect name change
34  of included file from "aes.h" to "gcm_aes.h"
35  Changed by Peter Lovell, SPARTA Inc., for DTN project.
36 */
37 
38 #ifndef _GCM_H
39 #define _GCM_H
40 
41 /* This define sets the memory alignment that will be used for fast move
42  and xor operations on buffers when the alignment matches this value.
43 */
44 #if !defined( BFR_UNIT )
45 # if 1
46 # define BFR_UNIT 64
47 # elif 0
48 # define BFR_UNIT 32
49 # else
50 # define BFR_UNIT 8
51 # endif
52 #endif
53 
54 #include "gcm_aes.h"
55 #include "gf128mul.h"
56 
57 #if defined(__cplusplus)
58 extern "C"
59 {
60 #endif
61 
62 /* After encryption or decryption operations the return value of
63  'compute tag' will be one of the values RETURN_OK, RETURN_WARN
64  or RETURN_ERROR, the latter indicating an error. A return value
65  RETURN_OK indicates that both encryption and authentication
66  have taken place and resulted in the returned tag value. If
67  the returned value is RETURN_WARN, the tag value is the result
68  of authentication alone without encryption (CCM) or decryption
69  (GCM and EAX).
70 */
71 #ifndef RETURN_OK
72 # define RETURN_WARN 1
73 # define RETURN_OK 0
74 # define RETURN_ERROR -1
75 #endif
76 
77 typedef int ret_type;
78 dec_unit_type(BFR_UNIT, buf_unit);
79 dec_bufr_type(BFR_UNIT, AES_BLOCK_SIZE, buf_type);
80 
81 #define GCM_BLOCK_SIZE AES_BLOCK_SIZE
82 
83 /* The GCM-AES context */
84 
85 typedef struct
86 {
87 #if defined( TABLES_64K )
88  uint_32t gf_t64k[16][256][GCM_BLOCK_SIZE / 4];
89 #endif
90 #if defined( TABLES_8K )
91  uint_32t gf_t8k[32][16][GCM_BLOCK_SIZE / 4];
92 #endif
93 #if defined( TABLES_4K )
94  uint_32t gf_t4k[256][GCM_BLOCK_SIZE / 4];
95 #endif
96 #if defined( TABLES_256 )
97  uint_32t gf_t256[16][GCM_BLOCK_SIZE / 4];
98 #endif
99  buf_type ctr_val; /* CTR counter value */
100  buf_type enc_ctr; /* encrypted CTR block */
101  buf_type hdr_ghv; /* ghash buffer (header) */
102  buf_type txt_ghv; /* ghash buffer (ciphertext) */
103  buf_type ghash_h; /* ghash H value */
104  aes_encrypt_ctx aes[1]; /* AES encryption context */
105  uint_32t y0_val; /* initial counter value */
106  uint_32t hdr_cnt; /* header bytes so far */
107  uint_32t txt_ccnt; /* text bytes so far (encrypt) */
108  uint_32t txt_acnt; /* text bytes so far (auth) */
109 } gcm_ctx;
110 
111 /* The following calls handle mode initialisation, keying and completion */
112 
113 ret_type gcm_init_and_key( /* initialise mode and set key */
114  const unsigned char key[], /* the key value */
115  unsigned long key_len, /* and its length in bytes */
116  gcm_ctx ctx[1]); /* the mode context */
117 
118 ret_type gcm_end( /* clean up and end operation */
119  gcm_ctx ctx[1]); /* the mode context */
120 
121 /* The following calls handle complete messages in memory in a single operation */
122 
123 ret_type gcm_encrypt_message( /* encrypt an entire message */
124  const unsigned char iv[], /* the initialisation vector */
125  unsigned long iv_len, /* and its length in bytes */
126  const unsigned char hdr[], /* the header buffer */
127  unsigned long hdr_len, /* and its length in bytes */
128  unsigned char msg[], /* the message buffer */
129  unsigned long msg_len, /* and its length in bytes */
130  unsigned char tag[], /* the buffer for the tag */
131  unsigned long tag_len, /* and its length in bytes */
132  gcm_ctx ctx[1]); /* the mode context */
133 
134  /* RETURN_OK is returned if the input tag */
135  /* matches that for the decrypted message */
136 ret_type gcm_decrypt_message( /* decrypt an entire message */
137  const unsigned char iv[], /* the initialisation vector */
138  unsigned long iv_len, /* and its length in bytes */
139  const unsigned char hdr[], /* the header buffer */
140  unsigned long hdr_len, /* and its length in bytes */
141  unsigned char msg[], /* the message buffer */
142  unsigned long msg_len, /* and its length in bytes */
143  const unsigned char tag[], /* the buffer for the tag */
144  unsigned long tag_len, /* and its length in bytes */
145  gcm_ctx ctx[1]); /* the mode context */
146 
147 /* The following calls handle messages in a sequence of operations followed by */
148 /* tag computation after the sequence has been completed. In these calls the */
149 /* user is responsible for verfiying the computed tag on decryption */
150 
151 ret_type gcm_init_message( /* initialise a new message */
152  const unsigned char iv[], /* the initialisation vector */
153  unsigned long iv_len, /* and its length in bytes */
154  gcm_ctx ctx[1]); /* the mode context */
155 
156 ret_type gcm_auth_header( /* authenticate the header */
157  const unsigned char hdr[], /* the header buffer */
158  unsigned long hdr_len, /* and its length in bytes */
159  gcm_ctx ctx[1]); /* the mode context */
160 
161 ret_type gcm_encrypt( /* encrypt & authenticate data */
162  unsigned char data[], /* the data buffer */
163  unsigned long data_len, /* and its length in bytes */
164  gcm_ctx ctx[1]); /* the mode context */
165 
166 ret_type gcm_decrypt( /* authenticate & decrypt data */
167  unsigned char data[], /* the data buffer */
168  unsigned long data_len, /* and its length in bytes */
169  gcm_ctx ctx[1]); /* the mode context */
170 
171 ret_type gcm_compute_tag( /* compute authentication tag */
172  unsigned char tag[], /* the buffer for the tag */
173  unsigned long tag_len, /* and its length in bytes */
174  gcm_ctx ctx[1]); /* the mode context */
175 
176 /* The use of the following calls should be avoided if possible because their
177  use requires a very good understanding of the way this encryption mode
178  works and the way in which this code implements it in order to use them
179  correctly.
180 
181  The gcm_auth_data routine is used to authenticate encrypted message data.
182  In message encryption gcm_crypt_data must be called before gcm_auth_data
183  is called since it is encrypted data that is authenticated. In message
184  decryption authentication must occur before decryption and data can be
185  authenticated without being decrypted if necessary.
186 
187  If these calls are used it is up to the user to ensure that these routines
188  are called in the correct order and that the correct data is passed to them.
189 
190  When gcm_compute_tag is called it is assumed that an error in use has
191  occurred if both encryption (or decryption) and authentication have taken
192  place but the total lengths of the message data respectively authenticated
193  and encrypted are not the same. If authentication has taken place but there
194  has been no corresponding encryption or decryption operations (none at all)
195  only a warning is issued. This should be treated as an error if it occurs
196  during encryption but it is only signalled as a warning as it might be
197  intentional when decryption operations are involved (this avoids having
198  different compute tag functions for encryption and decryption). Decryption
199  operations can be undertaken freely after authetication but if the tag is
200  computed after such operations an error will be signalled if the lengths of
201  the data authenticated and decrypted don't match.
202 */
203 
204 ret_type gcm_auth_data( /* authenticate ciphertext data */
205  const unsigned char data[], /* the data buffer */
206  unsigned long data_len, /* and its length in bytes */
207  gcm_ctx ctx[1]); /* the mode context */
208 
209 ret_type gcm_crypt_data( /* encrypt or decrypt data */
210  unsigned char data[], /* the data buffer */
211  unsigned long data_len, /* and its length in bytes */
212  gcm_ctx ctx[1]); /* the mode context */
213 
214 #if defined(__cplusplus)
215 }
216 #endif
217 
218 #endif