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#include <Availability.h>
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40/*!
41    @enum       CCHmacAlgorithm
42    @abstract   Algorithms implemented in this module.
43
44    @constant   kCCHmacAlgSHA1      HMAC with SHA1 digest
45    @constant   kCCHmacAlgMD5       HMAC with MD5 digest
46    @constant   kCCHmacAlgSHA256    HMAC with SHA256 digest
47    @constant   kCCHmacAlgSHA384    HMAC with SHA384 digest
48    @constant   kCCHmacAlgSHA512    HMAC with SHA512 digest
49    @constant   kCCHmacAlgSHA224    HMAC with SHA224 digest
50 */
51enum {
52    kCCHmacAlgSHA1,
53    kCCHmacAlgMD5,
54    kCCHmacAlgSHA256,
55    kCCHmacAlgSHA384,
56    kCCHmacAlgSHA512,
57    kCCHmacAlgSHA224
58};
59typedef uint32_t CCHmacAlgorithm;
60
61/*!
62    @typedef    CCHmacContext
63    @abstract   HMAC context.
64 */
65#define CC_HMAC_CONTEXT_SIZE    96
66typedef struct {
67    uint32_t            ctx[CC_HMAC_CONTEXT_SIZE];
68} CCHmacContext;
69
70/*!
71    @function   CCHmacInit
72    @abstract   Initialize an CCHmacContext with provided raw key bytes.
73
74    @param      ctx         An HMAC context.
75    @param      algorithm   HMAC algorithm to perform.
76    @param      key         Raw key bytes.
77    @param      keyLength   Length of raw key bytes; can be any
78                            length including zero.
79 */
80void CCHmacInit(
81    CCHmacContext *ctx,
82    CCHmacAlgorithm algorithm,
83    const void *key,
84    size_t keyLength)
85    __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0);
86
87
88/*!
89    @function   CCHmacUpdate
90    @abstract   Process some data.
91
92    @param      ctx         An HMAC context.
93    @param      data        Data to process.
94    @param      dataLength  Length of data to process, in bytes.
95
96    @discussion This can be called multiple times.
97 */
98void CCHmacUpdate(
99    CCHmacContext *ctx,
100    const void *data,
101    size_t dataLength)
102    __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0);
103
104
105/*!
106    @function   CCHmacFinal
107    @abstract   Obtain the final Message Authentication Code.
108
109    @param      ctx         An HMAC context.
110    @param      macOut      Destination of MAC; allocated by caller.
111
112    @discussion The length of the MAC written to *macOut is the same as
113                the digest length associated with the HMAC algorithm:
114
115                kCCHmacSHA1 : CC_SHA1_DIGEST_LENGTH
116
117                kCCHmacMD5  : CC_MD5_DIGEST_LENGTH
118 */
119void CCHmacFinal(
120    CCHmacContext *ctx,
121    void *macOut)
122    __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0);
123
124
125/*
126 * Stateless, one-shot HMAC function.
127 * Output is written to caller-supplied buffer, as in CCHmacFinal().
128 */
129void CCHmac(
130    CCHmacAlgorithm algorithm,  /* kCCHmacSHA1, kCCHmacMD5 */
131    const void *key,
132    size_t keyLength,           /* length of key in bytes */
133    const void *data,
134    size_t dataLength,          /* length of data in bytes */
135    void *macOut)               /* MAC written here */
136    __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0);
137
138#ifdef __cplusplus
139}
140#endif
141
142#endif  /* _CC_COMMON_HMAC_H_ */
143