Selaa lähdekoodia

psa: add README.md and doxygen header

Marco Oliverio 2 vuotta sitten
vanhempi
commit
b8635efda7

+ 1 - 1
doc/dox_comments/header_files/doxygen_groups.h

@@ -226,7 +226,7 @@
 
     If compiled in, the module supports IoT-Safe random number generator as source of entropy for wolfCrypt.
 
-
+    \defgroup PSA Platform Security Architecture (PSA) API
     \defgroup Keys Key and Cert Conversion
     \defgroup Logging Logging
     \defgroup Math Math API

+ 1 - 0
doc/dox_comments/header_files/doxygen_pages.h

@@ -18,6 +18,7 @@
         <li>\ref Compression</li>
         <li>\ref Error</li>
         <li>\ref IoTSafe</li>
+        <li>\ref PSA</li>
         <li>\ref Keys</li>
         <li>\ref Logging</li>
         <li>\ref Math</li>

+ 96 - 0
doc/dox_comments/header_files/psa.h

@@ -0,0 +1,96 @@
+/*!
+    \ingroup PSA
+    \brief This function enables PSA support on the given context.
+
+    \param ctx pointer to the WOLFSSL_CTX object on which the PSA support must be enabled
+    \return WOLFSSL_SUCCESS on success
+    \return BAD_FUNC_ARG if ctx == NULL
+
+    _Example_
+    \code
+    WOLFSSL_CTX *ctx;
+    ctx = wolfSSL_CTX_new(wolfTLSv1_2_client_method());
+    if (!ctx)
+        return NULL;
+    ret = wolfSSL_CTX_psa_enable(ctx);
+    if (ret != WOLFSSL_SUCCESS)
+        printf("can't enable PSA on ctx");
+
+    \endcode
+
+    \sa wolfSSL_set_psa_ctx
+*/
+WOLFSSL_API int wolfSSL_CTX_psa_enable(WOLFSSL_CTX *ctx);
+
+/*!
+    \ingroup PSA
+
+    \brief This function setup the PSA context for the given SSL session
+
+    \param ssl pointer to the WOLFSSL where the ctx will be enabled
+    \param ctx pointer to a struct psa_ssl_ctx (must be unique for a ssl session)
+
+    \return WOLFSSL_SUCCESS on success
+    \return BAD_FUNC_ARG if ssl or ctx are NULL
+
+    This function setup the PSA context for the TLS callbacks to the given SSL
+    session. At the end of the session, the resources used by the context
+    should be freed using wolfSSL_free_psa_ctx().
+
+    _Example_
+    \code
+    // Create new ssl session
+    WOLFSSL *ssl;
+    struct psa_ssl_ctx psa_ctx = { 0 };
+    ssl = wolfSSL_new(ctx);
+    if (!ssl)
+        return NULL;
+    // setup PSA context
+    ret = wolfSSL_set_psa_ctx(ssl, ctx);
+    \endcode
+
+    \sa wolfSSL_psa_set_private_key_id
+    \sa wolfSSL_psa_free_psa_ctx
+*/
+WOLFSSL_API int wolfSSL_set_psa_ctx(WOLFSSL *ssl, struct psa_ssl_ctx *ctx);
+
+/*!
+    \ingroup PSA
+    \brief This function releases the resources used by a PSA context
+
+    \param ctx pointer to a struct psa_ssl_ctx
+
+    \sa wolfSSL_set_psa_ctx
+*/
+WOLFSSL_API void wolfSSL_free_psa_ctx(struct psa_ssl_ctx *ctx);
+
+/*!
+    \ingroup PSA
+    \brief This function set the private key used by an SSL session
+
+    \param ctx pointer to a struct psa_ssl_ctx
+    \param id PSA id of the key to be used as private key
+
+    _Example_
+    \code
+    // Create new ssl session
+    WOLFSSL *ssl;
+    struct psa_ssl_ctx psa_ctx = { 0 };
+    psa_key_id_t key_id;
+
+    // key provisioning already done
+    get_private_key_id(&key_id);
+
+    ssl = wolfSSL_new(ctx);
+    if (!ssl)
+        return NULL;
+
+    wolfSSL_psa_set_private_key_id(&psa_ctx, key_id);
+    wolfSSL_set_psa_ctx(ssl, ctx);
+    \endcode
+
+    \sa wolfSSL_set_psa_ctx
+*/
+
+WOLFSSL_API int wolfSSL_psa_set_private_key_id(struct psa_ssl_ctx *ctx,
+                                               psa_key_id_t id);

+ 1 - 0
wolfcrypt/src/include.am

@@ -191,3 +191,4 @@ src_libwolfssl_la_SOURCES += wolfcrypt/src/port/psa/psa_hash.c
 src_libwolfssl_la_SOURCES += wolfcrypt/src/port/psa/psa_aes.c
 src_libwolfssl_la_SOURCES += wolfcrypt/src/port/psa/psa_pkcbs.c
 endif
+EXTRA_DIST += wolfcrypt/src/port/psa/README.md

+ 115 - 0
wolfcrypt/src/port/psa/README.md

@@ -0,0 +1,115 @@
+wolfSSL using Platform Security Architecture (PSA)
+=================================================
+
+## Overview
+
+wolfSSL can be configured to use a PSA library for the following operations:
+* hashes: SHA-1, SHA-224, SAH-256
+* AES: AES-ECB, AES-CBC, AES-CTR, AES-GCM, AES-CCM
+* ECDH PK callbacks (P-256)
+* ECDSA PK callbacks (P-256)
+* RNG
+
+Client certificates are not supported.
+
+## Build
+### Basic configuration
+
+To enable PSA support in wolfSSL you need to provide the name of the library
+that implements the PSA interface using `--with-psa-lib-name=LIBNAME`. You may
+also provide the path to the library headers (with `--with-psa-include`) and to
+to the PSA library itself (with `--with-psa-lib`). As an example, to use mbedtls
+PSA implementation you may use:
+
+```
+./configure --enable-psa --with-psa-include=/dir/to/mbedtls/include --with-psa-lib=/dir/to/mbedtls/library --with-psa-lib-name=mbedcrypto
+```
+
+### Customize build
+
+You can switch off some of the algorithms supported using the following defines:
+
+ * `WOLFSSL_PSA_NO_RNG`: disable PSA random generator support
+ * `WOLFSSL_PSA_NO_HASH`: disable PSA hashing support
+ * `WOLFSSL_PSA_NO_AES`: disable PSA AES support
+ * `WOLFSSL_PSA_NO_PKCBS`: disable PK callbacks support
+
+## Supporting non-thread safe PSA implementation
+
+If the PSA implementation used is not thread-safe, you can serialize all calls
+to the PSA library using the define `WOLFSSL_PSA_GLOBAL_LOCK`.
+
+## Using PSA PK callbacks
+
+To use Public Key PSA callbacks you need to enable them using the function:
+
+`wolfSSL_CTX_psa_enable(WOLFSSL_CTX *ctx)`
+
+Context information regarding a single SSL session is stored inside a `struct
+psa_ssl_ctx`.  The user needs to define and setup a `struct psa_ssl_ctx`, then
+to attach it to an ssl session with `wolfSSL_set_psa_ctx(WOLFSSL *ssl, struct
+psa_ssl_ctx *ctx)`. When the session is over, the application should free the
+psa context with `wolfSSL_free_psa_ctx(struct psa_ssl_ctx *ctx)`.
+
+Example:
+```
+    struct psa_ssl_ctx psa_ctx = { 0 };
+    WOLFSSL_CTX*     ctx;
+    WOLFSSL*         ssl;
+    int ret
+
+    /* WOLFSSL_CTX initialization here */
+
+    ret = wolfSSL_CTX_psa_enable(ctx);
+    if (ret != WOLFSSL_SUCCESS)
+        printf("can't enable PSA on ctx");
+
+    ssl = wolfSSL_new(ctx);
+    ret = wolfSSL_set_psa_ctx(ssl, &psa_ctx);
+    if (ret != WOLFSSL_SUCCESS)
+        printf("can't enable PSA on ctx");
+
+    /* SSL communication */
+
+    wolfSSL_free_psa_ctx(&psa_ctx);
+    SSL_free(ssl); ssl = NULL;
+    SSL_CTX_free(ctx); ctx = NULL;
+```
+
+### Setup server side private key
+
+On the server side, the private key of the server should be loaded inside the
+PSA engine storage. To use the key inside the ssl session you have to invoke
+`wolfSSL_psa_set_private_key_id(struct psa_ssl_ctx *ctx, psa_key_id_t id);`. The
+key needs to have `PSA_KEY_USAGE_SIGN_HASH` usage flag set.  Example:
+
+```
+    psa_key_attributes_t key_attr = { 0 };
+    struct psa_ssl_ctx psa_ctx = { 0 };
+    psa_key_type_t key_type;
+    psa_key_id_t key_id;
+    psa_status_t status;
+
+    key_type = PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1);
+
+    psa_set_key_type(&key_attr, key_type);
+    psa_set_key_usage_flags(&key_attr, PSA_KEY_USAGE_SIGN_HASH);
+    psa_set_key_algorithm(&key_attr, PSA_ALG_ECDSA_ANY);
+
+    status = psa_import_key(&key_attr, ecc_key_256,
+                            sizeof(ecc_key_256), &key_id);
+
+    if (status != PSA_SUCCESS) {
+        fprintf(stderr,
+                "ERROR: provisioning of private key failed: [%d] \n", status);
+        exit(-1);
+    }
+
+    wolfSSL_psa_set_private_key_id(&psa_ctx, key_id);
+}
+
+```
+
+## Additional note
+    - AES-GCM, AES-CTR, AES-CCM are not implemented directly. The software
+      implementation uses the AES-ECB PSA one to implement them.