1"""Knowledge about cryptographic mechanisms implemented in Mbed TLS. 2 3This module is entirely based on the PSA API. 4""" 5 6# Copyright The Mbed TLS Contributors 7# SPDX-License-Identifier: Apache-2.0 8# 9# Licensed under the Apache License, Version 2.0 (the "License"); you may 10# not use this file except in compliance with the License. 11# You may obtain a copy of the License at 12# 13# http://www.apache.org/licenses/LICENSE-2.0 14# 15# Unless required by applicable law or agreed to in writing, software 16# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 17# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 18# See the License for the specific language governing permissions and 19# limitations under the License. 20 21import re 22from typing import Dict, Iterable, Optional, Pattern, Tuple 23 24from mbedtls_dev.asymmetric_key_data import ASYMMETRIC_KEY_DATA 25 26class KeyType: 27 """Knowledge about a PSA key type.""" 28 29 def __init__(self, name: str, params: Optional[Iterable[str]] = None): 30 """Analyze a key type. 31 32 The key type must be specified in PSA syntax. In its simplest form, 33 `name` is a string 'PSA_KEY_TYPE_xxx' which is the name of a PSA key 34 type macro. For key types that take arguments, the arguments can 35 be passed either through the optional argument `params` or by 36 passing an expression of the form 'PSA_KEY_TYPE_xxx(param1, ...)' 37 in `name` as a string. 38 """ 39 40 self.name = name.strip() 41 """The key type macro name (``PSA_KEY_TYPE_xxx``). 42 43 For key types constructed from a macro with arguments, this is the 44 name of the macro, and the arguments are in `self.params`. 45 """ 46 if params is None: 47 if '(' in self.name: 48 m = re.match(r'(\w+)\s*\((.*)\)\Z', self.name) 49 assert m is not None 50 self.name = m.group(1) 51 params = m.group(2).split(',') 52 self.params = (None if params is None else 53 [param.strip() for param in params]) 54 """The parameters of the key type, if there are any. 55 56 None if the key type is a macro without arguments. 57 """ 58 assert re.match(r'PSA_KEY_TYPE_\w+\Z', self.name) 59 60 self.expression = self.name 61 """A C expression whose value is the key type encoding.""" 62 if self.params is not None: 63 self.expression += '(' + ', '.join(self.params) + ')' 64 65 self.private_type = re.sub(r'_PUBLIC_KEY\Z', r'_KEY_PAIR', self.name) 66 """The key type macro name for the corresponding key pair type. 67 68 For everything other than a public key type, this is the same as 69 `self.name`. 70 """ 71 72 ECC_KEY_SIZES = { 73 'PSA_ECC_FAMILY_SECP_K1': (192, 224, 256), 74 'PSA_ECC_FAMILY_SECP_R1': (225, 256, 384, 521), 75 'PSA_ECC_FAMILY_SECP_R2': (160,), 76 'PSA_ECC_FAMILY_SECT_K1': (163, 233, 239, 283, 409, 571), 77 'PSA_ECC_FAMILY_SECT_R1': (163, 233, 283, 409, 571), 78 'PSA_ECC_FAMILY_SECT_R2': (163,), 79 'PSA_ECC_FAMILY_BRAINPOOL_P_R1': (160, 192, 224, 256, 320, 384, 512), 80 'PSA_ECC_FAMILY_MONTGOMERY': (255, 448), 81 'PSA_ECC_FAMILY_TWISTED_EDWARDS': (255, 448), 82 } 83 KEY_TYPE_SIZES = { 84 'PSA_KEY_TYPE_AES': (128, 192, 256), # exhaustive 85 'PSA_KEY_TYPE_ARIA': (128, 192, 256), # exhaustive 86 'PSA_KEY_TYPE_CAMELLIA': (128, 192, 256), # exhaustive 87 'PSA_KEY_TYPE_CHACHA20': (256,), # exhaustive 88 'PSA_KEY_TYPE_DERIVE': (120, 128), # sample 89 'PSA_KEY_TYPE_DES': (64, 128, 192), # exhaustive 90 'PSA_KEY_TYPE_HMAC': (128, 160, 224, 256, 384, 512), # standard size for each supported hash 91 'PSA_KEY_TYPE_PASSWORD': (48, 168, 336), # sample 92 'PSA_KEY_TYPE_PASSWORD_HASH': (128, 256), # sample 93 'PSA_KEY_TYPE_PEPPER': (128, 256), # sample 94 'PSA_KEY_TYPE_RAW_DATA': (8, 40, 128), # sample 95 'PSA_KEY_TYPE_RSA_KEY_PAIR': (1024, 1536), # small sample 96 } 97 def sizes_to_test(self) -> Tuple[int, ...]: 98 """Return a tuple of key sizes to test. 99 100 For key types that only allow a single size, or only a small set of 101 sizes, these are all the possible sizes. For key types that allow a 102 wide range of sizes, these are a representative sample of sizes, 103 excluding large sizes for which a typical resource-constrained platform 104 may run out of memory. 105 """ 106 if self.private_type == 'PSA_KEY_TYPE_ECC_KEY_PAIR': 107 assert self.params is not None 108 return self.ECC_KEY_SIZES[self.params[0]] 109 return self.KEY_TYPE_SIZES[self.private_type] 110 111 # "48657265006973206b6579a064617461" 112 DATA_BLOCK = b'Here\000is key\240data' 113 def key_material(self, bits: int) -> bytes: 114 """Return a byte string containing suitable key material with the given bit length. 115 116 Use the PSA export representation. The resulting byte string is one that 117 can be obtained with the following code: 118 ``` 119 psa_set_key_type(&attributes, `self.expression`); 120 psa_set_key_bits(&attributes, `bits`); 121 psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_EXPORT); 122 psa_generate_key(&attributes, &id); 123 psa_export_key(id, `material`, ...); 124 ``` 125 """ 126 if self.expression in ASYMMETRIC_KEY_DATA: 127 if bits not in ASYMMETRIC_KEY_DATA[self.expression]: 128 raise ValueError('No key data for {}-bit {}' 129 .format(bits, self.expression)) 130 return ASYMMETRIC_KEY_DATA[self.expression][bits] 131 if bits % 8 != 0: 132 raise ValueError('Non-integer number of bytes: {} bits for {}' 133 .format(bits, self.expression)) 134 length = bits // 8 135 if self.name == 'PSA_KEY_TYPE_DES': 136 # "644573206b457901644573206b457902644573206b457904" 137 des3 = b'dEs kEy\001dEs kEy\002dEs kEy\004' 138 return des3[:length] 139 return b''.join([self.DATA_BLOCK] * (length // len(self.DATA_BLOCK)) + 140 [self.DATA_BLOCK[:length % len(self.DATA_BLOCK)]]) 141 142 KEY_TYPE_FOR_SIGNATURE = { 143 'PSA_KEY_USAGE_SIGN_HASH': re.compile('.*KEY_PAIR'), 144 'PSA_KEY_USAGE_VERIFY_HASH': re.compile('.*KEY.*') 145 } #type: Dict[str, Pattern] 146 """Use a regexp to determine key types for which signature is possible 147 when using the actual usage flag. 148 """ 149 def is_valid_for_signature(self, usage: str) -> bool: 150 """Determine if the key type is compatible with the specified 151 signitute type. 152 153 """ 154 # This is just temporaly solution for the implicit usage flags. 155 return re.match(self.KEY_TYPE_FOR_SIGNATURE[usage], self.name) is not None 156