1 /*
2 * Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package sun.security.ssl;
27
28 import java.security.NoSuchAlgorithmException;
29 import java.security.InvalidKeyException;
30 import javax.crypto.Mac;
31 import javax.crypto.SecretKey;
32 import javax.crypto.ShortBufferException;
33 import javax.crypto.spec.SecretKeySpec;
34 import java.util.Objects;
35
36 /**
37 * An implementation of the HKDF key derivation algorithm outlined in RFC 5869,
38 * specific to the needs of TLS 1.3 key derivation in JSSE. This is not a
39 * general purpose HKDF implementation and is suited only to single-key output
40 * derivations.
41 *
42 * HKDF objects are created by specifying a message digest algorithm. That
43 * digest algorithm will be used by the HMAC function as part of the HKDF
44 * derivation process.
45 */
46 class HKDF {
47 private final String hmacAlg;
48 private final Mac hmacObj;
49 private final int hmacLen;
50
51 /**
52 * Create an HDKF object, specifying the underlying message digest
53 * algorithm.
54 *
55 * @param hashAlg a standard name corresponding to a supported message
56 * digest algorithm.
57 *
58 * @throws NoSuchAlgorithmException if that message digest algorithm does
59 * not have an HMAC variant supported on any available provider.
60 */
61 HKDF(String hashAlg) throws NoSuchAlgorithmException {
62 Objects.requireNonNull(hashAlg,
63 "Must provide underlying HKDF Digest algorithm.");
64 hmacAlg = "Hmac" + hashAlg.replace("-", "");
65 hmacObj = Mac.getInstance(hmacAlg);
66 hmacLen = hmacObj.getMacLength();
67 }
68
69 /**
70 * Perform the HMAC-Extract derivation.
71 *
72 * @param salt a salt value, implemented as a {@code SecretKey}. A
73 * {@code null} value is allowed, which will internally use an array of
74 * zero bytes the same size as the underlying hash output length.
75 * @param inputKey the input keying material provided as a
76 * {@code SecretKey}.
77 * @param keyAlg the algorithm name assigned to the resulting
78 * {@code SecretKey} object.
79 *
80 * @return a {@code SecretKey} that is the result of the HKDF extract
81 * operation.
82 *
83 * @throws InvalidKeyException if the {@code salt} parameter cannot be
84 * used to initialize the underlying HMAC.
85 */
86 SecretKey extract(SecretKey salt, SecretKey inputKey, String keyAlg)
87 throws InvalidKeyException {
88 if (salt == null) {
89 salt = new SecretKeySpec(new byte[hmacLen], "HKDF-Salt");
90 }
91 hmacObj.init(salt);
92
93 return new SecretKeySpec(hmacObj.doFinal(inputKey.getEncoded()),
94 keyAlg);
95 }
96
97 /**
98 * Perform the HMAC-Extract derivation.
99 *
100 * @param salt a salt value as cleartext bytes. A {@code null} value is
101 * allowed, which will internally use an array of zero bytes the same
102 * size as the underlying hash output length.
103 * @param inputKey the input keying material provided as a
104 * {@code SecretKey}.
105 * @param keyAlg the algorithm name assigned to the resulting
106 * {@code SecretKey} object.
107 *
108 * @return a {@code SecretKey} that is the result of the HKDF extract
109 * operation.
110 *
111 * @throws InvalidKeyException if the {@code salt} parameter cannot be
112 * used to initialize the underlying HMAC.
113 */
114 SecretKey extract(byte[] salt, SecretKey inputKey, String keyAlg)
115 throws InvalidKeyException {
116 if (salt == null) {
117 salt = new byte[hmacLen];
118 }
119 return extract(new SecretKeySpec(salt, "HKDF-Salt"), inputKey, keyAlg);
120 }
121
122 /**
123 * Perform the HKDF-Expand derivation for a single-key output.
124 *
125 * @param pseudoRandKey the pseudo random key (PRK).
126 * @param info optional context-specific info. A {@code null} value is
127 * allowed in which case a zero-length byte array will be used.
128 * @param outLen the length of the resulting {@code SecretKey}
129 * @param keyAlg the algorithm name applied to the resulting
130 * {@code SecretKey}
131 *
132 * @return the resulting key derivation as a {@code SecretKey} object
133 *
134 * @throws InvalidKeyException if the underlying HMAC operation cannot
135 * be initialized using the provided {@code pseudoRandKey} object.
136 */
137 SecretKey expand(SecretKey pseudoRandKey, byte[] info, int outLen,
138 String keyAlg) throws InvalidKeyException {
139 byte[] kdfOutput;
140
141 // Calculate the number of rounds of HMAC that are needed to
142 // meet the requested data. Then set up the buffers we will need.
143 Objects.requireNonNull(pseudoRandKey, "A null PRK is not allowed.");
144 hmacObj.init(pseudoRandKey);
145 if (info == null) {
146 info = new byte[0];
147 }
148 int rounds = (outLen + hmacLen - 1) / hmacLen;
149 kdfOutput = new byte[rounds * hmacLen];
150 int offset = 0;
151 int tLength = 0;
152
153 for (int i = 0; i < rounds ; i++) {
154
155 // Calculate this round
156 try {
157 // Add T(i). This will be an empty string on the first
158 // iteration since tLength starts at zero. After the first
159 // iteration, tLength is changed to the HMAC length for the
160 // rest of the loop.
161 hmacObj.update(kdfOutput,
162 Math.max(0, offset - hmacLen), tLength);
163 hmacObj.update(info); // Add info
164 hmacObj.update((byte)(i + 1)); // Add round number
165 hmacObj.doFinal(kdfOutput, offset);
166
167 tLength = hmacLen;
168 offset += hmacLen; // For next iteration
169 } catch (ShortBufferException sbe) {
170 // This really shouldn't happen given that we've
171 // sized the buffers to their largest possible size up-front,
172 // but just in case...
173 throw new RuntimeException(sbe);
174 }
175 }
176
177 return new SecretKeySpec(kdfOutput, 0, outLen, keyAlg);
178 }
179
180 /**
181 * Perform the HKDF Extract-then-Expand operation.
182 *
183 * @param inputKey the input keying material provided as a
184 * {@code SecretKey}.
185 * @param salt a salt value, implemented as a {@code SecretKey}. A
186 * {@code null} value is allowed, which will internally use an array of
187 * zero bytes the same size as the underlying hash output length.
188 * @param info optional context-specific info. A {@code null} value is
189 * allowed in which case a zero-length byte array will be used.
190 * @param outLen the length of the resulting {@code SecretKey}
191 * @param keyAlg the algorithm name applied to the resulting
192 * {@code SecretKey}
193 *
194 * @return the resulting derivation stored in a {@code SecretKey} object.
195 *
196 * @throws InvalidKeyException if initialization of the underlying HMAC
197 * process fails with the salt during the extract phase, or with the
198 * resulting PRK during the expand phase.
199 */
200 SecretKey extractExpand(SecretKey inputKey, SecretKey salt, byte[] info,
201 int outLen, String keyAlg) throws InvalidKeyException {
202 SecretKey prk = extract(salt, inputKey, "HKDF-PRK");
203 return expand(prk, info, outLen, keyAlg);
204 }
205
206 /**
207 * Perform the HKDF Extract-then-Expand operation.
208 *
209 * @param inputKey the input keying material provided as a
210 * {@code SecretKey}.
211 * @param salt a salt value as cleartext bytes. A {@code null} value is
212 * allowed, which will internally use an array of zero bytes the same
213 * size as the underlying hash output length.
214 * @param info optional context-specific info. A {@code null} value is
215 * allowed in which case a zero-length byte array will be used.
216 * @param outLen the length of the resulting {@code SecretKey}
217 * @param keyAlg the algorithm name applied to the resulting
218 * {@code SecretKey}
219 *
220 * @return the resulting derivation stored in a {@code SecretKey} object.
221 *
222 * @throws InvalidKeyException if initialization of the underlying HMAC
223 * process fails with the salt during the extract phase, or with the
224 * resulting PRK during the expand phase.
225 */
226 SecretKey extractExpand(SecretKey inputKey, byte[] salt, byte[] info,
227 int outLen, String keyAlg) throws InvalidKeyException {
228 byte[] saltBytes = (salt != null) ? salt : new byte[hmacLen];
229 return extractExpand(inputKey,
230 new SecretKeySpec(saltBytes, "HKDF-PRK"), info, outLen, keyAlg);
231 }
232 }