1/*
2 * CDDL HEADER START
3 *
4 * The contents of this file are subject to the terms of the
5 * Common Development and Distribution License (the "License").
6 * You may not use this file except in compliance with the License.
7 *
8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 * or http://www.opensolaris.org/os/licensing.
10 * See the License for the specific language governing permissions
11 * and limitations under the License.
12 *
13 * When distributing Covered Code, include this CDDL HEADER in each
14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 * If applicable, add the following below this CDDL HEADER, with the
16 * fields enclosed by brackets "[]" replaced with your own identifying
17 * information: Portions Copyright [yyyy] [name of copyright owner]
18 *
19 * CDDL HEADER END
20 */
21
22/*
23 * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
24 */
25
26/**
27 * \file KMSAgentChallenge.h
28 */
29
30#ifndef KMSAagentChallenge_H
31#define	KMSAagentChallenge_H
32
33/**
34 *   computes the response to the KMA's challenge using
35 *   HMAC-SHA1( RootCACertificate || AuthenticationChallenge,
36 *      AuthenticationSecret ).  The AuthenticationSecret is
37 *   used as the key in the HMAC-SHA1 computation.
38 *
39 *   @param i_pAuthenticationSecret
40 *   @param i_iAuthenticationSecretLength
41 *   @param i_pRootCACertificate
42 *   @param i_iRootCACertificateLength
43 *   @param i_pAuthenticationChallenge
44 *   @param i_iAuthenticationChallengeLength
45 *   @param o_pAuthenticationChallengeResponse
46 *   @param i_iAuthenticationChallengeResponseLength
47 *
48 *   @return boolean success indicator
49 */
50bool ComputeChallengeResponse(
51        const unsigned char* i_pAuthenticationSecret,
52        int i_iAuthenticationSecretLength,
53        const unsigned char* i_pRootCACertificate,
54        int i_iRootCACertificateLength,
55        const unsigned char* i_pAuthenticationChallenge,
56        int i_iAuthenticationChallengeLength,
57        unsigned char* o_pAuthenticationChallengeResponse,
58        int i_iAuthenticationChallengeResponseLength );
59
60/**
61 *  computes the SHA1 hash of the specified passphrase.
62 *  The number of SHA1 iterations
63 *  is recorded in <code>o_iAuthenticationHashIterationCount</code> and the result
64 *  stored in o_sHexAuthenticationSecret as a UTF8 hex string.
65 *  HexAuthenticationSecret is SHA1( SHA1( ... ( SHA1( HashedPassphrase ) ) )
66 *  The number of iterations is time bounded at 1/10 of a second, and also
67 *  bounded by fixed minimum and maximum values (to prevent too weak of a
68 *  computation and to prevent a DoS, respectively).
69 *  This value is used as the shared secret in challenge-response
70 *  authentication exchanges.
71
72 *  @param i_sPassphrase            the passphrase to be hashed
73 *  @param o_sHexHashedPassphrase   the hashed passphrase
74 *                                  returned in UTF8 hexadecimal, this
75 *                                  buffer should be at least
76 *                                  2*HASH_LENGTH+1 bytes
77 *  @param o_iAuthenticationHashIterationCount
78 *  @param o_sHexAuthenticationSecret
79 *
80 *  @return boolean success indicator
81 */
82bool ComputeEntityHashedPassphraseAndAuthenticationSecret(
83   const char* const   i_sPassphrase,
84   char* const         o_sHexHashedPassphrase,
85   int* const          o_piAuthenticationHashIterationCount,
86   char* const         o_sHexAuthenticationSecret );
87
88/**
89 *  computes the SHA1 hash of the specified passphrase.  The SHA1 is
90 *  performed a "fixed" number of times as specified by
91 *   <code>i_iAuthenticationHashIterationCount</code>.
92 *
93 *  @param i_sPassphrase  the passprhase to be SHA1 hashed
94 *  @param o_sHexHashedPassphrase the SHA1 hash
95 *            of i_sPassphrase stored as a UTF8 hex string
96 *  @param i_iAuthenticationHashIterationCount the number
97 *            of times to SHA1 hash the passphrase
98 *  @param o_sHexAuthenticationSecret the passphrase hashed
99 *            the fixed number of times and stored as a UTF8
100 *            hex string
101 *
102 *  @return boolean success indicator
103 */
104bool ComputeFixedEntityHashedPassphraseAndAuthenticationSecret(
105   const char* i_sPassphrase,
106   char* const o_sHexHashedPassphrase,
107   int         i_iAuthenticationHashIterationCount,
108   char* const o_sHexAuthenticationSecret );
109
110#endif	/* KMSAagentChallenge_H */
111
112