1# Copyright 2019 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"""Pre-generated KeyTemplate for Aead. 16 17One can use these templates to generate a new tink_pb2.Keyset with 18tink_pb2.KeysetHandle. To generate a new keyset that contains a single 19aes_eax_pb2.AesEaxKey, one can do: 20handle = keyset_handle.KeysetHandle(aead_key_templates.AES128_EAX). 21""" 22 23import warnings 24 25from tink.proto import aes_ctr_hmac_aead_pb2 26from tink.proto import aes_eax_pb2 27from tink.proto import aes_gcm_pb2 28from tink.proto import aes_gcm_siv_pb2 29from tink.proto import common_pb2 30from tink.proto import kms_aead_pb2 31from tink.proto import kms_envelope_pb2 32from tink.proto import tink_pb2 33 34_AES_EAX_KEY_TYPE_URL = 'type.googleapis.com/google.crypto.tink.AesEaxKey' 35_AES_GCM_KEY_TYPE_URL = 'type.googleapis.com/google.crypto.tink.AesGcmKey' 36_AES_GCM_SIV_KEY_TYPE_URL = ( 37 'type.googleapis.com/google.crypto.tink.AesGcmSivKey') 38_AES_CTR_HMAC_AEAD_KEY_TYPE_URL = ( 39 'type.googleapis.com/google.crypto.tink.AesCtrHmacAeadKey') 40_XCHACHA20_POLY1305_KEY_TYPE_URL = ( 41 'type.googleapis.com/google.crypto.tink.XChaCha20Poly1305Key') 42_KMS_AEAD_KEY_TYPE_URL = ( 43 'type.googleapis.com/google.crypto.tink.KmsAeadKey') 44_KMS_ENVELOPE_AEAD_KEY_TYPE_URL = ( 45 'type.googleapis.com/google.crypto.tink.KmsEnvelopeAeadKey') 46 47 48def _create_aes_eax_key_template( 49 key_size: int, 50 iv_size: int, 51 output_prefix_type: tink_pb2.OutputPrefixType = tink_pb2.TINK 52) -> tink_pb2.KeyTemplate: 53 """Creates an AES EAX KeyTemplate, and fills in its values.""" 54 key_format = aes_eax_pb2.AesEaxKeyFormat() 55 key_format.params.iv_size = iv_size 56 key_format.key_size = key_size 57 key_template = tink_pb2.KeyTemplate( 58 value=key_format.SerializeToString(), 59 type_url=_AES_EAX_KEY_TYPE_URL, 60 output_prefix_type=output_prefix_type, 61 ) 62 return key_template 63 64 65def _create_aes_gcm_key_template( 66 key_size: int, 67 output_prefix_type: tink_pb2.OutputPrefixType = tink_pb2.TINK 68) -> tink_pb2.KeyTemplate: 69 """Creates an AES GCM KeyTemplate, and fills in its values.""" 70 key_format = aes_gcm_pb2.AesGcmKeyFormat(key_size=key_size) 71 key_template = tink_pb2.KeyTemplate( 72 value=key_format.SerializeToString(), 73 type_url=_AES_GCM_KEY_TYPE_URL, 74 output_prefix_type=output_prefix_type, 75 ) 76 return key_template 77 78 79def _create_aes_gcm_siv_key_template( 80 key_size: int, 81 output_prefix_type: tink_pb2.OutputPrefixType = tink_pb2.TINK 82) -> tink_pb2.KeyTemplate: 83 """Creates an AES GCM SIV KeyTemplate, and fills in its values.""" 84 key_format = aes_gcm_siv_pb2.AesGcmSivKeyFormat( 85 key_size=key_size, 86 ) 87 key_template = tink_pb2.KeyTemplate( 88 value=key_format.SerializeToString(), 89 type_url=_AES_GCM_SIV_KEY_TYPE_URL, 90 output_prefix_type=output_prefix_type, 91 ) 92 return key_template 93 94 95def _create_aes_ctr_hmac_aead_key_template( 96 aes_key_size: int, 97 iv_size: int, 98 hmac_key_size: int, 99 tag_size: int, 100 hash_type: common_pb2.HashType, 101 output_prefix_type: tink_pb2.OutputPrefixType = tink_pb2.TINK 102) -> tink_pb2.KeyTemplate: 103 """Creates an AES CTR HMAC AEAD KeyTemplate, and fills in its values.""" 104 key_format = aes_ctr_hmac_aead_pb2.AesCtrHmacAeadKeyFormat() 105 key_format.aes_ctr_key_format.params.iv_size = iv_size 106 key_format.aes_ctr_key_format.key_size = aes_key_size 107 key_format.hmac_key_format.params.hash = hash_type 108 key_format.hmac_key_format.params.tag_size = tag_size 109 key_format.hmac_key_format.key_size = hmac_key_size 110 key_template = tink_pb2.KeyTemplate( 111 value=key_format.SerializeToString(), 112 type_url=_AES_CTR_HMAC_AEAD_KEY_TYPE_URL, 113 output_prefix_type=output_prefix_type, 114 ) 115 return key_template 116 117 118def create_kms_aead_key_template(key_uri: str) -> tink_pb2.KeyTemplate: 119 """Creates a KMS AEAD KeyTemplate from a KEK URI. 120 121 Keys generated by this key template uses RAW output prefix to make them 122 compatible with the remote KMS' encrypt/decrypt operations. Unlike other 123 templates, when you generate new keys with this template, Tink does not 124 generate new key material, but only creates a reference to the remote KEK. 125 126 Args: 127 key_uri: Text. The remote key URI. 128 Returns: 129 A KMS Aead KeyTemplate. 130 """ 131 key_format = kms_aead_pb2.KmsAeadKeyFormat(key_uri=key_uri) 132 key_template = tink_pb2.KeyTemplate( 133 value=key_format.SerializeToString(), 134 type_url=_KMS_AEAD_KEY_TYPE_URL, 135 output_prefix_type=tink_pb2.RAW, 136 ) 137 return key_template 138 139 140def create_kms_envelope_aead_key_template( 141 kek_uri: str, dek_template: tink_pb2.KeyTemplate) -> tink_pb2.KeyTemplate: 142 """Creates a KMS Envelope AEAD key template from a KEK URI and a DEK template. 143 144 Keys generated by this key template uses RAW output prefix to make them 145 compatible with the remote KMS' encrypt/decrypt operations. Unlike other 146 templates, when you generate new keys with this template, Tink does not 147 generate new key material, but only creates a reference to the remote KEK. 148 149 Args: 150 kek_uri: Text. The URI of the KEK that resides in an external KMS. 151 dek_template: tink_pb2.KeyTemplate. The template of the DEK. 152 Returns: 153 the resulting key template 154 """ 155 key_format = kms_envelope_pb2.KmsEnvelopeAeadKeyFormat( 156 kek_uri=kek_uri, dek_template=dek_template 157 ) 158 key_template = tink_pb2.KeyTemplate( 159 value=key_format.SerializeToString(), 160 type_url=_KMS_ENVELOPE_AEAD_KEY_TYPE_URL, 161 output_prefix_type=tink_pb2.RAW, 162 ) 163 return key_template 164 165 166AES128_EAX = _create_aes_eax_key_template(key_size=16, iv_size=16) 167AES128_EAX_RAW = _create_aes_eax_key_template( 168 key_size=16, iv_size=16, output_prefix_type=tink_pb2.RAW) 169AES256_EAX = _create_aes_eax_key_template(key_size=32, iv_size=16) 170AES256_EAX_RAW = _create_aes_eax_key_template( 171 key_size=32, iv_size=16, output_prefix_type=tink_pb2.RAW) 172AES128_GCM = _create_aes_gcm_key_template(key_size=16) 173AES128_GCM_RAW = _create_aes_gcm_key_template( 174 key_size=16, output_prefix_type=tink_pb2.RAW) 175AES256_GCM = _create_aes_gcm_key_template(key_size=32) 176AES256_GCM_RAW = _create_aes_gcm_key_template( 177 key_size=32, output_prefix_type=tink_pb2.RAW) 178AES128_GCM_SIV = _create_aes_gcm_siv_key_template(key_size=16) 179AES128_GCM_SIV_RAW = _create_aes_gcm_siv_key_template( 180 key_size=16, output_prefix_type=tink_pb2.RAW) 181AES256_GCM_SIV = _create_aes_gcm_siv_key_template(key_size=32) 182AES256_GCM_SIV_RAW = _create_aes_gcm_siv_key_template( 183 key_size=32, output_prefix_type=tink_pb2.RAW) 184AES128_CTR_HMAC_SHA256 = _create_aes_ctr_hmac_aead_key_template( 185 aes_key_size=16, 186 iv_size=16, 187 hmac_key_size=32, 188 tag_size=16, 189 hash_type=common_pb2.SHA256) 190AES128_CTR_HMAC_SHA256_RAW = _create_aes_ctr_hmac_aead_key_template( 191 aes_key_size=16, 192 iv_size=16, 193 hmac_key_size=32, 194 tag_size=16, 195 hash_type=common_pb2.SHA256, 196 output_prefix_type=tink_pb2.RAW) 197AES256_CTR_HMAC_SHA256 = _create_aes_ctr_hmac_aead_key_template( 198 aes_key_size=32, 199 iv_size=16, 200 hmac_key_size=32, 201 tag_size=32, 202 hash_type=common_pb2.SHA256) 203AES256_CTR_HMAC_SHA256_RAW = _create_aes_ctr_hmac_aead_key_template( 204 aes_key_size=32, 205 iv_size=16, 206 hmac_key_size=32, 207 tag_size=32, 208 hash_type=common_pb2.SHA256, 209 output_prefix_type=tink_pb2.RAW) 210XCHACHA20_POLY1305 = tink_pb2.KeyTemplate( 211 type_url=_XCHACHA20_POLY1305_KEY_TYPE_URL, 212 output_prefix_type=tink_pb2.TINK) 213XCHACHA20_POLY1305_RAW = tink_pb2.KeyTemplate( 214 type_url=_XCHACHA20_POLY1305_KEY_TYPE_URL, output_prefix_type=tink_pb2.RAW) 215 216 217# Deprecated. Use the predefined constant templates above instead. 218def create_aes_eax_key_template( 219 key_size: int, 220 iv_size: int, 221 output_prefix_type: tink_pb2.OutputPrefixType = tink_pb2.TINK 222) -> tink_pb2.KeyTemplate: 223 warnings.warn('The "create_aes_eax_key_template" function is deprecated.', 224 DeprecationWarning, 2) 225 return _create_aes_eax_key_template(key_size, iv_size, output_prefix_type) 226 227 228# Deprecated. Use the predefined constant templates above instead. 229def create_aes_gcm_key_template( 230 key_size: int, 231 output_prefix_type: tink_pb2.OutputPrefixType = tink_pb2.TINK 232) -> tink_pb2.KeyTemplate: 233 warnings.warn('The "create_aes_gcm_key_template" function is deprecated.', 234 DeprecationWarning, 2) 235 return _create_aes_gcm_key_template(key_size, output_prefix_type) 236 237 238# Deprecated. Use the predefined constant templates above instead. 239def create_aes_gcm_siv_key_template( 240 key_size: int, 241 output_prefix_type: tink_pb2.OutputPrefixType = tink_pb2.TINK 242) -> tink_pb2.KeyTemplate: 243 warnings.warn('The "create_aes_gcm_siv_key_template" function is deprecated.', 244 DeprecationWarning, 2) 245 return _create_aes_gcm_siv_key_template(key_size, output_prefix_type) 246 247 248# Deprecated. Use the predefined constant templates above instead. 249def create_aes_ctr_hmac_aead_key_template( 250 aes_key_size: int, 251 iv_size: int, 252 hmac_key_size: int, 253 tag_size: int, 254 hash_type: common_pb2.HashType, 255 output_prefix_type: tink_pb2.OutputPrefixType = tink_pb2.TINK 256) -> tink_pb2.KeyTemplate: 257 """Creates AesCtrHmacAeadKey template.""" 258 warnings.warn( 259 'The "create_aes_ctr_hmac_aead_key_template" function is deprecated.', 260 DeprecationWarning, 2) 261 return _create_aes_ctr_hmac_aead_key_template(aes_key_size, iv_size, 262 hmac_key_size, tag_size, 263 hash_type, output_prefix_type) 264