PostgreSQL Source Code  git master
hmac.c
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * hmac.c
4  * Implements Keyed-Hashing for Message Authentication (HMAC)
5  *
6  * Fallback implementation of HMAC, as specified in RFC 2104.
7  *
8  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
9  * Portions Copyright (c) 1994, Regents of the University of California
10  *
11  * IDENTIFICATION
12  * src/common/hmac.c
13  *
14  *-------------------------------------------------------------------------
15  */
16 
17 #ifndef FRONTEND
18 #include "postgres.h"
19 #else
20 #include "postgres_fe.h"
21 #endif
22 
23 #include "common/cryptohash.h"
24 #include "common/hmac.h"
25 #include "common/md5.h"
26 #include "common/sha1.h"
27 #include "common/sha2.h"
28 
29 /*
30  * In backend, use palloc/pfree to ease the error handling. In frontend,
31  * use malloc to be able to return a failure status back to the caller.
32  */
33 #ifndef FRONTEND
34 #define ALLOC(size) palloc(size)
35 #define FREE(ptr) pfree(ptr)
36 #else
37 #define ALLOC(size) malloc(size)
38 #define FREE(ptr) free(ptr)
39 #endif
40 
41 /* Set of error states */
42 typedef enum pg_hmac_errno
43 {
48 
49 /* Internal pg_hmac_ctx structure */
51 {
55  const char *errreason;
58 
59  /*
60  * Use the largest block size among supported options. This wastes some
61  * memory but simplifies the allocation logic.
62  */
65 };
66 
67 #define HMAC_IPAD 0x36
68 #define HMAC_OPAD 0x5C
69 
70 /*
71  * pg_hmac_create
72  *
73  * Allocate a hash context. Returns NULL on failure for an OOM. The
74  * backend issues an error, without returning.
75  */
78 {
79  pg_hmac_ctx *ctx;
80 
81  ctx = ALLOC(sizeof(pg_hmac_ctx));
82  if (ctx == NULL)
83  return NULL;
84  memset(ctx, 0, sizeof(pg_hmac_ctx));
85  ctx->type = type;
87  ctx->errreason = NULL;
88 
89  /*
90  * Initialize the context data. This requires to know the digest and
91  * block lengths, that depend on the type of hash used.
92  */
93  switch (type)
94  {
95  case PG_MD5:
98  break;
99  case PG_SHA1:
102  break;
103  case PG_SHA224:
106  break;
107  case PG_SHA256:
110  break;
111  case PG_SHA384:
114  break;
115  case PG_SHA512:
118  break;
119  }
120 
122  if (ctx->hash == NULL)
123  {
124  explicit_bzero(ctx, sizeof(pg_hmac_ctx));
125  FREE(ctx);
126  return NULL;
127  }
128 
129  return ctx;
130 }
131 
132 /*
133  * pg_hmac_init
134  *
135  * Initialize a HMAC context. Returns 0 on success, -1 on failure.
136  */
137 int
138 pg_hmac_init(pg_hmac_ctx *ctx, const uint8 *key, size_t len)
139 {
140  int i;
141  int digest_size;
142  int block_size;
143  uint8 *shrinkbuf = NULL;
144 
145  if (ctx == NULL)
146  return -1;
147 
148  digest_size = ctx->digest_size;
149  block_size = ctx->block_size;
150 
151  memset(ctx->k_opad, HMAC_OPAD, ctx->block_size);
152  memset(ctx->k_ipad, HMAC_IPAD, ctx->block_size);
153 
154  /*
155  * If the key is longer than the block size, pass it through the hash once
156  * to shrink it down.
157  */
158  if (len > block_size)
159  {
160  pg_cryptohash_ctx *hash_ctx;
161 
162  /* temporary buffer for one-time shrink */
163  shrinkbuf = ALLOC(digest_size);
164  if (shrinkbuf == NULL)
165  {
166  ctx->error = PG_HMAC_ERROR_OOM;
167  return -1;
168  }
169  memset(shrinkbuf, 0, digest_size);
170 
171  hash_ctx = pg_cryptohash_create(ctx->type);
172  if (hash_ctx == NULL)
173  {
174  ctx->error = PG_HMAC_ERROR_OOM;
175  FREE(shrinkbuf);
176  return -1;
177  }
178 
179  if (pg_cryptohash_init(hash_ctx) < 0 ||
180  pg_cryptohash_update(hash_ctx, key, len) < 0 ||
181  pg_cryptohash_final(hash_ctx, shrinkbuf, digest_size) < 0)
182  {
184  ctx->errreason = pg_cryptohash_error(hash_ctx);
185  pg_cryptohash_free(hash_ctx);
186  FREE(shrinkbuf);
187  return -1;
188  }
189 
190  key = shrinkbuf;
191  len = digest_size;
192  pg_cryptohash_free(hash_ctx);
193  }
194 
195  for (i = 0; i < len; i++)
196  {
197  ctx->k_ipad[i] ^= key[i];
198  ctx->k_opad[i] ^= key[i];
199  }
200 
201  /* tmp = H(K XOR ipad, text) */
202  if (pg_cryptohash_init(ctx->hash) < 0 ||
203  pg_cryptohash_update(ctx->hash, ctx->k_ipad, ctx->block_size) < 0)
204  {
206  ctx->errreason = pg_cryptohash_error(ctx->hash);
207  if (shrinkbuf)
208  FREE(shrinkbuf);
209  return -1;
210  }
211 
212  if (shrinkbuf)
213  FREE(shrinkbuf);
214  return 0;
215 }
216 
217 /*
218  * pg_hmac_update
219  *
220  * Update a HMAC context. Returns 0 on success, -1 on failure.
221  */
222 int
223 pg_hmac_update(pg_hmac_ctx *ctx, const uint8 *data, size_t len)
224 {
225  if (ctx == NULL)
226  return -1;
227 
228  if (pg_cryptohash_update(ctx->hash, data, len) < 0)
229  {
231  ctx->errreason = pg_cryptohash_error(ctx->hash);
232  return -1;
233  }
234 
235  return 0;
236 }
237 
238 /*
239  * pg_hmac_final
240  *
241  * Finalize a HMAC context. Returns 0 on success, -1 on failure.
242  */
243 int
245 {
246  uint8 *h;
247 
248  if (ctx == NULL)
249  return -1;
250 
251  h = ALLOC(ctx->digest_size);
252  if (h == NULL)
253  {
254  ctx->error = PG_HMAC_ERROR_OOM;
255  return -1;
256  }
257  memset(h, 0, ctx->digest_size);
258 
259  if (pg_cryptohash_final(ctx->hash, h, ctx->digest_size) < 0)
260  {
262  ctx->errreason = pg_cryptohash_error(ctx->hash);
263  FREE(h);
264  return -1;
265  }
266 
267  /* H(K XOR opad, tmp) */
268  if (pg_cryptohash_init(ctx->hash) < 0 ||
269  pg_cryptohash_update(ctx->hash, ctx->k_opad, ctx->block_size) < 0 ||
270  pg_cryptohash_update(ctx->hash, h, ctx->digest_size) < 0 ||
271  pg_cryptohash_final(ctx->hash, dest, len) < 0)
272  {
274  ctx->errreason = pg_cryptohash_error(ctx->hash);
275  FREE(h);
276  return -1;
277  }
278 
279  FREE(h);
280  return 0;
281 }
282 
283 /*
284  * pg_hmac_free
285  *
286  * Free a HMAC context.
287  */
288 void
290 {
291  if (ctx == NULL)
292  return;
293 
294  pg_cryptohash_free(ctx->hash);
295  explicit_bzero(ctx, sizeof(pg_hmac_ctx));
296  FREE(ctx);
297 }
298 
299 /*
300  * pg_hmac_error
301  *
302  * Returns a static string providing details about an error that happened
303  * during a HMAC computation.
304  */
305 const char *
307 {
308  if (ctx == NULL)
309  return _("out of memory");
310 
311  /*
312  * If a reason is provided, rely on it, else fallback to any error code
313  * set.
314  */
315  if (ctx->errreason)
316  return ctx->errreason;
317 
318  switch (ctx->error)
319  {
320  case PG_HMAC_ERROR_NONE:
321  return _("success");
323  return _("internal error");
324  case PG_HMAC_ERROR_OOM:
325  return _("out of memory");
326  }
327 
328  Assert(false); /* cannot be reached */
329  return _("success");
330 }
unsigned char uint8
Definition: c.h:491
int pg_cryptohash_update(pg_cryptohash_ctx *ctx, const uint8 *data, size_t len)
Definition: cryptohash.c:136
int pg_cryptohash_init(pg_cryptohash_ctx *ctx)
Definition: cryptohash.c:100
void pg_cryptohash_free(pg_cryptohash_ctx *ctx)
Definition: cryptohash.c:238
pg_cryptohash_ctx * pg_cryptohash_create(pg_cryptohash_type type)
Definition: cryptohash.c:74
int pg_cryptohash_final(pg_cryptohash_ctx *ctx, uint8 *dest, size_t len)
Definition: cryptohash.c:172
const char * pg_cryptohash_error(pg_cryptohash_ctx *ctx)
Definition: cryptohash.c:254
pg_cryptohash_type
Definition: cryptohash.h:20
@ PG_SHA512
Definition: cryptohash.h:26
@ PG_SHA224
Definition: cryptohash.h:23
@ PG_SHA384
Definition: cryptohash.h:25
@ PG_SHA1
Definition: cryptohash.h:22
@ PG_SHA256
Definition: cryptohash.h:24
@ PG_MD5
Definition: cryptohash.h:21
#define _(x)
Definition: elog.c:90
static int block_size
Definition: guc_tables.c:596
pg_hmac_ctx * pg_hmac_create(pg_cryptohash_type type)
Definition: hmac.c:77
#define FREE(ptr)
Definition: hmac.c:35
const char * pg_hmac_error(pg_hmac_ctx *ctx)
Definition: hmac.c:306
#define HMAC_OPAD
Definition: hmac.c:68
void pg_hmac_free(pg_hmac_ctx *ctx)
Definition: hmac.c:289
int pg_hmac_update(pg_hmac_ctx *ctx, const uint8 *data, size_t len)
Definition: hmac.c:223
int pg_hmac_init(pg_hmac_ctx *ctx, const uint8 *key, size_t len)
Definition: hmac.c:138
#define ALLOC(size)
Definition: hmac.c:34
#define HMAC_IPAD
Definition: hmac.c:67
pg_hmac_errno
Definition: hmac.c:43
@ PG_HMAC_ERROR_INTERNAL
Definition: hmac.c:46
@ PG_HMAC_ERROR_OOM
Definition: hmac.c:45
@ PG_HMAC_ERROR_NONE
Definition: hmac.c:44
int pg_hmac_final(pg_hmac_ctx *ctx, uint8 *dest, size_t len)
Definition: hmac.c:244
int i
Definition: isn.c:73
Assert(fmt[strlen(fmt) - 1] !='\n')
#define MD5_DIGEST_LENGTH
Definition: md5.h:20
#define MD5_BLOCK_SIZE
Definition: md5.h:22
const void size_t len
const void * data
void explicit_bzero(void *buf, size_t len)
#define SHA1_DIGEST_LENGTH
Definition: sha1.h:17
#define SHA1_BLOCK_SIZE
Definition: sha1.h:19
#define PG_SHA256_DIGEST_LENGTH
Definition: sha2.h:23
#define PG_SHA384_BLOCK_LENGTH
Definition: sha2.h:25
#define PG_SHA384_DIGEST_LENGTH
Definition: sha2.h:26
#define PG_SHA512_DIGEST_LENGTH
Definition: sha2.h:29
#define PG_SHA256_BLOCK_LENGTH
Definition: sha2.h:22
#define PG_SHA512_BLOCK_LENGTH
Definition: sha2.h:28
#define PG_SHA224_BLOCK_LENGTH
Definition: sha2.h:19
#define PG_SHA224_DIGEST_LENGTH
Definition: sha2.h:20
const char * errreason
Definition: hmac.c:55
uint8 k_opad[PG_SHA512_BLOCK_LENGTH]
Definition: hmac.c:64
pg_cryptohash_ctx * hash
Definition: hmac.c:52
int digest_size
Definition: hmac.c:57
uint8 k_ipad[PG_SHA512_BLOCK_LENGTH]
Definition: hmac.c:63
int block_size
Definition: hmac.c:56
pg_cryptohash_type type
Definition: hmac.c:53
pg_hmac_errno error
Definition: hmac.c:54
const char * type