<?xml version="1.0" encoding="UTF-8"?>
<!--

 File Name          : KMS.xml
 Description        : Contextual documentation of the KMS
                      for all MCU series

 COPYRIGHT(c) 2020 STMicroelectronics

====================================================================
| version 0.1  |  F. Gohier        | Creation                      |
====================================================================

Contextual help database for KMS middleware, it contains:
    - peripheral generic information under <peripheral> node
    - information about peripheral mode under <mode> node
    - details about the peripheral configuration under <config> node

-->
<ctx_periph_help xsi:noNamespaceSchemaLocation="../../../../../../../doc/V4/Development/Specifications/contextualDocumentation/peripherals.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <!-- serie "ref" is the MCU series you want to document e.g. STM32F0, STM32F1... -->
    <serie ref="Default">
        <peripheral>
            <!-- Title of the contextual widget -->
            <title>KMS</title>
            <!-- Generic description displayed in the first panel of the tooltip -->
            <extract>STM32 Key Management Services</extract>
            <!-- Detailed information displayed in the expandable panel when no MCU series has been selected -->
            <help_text>Key Management Services (KMS) provides cryptographic services through the standard &lt;br/&gt;
                PKCS#11 APIs (developed by OASIS) allowing to abstract the key value to the caller &lt;br/&gt;
                (using object ID and not directly the key value). KMS can be executed inside a &lt;br/&gt;
                protected/isolated environment in order to ensure that key value can’t be accessed by &lt;br/&gt;
                an unauthorized code running outside the protected/isolated environment. &lt;br/&gt;
                KMS manages 3 types of keys: &lt;br/&gt;
                    - Static Embedded keys : &lt;br/&gt;
                        - Predefined keys embedded within the code that can’t be modified &lt;br/&gt;
                    - Updatable keys with Static ID : &lt;br/&gt;
                        - Keys IDs are predefined in the system &lt;br/&gt;
                        - Key(s) can be injected or updated in a NVM storage via a secure &lt;br/&gt;
                          procedure using. Static Embedded Keys(authenticity check, data &lt;br/&gt;
                          integrity check and data decryption) &lt;br/&gt;
                        - Key can’t be deleted &lt;br/&gt;
                    - Updatable keys with dynamic ID : &lt;br/&gt;
                        - Keys IDs are defined when keys are created using KMS services &lt;br/&gt;
                        - Key value can be updated using KMS services &lt;br/&gt;
                        - Key can be deleted &lt;br/&gt;
                KMS only supports a subset of PKCS#11 APIs: &lt;br/&gt;
                    - Object management functions: creation / update / deletion &lt;br/&gt;
                    - AES Encrypt &amp; Decrypt functions &lt;br/&gt;
                    - SHA Digest functions &lt;br/&gt;
                    - RSA and ECDSA Sign / Verify functions &lt;br/&gt;
            </help_text>
            <!-- Links that will be displayed on the help widgets:
            - filter: In case a selection needs to be made, use it as regexp on mcu name (STM32F042T6x)
            - display: string that will be displayed in front of the hyperlink
            - type: the type of file you want to display ("txt" "pdf", "chm", "html", "dynamic")
            dynamic stands for the document that have to be retrieved from the JSON database
            - reference: path to the document to be displayed (http or local path)
              If the file is dynamic, indicate the kind of file you want to display:
                * dataSheet => for datasheet document type
                * appNote => for application note document type
                * refMan => for reference manual document type
                * usrMan => for user Manual document type
                * prgMan => for Programming Manual document type
                * errSheet => for Errata Sheet document type
            - index: for pdf,html and chm type it specifies the chapter where the viewer will point
            for dynamic file it can specify a chapter except for application notes where it specifies
            the document display name (e.g. AN1015). This field may be left blank, then the full document
            is displayed -->
            <link display="UM2262: Getting started with the X-CUBE-SBSFU STM32Cube Expansion Package" type="pdf" reference="https://www.st.com/st-web-ui/static/active/en/resource/technical/document/user_manual/DM00414687.pdf" index=""/>
        </peripheral>
        <mode>
            <!-- @TODO Describe the mode TBD for CubeMX -->
        </mode>
        <config>
            <!-- @TODO configuration panel TBD for CubeMX -->
        </config>
    </serie>
    <serie ref="STM32WL">
        <peripheral>
            <!-- Title of the contextual widget -->
            <title>KMS</title>
            <!-- Generic description displayed in the first panel of the tooltip -->
            <extract>STM32 Key Management Services</extract>
            <!-- Detailed information displayed in the expandable panel when no MCU series has been selected -->
            <help_text>Key Management Services (KMS) provides cryptographic services through the standard &lt;br/&gt;
                PKCS#11 APIs (developed by OASIS) allowing to abstract the key value to the caller &lt;br/&gt;
                (using object ID and not directly the key value). KMS can be executed inside a &lt;br/&gt;
                protected/isolated environment in order to ensure that key value can’t be accessed by &lt;br/&gt;
                an unauthorized code running outside the protected/isolated environment. &lt;br/&gt;
                KMS manages 3 types of keys: &lt;br/&gt;
                    - Static Embedded keys : &lt;br/&gt;
                        - Predefined keys embedded within the code that can’t be modified &lt;br/&gt;
                    - Updatable keys with Static ID : &lt;br/&gt;
                        - Keys IDs are predefined in the system &lt;br/&gt;
                        - Key(s) can be injected or updated in a NVM storage via a secure &lt;br/&gt;
                          procedure using. Static Embedded Keys(authenticity check, data &lt;br/&gt;
                          integrity check and data decryption) &lt;br/&gt;
                        - Key can’t be deleted &lt;br/&gt;
                    - Updatable keys with dynamic ID : &lt;br/&gt;
                        - Keys IDs are defined when keys are created using KMS services &lt;br/&gt;
                        - Key value can be updated using KMS services &lt;br/&gt;
                        - Key can be deleted &lt;br/&gt;
                KMS only supports a subset of PKCS#11 APIs: &lt;br/&gt;
                    - Object management functions: creation / update / deletion &lt;br/&gt;
                    - AES Encrypt &amp; Decrypt functions &lt;br/&gt;
                    - SHA Digest functions &lt;br/&gt;
                    - RSA Sign / Verify functions &lt;br/&gt;
                    - ECDSA Sign functions &lt;br/&gt;
            </help_text>
            <!-- Links that will be displayed on the help widgets:
            - filter: In case a selection needs to be made, use it as regexp on mcu name (STM32F042T6x)
            - display: string that will be displayed in front of the hyperlink
            - type: the type of file you want to display ("txt" "pdf", "chm", "html", "dynamic")
            dynamic stands for the document that have to be retrieved from the JSON database
            - reference: path to the document to be displayed (http or local path)
              If the file is dynamic, indicate the kind of file you want to display:
                * dataSheet => for datasheet document type
                * appNote => for application note document type
                * refMan => for reference manual document type
                * usrMan => for user Manual document type
                * prgMan => for Programming Manual document type
                * errSheet => for Errata Sheet document type
            - index: for pdf,html and chm type it specifies the chapter where the viewer will point
            for dynamic file it can specify a chapter except for application notes where it specifies
            the document display name (e.g. AN1015). This field may be left blank, then the full document
            is displayed -->
            <link display="UM2262: Getting started with the X-CUBE-SBSFU STM32Cube Expansion Package" type="pdf" reference="https://www.st.com/st-web-ui/static/active/en/resource/technical/document/user_manual/DM00414687.pdf" index=""/>
        </peripheral>
        <mode>
            <!-- @TODO Describe the mode TBD for CubeMX -->
        </mode>
        <config>
            <!-- @TODO configuration panel TBD for CubeMX -->
        </config>
    </serie>
</ctx_periph_help>
