1 // Copyright 2023 Google LLC 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 static com.google.crypto.tink.internal.TinkBugException.exceptionIsBug; 20 21 22 /** 23 * Pre-generated {@link com.google.crypto.tink.Parameters} objects for creating new instances of 24 * {@link AeadKey}. 25 * 26 * <p>Note: if you want to keep dependencies small, consider inlining the constants here. 27 */ 28 public final class PredefinedAeadParameters { 29 /** 30 * A {@link com.google.crypto.tink.Parameters} object for generating new instances of {@link 31 * AesGcmKey} with the following parameters: 32 * 33 * <ul> 34 * <li>Key size: 16 bytes 35 * </ul> 36 * 37 * <p>On Android KitKat (API level 19), the {@link com.google.crypto.tink.Aead} instance generated 38 * by this key template does not support associated data. It might not work at all in older 39 * versions. 40 */ 41 public static final AesGcmParameters AES128_GCM = 42 exceptionIsBug( 43 () -> 44 AesGcmParameters.builder() 45 .setIvSizeBytes(12) 46 .setKeySizeBytes(16) 47 .setTagSizeBytes(16) 48 .setVariant(AesGcmParameters.Variant.TINK) 49 .build()); 50 51 /** 52 * A {@link com.google.crypto.tink.Parameters} object for generating new instances of {@link 53 * AesGcmKey} with the following parameters: 54 * 55 * <ul> 56 * <li>Key size: 32 bytes 57 * </ul> 58 * 59 * <p>On Android KitKat (API level 19), the {@link com.google.crypto.tink.Aead} instance generated 60 * by this key template does not support associated data. It might not work at all in older 61 * versions. 62 */ 63 public static final AesGcmParameters AES256_GCM = 64 exceptionIsBug( 65 () -> 66 AesGcmParameters.builder() 67 .setIvSizeBytes(12) 68 .setKeySizeBytes(32) 69 .setTagSizeBytes(16) 70 .setVariant(AesGcmParameters.Variant.TINK) 71 .build()); 72 73 /** 74 * A {@link com.google.crypto.tink.Parameters} object for generating new instances of {@link 75 * AesEaxKey} with the following parameters: 76 * 77 * <ul> 78 * <li>Key size: 16 bytes 79 * <li>IV size: 16 bytes 80 * </ul> 81 */ 82 public static final AesEaxParameters AES128_EAX = 83 exceptionIsBug( 84 () -> 85 AesEaxParameters.builder() 86 .setIvSizeBytes(16) 87 .setKeySizeBytes(16) 88 .setTagSizeBytes(16) 89 .setVariant(AesEaxParameters.Variant.TINK) 90 .build()); 91 92 /** 93 * A {@link com.google.crypto.tink.Parameters} object for generating new instances of {@link 94 * AesEaxKey} with the following parameters: 95 * 96 * <ul> 97 * <li>Key size: 32 bytes 98 * <li>IV size: 16 bytes 99 * </ul> 100 */ 101 public static final AesEaxParameters AES256_EAX = 102 exceptionIsBug( 103 () -> 104 AesEaxParameters.builder() 105 .setIvSizeBytes(16) 106 .setKeySizeBytes(32) 107 .setTagSizeBytes(16) 108 .setVariant(AesEaxParameters.Variant.TINK) 109 .build()); 110 111 /** 112 * A {@link com.google.crypto.tink.Parameters} object for generating new instances of {@link 113 * AesCtrHmacAeadKey} with the following parameters: 114 * 115 * <ul> 116 * <li>AES key size: 16 bytes 117 * <li>AES CTR IV size: 16 byte 118 * <li>HMAC key size: 32 bytes 119 * <li>HMAC tag size: 16 bytes 120 * <li>HMAC hash function: SHA256 121 * </ul> 122 */ 123 public static final AesCtrHmacAeadParameters AES128_CTR_HMAC_SHA256 = 124 exceptionIsBug( 125 () -> 126 AesCtrHmacAeadParameters.builder() 127 .setAesKeySizeBytes(16) 128 .setHmacKeySizeBytes(32) 129 .setTagSizeBytes(16) 130 .setIvSizeBytes(16) 131 .setHashType(AesCtrHmacAeadParameters.HashType.SHA256) 132 .setVariant(AesCtrHmacAeadParameters.Variant.TINK) 133 .build()); 134 135 /** 136 * A {@link com.google.crypto.tink.Parameters} object for generating new instances of {@link 137 * AesCtrHmacAeadKey} with the following parameters: 138 * 139 * <ul> 140 * <li>AES key size: 32 bytes 141 * <li>AES CTR IV size: 16 byte 142 * <li>HMAC key size: 32 bytes 143 * <li>HMAC tag size: 32 bytes 144 * <li>HMAC hash function: SHA256 145 * </ul> 146 */ 147 public static final AesCtrHmacAeadParameters AES256_CTR_HMAC_SHA256 = 148 exceptionIsBug( 149 () -> 150 AesCtrHmacAeadParameters.builder() 151 .setAesKeySizeBytes(32) 152 .setHmacKeySizeBytes(32) 153 .setTagSizeBytes(32) 154 .setIvSizeBytes(16) 155 .setHashType(AesCtrHmacAeadParameters.HashType.SHA256) 156 .setVariant(AesCtrHmacAeadParameters.Variant.TINK) 157 .build()); 158 159 /** 160 * A {@link com.google.crypto.tink.Parameters} object that generates new instances of {@link 161 * ChaCha20Poly1305Key}. 162 */ 163 public static final ChaCha20Poly1305Parameters CHACHA20_POLY1305 = 164 ChaCha20Poly1305Parameters.create(ChaCha20Poly1305Parameters.Variant.TINK); 165 166 /** 167 * A {@link com.google.crypto.tink.Parameters} object that generates new instances of {@link 168 * XChaCha20Poly1305Key}. 169 */ 170 public static final XChaCha20Poly1305Parameters XCHACHA20_POLY1305 = 171 XChaCha20Poly1305Parameters.create(XChaCha20Poly1305Parameters.Variant.TINK); 172 173 /** 174 * A {@link com.google.crypto.tink.Parameters} object for generating new instances of {@link 175 * XAesGcmKey}. This follows the algorithm defined in the <a 176 * href="https://github.com/C2SP/C2SP/blob/main/XAES-256-GCM.md">XAES-256-GCM specification</a> 177 * 178 * <ul> 179 * <li>Key size: 32 bytes 180 * <li>Nonce size: 24 bytes (12 bytes of salt, 12 bytes of AES-GCM IV) 181 * <li>Salt size: 12 bytes 182 * <li>Tag size: 16 bytes 183 * <li>Output prefix: TINK 184 * </ul> 185 */ 186 public static final XAesGcmParameters XAES_256_GCM_192_BIT_NONCE = 187 exceptionIsBug( 188 () -> XAesGcmParameters.create(XAesGcmParameters.Variant.TINK, /* saltSizeBytes= */ 12)); 189 190 /** 191 * A {@link com.google.crypto.tink.Parameters} object for generating new instances of {@link 192 * XAesGcmKey}. This follows the algorithm defined in the <a 193 * href="https://github.com/C2SP/C2SP/blob/main/XAES-256-GCM.md">XAES-256-GCM specification</a> 194 * 195 * <ul> 196 * <li>Key size: 32 bytes 197 * <li>Nonce size: 24 bytes (12 bytes of salt, 12 bytes of AES-GCM IV) 198 * <li>Salt size: 12 bytes 199 * <li>Tag size: 16 bytes 200 * <li>Output prefix: NO_PREFIX 201 * </ul> 202 */ 203 public static final XAesGcmParameters XAES_256_GCM_192_BIT_NONCE_NO_PREFIX = 204 exceptionIsBug( 205 () -> 206 XAesGcmParameters.create( 207 XAesGcmParameters.Variant.NO_PREFIX, /* saltSizeBytes= */ 12)); 208 209 /** 210 * A {@link com.google.crypto.tink.Parameters} object for generating new instances of {@link 211 * XAesGcmKey}. This follows the algorithm defined in the <a 212 * href="https://github.com/C2SP/C2SP/blob/main/XAES-256-GCM.md">XAES-256-GCM specification</a>, 213 * except that the nonce size is 160 bits instead of 192 bits. The remaining 4 bytes are padded 214 * with zeros. 215 * 216 * <ul> 217 * <li>Key size: 32 bytes 218 * <li>Nonce size: 20 bytes (8 bytes of salt, 12 bytes of AES-GCM IV) 219 * <li>Salt size: 8 bytes 220 * <li>Tag size: 16 bytes 221 * <li>Output prefix: NO_PREFIX 222 * </ul> 223 */ 224 public static final XAesGcmParameters XAES_256_GCM_160_BIT_NONCE_NO_PREFIX = 225 exceptionIsBug( 226 () -> 227 XAesGcmParameters.create( 228 XAesGcmParameters.Variant.NO_PREFIX, /* saltSizeBytes= */ 8)); 229 230 /** 231 * @deprecated Use {@link #XAES_256_GCM_160_BIT_NONCE_NO_PREFIX} instead. 232 */ 233 @Deprecated 234 public static final XAesGcmParameters X_AES_GCM_8_BYTE_SALT_NO_PREFIX = 235 XAES_256_GCM_160_BIT_NONCE_NO_PREFIX; 236 PredefinedAeadParameters()237 private PredefinedAeadParameters() {} 238 } 239