Add API landing page

docs/diagrams/ident_provider_seq.puml

@@ -0,0 +1,85 @@
+
+  -- Copyright (c) 2019, Arm Limited, All Rights Reserved
+  -- 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.
+
+@startuml ident_provider_seq
+
+participant app as "Client Application"
+participant lib as "Client Library"
+participant orch as "Orchestrator"
+participant idprov as "Identity Provider"
+participant parsec as "Security Service"
+participant keystore as "Keystore/Crypto Engine"
+
+== System Lifecycle ==
+
+group Trust Relationship (Boot)
+orch -[#blue]> orch: Generate root cert
+note left of orch
+  //private key held in//
+  //local memory//
+end note
+orch -[#blue]> idprov: **ShareTrustBundle**(//root public cert//)
+group Trust Relationship (Refresh - periodic)
+orch -[#blue]> orch: Generate intermediate cert
+orch -[#blue]> idprov: **ShareTrustBundle**(//intermediate public cert//)
+end
+end
+group Trust Relationship (Boot)
+idprov -[#blue]> idprov: Generate root cert
+note left of idprov
+  //private key held in//
+  //local memory//
+end note
+idprov -[#blue]> parsec: **ShareTrustBundle**(//root public cert//)
+group Trust Relationship (Refresh - periodic)
+idprov -[#blue]> idprov: Generate intermediate cert
+idprov -[#blue]> parsec: **ShareTrustBundle**(//intermediate public cert//)
+end
+end
+
+== Client Lifecycle ==
+
+orch -> app: spawn client (eg. **docker run ,,,**)
+app -> orch: platform client details (eg. PID)
+orch -> orch: Sign client definition with intermediate private key
+orch -> idprov: **AddClient**(//signed client definition//)
+idprov -> idprov: Verify client with intermediate public key
+idprov -> idprov: Build/cache client JWT
+idprov -> idprov: generic attestations
+orch -> orch: platform-specific attestations
+orch -> orch: Sign proofs with private key
+orch -> idprov: **ProveClient**(//signed proofs//)
+idprov -> idprov: Verify proofs with intermediate public key
+idprov -> idprov: Sign client JWT with intermediate private key
+
+== Client Operations ==
+
+loop For each crypto operation
+app -> lib: Perform cryptographic operation\nwith simplified client API
+alt ID uncached or expired
+lib -> idprov: Get application ID
+idprov -> lib: Application ID (signed JWT)
+end
+lib -> parsec: Perform cryptographic operation using wire protocol API (JWT auth header)
+parsec -> parsec: Verify JWT with intermediate public key
+parsec -> keystore: Implementation-defined operation
+keystore -> parsec: Implementation-defined results
+parsec -> lib: API-defined results
+lib -> app: Simplified results
+end
+
+
+@enduml

docs/operation_directory.md

@@ -0,0 +1,136 @@
+<!--
+  -- Copyright (c) 2019, Arm Limited, All Rights Reserved
+  -- 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.
+--->
+# **Operation Directory**
+
+## **Introduction**
+This document provides links to full descriptions for all of the operations in the API.
+
+## **Status Note**
+This is preliminary documentation. It may be incomplete, and is subject to change without notice. Some operations are listed without being linked to documentation pages. These operations are not currently supported, but are intended for future roadmap. Only a small number of the PSA Crypto operations are supported in the current version.
+
+## **Identity Operations**
+Identity operations are not supported by the security service. These operations are reserved for use only by the identity provider, which is a separate service in the system, but supports a common wire protocol.
+
+* [**AddClient**](operation_directory/identity/add_client.md)
+* [**ProveClient**](operation_directory/identity/prove_client.md)
+
+
+## **Core Operations**
+Core operations are non-cryptographic operations supported by the core provider. Set the **provider** field of the request header to 0 (`0x00`) to invoke these operations.
+
+### **Service Health**
+
+* [**Ping**](operation_directory/core/ping.md)
+
+### **Service Configuration**
+
+* **GetProviders**
+
+### **Trust**
+
+* [**ShareTrustBundle**](operation_directory/trust/share_trust_bundle.md)
+
+## **PSA Crypto Operations**
+These operations are all derived from equivalent function definitions in the [**PSA Crypto API Specification**](https://github.com/ARMmbed/mbed-crypto/blob/psa-crypto-api/docs/PSA_Cryptography_API_Specification.pdf). 
+
+### **Key Management**
+
+* [**PsaCreateKey**](operation_directory/psa_crypto/psa_create_key.md)
+* **PsaExportKey**
+* [**PsaExportPublicKey**](operation_directory/psa_crypto/psa_export_public_key.md)
+* [**PsaImportKey**](operation_directory/psa_crypto/psa_import_key.md)
+* **PsaCopyKey**
+* [**PsaDestroyKey**](operation_directory/psa_crypto/psa_destroy_key.md)
+
+### **Symmetric Cryptography**
+
+* **PsaCipherEncrypt**
+* **PsaCipherDecrypt**
+* **PsaCipherOperationInit**
+* **PsaCipherEncryptSetup**
+* **PsaCipherDecryptSetup**
+* **PsaCipherGenerateIv**
+* **PsaCipherSetIv**
+* **PsaCipherUpdate**
+* **PsaCipherFinish**
+* **PsaCipherAbort**
+
+### **Asymmetric Cryptography**
+
+* [**PsaAsymmetricSign**](operation_directory/psa_crypto/psa_asymmetric_sign.md)
+* [**PsaAsymmetricVerify**](operation_directory/psa_crypto/psa_asymmetric_verify.md)
+* **PsaAsymmetricEncrypt**
+* **PsaAsymmetricDecrypt**
+
+### **Authenticated Encryption with Associated Data (AEAD)**
+
+* **PsaAeadEncrypt**
+* **PsaAeadDecrypt**
+* **PsaAeadOperationInit**
+* **PsaAeadEncryptSetup**
+* **PsaAeadDecryptSetup**
+* **PsaAeadGenerateNonce**
+* **PsaAeadSetNonce**
+* **PsaAeadSetLengths**
+* **PsaAeadUpdateAd**
+* **PsaAeadUpdate**
+* **PsaAeadFinish**
+* **PsaAeadVerify**
+* **PsaAeadAbort**
+
+### **Digests**
+
+* **PsaHashCompute**
+* **PsaHashCompare**
+* **PsaHashOperationInit**
+* **PsaHashSetup**
+* **PsaHashUpdate**
+* **PsaHashFinish**
+* **PsaHashVerify**
+* **PsaHashAbort**
+* **PsaHashClone**
+
+### **Message Authentication Codes (MAC)**
+
+* **PsaMacCompute**
+* **PsaMacVerify**
+* **PsaMacOperationInit**
+* **PsaMacSignSetup**
+* **PsaMacVerifySetup**
+* **PsaMacUpdate**
+* **PsaMacSignFinish**
+* **PsaMacVerifyFinish**
+* **PsaMacAbort**
+
+### **Key Derivation**
+
+* **PsaKeyDerivationOperationInit**
+* **PsaKeyDerivationSetup**
+* **PsaKeyDerivationGetCapacity**
+* **PsaKeyDerivationSetCapacity**
+* **PsaKeyDerivationInputBytes**
+* **PsaKeyDerivationInputKey**
+* **PsaKeyDerivationKeyAgreement**
+* **PsaKeyDerivationOutputBytes**
+* **PsaKeyDerivationOutputKey**
+* **PsaKeyDerivationAbort**
+* **PsaRawKeyAgreement**
+
+### **Entropy**
+
+* **PsaGenerateRandom**
+

docs/operation_directory/core/ping.md

@@ -0,0 +1,26 @@
+<!--
+  -- Copyright (c) 2019, Arm Limited, All Rights Reserved
+  -- 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.
+--->
+# **Ping**
+
+## **Opcode: 1 (decimal), 0x0001 (hex)**
+
+## **Summary**
+Determines whether the service is present and responsive on the expected endpoint.
+
+## **Contract**
+[Protobuf](/interface/protobuf/ping.proto)
+

docs/operation_directory/identity/add_client.md

@@ -0,0 +1,18 @@
+<!--
+  -- Copyright (c) 2019, Arm Limited, All Rights Reserved
+  -- 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.
+--->
+# **AddClient**
+Placeholder page.

docs/operation_directory/identity/prove_client.md

@@ -0,0 +1,18 @@
+<!--
+  -- Copyright (c) 2019, Arm Limited, All Rights Reserved
+  -- 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.
+--->
+# **ProveClient**
+Placeholder page.

docs/operation_directory/psa_crypto/psa_asymmetric_sign.md

@@ -0,0 +1,18 @@
+<!--
+  -- Copyright (c) 2019, Arm Limited, All Rights Reserved
+  -- 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.
+--->
+# **PsaAsymmetricSign**
+Placeholder page.

docs/operation_directory/psa_crypto/psa_asymmetric_verify.md

@@ -0,0 +1,18 @@
+<!--
+  -- Copyright (c) 2019, Arm Limited, All Rights Reserved
+  -- 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.
+--->
+# **PsaAsymmetricVerify**
+Placeholder page.

docs/operation_directory/psa_crypto/psa_create_key.md

@@ -0,0 +1,18 @@
+<!--
+  -- Copyright (c) 2019, Arm Limited, All Rights Reserved
+  -- 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.
+--->
+# **PsaCreateKey**
+Placeholder page.

docs/operation_directory/psa_crypto/psa_destroy_key.md

@@ -0,0 +1,18 @@
+<!--
+  -- Copyright (c) 2019, Arm Limited, All Rights Reserved
+  -- 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.
+--->
+# **PsaDestroyKey**
+Placeholder page.

docs/operation_directory/psa_crypto/psa_export_public_key.md

@@ -0,0 +1,18 @@
+<!--
+  -- Copyright (c) 2019, Arm Limited, All Rights Reserved
+  -- 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.
+--->
+# **PsaExportPublicKey**
+Placeholder page.