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.aead; 18 19 import com.google.crypto.tink.proto.AesCtrHmacAeadKeyFormat; 20 import com.google.crypto.tink.proto.AesCtrKeyFormat; 21 import com.google.crypto.tink.proto.AesCtrParams; 22 import com.google.crypto.tink.proto.AesEaxKeyFormat; 23 import com.google.crypto.tink.proto.AesEaxParams; 24 import com.google.crypto.tink.proto.AesGcmKeyFormat; 25 import com.google.crypto.tink.proto.HashType; 26 import com.google.crypto.tink.proto.HmacKeyFormat; 27 import com.google.crypto.tink.proto.HmacParams; 28 import com.google.crypto.tink.proto.KeyTemplate; 29 import com.google.crypto.tink.proto.KmsEnvelopeAeadKeyFormat; 30 import com.google.crypto.tink.proto.OutputPrefixType; 31 32 /** 33 * Pre-generated {@link KeyTemplate} for {@link com.google.crypto.tink.Aead} keys. 34 * 35 * <p>We recommend to avoid this class to keep dependencies small. 36 * 37 * <ul> 38 * <li>Using this class adds a dependency on protobuf. We hope that eventually it is possible to 39 * use Tink without a dependency on protobuf. 40 * <li>Using this class adds a dependency on classes for all involved key types. 41 * </ul> 42 * 43 * These dependencies all come from static class member variables, which are initialized when the 44 * class is loaded. This implies that static analysis and code minimization tools (such as proguard) 45 * cannot remove the usages either. 46 * 47 * <p>Instead, we recommend to use {@code KeysetHandle.generateEntryFromParametersName} or {@code 48 * KeysetHandle.generateEntryFromParameters}. 49 * 50 * <p>One can use these templates to generate new {@link com.google.crypto.tink.proto.Keyset} with 51 * {@link com.google.crypto.tink.KeysetHandle#generateNew}. To generate a new keyset that contains a 52 * single {@link com.google.crypto.tink.proto.AesGcmKey}, one can do: 53 * 54 * <pre>{@code 55 * AeadConfig.register(); 56 * KeysetHandle handle = KeysetHandle.generateNew(AeadKeyTemplates.AES128_GCM); 57 * Aead aead = handle.getPrimitive(RegistryConfiguration.get(), Aead.class); 58 * }</pre> 59 * 60 * @since 1.0.0 61 */ 62 public final class AeadKeyTemplates { 63 /** 64 * A {@link KeyTemplate} that generates new instances of {@link 65 * com.google.crypto.tink.proto.AesGcmKey} with the following parameters: 66 * 67 * <ul> 68 * <li>Key size: 16 bytes 69 * </ul> 70 * 71 * <p>On Android KitKat (API level 19), the {@link com.google.crypto.tink.Aead} instance generated 72 * by this key template does not support associated data. It might not work at all in older 73 * versions. 74 */ 75 public static final KeyTemplate AES128_GCM = createAesGcmKeyTemplate(16); 76 77 /** 78 * A {@link KeyTemplate} that generates new instances of {@link 79 * com.google.crypto.tink.proto.AesGcmKey} with the following parameters: 80 * 81 * <ul> 82 * <li>Key size: 32 bytes 83 * </ul> 84 * 85 * <p>On Android KitKat (API level 19), the {@link com.google.crypto.tink.Aead} instance generated 86 * by this key template does not support associated data. It might not work at all in older 87 * versions. 88 */ 89 public static final KeyTemplate AES256_GCM = createAesGcmKeyTemplate(32); 90 91 /** 92 * A {@link KeyTemplate} that generates new instances of {@code 93 * com.google.crypto.tink.proto.AesEaxKey} with the following parameters: 94 * 95 * <ul> 96 * <li>Key size: 16 bytes 97 * <li>IV size: 16 bytes 98 * </ul> 99 */ 100 public static final KeyTemplate AES128_EAX = createAesEaxKeyTemplate(16, 16); 101 102 /** 103 * A {@link KeyTemplate} that generates new instances of {@link 104 * com.google.crypto.tink.proto.AesEaxKey} with the following parameters: 105 * 106 * <ul> 107 * <li>Key size: 32 bytes 108 * <li>IV size: 16 bytes 109 * </ul> 110 */ 111 public static final KeyTemplate AES256_EAX = createAesEaxKeyTemplate(32, 16); 112 113 /** 114 * A {@link KeyTemplate} that generates new instances of {@link 115 * com.google.crypto.tink.proto.AesCtrHmacAeadKey} with the following parameters: 116 * 117 * <ul> 118 * <li>AES key size: 16 bytes 119 * <li>AES CTR IV size: 16 byte 120 * <li>HMAC key size: 32 bytes 121 * <li>HMAC tag size: 16 bytes 122 * <li>HMAC hash function: SHA256 123 * </ul> 124 */ 125 public static final KeyTemplate AES128_CTR_HMAC_SHA256 = 126 createAesCtrHmacAeadKeyTemplate(16, 16, 32, 16, HashType.SHA256); 127 128 /** 129 * A {@link KeyTemplate} that generates new instances of {@link 130 * com.google.crypto.tink.proto.AesCtrHmacAeadKey} with the following parameters: 131 * 132 * <ul> 133 * <li>AES key size: 32 bytes 134 * <li>AES CTR IV size: 16 byte 135 * <li>HMAC key size: 32 bytes 136 * <li>HMAC tag size: 32 bytes 137 * <li>HMAC hash function: SHA256 138 * </ul> 139 */ 140 public static final KeyTemplate AES256_CTR_HMAC_SHA256 = 141 createAesCtrHmacAeadKeyTemplate(32, 16, 32, 32, HashType.SHA256); 142 143 /** 144 * A {@link KeyTemplate} that generates new instances of {@link 145 * com.google.crypto.tink.proto.ChaCha20Poly1305Key}. 146 * 147 * @since 1.1.0 148 */ 149 public static final KeyTemplate CHACHA20_POLY1305 = 150 KeyTemplate.newBuilder() 151 .setTypeUrl(ChaCha20Poly1305KeyManager.getKeyType()) 152 .setOutputPrefixType(OutputPrefixType.TINK) 153 .build(); 154 155 /** 156 * A {@link KeyTemplate} that generates new instances of {@link 157 * com.google.crypto.tink.proto.XChaCha20Poly1305Key}. 158 * 159 * @since 1.3.0 160 */ 161 public static final KeyTemplate XCHACHA20_POLY1305 = 162 KeyTemplate.newBuilder() 163 .setTypeUrl(XChaCha20Poly1305KeyManager.getKeyType()) 164 .setOutputPrefixType(OutputPrefixType.TINK) 165 .build(); 166 167 /** 168 * @return a {@link KeyTemplate} containing a {@link AesGcmKeyFormat} with some specified 169 * parameters. 170 */ createAesGcmKeyTemplate(int keySize)171 public static KeyTemplate createAesGcmKeyTemplate(int keySize) { 172 AesGcmKeyFormat format = AesGcmKeyFormat.newBuilder() 173 .setKeySize(keySize) 174 .build(); 175 return KeyTemplate.newBuilder() 176 .setValue(format.toByteString()) 177 .setTypeUrl(AesGcmKeyManager.getKeyType()) 178 .setOutputPrefixType(OutputPrefixType.TINK) 179 .build(); 180 } 181 182 /** 183 * @return a {@link KeyTemplate} containing a {@link AesEaxKeyFormat} with some specified 184 * parameters. 185 */ createAesEaxKeyTemplate(int keySize, int ivSize)186 public static KeyTemplate createAesEaxKeyTemplate(int keySize, int ivSize) { 187 AesEaxKeyFormat format = AesEaxKeyFormat.newBuilder() 188 .setKeySize(keySize) 189 .setParams(AesEaxParams.newBuilder().setIvSize(ivSize).build()) 190 .build(); 191 return KeyTemplate.newBuilder() 192 .setValue(format.toByteString()) 193 .setTypeUrl(AesEaxKeyManager.getKeyType()) 194 .setOutputPrefixType(OutputPrefixType.TINK) 195 .build(); 196 } 197 198 /** 199 * @return a {@link KeyTemplate} containing a {@link AesCtrHmacAeadKeyFormat} with some specific 200 * parameters. 201 */ createAesCtrHmacAeadKeyTemplate( int aesKeySize, int ivSize, int hmacKeySize, int tagSize, HashType hashType)202 public static KeyTemplate createAesCtrHmacAeadKeyTemplate( 203 int aesKeySize, int ivSize, int hmacKeySize, int tagSize, HashType hashType) { 204 AesCtrKeyFormat aesCtrKeyFormat = AesCtrKeyFormat.newBuilder() 205 .setParams(AesCtrParams.newBuilder().setIvSize(ivSize).build()) 206 .setKeySize(aesKeySize) 207 .build(); 208 HmacKeyFormat hmacKeyFormat = HmacKeyFormat.newBuilder() 209 .setParams( 210 HmacParams.newBuilder().setHash(hashType).setTagSize(tagSize).build()) 211 .setKeySize(hmacKeySize) 212 .build(); 213 AesCtrHmacAeadKeyFormat format = AesCtrHmacAeadKeyFormat.newBuilder() 214 .setAesCtrKeyFormat(aesCtrKeyFormat) 215 .setHmacKeyFormat(hmacKeyFormat) 216 .build(); 217 return KeyTemplate.newBuilder() 218 .setValue(format.toByteString()) 219 .setTypeUrl(AesCtrHmacAeadKeyManager.getKeyType()) 220 .setOutputPrefixType(OutputPrefixType.TINK) 221 .build(); 222 } 223 224 /** 225 * Returns a new {@link KeyTemplate} that can generate a {@link 226 * com.google.crypto.tink.proto.KmsEnvelopeAeadKey} whose key encrypting key (KEK) is pointing to 227 * {@code kekUri} and DEK template is {@code dekTemplate}. Keys generated by this key template 228 * uses RAW output prefix to make them compatible with the remote KMS' encrypt/decrypt operations. 229 * Unlike other templates, when you generate new keys with this template, Tink does not generate 230 * new key material, but only creates a reference to the remote KEK. 231 */ createKmsEnvelopeAeadKeyTemplate( String kekUri, KeyTemplate dekTemplate)232 public static KeyTemplate createKmsEnvelopeAeadKeyTemplate( 233 String kekUri, KeyTemplate dekTemplate) { 234 KmsEnvelopeAeadKeyFormat format = KmsEnvelopeAeadKeyFormat.newBuilder() 235 .setDekTemplate(dekTemplate) 236 .setKekUri(kekUri) 237 .build(); 238 return KeyTemplate.newBuilder() 239 .setValue(format.toByteString()) 240 .setTypeUrl(KmsEnvelopeAeadKeyManager.getKeyType()) 241 .setOutputPrefixType(OutputPrefixType.RAW) 242 .build(); 243 } 244 AeadKeyTemplates()245 private AeadKeyTemplates() {} 246 } 247