Skip to content

Commit fbb7087

Browse files
heavypacketsheavypackets
authored
Merge pull request #8 from ionut-arm/api-landing
Add API landing page
2 parents a3317f1 + 61759ab commit fbb7087

15 files changed

+692
-0
lines changed

‎docs/api_overview.md

+112
Large diffs are not rendered by default.

‎docs/diagrams/ident_provider_seq.png

127 KB
Loading

‎docs/diagrams/ident_provider_seq.puml

+85
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
2+
-- Copyright (c) 2019, Arm Limited, All Rights Reserved
3+
-- SPDX-License-Identifier: Apache-2.0
4+
--
5+
-- Licensed under the Apache License, Version 2.0 (the "License"); you may
6+
-- not use this file except in compliance with the License.
7+
-- You may obtain a copy of the License at
8+
--
9+
-- http://www.apache.org/licenses/LICENSE-2.0
10+
--
11+
-- Unless required by applicable law or agreed to in writing, software
12+
-- distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13+
-- WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
-- See the License for the specific language governing permissions and
15+
-- limitations under the License.
16+
17+
@startuml ident_provider_seq
18+
19+
participant app as "Client Application"
20+
participant lib as "Client Library"
21+
participant orch as "Orchestrator"
22+
participant idprov as "Identity Provider"
23+
participant parsec as "Security Service"
24+
participant keystore as "Keystore/Crypto Engine"
25+
26+
== System Lifecycle ==
27+
28+
group Trust Relationship (Boot)
29+
orch -[#blue]> orch: Generate root cert
30+
note left of orch
31+
//private key held in//
32+
//local memory//
33+
end note
34+
orch -[#blue]> idprov: **ShareTrustBundle**(//root public cert//)
35+
group Trust Relationship (Refresh - periodic)
36+
orch -[#blue]> orch: Generate intermediate cert
37+
orch -[#blue]> idprov: **ShareTrustBundle**(//intermediate public cert//)
38+
end
39+
end
40+
group Trust Relationship (Boot)
41+
idprov -[#blue]> idprov: Generate root cert
42+
note left of idprov
43+
//private key held in//
44+
//local memory//
45+
end note
46+
idprov -[#blue]> parsec: **ShareTrustBundle**(//root public cert//)
47+
group Trust Relationship (Refresh - periodic)
48+
idprov -[#blue]> idprov: Generate intermediate cert
49+
idprov -[#blue]> parsec: **ShareTrustBundle**(//intermediate public cert//)
50+
end
51+
end
52+
53+
== Client Lifecycle ==
54+
55+
orch -> app: spawn client (eg. **docker run ,,,**)
56+
app -> orch: platform client details (eg. PID)
57+
orch -> orch: Sign client definition with intermediate private key
58+
orch -> idprov: **AddClient**(//signed client definition//)
59+
idprov -> idprov: Verify client with intermediate public key
60+
idprov -> idprov: Build/cache client JWT
61+
idprov -> idprov: generic attestations
62+
orch -> orch: platform-specific attestations
63+
orch -> orch: Sign proofs with private key
64+
orch -> idprov: **ProveClient**(//signed proofs//)
65+
idprov -> idprov: Verify proofs with intermediate public key
66+
idprov -> idprov: Sign client JWT with intermediate private key
67+
68+
== Client Operations ==
69+
70+
loop For each crypto operation
71+
app -> lib: Perform cryptographic operation\nwith simplified client API
72+
alt ID uncached or expired
73+
lib -> idprov: Get application ID
74+
idprov -> lib: Application ID (signed JWT)
75+
end
76+
lib -> parsec: Perform cryptographic operation using wire protocol API (JWT auth header)
77+
parsec -> parsec: Verify JWT with intermediate public key
78+
parsec -> keystore: Implementation-defined operation
79+
keystore -> parsec: Implementation-defined results
80+
parsec -> lib: API-defined results
81+
lib -> app: Simplified results
82+
end
83+
84+
85+
@enduml

‎docs/operation_directory.md

+136
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
<!--
2+
-- Copyright (c) 2019, Arm Limited, All Rights Reserved
3+
-- SPDX-License-Identifier: Apache-2.0
4+
--
5+
-- Licensed under the Apache License, Version 2.0 (the "License"); you may
6+
-- not use this file except in compliance with the License.
7+
-- You may obtain a copy of the License at
8+
--
9+
-- http://www.apache.org/licenses/LICENSE-2.0
10+
--
11+
-- Unless required by applicable law or agreed to in writing, software
12+
-- distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13+
-- WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
-- See the License for the specific language governing permissions and
15+
-- limitations under the License.
16+
--->
17+
# **Operation Directory**
18+
19+
## **Introduction**
20+
This document provides links to full descriptions for all of the operations in the API.
21+
22+
## **Status Note**
23+
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.
24+
25+
## **Identity Operations**
26+
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.
27+
28+
* [**AddClient**](operation_directory/identity/add_client.md)
29+
* [**ProveClient**](operation_directory/identity/prove_client.md)
30+
31+
32+
## **Core Operations**
33+
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.
34+
35+
### **Service Health**
36+
37+
* [**Ping**](operation_directory/core/ping.md)
38+
39+
### **Service Configuration**
40+
41+
* **GetProviders**
42+
43+
### **Trust**
44+
45+
* [**ShareTrustBundle**](operation_directory/trust/share_trust_bundle.md)
46+
47+
## **PSA Crypto Operations**
48+
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).
49+
50+
### **Key Management**
51+
52+
* [**PsaCreateKey**](operation_directory/psa_crypto/psa_create_key.md)
53+
* **PsaExportKey**
54+
* [**PsaExportPublicKey**](operation_directory/psa_crypto/psa_export_public_key.md)
55+
* [**PsaImportKey**](operation_directory/psa_crypto/psa_import_key.md)
56+
* **PsaCopyKey**
57+
* [**PsaDestroyKey**](operation_directory/psa_crypto/psa_destroy_key.md)
58+
59+
### **Symmetric Cryptography**
60+
61+
* **PsaCipherEncrypt**
62+
* **PsaCipherDecrypt**
63+
* **PsaCipherOperationInit**
64+
* **PsaCipherEncryptSetup**
65+
* **PsaCipherDecryptSetup**
66+
* **PsaCipherGenerateIv**
67+
* **PsaCipherSetIv**
68+
* **PsaCipherUpdate**
69+
* **PsaCipherFinish**
70+
* **PsaCipherAbort**
71+
72+
### **Asymmetric Cryptography**
73+
74+
* [**PsaAsymmetricSign**](operation_directory/psa_crypto/psa_asymmetric_sign.md)
75+
* [**PsaAsymmetricVerify**](operation_directory/psa_crypto/psa_asymmetric_verify.md)
76+
* **PsaAsymmetricEncrypt**
77+
* **PsaAsymmetricDecrypt**
78+
79+
### **Authenticated Encryption with Associated Data (AEAD)**
80+
81+
* **PsaAeadEncrypt**
82+
* **PsaAeadDecrypt**
83+
* **PsaAeadOperationInit**
84+
* **PsaAeadEncryptSetup**
85+
* **PsaAeadDecryptSetup**
86+
* **PsaAeadGenerateNonce**
87+
* **PsaAeadSetNonce**
88+
* **PsaAeadSetLengths**
89+
* **PsaAeadUpdateAd**
90+
* **PsaAeadUpdate**
91+
* **PsaAeadFinish**
92+
* **PsaAeadVerify**
93+
* **PsaAeadAbort**
94+
95+
### **Digests**
96+
97+
* **PsaHashCompute**
98+
* **PsaHashCompare**
99+
* **PsaHashOperationInit**
100+
* **PsaHashSetup**
101+
* **PsaHashUpdate**
102+
* **PsaHashFinish**
103+
* **PsaHashVerify**
104+
* **PsaHashAbort**
105+
* **PsaHashClone**
106+
107+
### **Message Authentication Codes (MAC)**
108+
109+
* **PsaMacCompute**
110+
* **PsaMacVerify**
111+
* **PsaMacOperationInit**
112+
* **PsaMacSignSetup**
113+
* **PsaMacVerifySetup**
114+
* **PsaMacUpdate**
115+
* **PsaMacSignFinish**
116+
* **PsaMacVerifyFinish**
117+
* **PsaMacAbort**
118+
119+
### **Key Derivation**
120+
121+
* **PsaKeyDerivationOperationInit**
122+
* **PsaKeyDerivationSetup**
123+
* **PsaKeyDerivationGetCapacity**
124+
* **PsaKeyDerivationSetCapacity**
125+
* **PsaKeyDerivationInputBytes**
126+
* **PsaKeyDerivationInputKey**
127+
* **PsaKeyDerivationKeyAgreement**
128+
* **PsaKeyDerivationOutputBytes**
129+
* **PsaKeyDerivationOutputKey**
130+
* **PsaKeyDerivationAbort**
131+
* **PsaRawKeyAgreement**
132+
133+
### **Entropy**
134+
135+
* **PsaGenerateRandom**
136+

‎docs/operation_directory/core/ping.md

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<!--
2+
-- Copyright (c) 2019, Arm Limited, All Rights Reserved
3+
-- SPDX-License-Identifier: Apache-2.0
4+
--
5+
-- Licensed under the Apache License, Version 2.0 (the "License"); you may
6+
-- not use this file except in compliance with the License.
7+
-- You may obtain a copy of the License at
8+
--
9+
-- http://www.apache.org/licenses/LICENSE-2.0
10+
--
11+
-- Unless required by applicable law or agreed to in writing, software
12+
-- distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13+
-- WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
-- See the License for the specific language governing permissions and
15+
-- limitations under the License.
16+
--->
17+
# **Ping**
18+
19+
## **Opcode: 1 (decimal), 0x0001 (hex)**
20+
21+
## **Summary**
22+
Determines whether the service is present and responsive on the expected endpoint.
23+
24+
## **Contract**
25+
[Protobuf](/interface/protobuf/ping.proto)
26+

‎docs/operation_directory/identity/add_client.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<!--
2+
-- Copyright (c) 2019, Arm Limited, All Rights Reserved
3+
-- SPDX-License-Identifier: Apache-2.0
4+
--
5+
-- Licensed under the Apache License, Version 2.0 (the "License"); you may
6+
-- not use this file except in compliance with the License.
7+
-- You may obtain a copy of the License at
8+
--
9+
-- http://www.apache.org/licenses/LICENSE-2.0
10+
--
11+
-- Unless required by applicable law or agreed to in writing, software
12+
-- distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13+
-- WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
-- See the License for the specific language governing permissions and
15+
-- limitations under the License.
16+
--->
17+
# **AddClient**
18+
Placeholder page.

‎docs/operation_directory/identity/prove_client.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<!--
2+
-- Copyright (c) 2019, Arm Limited, All Rights Reserved
3+
-- SPDX-License-Identifier: Apache-2.0
4+
--
5+
-- Licensed under the Apache License, Version 2.0 (the "License"); you may
6+
-- not use this file except in compliance with the License.
7+
-- You may obtain a copy of the License at
8+
--
9+
-- http://www.apache.org/licenses/LICENSE-2.0
10+
--
11+
-- Unless required by applicable law or agreed to in writing, software
12+
-- distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13+
-- WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
-- See the License for the specific language governing permissions and
15+
-- limitations under the License.
16+
--->
17+
# **ProveClient**
18+
Placeholder page.

‎docs/operation_directory/psa_crypto/psa_asymmetric_sign.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<!--
2+
-- Copyright (c) 2019, Arm Limited, All Rights Reserved
3+
-- SPDX-License-Identifier: Apache-2.0
4+
--
5+
-- Licensed under the Apache License, Version 2.0 (the "License"); you may
6+
-- not use this file except in compliance with the License.
7+
-- You may obtain a copy of the License at
8+
--
9+
-- http://www.apache.org/licenses/LICENSE-2.0
10+
--
11+
-- Unless required by applicable law or agreed to in writing, software
12+
-- distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13+
-- WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
-- See the License for the specific language governing permissions and
15+
-- limitations under the License.
16+
--->
17+
# **PsaAsymmetricSign**
18+
Placeholder page.

‎docs/operation_directory/psa_crypto/psa_asymmetric_verify.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<!--
2+
-- Copyright (c) 2019, Arm Limited, All Rights Reserved
3+
-- SPDX-License-Identifier: Apache-2.0
4+
--
5+
-- Licensed under the Apache License, Version 2.0 (the "License"); you may
6+
-- not use this file except in compliance with the License.
7+
-- You may obtain a copy of the License at
8+
--
9+
-- http://www.apache.org/licenses/LICENSE-2.0
10+
--
11+
-- Unless required by applicable law or agreed to in writing, software
12+
-- distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13+
-- WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
-- See the License for the specific language governing permissions and
15+
-- limitations under the License.
16+
--->
17+
# **PsaAsymmetricVerify**
18+
Placeholder page.

‎docs/operation_directory/psa_crypto/psa_create_key.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<!--
2+
-- Copyright (c) 2019, Arm Limited, All Rights Reserved
3+
-- SPDX-License-Identifier: Apache-2.0
4+
--
5+
-- Licensed under the Apache License, Version 2.0 (the "License"); you may
6+
-- not use this file except in compliance with the License.
7+
-- You may obtain a copy of the License at
8+
--
9+
-- http://www.apache.org/licenses/LICENSE-2.0
10+
--
11+
-- Unless required by applicable law or agreed to in writing, software
12+
-- distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13+
-- WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
-- See the License for the specific language governing permissions and
15+
-- limitations under the License.
16+
--->
17+
# **PsaCreateKey**
18+
Placeholder page.

‎docs/operation_directory/psa_crypto/psa_destroy_key.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<!--
2+
-- Copyright (c) 2019, Arm Limited, All Rights Reserved
3+
-- SPDX-License-Identifier: Apache-2.0
4+
--
5+
-- Licensed under the Apache License, Version 2.0 (the "License"); you may
6+
-- not use this file except in compliance with the License.
7+
-- You may obtain a copy of the License at
8+
--
9+
-- http://www.apache.org/licenses/LICENSE-2.0
10+
--
11+
-- Unless required by applicable law or agreed to in writing, software
12+
-- distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13+
-- WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
-- See the License for the specific language governing permissions and
15+
-- limitations under the License.
16+
--->
17+
# **PsaDestroyKey**
18+
Placeholder page.

‎docs/operation_directory/psa_crypto/psa_export_public_key.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<!--
2+
-- Copyright (c) 2019, Arm Limited, All Rights Reserved
3+
-- SPDX-License-Identifier: Apache-2.0
4+
--
5+
-- Licensed under the Apache License, Version 2.0 (the "License"); you may
6+
-- not use this file except in compliance with the License.
7+
-- You may obtain a copy of the License at
8+
--
9+
-- http://www.apache.org/licenses/LICENSE-2.0
10+
--
11+
-- Unless required by applicable law or agreed to in writing, software
12+
-- distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13+
-- WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
-- See the License for the specific language governing permissions and
15+
-- limitations under the License.
16+
--->
17+
# **PsaExportPublicKey**
18+
Placeholder page.

0 commit comments

Comments
 (0)