xref: /aosp_15_r20/external/tink/python/tink/streaming_aead/_streaming_aead_key_templates.py (revision e7b1675dde1b92d52ec075b0a92829627f2c52a5) 
1# Copyright 2020 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"""Pre-generated KeyTemplates for StreamingAead.
15
16
17Currently, these templates cannot be used to generate keysets, but they can be
18used to generate individual keys.
19In the future, it will be possible to use these templates to generate a new
20tink_pb2.Keyset with tink_pb2.KeysetHandle. To generate a new keyset that
21contains a single aes_ctr_hmac_streaming_pb2.AesCtrHmacStreamingKey, one can do:
22handle = keyset_handle.KeysetHandle(
23  streaming_aead_key_templates.AES256_CTR_HMAC_SHA256_4KB).
24"""
25
26import warnings
27
28from tink.proto import aes_ctr_hmac_streaming_pb2
29from tink.proto import aes_gcm_hkdf_streaming_pb2
30from tink.proto import common_pb2
31from tink.proto import tink_pb2
32
33_AES_GCM_HKDF_STREAMING_KEY_TYPE_URL = (
34    'type.googleapis.com/google.crypto.tink.AesGcmHkdfStreamingKey')
35_AES_CTR_HMAC_STREAMING_KEY_TYPE_URL = (
36    'type.googleapis.com/google.crypto.tink.AesCtrHmacStreamingKey')
37SEGMENT_SIZE_1MB = 1024 * 1024
38SEGMENT_SIZE_4KB = 4 * 1024
39
40
41def _create_aes_gcm_hkdf_streaming_key_template(
42    aes_key_size: int, hash_type: common_pb2.HashType, derived_key_size: int,
43    ciphertext_segment_size: int) -> tink_pb2.KeyTemplate:
44  """Creates an AES GCM HKDF Streaming KeyTemplate, and fills in its values."""
45  key_format = aes_gcm_hkdf_streaming_pb2.AesGcmHkdfStreamingKeyFormat()
46  key_format.key_size = aes_key_size
47  key_format.params.hkdf_hash_type = hash_type
48  key_format.params.derived_key_size = derived_key_size
49  key_format.params.ciphertext_segment_size = ciphertext_segment_size
50
51  key_template = tink_pb2.KeyTemplate(
52      value=key_format.SerializeToString(),
53      type_url=_AES_GCM_HKDF_STREAMING_KEY_TYPE_URL,
54      output_prefix_type=tink_pb2.RAW,
55  )
56  return key_template
57
58
59def _create_aes_ctr_hmac_streaming_key_template(
60    aes_key_size: int, hkdf_hash_type: common_pb2.HashType,
61    derived_key_size: int, mac_hash_type: common_pb2.HashType, tag_size: int,
62    ciphertext_segment_size: int) -> tink_pb2.KeyTemplate:
63  """Creates an AES CTR HMAC Streaming KeyTemplate, and fills in its values."""
64  key_format = aes_ctr_hmac_streaming_pb2.AesCtrHmacStreamingKeyFormat()
65  key_format.key_size = aes_key_size
66
67  key_format.params.ciphertext_segment_size = ciphertext_segment_size
68  key_format.params.derived_key_size = derived_key_size
69  key_format.params.hkdf_hash_type = hkdf_hash_type
70
71  key_format.params.hmac_params.hash = mac_hash_type
72  key_format.params.hmac_params.tag_size = tag_size
73
74  key_template = tink_pb2.KeyTemplate(
75      value=key_format.SerializeToString(),
76      type_url=_AES_CTR_HMAC_STREAMING_KEY_TYPE_URL,
77      output_prefix_type=tink_pb2.RAW,
78  )
79  return key_template
80
81
82AES128_GCM_HKDF_4KB = _create_aes_gcm_hkdf_streaming_key_template(
83    aes_key_size=16,
84    hash_type=common_pb2.HashType.SHA256,
85    derived_key_size=16,
86    ciphertext_segment_size=SEGMENT_SIZE_4KB)
87
88AES128_GCM_HKDF_1MB = _create_aes_gcm_hkdf_streaming_key_template(
89    aes_key_size=16,
90    hash_type=common_pb2.HashType.SHA256,
91    derived_key_size=16,
92    ciphertext_segment_size=SEGMENT_SIZE_1MB)
93
94AES256_GCM_HKDF_4KB = _create_aes_gcm_hkdf_streaming_key_template(
95    aes_key_size=32,
96    hash_type=common_pb2.HashType.SHA256,
97    derived_key_size=32,
98    ciphertext_segment_size=SEGMENT_SIZE_4KB)
99
100AES256_GCM_HKDF_1MB = _create_aes_gcm_hkdf_streaming_key_template(
101    aes_key_size=32,
102    hash_type=common_pb2.HashType.SHA256,
103    derived_key_size=32,
104    ciphertext_segment_size=SEGMENT_SIZE_1MB)
105
106AES128_CTR_HMAC_SHA256_4KB = _create_aes_ctr_hmac_streaming_key_template(
107    aes_key_size=16,
108    hkdf_hash_type=common_pb2.HashType.SHA256,
109    derived_key_size=16,
110    mac_hash_type=common_pb2.HashType.SHA256,
111    tag_size=32,
112    ciphertext_segment_size=SEGMENT_SIZE_4KB)
113
114AES128_CTR_HMAC_SHA256_1MB = _create_aes_ctr_hmac_streaming_key_template(
115    aes_key_size=16,
116    hkdf_hash_type=common_pb2.HashType.SHA256,
117    derived_key_size=16,
118    mac_hash_type=common_pb2.HashType.SHA256,
119    tag_size=32,
120    ciphertext_segment_size=SEGMENT_SIZE_1MB)
121
122AES256_CTR_HMAC_SHA256_4KB = _create_aes_ctr_hmac_streaming_key_template(
123    aes_key_size=32,
124    hkdf_hash_type=common_pb2.HashType.SHA256,
125    derived_key_size=32,
126    mac_hash_type=common_pb2.HashType.SHA256,
127    tag_size=32,
128    ciphertext_segment_size=SEGMENT_SIZE_4KB)
129
130AES256_CTR_HMAC_SHA256_1MB = _create_aes_ctr_hmac_streaming_key_template(
131    aes_key_size=32,
132    hkdf_hash_type=common_pb2.HashType.SHA256,
133    derived_key_size=32,
134    mac_hash_type=common_pb2.HashType.SHA256,
135    tag_size=32,
136    ciphertext_segment_size=SEGMENT_SIZE_1MB)
137
138
139# Deprecated. Use the predefined constant templates above instead.
140def create_aes_gcm_hkdf_streaming_key_template(
141    aes_key_size: int, hash_type: common_pb2.HashType, derived_key_size: int,
142    ciphertext_segment_size: int) -> tink_pb2.KeyTemplate:
143  warnings.warn(
144      'The create_aes_gcm_hkdf_streaming_key_template function is deprecated.',
145      DeprecationWarning, 2)
146  return _create_aes_gcm_hkdf_streaming_key_template(aes_key_size, hash_type,
147                                                     derived_key_size,
148                                                     ciphertext_segment_size)
149
150
151# Deprecated. Use the predefined constant templates above instead.
152def create_aes_ctr_hmac_streaming_key_template(
153    aes_key_size: int, hkdf_hash_type: common_pb2.HashType,
154    derived_key_size: int, mac_hash_type: common_pb2.HashType, tag_size: int,
155    ciphertext_segment_size: int) -> tink_pb2.KeyTemplate:
156  warnings.warn(
157      'The create_aes_ctr_hmac_streaming_key_template function is deprecated.',
158      DeprecationWarning, 2)
159  return _create_aes_ctr_hmac_streaming_key_template(aes_key_size,
160                                                     hkdf_hash_type,
161                                                     derived_key_size,
162                                                     mac_hash_type, tag_size,
163                                                     ciphertext_segment_size)
164