1 // Copyright 2017 Google Inc. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 // 15 //////////////////////////////////////////////////////////////////////////////// 16 17 package com.google.crypto.tink.streamingaead; 18 19 import com.google.crypto.tink.proto.AesCtrHmacStreamingKeyFormat; 20 import com.google.crypto.tink.proto.AesCtrHmacStreamingParams; 21 import com.google.crypto.tink.proto.AesGcmHkdfStreamingKeyFormat; 22 import com.google.crypto.tink.proto.AesGcmHkdfStreamingParams; 23 import com.google.crypto.tink.proto.HashType; 24 import com.google.crypto.tink.proto.HmacParams; 25 import com.google.crypto.tink.proto.KeyTemplate; 26 import com.google.crypto.tink.proto.OutputPrefixType; 27 28 /** 29 * Pre-generated {@link KeyTemplate} for {@link com.google.crypto.tink.StreamingAead} keys. 30 * 31 * <p>We recommend to avoid this class in order to keep dependencies small. 32 * 33 * <ul> 34 * <li>Using this class adds a dependency on protobuf. We hope that eventually it is possible to 35 * use Tink without a dependency on protobuf. 36 * <li>Using this class adds a dependency on classes for all involved key types. 37 * </ul> 38 * 39 * These dependencies all come from static class member variables, which are initialized when the 40 * class is loaded. This implies that static analysis and code minimization tools (such as proguard) 41 * cannot remove the usages either. 42 * 43 * <p>Instead, we recommend to use {@code KeysetHandle.generateEntryFromParametersName} or {@code 44 * KeysetHandle.generateEntryFromParameters}. 45 * 46 * <p>One can use these templates to generate new {@link com.google.crypto.tink.proto.Keyset} with 47 * {@code KeysetHandle}. To generate a new keyset that contains a {@link AesGcmHkdfStreamingKey}, 48 * one can do: 49 * 50 * <pre>{@code 51 * StreamingAeadConfig.register(); 52 * KeysetHandle handle = KeysetHandle.generateNew(StreamingAeadKeyTemplates.AES128_GCM_HKDF_4KB); 53 * StreamingAead ags = handle.getPrimitive(RegistryConfiguration.get(), StreamingAead.class); 54 * }</pre> 55 * 56 * @deprecated Try using our refaster templates to replace them (see 57 * https://github.com/tink-crypto/tink-java/tree/main/tools/refaster). If migration is unclear, 58 * please file an issue on https://github.com/tink-crypto/tink-java. 59 * @since 1.1.0 60 */ 61 @Deprecated 62 public final class StreamingAeadKeyTemplates { 63 /** 64 * A {@link KeyTemplate} that generates new instances of {@link 65 * com.google.crypto.tink.proto.AesCtrHmacStreamingKey} with the following parameters: 66 * 67 * <ul> 68 * <li>Size of the main key: 16 bytes 69 * <li>HKDF algo: HMAC-SHA256 70 * <li>Size of AES-CTR derived keys: 16 bytes 71 * <li>Tag algo: HMAC-SHA256 72 * <li>Tag size: 32 bytes 73 * <li>Ciphertext segment size: 4096 74 * </ul> 75 */ 76 public static final KeyTemplate AES128_CTR_HMAC_SHA256_4KB = 77 createAesCtrHmacStreamingKeyTemplate(16, HashType.SHA256, 16, HashType.SHA256, 32, 4096); 78 79 /** 80 * A {@link KeyTemplate} that generates new instances of {@link 81 * com.google.crypto.tink.proto.AesCtrHmacStreamingKey} with the following parameters: 82 * 83 * <ul> 84 * <li>Size of the main key: 16 bytes 85 * <li>HKDF algo: HMAC-SHA256 86 * <li>Size of AES-CTR derived keys: 16 bytes 87 * <li>Tag algo: HMAC-SHA256 88 * <li>Tag size: 32 bytes 89 * <li>Ciphertext segment size: 1048576 bytes (1 MB) 90 * </ul> 91 */ 92 public static final KeyTemplate AES128_CTR_HMAC_SHA256_1MB = 93 createAesCtrHmacStreamingKeyTemplate(16, HashType.SHA256, 16, HashType.SHA256, 32, 1048576); 94 95 /** 96 * A {@link KeyTemplate} that generates new instances of {@link 97 * com.google.crypto.tink.proto.AesCtrHmacStreamingKey} with the following parameters: 98 * 99 * <ul> 100 * <li>Size of the main key: 32 bytes 101 * <li>HKDF algo: HMAC-SHA256 102 * <li>Size of AES-CTR derived keys: 32 bytes 103 * <li>Tag algo: HMAC-SHA256 104 * <li>Tag size: 32 bytes 105 * <li>Ciphertext segment size: 4096 106 * </ul> 107 */ 108 public static final KeyTemplate AES256_CTR_HMAC_SHA256_4KB = 109 createAesCtrHmacStreamingKeyTemplate(32, HashType.SHA256, 32, HashType.SHA256, 32, 4096); 110 111 /** 112 * A {@link KeyTemplate} that generates new instances of {@link 113 * com.google.crypto.tink.proto.AesCtrHmacStreamingKey} with the following parameters: 114 * 115 * <ul> 116 * <li>Size of the main key: 32 bytes 117 * <li>HKDF algo: HMAC-SHA256 118 * <li>Size of AES-CTR derived keys: 32 bytes 119 * <li>Tag algo: HMAC-SHA256 120 * <li>Tag size: 32 bytes 121 * <li>Ciphertext segment size: 1048576 bytes (1 MB) 122 * </ul> 123 */ 124 public static final KeyTemplate AES256_CTR_HMAC_SHA256_1MB = 125 createAesCtrHmacStreamingKeyTemplate(32, HashType.SHA256, 32, HashType.SHA256, 32, 1048576); 126 127 /** 128 * A {@link KeyTemplate} that generates new instances of {@link 129 * com.google.crypto.tink.proto.AesGcmHkdfStreamingKey} with the following parameters: 130 * 131 * <ul> 132 * <li>Size of the main key: 16 bytes 133 * <li>HKDF algo: HMAC-SHA256 134 * <li>Size of AES-GCM derived keys: 16 bytes 135 * <li>Ciphertext segment size: 4096 bytes 136 * </ul> 137 */ 138 public static final KeyTemplate AES128_GCM_HKDF_4KB = 139 createAesGcmHkdfStreamingKeyTemplate(16, HashType.SHA256, 16, 4096); 140 141 /** 142 * A {@link KeyTemplate} that generates new instances of {@link 143 * com.google.crypto.tink.proto.AesGcmHkdfStreamingKey} with the following parameters: 144 * 145 * <ul> 146 * <li>Size of the main key: 16 bytes 147 * <li>HKDF algo: HMAC-SHA256 148 * <li>Size of AES-GCM derived keys: 16 bytes 149 * <li>Ciphertext segment size: 1048576 bytes (1 MB) 150 * </ul> 151 */ 152 public static final KeyTemplate AES128_GCM_HKDF_1MB = 153 createAesGcmHkdfStreamingKeyTemplate(16, HashType.SHA256, 16, 1048576); 154 155 /** 156 * A {@link KeyTemplate} that generates new instances of {@link 157 * com.google.crypto.tink.proto.AesGcmHkdfStreamingKey} with the following parameters: 158 * 159 * <ul> 160 * <li>Size of the main key: 32 bytes 161 * <li>HKDF algo: HMAC-SHA256 162 * <li>Size of AES-GCM derived keys: 32 bytes 163 * <li>Ciphertext segment size: 4096 bytes 164 * </ul> 165 */ 166 public static final KeyTemplate AES256_GCM_HKDF_4KB = 167 createAesGcmHkdfStreamingKeyTemplate(32, HashType.SHA256, 32, 4096); 168 169 /** 170 * A {@link KeyTemplate} that generates new instances of {@link 171 * com.google.crypto.tink.proto.AesGcmHkdfStreamingKey} with the following parameters: 172 * 173 * <ul> 174 * <li>Size of the main key: 32 bytes 175 * <li>HKDF algo: HMAC-SHA256 176 * <li>Size of AES-GCM derived keys: 32 bytes 177 * <li>Ciphertext segment size: 1048576 bytes (1 MB) 178 * </ul> 179 */ 180 public static final KeyTemplate AES256_GCM_HKDF_1MB = 181 createAesGcmHkdfStreamingKeyTemplate(32, HashType.SHA256, 32, 1048576); 182 183 /** 184 * @return a {@link KeyTemplate} containing a {@link AesCtrHmacStreamingKeyFormat} with some 185 * specified parameters. 186 */ createAesCtrHmacStreamingKeyTemplate( int mainKeySize, HashType hkdfHashType, int derivedKeySize, HashType macHashType, int tagSize, int ciphertextSegmentSize)187 public static KeyTemplate createAesCtrHmacStreamingKeyTemplate( 188 int mainKeySize, 189 HashType hkdfHashType, 190 int derivedKeySize, 191 HashType macHashType, 192 int tagSize, 193 int ciphertextSegmentSize) { 194 HmacParams hmacParams = HmacParams.newBuilder() 195 .setHash(macHashType) 196 .setTagSize(tagSize) 197 .build(); 198 AesCtrHmacStreamingParams params = 199 AesCtrHmacStreamingParams.newBuilder() 200 .setCiphertextSegmentSize(ciphertextSegmentSize) 201 .setDerivedKeySize(derivedKeySize) 202 .setHkdfHashType(hkdfHashType) 203 .setHmacParams(hmacParams) 204 .build(); 205 AesCtrHmacStreamingKeyFormat format = AesCtrHmacStreamingKeyFormat.newBuilder() 206 .setParams(params) 207 .setKeySize(mainKeySize) 208 .build(); 209 return KeyTemplate.newBuilder() 210 .setValue(format.toByteString()) 211 .setTypeUrl(AesCtrHmacStreamingKeyManager.getKeyType()) 212 .setOutputPrefixType(OutputPrefixType.RAW) 213 .build(); 214 } 215 216 /** 217 * @return a {@code KeyTemplate} containing a {@code AesGcmHkdfStreamingKeyFormat} 218 * with some specified parameters. 219 */ createAesGcmHkdfStreamingKeyTemplate( int mainKeySize, HashType hkdfHashType, int derivedKeySize, int ciphertextSegmentSize)220 public static KeyTemplate createAesGcmHkdfStreamingKeyTemplate( 221 int mainKeySize, HashType hkdfHashType, int derivedKeySize, int ciphertextSegmentSize) { 222 AesGcmHkdfStreamingParams keyParams = 223 AesGcmHkdfStreamingParams.newBuilder() 224 .setCiphertextSegmentSize(ciphertextSegmentSize) 225 .setDerivedKeySize(derivedKeySize) 226 .setHkdfHashType(hkdfHashType) 227 .build(); 228 AesGcmHkdfStreamingKeyFormat format = 229 AesGcmHkdfStreamingKeyFormat.newBuilder() 230 .setKeySize(mainKeySize) 231 .setParams(keyParams) 232 .build(); 233 return KeyTemplate.newBuilder() 234 .setValue(format.toByteString()) 235 .setTypeUrl(AesGcmHkdfStreamingKeyManager.getKeyType()) 236 .setOutputPrefixType(OutputPrefixType.RAW) 237 .build(); 238 } 239 StreamingAeadKeyTemplates()240 private StreamingAeadKeyTemplates() {} 241 } 242