tests: src: pk_helpers: add documentation and proper functions prefix Signed-off-by: Valerio Setti <vsetti@baylibre.com>
diff --git a/tests/include/test/pk_helpers.h b/tests/include/test/pk_helpers.h index 21a38d9..212d45a 100644 --- a/tests/include/test/pk_helpers.h +++ b/tests/include/test/pk_helpers.h
@@ -1,5 +1,6 @@ /* - * Helper functions for PK + * Helper functions for PK. + * This is only for TF-PSA-Crypto 1.0 and above. */ /* * Copyright The Mbed TLS Contributors @@ -20,18 +21,55 @@ TEST_PK_COPY_PUBLIC_FROM_PSA, } pk_context_populate_method_t; -int pk_helpers_get_predefined_key_data(int is_ec, int group_id_or_keybits, - const unsigned char **key, size_t *key_len, - const unsigned char **pub_key, size_t *pub_key_len); +/** + * Get predefined key pair/public key data for the requested key. For the time + * being it only works with EC and RSA keys. + * + * \param is_ec: 1 for EC keys, 0 for RSA. + * \param group_id_or_keybits: this should be 'group_id' in case of EC keys, and + * bitsize in case of RSA keys. + * \param key: output buffer where the key pair will be copied. + * \param key_len: size in bytes of the "key" buffer. + * \param pub_key: output buffer where the public key will be copied. + * \param pub_key_len: size in bytes of the "pub_key" buffer. + * + * \return 0 on success; + */ +int mbedtls_pk_helpers_get_predefined_key_data(int is_ec, int group_id_or_keybits, + const unsigned char **key, size_t *key_len, + const unsigned char **pub_key, size_t *pub_key_len); -mbedtls_svc_key_id_t pk_helpers_make_psa_key_from_predefined(psa_key_type_t key_type, - psa_key_bits_t key_bits, - psa_algorithm_t alg, - psa_algorithm_t alg2, - psa_key_usage_t usage_flags); +/** + * Create a PSA key using prefined key data. + * + * Predefined key data is used to create the key and the choice of predefined + * key material is based on the combination of "key_type" and "key_bits". + * + * \param key_type: type of key to be created. For the time being only RSA and + * EC key types are supported. + * \param key_bits: length of the key (in bits). + * \param alg: algorithm to be associated with the key. + * \param alg2: enrollmente alogrithm to be associated with the key. + * \param usage_flags: usage flags to be associated with the key. + * + * \return the key ID of the created PSA key. + */ +mbedtls_svc_key_id_t mbedtls_pk_helpers_make_psa_key_from_predefined(psa_key_type_t key_type, + psa_key_bits_t key_bits, + psa_algorithm_t alg, + psa_algorithm_t alg2, + psa_key_usage_t usage_flags); -void pk_helpers_populate_context(mbedtls_pk_context *pk, mbedtls_svc_key_id_t key_id, - pk_context_populate_method_t method); +/** + * Populate the given PK context using "key_id" and the desired "method". + * + * \param pk: the PK context to be populated; it must have been initialized. + * \param key_id: the PSA key ID to be used to populate the PK context. + * \param method: the desired method for populating the PK context. See + * "pk_context_populate_method_t" for available options. + */ +void mbedtls_pk_helpers_populate_context(mbedtls_pk_context *pk, mbedtls_svc_key_id_t key_id, + pk_context_populate_method_t method); #endif /* MBEDTLS_PK_C */
diff --git a/tests/src/pk_helpers.c b/tests/src/pk_helpers.c index ff1832e..301ef36 100644 --- a/tests/src/pk_helpers.c +++ b/tests/src/pk_helpers.c
@@ -1,5 +1,6 @@ /* - * Helper functions for PK + * Helper functions for PK. + * This is only for TF-PSA-Crypto 1.0 and above. */ /* * Copyright The Mbed TLS Contributors @@ -20,9 +21,9 @@ #if defined(MBEDTLS_PK_C) -int pk_helpers_get_predefined_key_data(int is_ec, int group_id_or_keybits, - const unsigned char **key, size_t *key_len, - const unsigned char **pub_key, size_t *pub_key_len) +int mbedtls_pk_helpers_get_predefined_key_data(int is_ec, int group_id_or_keybits, + const unsigned char **key, size_t *key_len, + const unsigned char **pub_key, size_t *pub_key_len) { size_t i; struct predefined_key_element *predefined_key = NULL; @@ -53,11 +54,11 @@ return MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE; } -mbedtls_svc_key_id_t pk_helpers_make_psa_key_from_predefined(psa_key_type_t key_type, - psa_key_bits_t key_bits, - psa_algorithm_t alg, - psa_algorithm_t alg2, - psa_key_usage_t usage_flags) +mbedtls_svc_key_id_t mbedtls_pk_helpers_make_psa_key_from_predefined(psa_key_type_t key_type, + psa_key_bits_t key_bits, + psa_algorithm_t alg, + psa_algorithm_t alg2, + psa_key_usage_t usage_flags) { mbedtls_svc_key_id_t key_id = MBEDTLS_SVC_KEY_ID_INIT; psa_key_attributes_t attr = PSA_KEY_ATTRIBUTES_INIT; @@ -69,8 +70,8 @@ #if defined(PSA_WANT_KEY_TYPE_RSA_PUBLIC_KEY) if (PSA_KEY_TYPE_IS_RSA(key_type)) { - ret = pk_helpers_get_predefined_key_data(0, key_bits, &priv_key, &priv_key_len, - &pub_key, &pub_key_len); + ret = mbedtls_pk_helpers_get_predefined_key_data(0, key_bits, &priv_key, &priv_key_len, + &pub_key, &pub_key_len); TEST_EQUAL(ret, 0); } else #endif /* PSA_WANT_KEY_TYPE_RSA_PUBLIC_KEY */ @@ -78,8 +79,8 @@ if (PSA_KEY_TYPE_IS_ECC(key_type)) { psa_ecc_family_t ec_family = PSA_KEY_TYPE_ECC_GET_FAMILY(key_type); mbedtls_ecp_group_id ecp_group = mbedtls_ecc_group_from_psa(ec_family, key_bits); - ret = pk_helpers_get_predefined_key_data(1, ecp_group, &priv_key, &priv_key_len, - &pub_key, &pub_key_len); + ret = mbedtls_pk_helpers_get_predefined_key_data(1, ecp_group, &priv_key, &priv_key_len, + &pub_key, &pub_key_len); TEST_EQUAL(ret, 0); } else #endif /* PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY */ @@ -97,8 +98,8 @@ return key_id; } -void pk_helpers_populate_context(mbedtls_pk_context *pk, mbedtls_svc_key_id_t key_id, - pk_context_populate_method_t method) +void mbedtls_pk_helpers_populate_context(mbedtls_pk_context *pk, mbedtls_svc_key_id_t key_id, + pk_context_populate_method_t method) { switch (method) { case TEST_PK_WRAP_PSA: