1/*
2 * Copyright (c) 2004 Apple Computer, Inc. All Rights Reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22 */
23
24/*!
25 @header CommonHMAC.h
26 @abstract Keyed Message Authentication Code (HMAC) functions.
27 */
28
29#ifndef _CC_COMMON_HMAC_H_
30#define _CC_COMMON_HMAC_H_
31
32#include <CommonCrypto/CommonDigest.h>
33#include <sys/types.h>
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39/*!
40 @enum CCHmacAlgorithm
41 @abstract Algorithms implemented in this module.
42
43 @constant kCCHmacAlgSHA1 HMAC with SHA1 digest
44 @constant kCCHmacAlgMD5 HMAC with MD5 digest
45 @constant kCCHmacAlgSHA256 HMAC with SHA256 digest
46 @constant kCCHmacAlgSHA384 HMAC with SHA384 digest
47 @constant kCCHmacAlgSHA512 HMAC with SHA512 digest
48 @constant kCCHmacAlgSHA224 HMAC with SHA224 digest
49 */
50enum {
51 kCCHmacAlgSHA1,
52 kCCHmacAlgMD5,
53 kCCHmacAlgSHA256,
54 kCCHmacAlgSHA384,
55 kCCHmacAlgSHA512,
56 kCCHmacAlgSHA224
57};
58typedef uint32_t CCHmacAlgorithm;
59
60/*!
61 @typedef CCHmacContext
62 @abstract HMAC context.
63 */
64#define CC_HMAC_CONTEXT_SIZE 96
65typedef struct {
66 uint32_t ctx[CC_HMAC_CONTEXT_SIZE];
67} CCHmacContext;
68
69/*!
70 @function CCHmacInit
71 @abstract Initialize an CCHmacContext with provided raw key bytes.
72
73 @param ctx An HMAC context.
74 @param algorithm HMAC algorithm to perform.
75 @param key Raw key bytes.
76 @param keyLength Length of raw key bytes; can be any
77 length including zero.
78 */
79void CCHmacInit(
80 CCHmacContext *ctx,
81 CCHmacAlgorithm algorithm,
82 const void *key,
83 size_t keyLength)
84 API_AVAILABLE(macos(10.4), ios(2.0));
85
86
87/*!
88 @function CCHmacUpdate
89 @abstract Process some data.
90
91 @param ctx An HMAC context.
92 @param data Data to process.
93 @param dataLength Length of data to process, in bytes.
94
95 @discussion This can be called multiple times.
96 */
97void CCHmacUpdate(
98 CCHmacContext *ctx,
99 const void *data,
100 size_t dataLength)
101 API_AVAILABLE(macos(10.4), ios(2.0));
102
103
104/*!
105 @function CCHmacFinal
106 @abstract Obtain the final Message Authentication Code.
107
108 @param ctx An HMAC context.
109 @param macOut Destination of MAC; allocated by caller.
110
111 @discussion The length of the MAC written to *macOut is the same as
112 the digest length associated with the HMAC algorithm:
113
114 kCCHmacAlgSHA1 : CC_SHA1_DIGEST_LENGTH
115 kCCHmacAlgSHA256 : CC_SHA256_DIGEST_LENGTH
116
117 The MAC must be verified by comparing the computed and expected values
118 using timingsafe_bcmp. Other comparison functions (e.g. memcmp)
119 must not be used as they may be vulnerable to practical timing attacks,
120 leading to MAC forgery.
121 */
122void CCHmacFinal(
123 CCHmacContext *ctx,
124 void *macOut)
125 API_AVAILABLE(macos(10.4), ios(2.0));
126
127/*!
128 @function CCHmac
129 @abstract Stateless, one-shot HMAC function
130
131 @param algorithm HMAC algorithm to perform.
132 @param key Raw key bytes.
133 @param keyLength Length of raw key bytes; can be any
134 length including zero.
135 @param data Data to process.
136 @param dataLength Length of data to process, in bytes.
137 @param macOut Destination of MAC; allocated by caller.
138
139 @discussion The length of the MAC written to *macOut is the same as the digest length associated with the HMAC algorithm:
140 kCCHmacAlgSHA1 : CC_SHA1_DIGEST_LENGTH
141 kCCHmacAlgSHA256 : CC_SHA256_DIGEST_LENGTH
142
143 The MAC must be verified by comparing the computed and expected values
144 using timingsafe_bcmp. Other comparison functions (e.g. memcmp)
145 must not be used as they may be vulnerable to practical timing attacks,
146 leading to MAC forgery.
147*/
148
149void CCHmac(
150 CCHmacAlgorithm algorithm, /* kCCHmacAlgSHA256, kCCHmacAlgSHA1 */
151 const void *key,
152 size_t keyLength, /* length of key in bytes */
153 const void *data,
154 size_t dataLength, /* length of data in bytes */
155 void *macOut) /* MAC written here */
156 API_AVAILABLE(macos(10.4), ios(2.0));
157
158#ifdef __cplusplus
159}
160#endif
161
162#endif /* _CC_COMMON_HMAC_H_ */