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