增加所有文件

middleware/mbedtls/programs/psa/CMakeLists.txt

@@ -0,0 +1,47 @@
+set(executables
+    aead_demo
+    crypto_examples
+    hmac_demo
+    key_ladder_demo
+    psa_constant_names
+)
+
+if(GEN_FILES)
+    add_custom_command(
+        OUTPUT
+            ${CMAKE_CURRENT_BINARY_DIR}/psa_constant_names_generated.c
+        COMMAND
+            ${MBEDTLS_PYTHON_EXECUTABLE}
+                ${CMAKE_CURRENT_SOURCE_DIR}/../../scripts/generate_psa_constants.py
+                ${CMAKE_CURRENT_BINARY_DIR}
+        WORKING_DIRECTORY
+            ${CMAKE_CURRENT_SOURCE_DIR}/../..
+        DEPENDS
+            ${CMAKE_CURRENT_SOURCE_DIR}/../../scripts/generate_psa_constants.py
+            ${CMAKE_CURRENT_SOURCE_DIR}/../../include/psa/crypto_values.h
+            ${CMAKE_CURRENT_SOURCE_DIR}/../../include/psa/crypto_extra.h
+    )
+else()
+    link_to_source(psa_constant_names_generated.c)
+endif()
+
+foreach(exe IN LISTS executables)
+    add_executable(${exe} ${exe}.c $<TARGET_OBJECTS:mbedtls_test>)
+    target_link_libraries(${exe} ${mbedcrypto_target})
+    target_include_directories(${exe} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../../tests/include)
+endforeach()
+
+target_include_directories(psa_constant_names PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
+if(GEN_FILES)
+    add_custom_target(generate_psa_constant_names_generated_c
+        DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/psa_constant_names_generated.c)
+    add_dependencies(psa_constant_names generate_psa_constant_names_generated_c)
+endif()
+
+install(TARGETS ${executables}
+        DESTINATION "bin"
+        PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE)
+
+install(PROGRAMS
+            key_ladder_demo.sh
+        DESTINATION "bin")

middleware/mbedtls/programs/psa/aead_demo.c

@@ -0,0 +1,293 @@
+/**
+ * PSA API multi-part AEAD demonstration.
+ *
+ * This program AEAD-encrypts a message, using the algorithm and key size
+ * specified on the command line, using the multi-part API.
+ *
+ * It comes with a companion program cipher/cipher_aead_demo.c, which does the
+ * same operations with the legacy Cipher API. The goal is that comparing the
+ * two programs will help people migrating to the PSA Crypto API.
+ *
+ * When used with multi-part AEAD operations, the `mbedtls_cipher_context`
+ * serves a triple purpose (1) hold the key, (2) store the algorithm when no
+ * operation is active, and (3) save progress information for the current
+ * operation. With PSA those roles are held by disinct objects: (1) a
+ * psa_key_id_t to hold the key, a (2) psa_algorithm_t to represent the
+ * algorithm, and (3) a psa_operation_t for multi-part progress.
+ *
+ * On the other hand, with PSA, the algorithms encodes the desired tag length;
+ * with Cipher the desired tag length needs to be tracked separately.
+ *
+ * This program and its companion cipher/cipher_aead_demo.c illustrate this by
+ * doing the same sequence of multi-part AEAD computation with both APIs;
+ * looking at the two side by side should make the differences and
+ * similarities clear.
+ */
+
+/*
+ *  Copyright The Mbed TLS Contributors
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *  not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+/* First include Mbed TLS headers to get the Mbed TLS configuration and
+ * platform definitions that we'll use in this program. Also include
+ * standard C headers for functions we'll use here. */
+#include "mbedtls/build_info.h"
+
+#include "psa/crypto.h"
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <string.h>
+
+/* If the build options we need are not enabled, compile a placeholder. */
+#if !defined(MBEDTLS_PSA_CRYPTO_C) || \
+    !defined(MBEDTLS_AES_C) || !defined(MBEDTLS_GCM_C) || \
+    !defined(MBEDTLS_CHACHAPOLY_C) || \
+    defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER)
+int main( void )
+{
+    printf( "MBEDTLS_PSA_CRYPTO_C and/or "
+            "MBEDTLS_AES_C and/or MBEDTLS_GCM_C and/or "
+            "MBEDTLS_CHACHAPOLY_C not defined, and/or "
+            "MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER defined\r\n" );
+    return( 0 );
+}
+#else
+
+/* The real program starts here. */
+
+const char usage[] =
+"Usage: aead_demo [aes128-gcm|aes256-gcm|aes128-gcm_8|chachapoly]";
+
+/* Dummy data for encryption: IV/nonce, additional data, 2-part message */
+const unsigned char iv1[12] = { 0x00 };
+const unsigned char add_data1[] = { 0x01, 0x02 };
+const unsigned char msg1_part1[] = { 0x03, 0x04 };
+const unsigned char msg1_part2[] = { 0x05, 0x06, 0x07 };
+
+/* Dummy data (2nd message) */
+const unsigned char iv2[12] = { 0x10 };
+const unsigned char add_data2[] = { 0x11, 0x12 };
+const unsigned char msg2_part1[] = { 0x13, 0x14 };
+const unsigned char msg2_part2[] = { 0x15, 0x16, 0x17 };
+
+/* Maximum total size of the messages */
+#define MSG1_SIZE ( sizeof( msg1_part1 ) + sizeof( msg1_part2 ) )
+#define MSG2_SIZE ( sizeof( msg2_part1 ) + sizeof( msg2_part2 ) )
+#define MSG_MAX_SIZE ( MSG1_SIZE > MSG2_SIZE ? MSG1_SIZE : MSG2_SIZE )
+
+/* Dummy key material - never do this in production!
+ * 32-byte is enough to all the key size supported by this program. */
+const unsigned char key_bytes[32] = { 0x2a };
+
+/* Print the contents of a buffer in hex */
+void print_buf( const char *title, uint8_t *buf, size_t len )
+{
+    printf( "%s:", title );
+    for( size_t i = 0; i < len; i++ )
+        printf( " %02x", buf[i] );
+    printf( "\n" );
+}
+
+/* Run a PSA function and bail out if it fails.
+ * The symbolic name of the error code can be recovered using:
+ * programs/psa/psa_consant_name status <value> */
+#define PSA_CHECK( expr )                                       \
+    do                                                          \
+    {                                                           \
+        status = ( expr );                                      \
+        if( status != PSA_SUCCESS )                             \
+        {                                                       \
+            printf( "Error %d at line %d: %s\n",                \
+                    (int) status,                               \
+                    __LINE__,                                   \
+                    #expr );                                    \
+            goto exit;                                          \
+        }                                                       \
+    }                                                           \
+    while( 0 )
+
+/*
+ * Prepare encryption material:
+ * - interpret command-line argument
+ * - set up key
+ * - outputs: key and algorithm, which together hold all the information
+ */
+static psa_status_t aead_prepare( const char *info,
+                                  psa_key_id_t *key,
+                                  psa_algorithm_t *alg )
+{
+    psa_status_t status;
+
+    /* Convert arg to alg + key_bits + key_type */
+    size_t key_bits;
+    psa_key_type_t key_type;
+    if( strcmp( info, "aes128-gcm" ) == 0 ) {
+        *alg = PSA_ALG_GCM;
+        key_bits = 128;
+        key_type = PSA_KEY_TYPE_AES;
+    } else if( strcmp( info, "aes256-gcm" ) == 0 ) {
+        *alg = PSA_ALG_GCM;
+        key_bits = 256;
+        key_type = PSA_KEY_TYPE_AES;
+    } else if( strcmp( info, "aes128-gcm_8" ) == 0 ) {
+        *alg = PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_GCM, 8);
+        key_bits = 128;
+        key_type = PSA_KEY_TYPE_AES;
+    } else if( strcmp( info, "chachapoly" ) == 0 ) {
+        *alg = PSA_ALG_CHACHA20_POLY1305;
+        key_bits = 256;
+        key_type = PSA_KEY_TYPE_CHACHA20;
+    } else {
+        puts( usage );
+        return( PSA_ERROR_INVALID_ARGUMENT );
+    }
+
+    /* Prepare key attributes */
+    psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+    psa_set_key_usage_flags( &attributes, PSA_KEY_USAGE_ENCRYPT );
+    psa_set_key_algorithm( &attributes, *alg );
+    psa_set_key_type( &attributes, key_type );
+    psa_set_key_bits( &attributes, key_bits ); // optional
+
+    /* Import key */
+    PSA_CHECK( psa_import_key( &attributes, key_bytes, key_bits / 8, key ) );
+
+exit:
+    return( status );
+}
+
+/*
+ * Print out some information.
+ *
+ * All of this information was present in the command line argument, but his
+ * function demonstrates how each piece can be recovered from (key, alg).
+ */
+static void aead_info( psa_key_id_t key, psa_algorithm_t alg )
+{
+    psa_key_attributes_t attr = PSA_KEY_ATTRIBUTES_INIT;
+    (void) psa_get_key_attributes( key, &attr );
+    psa_key_type_t key_type = psa_get_key_type( &attr );
+    size_t key_bits = psa_get_key_bits( &attr );
+    psa_algorithm_t base_alg = PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG( alg );
+    size_t tag_len = PSA_AEAD_TAG_LENGTH( key_type, key_bits, alg );
+
+    const char *type_str = key_type == PSA_KEY_TYPE_AES ? "AES"
+                         : key_type == PSA_KEY_TYPE_CHACHA20 ? "Chacha"
+                         : "???";
+    const char *base_str = base_alg == PSA_ALG_GCM ? "GCM"
+                         : base_alg == PSA_ALG_CHACHA20_POLY1305 ? "ChachaPoly"
+                         : "???";
+
+    printf( "%s, %u, %s, %u\n",
+            type_str, (unsigned) key_bits, base_str, (unsigned) tag_len );
+}
+
+/*
+ * Encrypt a 2-part message.
+ */
+static int aead_encrypt( psa_key_id_t key, psa_algorithm_t alg,
+        const unsigned char *iv, size_t iv_len,
+        const unsigned char *ad, size_t ad_len,
+        const unsigned char *part1, size_t part1_len,
+        const unsigned char *part2, size_t part2_len )
+{
+    psa_status_t status;
+    size_t olen, olen_tag;
+    unsigned char out[PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(MSG_MAX_SIZE)];
+    unsigned char *p = out, *end = out + sizeof( out );
+    unsigned char tag[PSA_AEAD_TAG_MAX_SIZE];
+
+    psa_aead_operation_t op = PSA_AEAD_OPERATION_INIT;
+    PSA_CHECK( psa_aead_encrypt_setup( &op, key, alg ) );
+
+    PSA_CHECK( psa_aead_set_nonce( &op, iv, iv_len ) );
+    PSA_CHECK( psa_aead_update_ad( &op, ad, ad_len ) );
+    PSA_CHECK( psa_aead_update( &op, part1, part1_len, p, end - p, &olen ) );
+    p += olen;
+    PSA_CHECK( psa_aead_update( &op, part2, part2_len, p, end - p, &olen ) );
+    p += olen;
+    PSA_CHECK( psa_aead_finish( &op, p, end - p, &olen,
+                               tag, sizeof( tag ), &olen_tag ) );
+    p += olen;
+    memcpy( p, tag, olen_tag );
+    p += olen_tag;
+
+    olen = p - out;
+    print_buf( "out", out, olen );
+
+exit:
+    psa_aead_abort( &op ); // required on errors, harmless on success
+    return( status );
+}
+
+/*
+ * AEAD demo: set up key/alg, print out info, encrypt messages.
+ */
+static psa_status_t aead_demo( const char *info )
+{
+    psa_status_t status;
+
+    psa_key_id_t key;
+    psa_algorithm_t alg;
+
+    PSA_CHECK( aead_prepare( info, &key, &alg ) );
+
+    aead_info( key, alg );
+
+    PSA_CHECK( aead_encrypt( key, alg,
+                       iv1, sizeof( iv1 ), add_data1, sizeof( add_data1 ),
+                       msg1_part1, sizeof( msg1_part1 ),
+                       msg1_part2, sizeof( msg1_part2 ) ) );
+    PSA_CHECK( aead_encrypt( key, alg,
+                       iv2, sizeof( iv2 ), add_data2, sizeof( add_data2 ),
+                       msg2_part1, sizeof( msg2_part1 ),
+                       msg2_part2, sizeof( msg2_part2 ) ) );
+
+exit:
+    psa_destroy_key( key );
+
+    return( status );
+}
+
+/*
+ * Main function
+ */
+int main( int argc, char **argv )
+{
+    psa_status_t status = PSA_SUCCESS;
+
+    /* Check usage */
+    if( argc != 2 )
+    {
+        puts( usage );
+        return( EXIT_FAILURE );
+    }
+
+    /* Initialize the PSA crypto library. */
+    PSA_CHECK( psa_crypto_init( ) );
+
+    /* Run the demo */
+    PSA_CHECK( aead_demo( argv[1] ) );
+
+    /* Deinitialize the PSA crypto library. */
+    mbedtls_psa_crypto_free( );
+
+exit:
+    return( status == PSA_SUCCESS ? EXIT_SUCCESS : EXIT_FAILURE );
+}
+
+#endif

middleware/mbedtls/programs/psa/crypto_examples.c

@@ -0,0 +1,331 @@
+/*
+ *  Copyright The Mbed TLS Contributors
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *  not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+#include "psa/crypto.h"
+#include <string.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+#define ASSERT( predicate )                                                   \
+    do                                                                        \
+    {                                                                         \
+        if( ! ( predicate ) )                                                 \
+        {                                                                     \
+            printf( "\tassertion failed at %s:%d - '%s'\r\n",         \
+                    __FILE__, __LINE__, #predicate);                  \
+            goto exit;                                                        \
+        }                                                                     \
+    } while ( 0 )
+
+#define ASSERT_STATUS( actual, expected )                                     \
+    do                                                                        \
+    {                                                                         \
+        if( ( actual ) != ( expected ) )                                      \
+        {                                                                     \
+            printf( "\tassertion failed at %s:%d - "                  \
+                    "actual:%d expected:%d\r\n", __FILE__, __LINE__,  \
+                            (psa_status_t) actual, (psa_status_t) expected ); \
+            goto exit;                                                        \
+        }                                                                     \
+    } while ( 0 )
+
+#if !defined(MBEDTLS_PSA_CRYPTO_C) || !defined(MBEDTLS_AES_C) || \
+    !defined(MBEDTLS_CIPHER_MODE_CBC) || !defined(MBEDTLS_CIPHER_MODE_CTR) || \
+    !defined(MBEDTLS_CIPHER_MODE_WITH_PADDING) || \
+    defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER)
+int main( void )
+{
+    printf( "MBEDTLS_PSA_CRYPTO_C and/or MBEDTLS_AES_C and/or "
+            "MBEDTLS_CIPHER_MODE_CBC and/or MBEDTLS_CIPHER_MODE_CTR "
+            "and/or MBEDTLS_CIPHER_MODE_WITH_PADDING "
+            "not defined and/or MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER"
+            " defined.\r\n" );
+    return( 0 );
+}
+#else
+
+static psa_status_t cipher_operation( psa_cipher_operation_t *operation,
+                                      const uint8_t * input,
+                                      size_t input_size,
+                                      size_t part_size,
+                                      uint8_t * output,
+                                      size_t output_size,
+                                      size_t *output_len )
+{
+    psa_status_t status;
+    size_t bytes_to_write = 0, bytes_written = 0, len = 0;
+
+    *output_len = 0;
+    while( bytes_written != input_size )
+    {
+        bytes_to_write = ( input_size - bytes_written > part_size ?
+                           part_size :
+                           input_size - bytes_written );
+
+        status = psa_cipher_update( operation, input + bytes_written,
+                                    bytes_to_write, output + *output_len,
+                                    output_size - *output_len, &len );
+        ASSERT_STATUS( status, PSA_SUCCESS );
+
+        bytes_written += bytes_to_write;
+        *output_len += len;
+    }
+
+    status = psa_cipher_finish( operation, output + *output_len,
+                                output_size - *output_len, &len );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+    *output_len += len;
+
+exit:
+    return( status );
+}
+
+static psa_status_t cipher_encrypt( psa_key_id_t key,
+                                    psa_algorithm_t alg,
+                                    uint8_t * iv,
+                                    size_t iv_size,
+                                    const uint8_t * input,
+                                    size_t input_size,
+                                    size_t part_size,
+                                    uint8_t * output,
+                                    size_t output_size,
+                                    size_t *output_len )
+{
+    psa_status_t status;
+    psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
+    size_t iv_len = 0;
+
+    memset( &operation, 0, sizeof( operation ) );
+    status = psa_cipher_encrypt_setup( &operation, key, alg );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    status = psa_cipher_generate_iv( &operation, iv, iv_size, &iv_len );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    status = cipher_operation( &operation, input, input_size, part_size,
+                               output, output_size, output_len );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+exit:
+    psa_cipher_abort( &operation );
+    return( status );
+}
+
+static psa_status_t cipher_decrypt( psa_key_id_t key,
+                                    psa_algorithm_t alg,
+                                    const uint8_t * iv,
+                                    size_t iv_size,
+                                    const uint8_t * input,
+                                    size_t input_size,
+                                    size_t part_size,
+                                    uint8_t * output,
+                                    size_t output_size,
+                                    size_t *output_len )
+{
+    psa_status_t status;
+    psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
+
+    memset( &operation, 0, sizeof( operation ) );
+    status = psa_cipher_decrypt_setup( &operation, key, alg );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    status = psa_cipher_set_iv( &operation, iv, iv_size );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    status = cipher_operation( &operation, input, input_size, part_size,
+                               output, output_size, output_len );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+exit:
+    psa_cipher_abort( &operation );
+    return( status );
+}
+
+static psa_status_t
+cipher_example_encrypt_decrypt_aes_cbc_nopad_1_block( void )
+{
+    enum {
+        block_size = PSA_BLOCK_CIPHER_BLOCK_LENGTH( PSA_KEY_TYPE_AES ),
+        key_bits = 256,
+        part_size = block_size,
+    };
+    const psa_algorithm_t alg = PSA_ALG_CBC_NO_PADDING;
+
+    psa_status_t status;
+    psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+    psa_key_id_t key = 0;
+    size_t output_len = 0;
+    uint8_t iv[block_size];
+    uint8_t input[block_size];
+    uint8_t encrypt[block_size];
+    uint8_t decrypt[block_size];
+
+    status = psa_generate_random( input, sizeof( input ) );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    psa_set_key_usage_flags( &attributes,
+                             PSA_KEY_USAGE_ENCRYPT | PSA_KEY_USAGE_DECRYPT );
+    psa_set_key_algorithm( &attributes, alg );
+    psa_set_key_type( &attributes, PSA_KEY_TYPE_AES );
+    psa_set_key_bits( &attributes, key_bits );
+
+    status = psa_generate_key( &attributes, &key );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    status = cipher_encrypt( key, alg, iv, sizeof( iv ),
+                             input, sizeof( input ), part_size,
+                             encrypt, sizeof( encrypt ), &output_len );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    status = cipher_decrypt( key, alg, iv, sizeof( iv ),
+                             encrypt, output_len, part_size,
+                             decrypt, sizeof( decrypt ), &output_len );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    status = memcmp( input, decrypt, sizeof( input ) );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+exit:
+    psa_destroy_key( key );
+    return( status );
+}
+
+static psa_status_t cipher_example_encrypt_decrypt_aes_cbc_pkcs7_multi( void )
+{
+    enum {
+        block_size = PSA_BLOCK_CIPHER_BLOCK_LENGTH( PSA_KEY_TYPE_AES ),
+        key_bits = 256,
+        input_size = 100,
+        part_size = 10,
+    };
+
+    const psa_algorithm_t alg = PSA_ALG_CBC_PKCS7;
+
+    psa_status_t status;
+    psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+    psa_key_id_t key = 0;
+    size_t output_len = 0;
+    uint8_t iv[block_size], input[input_size],
+            encrypt[input_size + block_size], decrypt[input_size + block_size];
+
+    status = psa_generate_random( input, sizeof( input ) );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    psa_set_key_usage_flags( &attributes,
+                             PSA_KEY_USAGE_ENCRYPT | PSA_KEY_USAGE_DECRYPT );
+    psa_set_key_algorithm( &attributes, alg );
+    psa_set_key_type( &attributes, PSA_KEY_TYPE_AES );
+    psa_set_key_bits( &attributes, key_bits );
+
+    status = psa_generate_key( &attributes, &key );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    status = cipher_encrypt( key, alg, iv, sizeof( iv ),
+                             input, sizeof( input ), part_size,
+                             encrypt, sizeof( encrypt ), &output_len );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    status = cipher_decrypt( key, alg, iv, sizeof( iv ),
+                             encrypt, output_len, part_size,
+                             decrypt, sizeof( decrypt ), &output_len );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    status = memcmp( input, decrypt, sizeof( input ) );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+exit:
+    psa_destroy_key( key );
+    return( status );
+}
+
+static psa_status_t cipher_example_encrypt_decrypt_aes_ctr_multi( void )
+{
+    enum {
+        block_size = PSA_BLOCK_CIPHER_BLOCK_LENGTH( PSA_KEY_TYPE_AES ),
+        key_bits = 256,
+        input_size = 100,
+        part_size = 10,
+    };
+    const psa_algorithm_t alg = PSA_ALG_CTR;
+
+    psa_status_t status;
+    psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+    psa_key_id_t key = 0;
+    size_t output_len = 0;
+    uint8_t iv[block_size], input[input_size], encrypt[input_size],
+            decrypt[input_size];
+
+    status = psa_generate_random( input, sizeof( input ) );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    psa_set_key_usage_flags( &attributes,
+                             PSA_KEY_USAGE_ENCRYPT | PSA_KEY_USAGE_DECRYPT );
+    psa_set_key_algorithm( &attributes, alg );
+    psa_set_key_type( &attributes, PSA_KEY_TYPE_AES );
+    psa_set_key_bits( &attributes, key_bits );
+
+    status = psa_generate_key( &attributes, &key );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    status = cipher_encrypt( key, alg, iv, sizeof( iv ),
+                             input, sizeof( input ), part_size,
+                             encrypt, sizeof( encrypt ), &output_len );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    status = cipher_decrypt( key, alg, iv, sizeof( iv ),
+                             encrypt, output_len, part_size,
+                             decrypt, sizeof( decrypt ), &output_len );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+    status = memcmp( input, decrypt, sizeof( input ) );
+    ASSERT_STATUS( status, PSA_SUCCESS );
+
+exit:
+    psa_destroy_key( key );
+    return( status );
+}
+
+static void cipher_examples( void )
+{
+    psa_status_t status;
+
+    printf( "cipher encrypt/decrypt AES CBC no padding:\r\n" );
+    status = cipher_example_encrypt_decrypt_aes_cbc_nopad_1_block( );
+    if( status == PSA_SUCCESS )
+        printf( "\tsuccess!\r\n" );
+
+    printf( "cipher encrypt/decrypt AES CBC PKCS7 multipart:\r\n" );
+    status = cipher_example_encrypt_decrypt_aes_cbc_pkcs7_multi( );
+    if( status == PSA_SUCCESS )
+        printf( "\tsuccess!\r\n" );
+
+    printf( "cipher encrypt/decrypt AES CTR multipart:\r\n" );
+    status = cipher_example_encrypt_decrypt_aes_ctr_multi( );
+    if( status == PSA_SUCCESS )
+        printf( "\tsuccess!\r\n" );
+}
+
+int main( void )
+{
+    ASSERT( psa_crypto_init( ) == PSA_SUCCESS );
+    cipher_examples( );
+exit:
+    mbedtls_psa_crypto_free( );
+    return( 0 );
+}
+#endif /* MBEDTLS_PSA_CRYPTO_C && MBEDTLS_AES_C && MBEDTLS_CIPHER_MODE_CBC &&
+          MBEDTLS_CIPHER_MODE_CTR && MBEDTLS_CIPHER_MODE_WITH_PADDING */

middleware/mbedtls/programs/psa/hmac_demo.c

@@ -0,0 +1,169 @@
+/**
+ * PSA API multi-part HMAC demonstration.
+ *
+ * This programs computes the HMAC of two messages using the multi-part API.
+ *
+ * It comes with a companion program hash/md_hmac_demo.c, which does the same
+ * operations with the legacy MD API. The goal is that comparing the two
+ * programs will help people migrating to the PSA Crypto API.
+ *
+ * When it comes to multi-part HMAC operations, the `mbedtls_md_context`
+ * serves a dual purpose (1) hold the key, and (2) save progress information
+ * for the current operation. With PSA those roles are held by two disinct
+ * objects: (1) a psa_key_id_t to hold the key, and (2) a psa_operation_t for
+ * multi-part progress.
+ *
+ * This program and its companion hash/md_hmac_demo.c illustrate this by doing
+ * the same sequence of multi-part HMAC computation with both APIs; looking at
+ * the two side by side should make the differences and similarities clear.
+ */
+
+/*
+ *  Copyright The Mbed TLS Contributors
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *  not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+/* First include Mbed TLS headers to get the Mbed TLS configuration and
+ * platform definitions that we'll use in this program. Also include
+ * standard C headers for functions we'll use here. */
+#include "mbedtls/build_info.h"
+
+#include "psa/crypto.h"
+
+#include "mbedtls/platform_util.h" // for mbedtls_platform_zeroize
+
+#include <stdlib.h>
+#include <stdio.h>
+
+/* If the build options we need are not enabled, compile a placeholder. */
+#if !defined(MBEDTLS_PSA_CRYPTO_C) || \
+    defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER)
+int main( void )
+{
+    printf( "MBEDTLS_PSA_CRYPTO_C not defined, "
+            "and/or MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER defined\r\n" );
+    return( 0 );
+}
+#else
+
+/* The real program starts here. */
+
+/* Dummy inputs for HMAC */
+const unsigned char msg1_part1[] = { 0x01, 0x02 };
+const unsigned char msg1_part2[] = { 0x03, 0x04 };
+const unsigned char msg2_part1[] = { 0x05, 0x05 };
+const unsigned char msg2_part2[] = { 0x06, 0x06 };
+
+/* Dummy key material - never do this in production!
+ * This example program uses SHA-256, so a 32-byte key makes sense. */
+const unsigned char key_bytes[32] = { 0 };
+
+/* Print the contents of a buffer in hex */
+void print_buf( const char *title, uint8_t *buf, size_t len )
+{
+    printf( "%s:", title );
+    for( size_t i = 0; i < len; i++ )
+        printf( " %02x", buf[i] );
+    printf( "\n" );
+}
+
+/* Run a PSA function and bail out if it fails.
+ * The symbolic name of the error code can be recovered using:
+ * programs/psa/psa_consant_name status <value> */
+#define PSA_CHECK( expr )                                       \
+    do                                                          \
+    {                                                           \
+        status = ( expr );                                      \
+        if( status != PSA_SUCCESS )                             \
+        {                                                       \
+            printf( "Error %d at line %d: %s\n",                \
+                    (int) status,                               \
+                    __LINE__,                                   \
+                    #expr );                                    \
+            goto exit;                                          \
+        }                                                       \
+    }                                                           \
+    while( 0 )
+
+/*
+ * This function demonstrates computation of the HMAC of two messages using
+ * the multipart API.
+ */
+psa_status_t hmac_demo(void)
+{
+    psa_status_t status;
+    const psa_algorithm_t alg = PSA_ALG_HMAC(PSA_ALG_SHA_256);
+    uint8_t out[PSA_MAC_MAX_SIZE]; // safe but not optimal
+    /* PSA_MAC_LENGTH(PSA_KEY_TYPE_HMAC, 8 * sizeof( key_bytes ), alg)
+     * should work but see https://github.com/Mbed-TLS/mbedtls/issues/4320 */
+
+    psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+    psa_key_id_t key = 0;
+
+    /* prepare key */
+    psa_set_key_usage_flags( &attributes, PSA_KEY_USAGE_SIGN_MESSAGE );
+    psa_set_key_algorithm( &attributes, alg );
+    psa_set_key_type( &attributes, PSA_KEY_TYPE_HMAC );
+    psa_set_key_bits( &attributes, 8 * sizeof( key_bytes ) ); // optional
+
+    status = psa_import_key( &attributes,
+                             key_bytes, sizeof( key_bytes ), &key );
+    if( status != PSA_SUCCESS )
+        return( status );
+
+    /* prepare operation */
+    psa_mac_operation_t op = PSA_MAC_OPERATION_INIT;
+    size_t out_len = 0;
+
+    /* compute HMAC(key, msg1_part1 | msg1_part2) */
+    PSA_CHECK( psa_mac_sign_setup( &op, key, alg ) );
+    PSA_CHECK( psa_mac_update( &op, msg1_part1, sizeof( msg1_part1 ) ) );
+    PSA_CHECK( psa_mac_update( &op, msg1_part2, sizeof( msg1_part2 ) ) );
+    PSA_CHECK( psa_mac_sign_finish( &op, out, sizeof( out ), &out_len ) );
+    print_buf( "msg1", out, out_len );
+
+    /* compute HMAC(key, msg2_part1 | msg2_part2) */
+    PSA_CHECK( psa_mac_sign_setup( &op, key, alg ) );
+    PSA_CHECK( psa_mac_update( &op, msg2_part1, sizeof( msg2_part1 ) ) );
+    PSA_CHECK( psa_mac_update( &op, msg2_part2, sizeof( msg2_part2 ) ) );
+    PSA_CHECK( psa_mac_sign_finish( &op, out, sizeof( out ), &out_len ) );
+    print_buf( "msg2", out, out_len );
+
+exit:
+    psa_mac_abort( &op ); // needed on error, harmless on success
+    psa_destroy_key( key );
+    mbedtls_platform_zeroize( out, sizeof( out ) );
+
+    return( status );
+}
+
+int main(void)
+{
+    psa_status_t status = PSA_SUCCESS;
+
+    /* Initialize the PSA crypto library. */
+    PSA_CHECK( psa_crypto_init( ) );
+
+    /* Run the demo */
+    PSA_CHECK( hmac_demo() );
+
+    /* Deinitialize the PSA crypto library. */
+    mbedtls_psa_crypto_free( );
+
+exit:
+    return( status == PSA_SUCCESS ? EXIT_SUCCESS : EXIT_FAILURE );
+}
+
+#endif

middleware/mbedtls/programs/psa/key_ladder_demo.c

@@ -0,0 +1,716 @@
+/**
+ * PSA API key derivation demonstration
+ *
+ * This program calculates a key ladder: a chain of secret material, each
+ * derived from the previous one in a deterministic way based on a label.
+ * Two keys are identical if and only if they are derived from the same key
+ * using the same label.
+ *
+ * The initial key is called the master key. The master key is normally
+ * randomly generated, but it could itself be derived from another key.
+ *
+ * This program derives a series of keys called intermediate keys.
+ * The first intermediate key is derived from the master key using the
+ * first label passed on the command line. Each subsequent intermediate
+ * key is derived from the previous one using the next label passed
+ * on the command line.
+ *
+ * This program has four modes of operation:
+ *
+ * - "generate": generate a random master key.
+ * - "wrap": derive a wrapping key from the last intermediate key,
+ *           and use that key to encrypt-and-authenticate some data.
+ * - "unwrap": derive a wrapping key from the last intermediate key,
+ *             and use that key to decrypt-and-authenticate some
+ *             ciphertext created by wrap mode.
+ * - "save": save the last intermediate key so that it can be reused as
+ *           the master key in another run of the program.
+ *
+ * See the usage() output for the command line usage. See the file
+ * `key_ladder_demo.sh` for an example run.
+ */
+
+/*
+ *  Copyright The Mbed TLS Contributors
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *  not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+/* First include Mbed TLS headers to get the Mbed TLS configuration and
+ * platform definitions that we'll use in this program. Also include
+ * standard C headers for functions we'll use here. */
+#include "mbedtls/build_info.h"
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <string.h>
+
+#include "mbedtls/platform.h" // for mbedtls_setbuf
+#include "mbedtls/platform_util.h" // for mbedtls_platform_zeroize
+
+#include <psa/crypto.h>
+
+/* If the build options we need are not enabled, compile a placeholder. */
+#if !defined(MBEDTLS_SHA256_C) || !defined(MBEDTLS_MD_C) ||      \
+    !defined(MBEDTLS_AES_C) || !defined(MBEDTLS_CCM_C) ||        \
+    !defined(MBEDTLS_PSA_CRYPTO_C) || !defined(MBEDTLS_FS_IO) || \
+    defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER)
+int main( void )
+{
+    printf( "MBEDTLS_SHA256_C and/or MBEDTLS_MD_C and/or "
+            "MBEDTLS_AES_C and/or MBEDTLS_CCM_C and/or "
+            "MBEDTLS_PSA_CRYPTO_C and/or MBEDTLS_FS_IO "
+            "not defined and/or MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER "
+            "defined.\n" );
+    return( 0 );
+}
+#else
+
+/* The real program starts here. */
+
+/* Run a system function and bail out if it fails. */
+#define SYS_CHECK( expr )                                       \
+    do                                                          \
+    {                                                           \
+        if( ! ( expr ) )                                        \
+        {                                                       \
+            perror( #expr );                                    \
+            status = DEMO_ERROR;                                \
+            goto exit;                                          \
+        }                                                       \
+    }                                                           \
+    while( 0 )
+
+/* Run a PSA function and bail out if it fails. */
+#define PSA_CHECK( expr )                                       \
+    do                                                          \
+    {                                                           \
+        status = ( expr );                                      \
+        if( status != PSA_SUCCESS )                             \
+        {                                                       \
+            printf( "Error %d at line %d: %s\n",                \
+                    (int) status,                               \
+                    __LINE__,                                   \
+                    #expr );                                    \
+            goto exit;                                          \
+        }                                                       \
+    }                                                           \
+    while( 0 )
+
+/* To report operational errors in this program, use an error code that is
+ * different from every PSA error code. */
+#define DEMO_ERROR 120
+
+/* The maximum supported key ladder depth. */
+#define MAX_LADDER_DEPTH 10
+
+/* Salt to use when deriving an intermediate key. */
+#define DERIVE_KEY_SALT ( (uint8_t *) "key_ladder_demo.derive" )
+#define DERIVE_KEY_SALT_LENGTH ( strlen( (const char*) DERIVE_KEY_SALT ) )
+
+/* Salt to use when deriving a wrapping key. */
+#define WRAPPING_KEY_SALT ( (uint8_t *) "key_ladder_demo.wrap" )
+#define WRAPPING_KEY_SALT_LENGTH ( strlen( (const char*) WRAPPING_KEY_SALT ) )
+
+/* Size of the key derivation keys (applies both to the master key and
+ * to intermediate keys). */
+#define KEY_SIZE_BYTES 40
+
+/* Algorithm for key derivation. */
+#define KDF_ALG PSA_ALG_HKDF( PSA_ALG_SHA_256 )
+
+/* Type and size of the key used to wrap data. */
+#define WRAPPING_KEY_TYPE PSA_KEY_TYPE_AES
+#define WRAPPING_KEY_BITS 128
+
+/* Cipher mode used to wrap data. */
+#define WRAPPING_ALG PSA_ALG_CCM
+
+/* Nonce size used to wrap data. */
+#define WRAPPING_IV_SIZE 13
+
+/* Header used in files containing wrapped data. We'll save this header
+ * directly without worrying about data representation issues such as
+ * integer sizes and endianness, because the data is meant to be read
+ * back by the same program on the same machine. */
+#define WRAPPED_DATA_MAGIC "key_ladder_demo" // including trailing null byte
+#define WRAPPED_DATA_MAGIC_LENGTH ( sizeof( WRAPPED_DATA_MAGIC ) )
+typedef struct
+{
+    char magic[WRAPPED_DATA_MAGIC_LENGTH];
+    size_t ad_size; /* Size of the additional data, which is this header. */
+    size_t payload_size; /* Size of the encrypted data. */
+    /* Store the IV inside the additional data. It's convenient. */
+    uint8_t iv[WRAPPING_IV_SIZE];
+} wrapped_data_header_t;
+
+/* The modes that this program can operate in (see usage). */
+enum program_mode
+{
+    MODE_GENERATE,
+    MODE_SAVE,
+    MODE_UNWRAP,
+    MODE_WRAP
+};
+
+/* Save a key to a file. In the real world, you may want to export a derived
+ * key sometimes, to share it with another party. */
+static psa_status_t save_key( psa_key_id_t key,
+                              const char *output_file_name )
+{
+    psa_status_t status = PSA_SUCCESS;
+    uint8_t key_data[KEY_SIZE_BYTES];
+    size_t key_size;
+    FILE *key_file = NULL;
+
+    PSA_CHECK( psa_export_key( key,
+                               key_data, sizeof( key_data ),
+                               &key_size ) );
+    SYS_CHECK( ( key_file = fopen( output_file_name, "wb" ) ) != NULL );
+    /* Ensure no stdio buffering of secrets, as such buffers cannot be wiped. */
+    mbedtls_setbuf( key_file, NULL );
+    SYS_CHECK( fwrite( key_data, 1, key_size, key_file ) == key_size );
+    SYS_CHECK( fclose( key_file ) == 0 );
+    key_file = NULL;
+
+exit:
+    if( key_file != NULL)
+        fclose( key_file );
+    return( status );
+}
+
+/* Generate a master key for use in this demo.
+ *
+ * Normally a master key would be non-exportable. For the purpose of this
+ * demo, we want to save it to a file, to avoid relying on the keystore
+ * capability of the PSA crypto library. */
+static psa_status_t generate( const char *key_file_name )
+{
+    psa_status_t status = PSA_SUCCESS;
+    psa_key_id_t key = 0;
+    psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+
+    psa_set_key_usage_flags( &attributes,
+                             PSA_KEY_USAGE_DERIVE | PSA_KEY_USAGE_EXPORT );
+    psa_set_key_algorithm( &attributes, KDF_ALG );
+    psa_set_key_type( &attributes, PSA_KEY_TYPE_DERIVE );
+    psa_set_key_bits( &attributes, PSA_BYTES_TO_BITS( KEY_SIZE_BYTES ) );
+
+    PSA_CHECK( psa_generate_key( &attributes, &key ) );
+
+    PSA_CHECK( save_key( key, key_file_name ) );
+
+exit:
+    (void) psa_destroy_key( key );
+    return( status );
+}
+
+/* Load the master key from a file.
+ *
+ * In the real world, this master key would be stored in an internal memory
+ * and the storage would be managed by the keystore capability of the PSA
+ * crypto library. */
+static psa_status_t import_key_from_file( psa_key_usage_t usage,
+                                          psa_algorithm_t alg,
+                                          const char *key_file_name,
+                                          psa_key_id_t *master_key )
+{
+    psa_status_t status = PSA_SUCCESS;
+    psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+    uint8_t key_data[KEY_SIZE_BYTES];
+    size_t key_size;
+    FILE *key_file = NULL;
+    unsigned char extra_byte;
+
+    SYS_CHECK( ( key_file = fopen( key_file_name, "rb" ) ) != NULL );
+    /* Ensure no stdio buffering of secrets, as such buffers cannot be wiped. */
+    mbedtls_setbuf( key_file, NULL );
+    SYS_CHECK( ( key_size = fread( key_data, 1, sizeof( key_data ),
+                                   key_file ) ) != 0 );
+    if( fread( &extra_byte, 1, 1, key_file ) != 0 )
+    {
+        printf( "Key file too large (max: %u).\n",
+                (unsigned) sizeof( key_data ) );
+        status = DEMO_ERROR;
+        goto exit;
+    }
+    SYS_CHECK( fclose( key_file ) == 0 );
+    key_file = NULL;
+
+    psa_set_key_usage_flags( &attributes, usage );
+    psa_set_key_algorithm( &attributes, alg );
+    psa_set_key_type( &attributes, PSA_KEY_TYPE_DERIVE );
+    PSA_CHECK( psa_import_key( &attributes, key_data, key_size, master_key ) );
+exit:
+    if( key_file != NULL )
+        fclose( key_file );
+    mbedtls_platform_zeroize( key_data, sizeof( key_data ) );
+    if( status != PSA_SUCCESS )
+    {
+        /* If the key creation hasn't happened yet or has failed,
+         * *master_key is null. psa_destroy_key( 0 ) is
+         * guaranteed to do nothing and return PSA_SUCCESS. */
+        (void) psa_destroy_key( *master_key );
+        *master_key = 0;
+    }
+    return( status );
+}
+
+/* Derive the intermediate keys, using the list of labels provided on
+ * the command line. On input, *key is the master key identifier.
+ * This function destroys the master key. On successful output, *key
+ * is the identifier of the final derived key.
+ */
+static psa_status_t derive_key_ladder( const char *ladder[],
+                                       size_t ladder_depth,
+                                       psa_key_id_t *key )
+{
+    psa_status_t status = PSA_SUCCESS;
+    psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+    psa_key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT;
+    size_t i;
+
+    psa_set_key_usage_flags( &attributes,
+                             PSA_KEY_USAGE_DERIVE | PSA_KEY_USAGE_EXPORT );
+    psa_set_key_algorithm( &attributes, KDF_ALG );
+    psa_set_key_type( &attributes, PSA_KEY_TYPE_DERIVE );
+    psa_set_key_bits( &attributes, PSA_BYTES_TO_BITS( KEY_SIZE_BYTES ) );
+
+    /* For each label in turn, ... */
+    for( i = 0; i < ladder_depth; i++ )
+    {
+        /* Start deriving material from the master key (if i=0) or from
+         * the current intermediate key (if i>0). */
+        PSA_CHECK( psa_key_derivation_setup( &operation, KDF_ALG ) );
+        PSA_CHECK( psa_key_derivation_input_bytes(
+                       &operation, PSA_KEY_DERIVATION_INPUT_SALT,
+                       DERIVE_KEY_SALT, DERIVE_KEY_SALT_LENGTH ) );
+        PSA_CHECK( psa_key_derivation_input_key(
+                       &operation, PSA_KEY_DERIVATION_INPUT_SECRET,
+                       *key ) );
+        PSA_CHECK( psa_key_derivation_input_bytes(
+                       &operation, PSA_KEY_DERIVATION_INPUT_INFO,
+                       (uint8_t*) ladder[i], strlen( ladder[i] ) ) );
+        /* When the parent key is not the master key, destroy it,
+         * since it is no longer needed. */
+        PSA_CHECK( psa_destroy_key( *key ) );
+        *key = 0;
+        /* Derive the next intermediate key from the parent key. */
+        PSA_CHECK( psa_key_derivation_output_key( &attributes, &operation,
+                                                  key ) );
+        PSA_CHECK( psa_key_derivation_abort( &operation ) );
+    }
+
+exit:
+    psa_key_derivation_abort( &operation );
+    if( status != PSA_SUCCESS )
+    {
+        psa_destroy_key( *key );
+        *key = 0;
+    }
+    return( status );
+}
+
+/* Derive a wrapping key from the last intermediate key. */
+static psa_status_t derive_wrapping_key( psa_key_usage_t usage,
+                                         psa_key_id_t derived_key,
+                                         psa_key_id_t *wrapping_key )
+{
+    psa_status_t status = PSA_SUCCESS;
+    psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+    psa_key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT;
+
+    *wrapping_key = 0;
+
+    /* Set up a key derivation operation from the key derived from
+     * the master key. */
+    PSA_CHECK( psa_key_derivation_setup( &operation, KDF_ALG ) );
+    PSA_CHECK( psa_key_derivation_input_bytes(
+                   &operation, PSA_KEY_DERIVATION_INPUT_SALT,
+                   WRAPPING_KEY_SALT, WRAPPING_KEY_SALT_LENGTH ) );
+    PSA_CHECK( psa_key_derivation_input_key(
+                   &operation, PSA_KEY_DERIVATION_INPUT_SECRET,
+                   derived_key ) );
+    PSA_CHECK( psa_key_derivation_input_bytes(
+                   &operation, PSA_KEY_DERIVATION_INPUT_INFO,
+                   NULL, 0 ) );
+
+    /* Create the wrapping key. */
+    psa_set_key_usage_flags( &attributes, usage );
+    psa_set_key_algorithm( &attributes, WRAPPING_ALG );
+    psa_set_key_type( &attributes, PSA_KEY_TYPE_AES );
+    psa_set_key_bits( &attributes, WRAPPING_KEY_BITS );
+    PSA_CHECK( psa_key_derivation_output_key( &attributes, &operation,
+                                              wrapping_key ) );
+
+exit:
+    psa_key_derivation_abort( &operation );
+    return( status );
+}
+
+static psa_status_t wrap_data( const char *input_file_name,
+                               const char *output_file_name,
+                               psa_key_id_t wrapping_key )
+{
+    psa_status_t status;
+    FILE *input_file = NULL;
+    FILE *output_file = NULL;
+    psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+    psa_key_type_t key_type;
+    long input_position;
+    size_t input_size;
+    size_t buffer_size = 0;
+    unsigned char *buffer = NULL;
+    size_t ciphertext_size;
+    wrapped_data_header_t header;
+
+    /* Find the size of the data to wrap. */
+    SYS_CHECK( ( input_file = fopen( input_file_name, "rb" ) ) != NULL );
+    /* Ensure no stdio buffering of secrets, as such buffers cannot be wiped. */
+    mbedtls_setbuf( input_file, NULL );
+    SYS_CHECK( fseek( input_file, 0, SEEK_END ) == 0 );
+    SYS_CHECK( ( input_position = ftell( input_file ) ) != -1 );
+#if LONG_MAX > SIZE_MAX
+    if( input_position > SIZE_MAX )
+    {
+        printf( "Input file too large.\n" );
+        status = DEMO_ERROR;
+        goto exit;
+    }
+#endif
+    input_size = input_position;
+    PSA_CHECK( psa_get_key_attributes( wrapping_key, &attributes ) );
+    key_type = psa_get_key_type( &attributes );
+    buffer_size =
+        PSA_AEAD_ENCRYPT_OUTPUT_SIZE( key_type, WRAPPING_ALG, input_size );
+    /* Check for integer overflow. */
+    if( buffer_size < input_size )
+    {
+        printf( "Input file too large.\n" );
+        status = DEMO_ERROR;
+        goto exit;
+    }
+
+    /* Load the data to wrap. */
+    SYS_CHECK( fseek( input_file, 0, SEEK_SET ) == 0 );
+    SYS_CHECK( ( buffer = calloc( 1, buffer_size ) ) != NULL );
+    SYS_CHECK( fread( buffer, 1, input_size, input_file ) == input_size );
+    SYS_CHECK( fclose( input_file ) == 0 );
+    input_file = NULL;
+
+    /* Construct a header. */
+    memcpy( &header.magic, WRAPPED_DATA_MAGIC, WRAPPED_DATA_MAGIC_LENGTH );
+    header.ad_size = sizeof( header );
+    header.payload_size = input_size;
+
+    /* Wrap the data. */
+    PSA_CHECK( psa_generate_random( header.iv, WRAPPING_IV_SIZE ) );
+    PSA_CHECK( psa_aead_encrypt( wrapping_key, WRAPPING_ALG,
+                                 header.iv, WRAPPING_IV_SIZE,
+                                 (uint8_t *) &header, sizeof( header ),
+                                 buffer, input_size,
+                                 buffer, buffer_size,
+                                 &ciphertext_size ) );
+
+    /* Write the output. */
+    SYS_CHECK( ( output_file = fopen( output_file_name, "wb" ) ) != NULL );
+    /* Ensure no stdio buffering of secrets, as such buffers cannot be wiped. */
+    mbedtls_setbuf( output_file, NULL );
+    SYS_CHECK( fwrite( &header, 1, sizeof( header ),
+                       output_file ) == sizeof( header ) );
+    SYS_CHECK( fwrite( buffer, 1, ciphertext_size,
+                       output_file ) == ciphertext_size );
+    SYS_CHECK( fclose( output_file ) == 0 );
+    output_file = NULL;
+
+exit:
+    if( input_file != NULL )
+        fclose( input_file );
+    if( output_file != NULL )
+        fclose( output_file );
+    if( buffer != NULL )
+        mbedtls_platform_zeroize( buffer, buffer_size );
+    free( buffer );
+    return( status );
+}
+
+static psa_status_t unwrap_data( const char *input_file_name,
+                                 const char *output_file_name,
+                                 psa_key_id_t wrapping_key )
+{
+    psa_status_t status;
+    FILE *input_file = NULL;
+    FILE *output_file = NULL;
+    psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+    psa_key_type_t key_type;
+    unsigned char *buffer = NULL;
+    size_t ciphertext_size = 0;
+    size_t plaintext_size;
+    wrapped_data_header_t header;
+    unsigned char extra_byte;
+
+    /* Load and validate the header. */
+    SYS_CHECK( ( input_file = fopen( input_file_name, "rb" ) ) != NULL );
+    /* Ensure no stdio buffering of secrets, as such buffers cannot be wiped. */
+    mbedtls_setbuf( input_file, NULL );
+    SYS_CHECK( fread( &header, 1, sizeof( header ),
+                      input_file ) == sizeof( header ) );
+    if( memcmp( &header.magic, WRAPPED_DATA_MAGIC,
+                WRAPPED_DATA_MAGIC_LENGTH ) != 0 )
+    {
+        printf( "The input does not start with a valid magic header.\n" );
+        status = DEMO_ERROR;
+        goto exit;
+    }
+    if( header.ad_size != sizeof( header ) )
+    {
+        printf( "The header size is not correct.\n" );
+        status = DEMO_ERROR;
+        goto exit;
+    }
+    PSA_CHECK( psa_get_key_attributes( wrapping_key, &attributes) );
+    key_type = psa_get_key_type( &attributes);
+    ciphertext_size =
+        PSA_AEAD_ENCRYPT_OUTPUT_SIZE( key_type, WRAPPING_ALG, header.payload_size );
+    /* Check for integer overflow. */
+    if( ciphertext_size < header.payload_size )
+    {
+        printf( "Input file too large.\n" );
+        status = DEMO_ERROR;
+        goto exit;
+    }
+
+    /* Load the payload data. */
+    SYS_CHECK( ( buffer = calloc( 1, ciphertext_size ) ) != NULL );
+    SYS_CHECK( fread( buffer, 1, ciphertext_size,
+                      input_file ) == ciphertext_size );
+    if( fread( &extra_byte, 1, 1, input_file ) != 0 )
+    {
+        printf( "Extra garbage after ciphertext\n" );
+        status = DEMO_ERROR;
+        goto exit;
+    }
+    SYS_CHECK( fclose( input_file ) == 0 );
+    input_file = NULL;
+
+    /* Unwrap the data. */
+    PSA_CHECK( psa_aead_decrypt( wrapping_key, WRAPPING_ALG,
+                                 header.iv, WRAPPING_IV_SIZE,
+                                 (uint8_t *) &header, sizeof( header ),
+                                 buffer, ciphertext_size,
+                                 buffer, ciphertext_size,
+                                 &plaintext_size ) );
+    if( plaintext_size != header.payload_size )
+    {
+        printf( "Incorrect payload size in the header.\n" );
+        status = DEMO_ERROR;
+        goto exit;
+    }
+
+    /* Write the output. */
+    SYS_CHECK( ( output_file = fopen( output_file_name, "wb" ) ) != NULL );
+    /* Ensure no stdio buffering of secrets, as such buffers cannot be wiped. */
+    mbedtls_setbuf( output_file, NULL );
+    SYS_CHECK( fwrite( buffer, 1, plaintext_size,
+                       output_file ) == plaintext_size );
+    SYS_CHECK( fclose( output_file ) == 0 );
+    output_file = NULL;
+
+exit:
+    if( input_file != NULL )
+        fclose( input_file );
+    if( output_file != NULL )
+        fclose( output_file );
+    if( buffer != NULL )
+        mbedtls_platform_zeroize( buffer, ciphertext_size );
+    free( buffer );
+    return( status );
+}
+
+static psa_status_t run( enum program_mode mode,
+                         const char *key_file_name,
+                         const char *ladder[], size_t ladder_depth,
+                         const char *input_file_name,
+                         const char *output_file_name )
+{
+    psa_status_t status = PSA_SUCCESS;
+    psa_key_id_t derivation_key = 0;
+    psa_key_id_t wrapping_key = 0;
+
+    /* Initialize the PSA crypto library. */
+    PSA_CHECK( psa_crypto_init( ) );
+
+    /* Generate mode is unlike the others. Generate the master key and exit. */
+    if( mode == MODE_GENERATE )
+        return( generate( key_file_name ) );
+
+    /* Read the master key. */
+    PSA_CHECK( import_key_from_file( PSA_KEY_USAGE_DERIVE | PSA_KEY_USAGE_EXPORT,
+                                     KDF_ALG,
+                                     key_file_name,
+                                     &derivation_key ) );
+
+    /* Calculate the derived key for this session. */
+    PSA_CHECK( derive_key_ladder( ladder, ladder_depth,
+                                  &derivation_key ) );
+
+    switch( mode )
+    {
+        case MODE_SAVE:
+            PSA_CHECK( save_key( derivation_key, output_file_name ) );
+            break;
+        case MODE_UNWRAP:
+            PSA_CHECK( derive_wrapping_key( PSA_KEY_USAGE_DECRYPT,
+                                            derivation_key,
+                                            &wrapping_key ) );
+            PSA_CHECK( unwrap_data( input_file_name, output_file_name,
+                                    wrapping_key ) );
+            break;
+        case MODE_WRAP:
+            PSA_CHECK( derive_wrapping_key( PSA_KEY_USAGE_ENCRYPT,
+                                            derivation_key,
+                                            &wrapping_key ) );
+            PSA_CHECK( wrap_data( input_file_name, output_file_name,
+                                  wrapping_key ) );
+            break;
+        default:
+            /* Unreachable but some compilers don't realize it. */
+            break;
+    }
+
+exit:
+    /* Destroy any remaining key. Deinitializing the crypto library would do
+     * this anyway since they are volatile keys, but explicitly destroying
+     * keys makes the code easier to reuse. */
+    (void) psa_destroy_key( derivation_key );
+    (void) psa_destroy_key( wrapping_key );
+    /* Deinitialize the PSA crypto library. */
+    mbedtls_psa_crypto_free( );
+    return( status );
+}
+
+static void usage( void )
+{
+    printf( "Usage: key_ladder_demo MODE [OPTION=VALUE]...\n" );
+    printf( "Demonstrate the usage of a key derivation ladder.\n" );
+    printf( "\n" );
+    printf( "Modes:\n" );
+    printf( "  generate  Generate the master key\n" );
+    printf( "  save      Save the derived key\n" );
+    printf( "  unwrap    Unwrap (decrypt) input with the derived key\n" );
+    printf( "  wrap      Wrap (encrypt) input with the derived key\n" );
+    printf( "\n" );
+    printf( "Options:\n" );
+    printf( "  input=FILENAME    Input file (required for wrap/unwrap)\n" );
+    printf( "  master=FILENAME   File containing the master key (default: master.key)\n" );
+    printf( "  output=FILENAME   Output file (required for save/wrap/unwrap)\n" );
+    printf( "  label=TEXT        Label for the key derivation.\n" );
+    printf( "                    This may be repeated multiple times.\n" );
+    printf( "                    To get the same key, you must use the same master key\n" );
+    printf( "                    and the same sequence of labels.\n" );
+}
+
+int main( int argc, char *argv[] )
+{
+    const char *key_file_name = "master.key";
+    const char *input_file_name = NULL;
+    const char *output_file_name = NULL;
+    const char *ladder[MAX_LADDER_DEPTH];
+    size_t ladder_depth = 0;
+    int i;
+    enum program_mode mode;
+    psa_status_t status;
+
+    if( argc <= 1 ||
+        strcmp( argv[1], "help" ) == 0 ||
+        strcmp( argv[1], "-help" ) == 0 ||
+        strcmp( argv[1], "--help" ) == 0 )
+    {
+        usage( );
+        return( EXIT_SUCCESS );
+    }
+
+    for( i = 2; i < argc; i++ )
+    {
+        char *q = strchr( argv[i], '=' );
+        if( q == NULL )
+        {
+            printf( "Missing argument to option %s\n", argv[i] );
+            goto usage_failure;
+        }
+        *q = 0;
+        ++q;
+        if( strcmp( argv[i], "input" ) == 0 )
+            input_file_name = q;
+        else if( strcmp( argv[i], "label" ) == 0 )
+        {
+            if( ladder_depth == MAX_LADDER_DEPTH )
+            {
+                printf( "Maximum ladder depth %u exceeded.\n",
+                                (unsigned) MAX_LADDER_DEPTH );
+                return( EXIT_FAILURE );
+            }
+            ladder[ladder_depth] = q;
+            ++ladder_depth;
+        }
+        else if( strcmp( argv[i], "master" ) == 0 )
+            key_file_name = q;
+        else if( strcmp( argv[i], "output" ) == 0 )
+            output_file_name = q;
+        else
+        {
+            printf( "Unknown option: %s\n", argv[i] );
+            goto usage_failure;
+        }
+    }
+
+    if( strcmp( argv[1], "generate" ) == 0 )
+        mode = MODE_GENERATE;
+    else if( strcmp( argv[1], "save" ) == 0 )
+        mode = MODE_SAVE;
+    else if( strcmp( argv[1], "unwrap" ) == 0 )
+        mode = MODE_UNWRAP;
+    else if( strcmp( argv[1], "wrap" ) == 0 )
+        mode = MODE_WRAP;
+    else
+    {
+        printf( "Unknown action: %s\n", argv[1] );
+        goto usage_failure;
+    }
+
+    if( input_file_name == NULL &&
+        ( mode == MODE_WRAP || mode == MODE_UNWRAP ) )
+    {
+        printf( "Required argument missing: input\n" );
+        return( DEMO_ERROR );
+    }
+    if( output_file_name == NULL &&
+        ( mode == MODE_SAVE || mode == MODE_WRAP || mode == MODE_UNWRAP ) )
+    {
+        printf( "Required argument missing: output\n" );
+        return( DEMO_ERROR );
+    }
+
+    status = run( mode, key_file_name,
+                  ladder, ladder_depth,
+                  input_file_name, output_file_name );
+    return( status == PSA_SUCCESS ?
+            EXIT_SUCCESS :
+            EXIT_FAILURE );
+
+usage_failure:
+    usage( );
+    return( EXIT_FAILURE );
+}
+#endif /* MBEDTLS_SHA256_C && MBEDTLS_MD_C && MBEDTLS_AES_C && MBEDTLS_CCM_C && MBEDTLS_PSA_CRYPTO_C && MBEDTLS_FS_IO */

middleware/mbedtls/programs/psa/key_ladder_demo.sh

@@ -0,0 +1,65 @@
+#!/bin/sh
+#
+# Copyright The Mbed TLS Contributors
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -e -u
+
+program="${0%/*}"/key_ladder_demo
+files_to_clean=
+
+run () {
+    echo
+    echo "# $1"
+    shift
+    echo "+ $*"
+    "$@"
+}
+
+if [ -e master.key ]; then
+    echo "# Reusing the existing master.key file."
+else
+    files_to_clean="$files_to_clean master.key"
+    run "Generate a master key." \
+        "$program" generate master=master.key
+fi
+
+files_to_clean="$files_to_clean input.txt hello_world.wrap"
+echo "Here is some input. See it wrapped." >input.txt
+run "Derive a key and wrap some data with it." \
+    "$program" wrap master=master.key label=hello label=world \
+               input=input.txt output=hello_world.wrap
+
+files_to_clean="$files_to_clean hello_world.txt"
+run "Derive the same key again and unwrap the data." \
+    "$program" unwrap master=master.key label=hello label=world \
+               input=hello_world.wrap output=hello_world.txt
+run "Compare the unwrapped data with the original input." \
+    cmp input.txt hello_world.txt
+
+files_to_clean="$files_to_clean hellow_orld.txt"
+! run "Derive a different key and attempt to unwrap the data. This must fail." \
+  "$program" unwrap master=master.key input=hello_world.wrap output=hellow_orld.txt label=hellow label=orld
+
+files_to_clean="$files_to_clean hello.key"
+run "Save the first step of the key ladder, then load it as a master key and construct the rest of the ladder." \
+    "$program" save master=master.key label=hello \
+               input=hello_world.wrap output=hello.key
+run "Check that we get the same key by unwrapping data made by the other key." \
+    "$program" unwrap master=hello.key label=world \
+               input=hello_world.wrap output=hello_world.txt
+
+# Cleanup
+rm -f $files_to_clean

middleware/mbedtls/programs/psa/psa_constant_names.c

@@ -0,0 +1,321 @@
+/*
+ *  Copyright The Mbed TLS Contributors
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *  not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+#include <errno.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "psa/crypto.h"
+
+/* This block is present to support Visual Studio builds prior to 2015 */
+#if defined(_MSC_VER) && _MSC_VER < 1900
+#include <stdarg.h>
+int snprintf( char *s, size_t n, const char *fmt, ... )
+{
+    int ret;
+    va_list argp;
+
+    /* Avoid calling the invalid parameter handler by checking ourselves */
+    if( s == NULL || n == 0 || fmt == NULL )
+        return( -1 );
+
+    va_start( argp, fmt );
+#if defined(_TRUNCATE) && !defined(__MINGW32__)
+    ret = _vsnprintf_s( s, n, _TRUNCATE, fmt, argp );
+#else
+    ret = _vsnprintf( s, n, fmt, argp );
+    if( ret < 0 || (size_t) ret == n )
+    {
+        s[n-1] = '\0';
+        ret = -1;
+    }
+#endif
+    va_end( argp );
+
+    return( ret );
+}
+#endif
+
+static void append(char **buffer, size_t buffer_size,
+                   size_t *required_size,
+                   const char *string, size_t length)
+{
+    *required_size += length;
+    if (*required_size < buffer_size) {
+        memcpy(*buffer, string, length);
+        *buffer += length;
+    }
+}
+
+static void append_integer(char **buffer, size_t buffer_size,
+                           size_t *required_size,
+                           const char *format /*printf format for value*/,
+                           unsigned long value)
+{
+    size_t n = snprintf(*buffer, buffer_size - *required_size, format, value);
+    if (n < buffer_size - *required_size) *buffer += n;
+    *required_size += n;
+}
+
+/* The code of these function is automatically generated and included below. */
+static const char *psa_ecc_family_name(psa_ecc_family_t curve);
+static const char *psa_dh_family_name(psa_dh_family_t group);
+static const char *psa_hash_algorithm_name(psa_algorithm_t hash_alg);
+
+static void append_with_curve(char **buffer, size_t buffer_size,
+                              size_t *required_size,
+                              const char *string, size_t length,
+                              psa_ecc_family_t curve)
+{
+    const char *family_name = psa_ecc_family_name(curve);
+    append(buffer, buffer_size, required_size, string, length);
+    append(buffer, buffer_size, required_size, "(", 1);
+    if (family_name != NULL) {
+        append(buffer, buffer_size, required_size,
+               family_name, strlen(family_name));
+    } else {
+        append_integer(buffer, buffer_size, required_size,
+                       "0x%02x", curve);
+    }
+    append(buffer, buffer_size, required_size, ")", 1);
+}
+
+static void append_with_group(char **buffer, size_t buffer_size,
+                              size_t *required_size,
+                              const char *string, size_t length,
+                              psa_dh_family_t group)
+{
+    const char *group_name = psa_dh_family_name(group);
+    append(buffer, buffer_size, required_size, string, length);
+    append(buffer, buffer_size, required_size, "(", 1);
+    if (group_name != NULL) {
+        append(buffer, buffer_size, required_size,
+               group_name, strlen(group_name));
+    } else {
+        append_integer(buffer, buffer_size, required_size,
+                       "0x%02x", group);
+    }
+    append(buffer, buffer_size, required_size, ")", 1);
+}
+
+typedef const char *(*psa_get_algorithm_name_func_ptr)(psa_algorithm_t alg);
+
+static void append_with_alg(char **buffer, size_t buffer_size,
+                            size_t *required_size,
+                            psa_get_algorithm_name_func_ptr get_name,
+                            psa_algorithm_t alg)
+{
+    const char *name = get_name(alg);
+    if (name != NULL) {
+        append(buffer, buffer_size, required_size,
+               name, strlen(name));
+    } else {
+        append_integer(buffer, buffer_size, required_size,
+                       "0x%08lx", alg);
+    }
+}
+
+#include "psa_constant_names_generated.c"
+
+static int psa_snprint_status(char *buffer, size_t buffer_size,
+                              psa_status_t status)
+{
+    const char *name = psa_strerror(status);
+    if (name == NULL) {
+        return snprintf(buffer, buffer_size, "%ld", (long) status);
+    } else {
+        size_t length = strlen(name);
+        if (length < buffer_size) {
+            memcpy(buffer, name, length + 1);
+            return (int) length;
+        } else {
+            return (int) buffer_size;
+        }
+    }
+}
+
+static int psa_snprint_ecc_curve(char *buffer, size_t buffer_size,
+                                 psa_ecc_family_t curve)
+{
+    const char *name = psa_ecc_family_name(curve);
+    if (name == NULL) {
+        return snprintf(buffer, buffer_size, "0x%02x", (unsigned) curve);
+    } else {
+        size_t length = strlen(name);
+        if (length < buffer_size) {
+            memcpy(buffer, name, length + 1);
+            return (int) length;
+        } else {
+            return (int) buffer_size;
+        }
+    }
+}
+
+static int psa_snprint_dh_group(char *buffer, size_t buffer_size,
+                                psa_dh_family_t group)
+{
+    const char *name = psa_dh_family_name(group);
+    if (name == NULL) {
+        return snprintf(buffer, buffer_size, "0x%02x", (unsigned) group);
+    } else {
+        size_t length = strlen(name);
+        if (length < buffer_size) {
+            memcpy(buffer, name, length + 1);
+            return (int) length;
+        } else {
+            return (int) buffer_size;
+        }
+    }
+}
+
+static void usage(const char *program_name)
+{
+    printf("Usage: %s TYPE VALUE [VALUE...]\n",
+           program_name == NULL ? "psa_constant_names" : program_name);
+    printf("Print the symbolic name whose numerical value is VALUE in TYPE.\n");
+    printf("Supported types (with = between aliases):\n");
+    printf("  alg=algorithm         Algorithm (psa_algorithm_t)\n");
+    printf("  curve=ecc_curve       Elliptic curve identifier (psa_ecc_family_t)\n");
+    printf("  group=dh_group        Diffie-Hellman group identifier (psa_dh_family_t)\n");
+    printf("  type=key_type         Key type (psa_key_type_t)\n");
+    printf("  usage=key_usage       Key usage (psa_key_usage_t)\n");
+    printf("  error=status          Status code (psa_status_t)\n");
+}
+
+typedef enum {
+    TYPE_STATUS,
+} signed_value_type;
+
+int process_signed(signed_value_type type, long min, long max, char **argp)
+{
+    for (; *argp != NULL; argp++) {
+        char buffer[200];
+        char *end;
+        long value = strtol(*argp, &end, 0);
+        if (*end) {
+            printf("Non-numeric value: %s\n", *argp);
+            return EXIT_FAILURE;
+        }
+        if (value < min || (errno == ERANGE && value < 0)) {
+            printf("Value too small: %s\n", *argp);
+            return EXIT_FAILURE;
+        }
+        if (value > max || (errno == ERANGE && value > 0)) {
+            printf("Value too large: %s\n", *argp);
+            return EXIT_FAILURE;
+        }
+
+        switch (type) {
+            case TYPE_STATUS:
+                psa_snprint_status(buffer, sizeof(buffer),
+                                   (psa_status_t) value);
+                break;
+        }
+        puts(buffer);
+    }
+
+    return EXIT_SUCCESS;
+}
+
+typedef enum {
+    TYPE_ALGORITHM,
+    TYPE_ECC_CURVE,
+    TYPE_DH_GROUP,
+    TYPE_KEY_TYPE,
+    TYPE_KEY_USAGE,
+} unsigned_value_type;
+
+int process_unsigned(unsigned_value_type type, unsigned long max, char **argp)
+{
+    for (; *argp != NULL; argp++) {
+        char buffer[200];
+        char *end;
+        unsigned long value = strtoul(*argp, &end, 0);
+        if (*end) {
+            printf("Non-numeric value: %s\n", *argp);
+            return EXIT_FAILURE;
+        }
+        if (value > max || errno == ERANGE) {
+            printf("Value out of range: %s\n", *argp);
+            return EXIT_FAILURE;
+        }
+
+        switch (type) {
+            case TYPE_ALGORITHM:
+                psa_snprint_algorithm(buffer, sizeof(buffer),
+                                      (psa_algorithm_t) value);
+                break;
+            case TYPE_ECC_CURVE:
+                psa_snprint_ecc_curve(buffer, sizeof(buffer),
+                                      (psa_ecc_family_t) value);
+                break;
+            case TYPE_DH_GROUP:
+                psa_snprint_dh_group(buffer, sizeof(buffer),
+                                     (psa_dh_family_t) value);
+                break;
+            case TYPE_KEY_TYPE:
+                psa_snprint_key_type(buffer, sizeof(buffer),
+                                     (psa_key_type_t) value);
+                break;
+            case TYPE_KEY_USAGE:
+                psa_snprint_key_usage(buffer, sizeof(buffer),
+                                      (psa_key_usage_t) value);
+                break;
+        }
+        puts(buffer);
+    }
+
+    return EXIT_SUCCESS;
+}
+
+int main(int argc, char *argv[])
+{
+    if (argc <= 1 ||
+        !strcmp(argv[1], "help") ||
+        !strcmp(argv[1], "--help"))
+    {
+        usage(argv[0]);
+        return EXIT_FAILURE;
+    }
+
+    if (!strcmp(argv[1], "error") || !strcmp(argv[1], "status")) {
+        /* There's no way to obtain the actual range of a signed type,
+         * so hard-code it here: psa_status_t is int32_t. */
+        return process_signed(TYPE_STATUS, INT32_MIN, INT32_MAX,
+                              argv + 2);
+    } else if (!strcmp(argv[1], "alg") || !strcmp(argv[1], "algorithm")) {
+        return process_unsigned(TYPE_ALGORITHM, (psa_algorithm_t) (-1),
+                                argv + 2);
+    } else if (!strcmp(argv[1], "curve") || !strcmp(argv[1], "ecc_curve")) {
+        return process_unsigned(TYPE_ECC_CURVE, (psa_ecc_family_t) (-1),
+                                argv + 2);
+    } else if (!strcmp(argv[1], "group") || !strcmp(argv[1], "dh_group")) {
+        return process_unsigned(TYPE_DH_GROUP, (psa_dh_family_t) (-1),
+                                argv + 2);
+    } else if (!strcmp(argv[1], "type") || !strcmp(argv[1], "key_type")) {
+        return process_unsigned(TYPE_KEY_TYPE, (psa_key_type_t) (-1),
+                                argv + 2);
+    } else if (!strcmp(argv[1], "usage") || !strcmp(argv[1], "key_usage")) {
+        return process_unsigned(TYPE_KEY_USAGE, (psa_key_usage_t) (-1),
+                                argv + 2);
+    } else {
+        printf("Unknown type: %s\n", argv[1]);
+        return EXIT_FAILURE;
+    }
+}