Merge pull request #301 from gilles-peskine-arm/pages-psa-landing-page
Create PSA landing pages
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..0f38bfa
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,19 @@
+PANDOC = pandoc
+
+default: all
+
+all_markdown = \
+ psa/index.md \
+ psa/accel/index.md \
+ psa/entropy/index.md \
+ psa/se/index.md \
+ # This line is intentionally left blank
+
+html: $(all_markdown:.md=.html)
+all: html
+
+.SUFFIXES:
+.SUFFIXES: .md .html
+
+.md.html:
+ $(PANDOC) -o $@ $<
diff --git a/docs/psa/accel/index.html b/docs/psa/accel/index.html
new file mode 100644
index 0000000..d3c4825
--- /dev/null
+++ b/docs/psa/accel/index.html
@@ -0,0 +1,5 @@
+<h1 id="psa-cryptographic-accelerator-interface">PSA cryptographic accelerator interface</h1>
+<p>The cryptographic accelerator driver interface lets you write drivers for hardware that performs cryptographic operations with keys in clear text. You can plug such drivers into any implementation of the <a href="../#application-programming-interface">PSA Cryptography API</a>.</p>
+<p><strong>Status: draft</strong> — major changes are still likely.</p>
+<p><strong>Documentation</strong>: for now, please see the header file: <a href="https://github.com/ARMmbed/mbed-crypto/blob/development/include/psa/crypto_accel_driver.h"><code>include/psa/crypto_accel_driver.h</code></a></p>
+<p><strong>Mbed Crypto support status</strong>: Not implemented yet. For now, accelerators use the <a href="https://tls.mbed.org/kb/development/hw_acc_guidelines">Mbed TLS alternative cryptography engine interface</a>.</p>
diff --git a/docs/psa/accel/index.md b/docs/psa/accel/index.md
new file mode 100644
index 0000000..9027883
--- /dev/null
+++ b/docs/psa/accel/index.md
@@ -0,0 +1,11 @@
+# PSA cryptographic accelerator interface
+
+The cryptographic accelerator driver interface lets you write drivers for hardware that performs cryptographic operations with keys in clear text.
+You can plug such drivers into any implementation of the [PSA Cryptography API](../#application-programming-interface).
+
+**Status: draft** — major changes are still likely.
+
+**Documentation**: for now, please see the header file:
+[`include/psa/crypto_accel_driver.h`](https://github.com/ARMmbed/mbed-crypto/blob/development/include/psa/crypto_accel_driver.h)
+
+**Mbed Crypto support status**: Not implemented yet. For now, accelerators use the [Mbed TLS alternative cryptography engine interface](https://tls.mbed.org/kb/development/hw_acc_guidelines).
diff --git a/docs/psa/entropy/index.html b/docs/psa/entropy/index.html
new file mode 100644
index 0000000..4784293
--- /dev/null
+++ b/docs/psa/entropy/index.html
@@ -0,0 +1,5 @@
+<h1 id="psa-entropy-source-driver-interface">PSA entropy source driver interface</h1>
+<p>The entropy source driver interface lets you write drivers for Hardware Random Number Generators (HRNG), also known as True Random Number Generators (TRNG). You can plug such drivers into any implementation of the <a href="../#application-programming-interface">PSA Cryptography API</a>.</p>
+<p><strong>Status: draft</strong> — major changes are still likely.</p>
+<p><strong>Documentation</strong>: for now, please see the header file: <a href="https://github.com/ARMmbed/mbed-crypto/blob/development/include/psa/crypto_entropy_driver.h"><code>include/psa/crypto_entropy_driver.h</code></a></p>
+<p><strong>Mbed Crypto support status</strong>: Not implemented yet. For now, entropy sources use the <a href="https://tls.mbed.org/kb/how-to/add-entropy-sources-to-entropy-pool">Mbed TLS entropy module</a>.</p>
diff --git a/docs/psa/entropy/index.md b/docs/psa/entropy/index.md
new file mode 100644
index 0000000..0891ad1
--- /dev/null
+++ b/docs/psa/entropy/index.md
@@ -0,0 +1,11 @@
+# PSA entropy source driver interface
+
+The entropy source driver interface lets you write drivers for Hardware Random Number Generators (HRNG), also known as True Random Number Generators (TRNG).
+You can plug such drivers into any implementation of the [PSA Cryptography API](../#application-programming-interface).
+
+**Status: draft** — major changes are still likely.
+
+**Documentation**: for now, please see the header file:
+[`include/psa/crypto_entropy_driver.h`](https://github.com/ARMmbed/mbed-crypto/blob/development/include/psa/crypto_entropy_driver.h)
+
+**Mbed Crypto support status**: Not implemented yet. For now, entropy sources use the [Mbed TLS entropy module](https://tls.mbed.org/kb/how-to/add-entropy-sources-to-entropy-pool).
diff --git a/docs/psa/index.html b/docs/psa/index.html
new file mode 100644
index 0000000..2ab33ec
--- /dev/null
+++ b/docs/psa/index.html
@@ -0,0 +1,20 @@
+<h1 id="psa-cryptography-interfaces">PSA cryptography interfaces</h1>
+<p>This page contains technical information about the cryptography interfaces in the Arm Platform Security Architecture (PSA) and related documents and software. For more information about the Platform Security Architecture, see <a href="https://developer.arm.com/architectures/security-architectures/platform-security-architecture">the Arm Developer website</a>.</p>
+<h2 id="application-programming-interface">Application programming interface</h2>
+<p>The PSA Cryptography API is a C programming interface for applications that wish to store cryptographic keys and use them to perform cryptographic operations.</p>
+<p><strong>Status: beta</strong> — version 1.0.0 beta 3. Minor changes and clarifications are planned before 1.0. Additional features are planned for 1.x releases.</p>
+<p><strong>Reference documentation</strong>: <a href="../html/index.html">HTML</a>, <a href="../PSA_Cryptography_API_Specification.pdf">PDF</a></p>
+<p><strong>Reference implementation</strong>: <a href="https://github.com/ARMmbed/mbed-crypto">Mbed Crypto</a></p>
+<h2 id="hardware-abstraction-layer">Hardware abstraction layer</h2>
+<p>PSA includes functional specifications describing a hardware abstraction layer covering <a href="accel/">cryptographic accelerators</a>, <a href="se/">secure elements</a> and <a href="entropy/">entropy sources</a>.</p>
+<h3 id="accelerator-driver-interface">Accelerator driver interface</h3>
+<p>The cryptographic accelerator driver interface lets you write drivers for hardware that performs cryptographic operations with keys in clear text. You can plug such drivers into any implementation of the PSA Cryptography API.</p>
+<p>For more information, see <a href="accel/">PSA cryptography accelerator driver interface</a>.</p>
+<h3 id="secure-element-driver-interface">Secure element driver interface</h3>
+<p>The secure element driver interface lets you write drivers for external cryptoprocessors such as secure elements (SE), smart cards and hardware security modules (HSM) that perform operations on keys that never leave the external processor and are accessed only through opaque handles. You can plug such drivers into any implementation of the PSA Cryptography API.</p>
+<p>For more information, see <a href="se/">PSA secure element driver interface</a>.</p>
+<h3 id="entropy-source-driver-interface">Entropy source driver interface</h3>
+<p>The entropy source driver interface lets you write drivers for Hardware Random Number Generators (HRNG), also known as True Random Number Generators (TRNG). You can plug such drivers into any implementation of the PSA Cryptography API.</p>
+<p>For more information, see <a href="entropy/">PSA entropy source driver interface</a>.</p>
+<h2 id="feedback">Feedback</h2>
+<p>Arm welcomes feedback on the design of the PSA cryptography interfaces. If you think something could be improved, please open an <a href="https://github.com/ARMmbed/mbed-crypto/labels/api-spec">issue on the Mbed Crypto GitHub repository</a>. Alternatively, if you prefer to provide your feedback privately, please email us at <code>mbed-crypto@arm.com</code>. All feedback received by email is treated confidentially.</p>
diff --git a/docs/psa/index.md b/docs/psa/index.md
new file mode 100644
index 0000000..14a59bc
--- /dev/null
+++ b/docs/psa/index.md
@@ -0,0 +1,47 @@
+# PSA cryptography interfaces
+
+This page contains technical information about the cryptography interfaces in the Arm Platform Security Architecture (PSA) and related documents and software.
+For more information about the Platform Security Architecture, see [the Arm Developer website](https://developer.arm.com/architectures/security-architectures/platform-security-architecture).
+
+## Application programming interface
+
+The PSA Cryptography API is a C programming interface for applications that wish to store cryptographic keys and use them to perform cryptographic operations.
+
+**Status: beta** — version 1.0.0 beta 3. Minor changes and clarifications are planned before 1.0. Additional features are planned for 1.x releases.
+
+**Reference documentation**:
+[HTML](../html/index.html),
+[PDF](../PSA_Cryptography_API_Specification.pdf)
+
+**Reference implementation**: [Mbed Crypto](https://github.com/ARMmbed/mbed-crypto)
+
+## Hardware abstraction layer
+
+PSA includes functional specifications describing a hardware abstraction layer covering [cryptographic accelerators](accel/), [secure elements](se/) and [entropy sources](entropy/).
+
+### Accelerator driver interface
+
+The cryptographic accelerator driver interface lets you write drivers for hardware that performs cryptographic operations with keys in clear text.
+You can plug such drivers into any implementation of the PSA Cryptography API.
+
+For more information, see [PSA cryptography accelerator driver interface](accel/).
+
+### Secure element driver interface
+
+The secure element driver interface lets you write drivers for external cryptoprocessors such as secure elements (SE), smart cards and hardware security modules (HSM) that perform operations on keys that never leave the external processor and are accessed only through opaque handles.
+You can plug such drivers into any implementation of the PSA Cryptography API.
+
+For more information, see [PSA secure element driver interface](se/).
+
+### Entropy source driver interface
+
+The entropy source driver interface lets you write drivers for Hardware Random Number Generators (HRNG), also known as True Random Number Generators (TRNG).
+You can plug such drivers into any implementation of the PSA Cryptography API.
+
+For more information, see [PSA entropy source driver interface](entropy/).
+
+## Feedback
+
+Arm welcomes feedback on the design of the PSA cryptography interfaces.
+If you think something could be improved, please open an [issue on the Mbed Crypto GitHub repository](https://github.com/ARMmbed/mbed-crypto/labels/api-spec).
+Alternatively, if you prefer to provide your feedback privately, please email us at `mbed-crypto@arm.com`. All feedback received by email is treated confidentially.
diff --git a/docs/psa/se/index.html b/docs/psa/se/index.html
new file mode 100644
index 0000000..1574c94
--- /dev/null
+++ b/docs/psa/se/index.html
@@ -0,0 +1,6 @@
+<h1 id="psa-secure-element-driver-interface">PSA secure element driver interface</h1>
+<p>The secure element driver interface lets you write drivers for external cryptoprocessors such as secure elements (SE), smart cards and hardware security modules (HSM) that perform operations on keys that never leave the external processor and are accessed only through opaque handles. You can plug such drivers into any implementation of the <a href="../#application-programming-interface">PSA Cryptography API</a>.</p>
+<p><strong>Status: draft</strong> — major changes are still likely.</p>
+<p><strong>Documentation</strong>: for now, please see the header file: <a href="https://github.com/ARMmbed/mbed-crypto/blob/development/include/psa/crypto_se_driver.h"><code>include/psa/crypto_se_driver.h</code></a></p>
+<p><strong>Mbed Crypto support status</strong>: Partial. Only a few operations are supported: key pair generation, import, export and destruction; signature and verification.</p>
+<p><strong>Example</strong>: You can see the code of an <a href="https://github.com/ARMmbed/mbed-os-atecc608a">example driver</a> for the <a href="https://www.microchip.com/wwwproducts/en/ATECC608A">Microchip ATECC608A secure element</a>. See the instructions for the <a href="https://github.com/ARMmbed/mbed-os-example-atecc608a">example application using this driver</a> for how to build <a href="https://github.com/ARMmbed/mbed-os">Mbed OS</a> with this driver.</p>
diff --git a/docs/psa/se/index.md b/docs/psa/se/index.md
new file mode 100644
index 0000000..989bd06
--- /dev/null
+++ b/docs/psa/se/index.md
@@ -0,0 +1,14 @@
+# PSA secure element driver interface
+
+The secure element driver interface lets you write drivers for external cryptoprocessors such as secure elements (SE), smart cards and hardware security modules (HSM) that perform operations on keys that never leave the external processor and are accessed only through opaque handles.
+You can plug such drivers into any implementation of the [PSA Cryptography API](../#application-programming-interface).
+
+**Status: draft** — major changes are still likely.
+
+**Documentation**: for now, please see the header file:
+[`include/psa/crypto_se_driver.h`](https://github.com/ARMmbed/mbed-crypto/blob/development/include/psa/crypto_se_driver.h)
+
+**Mbed Crypto support status**: Partial. Only a few operations are supported: key pair generation, import, export and destruction; signature and verification.
+
+**Example**: You can see the code of an [example driver](https://github.com/ARMmbed/mbed-os-atecc608a) for the [Microchip ATECC608A secure element](https://www.microchip.com/wwwproducts/en/ATECC608A).
+See the instructions for the [example application using this driver](https://github.com/ARMmbed/mbed-os-example-atecc608a) for how to build [Mbed OS](https://github.com/ARMmbed/mbed-os) with this driver.