Address review comments on the book

hug-dev · hug-dev · commit e426a593328a · 2020-09-23T11:12:46.000+01:00
Signed-off-by: Hugues de Valon &lt;hugues.devalon@arm.com&gt;
diff --git a/src/README.md b/src/README.md
@@ -7,7 +7,7 @@ Find here all the technical documentation of Parsec, alongside user and develope
 
 Go straight to the [overview](overview.md) to learn more about the project! Then, depending on what
 you want to know, you can go to the [users](parsec_users.md), [client
-developpers](parsec_client/README.md), [service developpers](parsec_service/README.md) or
+developers](parsec_client/README.md), [service developers](parsec_service/README.md) or
 [security](parsec_security/README.md) sections.
 
 # Disclaimer
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -37,9 +37,6 @@
       - [PsaMacVerify](parsec_client/operations/psa_mac_verify.md)
       - [PsaSignMessage](parsec_client/operations/psa_sign_message.md)
       - [PsaVerifyMessage](parsec_client/operations/psa_verify_message.md)
-      - [AddClient](parsec_client/operations/add_client.md)
-      - [ProveClient](parsec_client/operations/prove_client.md)
-      - [ShareTrustBundle](parsec_client/operations/share_trust_bundle.md)
 - [Parsec for service developers](parsec_service/README.md)
    - [System Architecture](parsec_service/system_architecture.md)
    - [Interfaces and Dataflow](parsec_service/interfaces_and_dataflow.md)
diff --git a/src/parsec_client/api_overview.md b/src/parsec_client/api_overview.md
@@ -184,9 +184,10 @@ permitted numerical values for this field are given as follows:-
 - A value of 1 (`0x01`) indicates direct authentication. The service will expect the
    **authentication** field to contain a cleartext copy of the application identity, encoded as a
    UTF-8 string.
-- A value of 2 (`0x02`) indicates authentication tokens. The service will expect the
-   **authentication** field to contain a JWT token. Tokens must be signed with the private key of
-   the identity provider and their validity period must cover the moment when the check is done.
+- A value of 2 (`0x02`) indicates authentication tokens. This authentication type is not currently
+   supported. The service will expect the **authentication** field to contain a JWT token. Tokens
+   must be signed with the private key of the identity provider and their validity period must cover
+   the moment when the check is done.
 - A value of 3 (`0x03`) indicates Unix peer credentials authentication. The service expects the
    **authentication** field to contain the Unix user identifier (UID, **not** username) of the
    connecting process as a zero-padded little-endian 32-bit unsigned integer. The Parsec service
diff --git a/src/parsec_client/operations/README.md b/src/parsec_client/operations/README.md
@@ -36,7 +36,7 @@ translated to the specific operation implementation language used.
 | [PsaSignMessage](psa_sign_message.md)             | `0x0018` |
 | [PsaVerifyMessage](psa_verify_message.md)         | `0x0019` |
 
-Find here the [current level of support](service_api_coverage.md) of those operations in Parsec.
+Find [here](service_api_coverage.md) the current level of support of those operations in Parsec.
 
 ## Status Note
 
@@ -45,15 +45,6 @@ Some operations are listed without being linked to documentation pages. These op
 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](add_client.md)
-- [ProveClient](prove_client.md)
-
 ## Core Operations
 
 Core operations are non-cryptographic operations supported by the core provider. Set the
@@ -69,10 +60,6 @@ Core operations are non-cryptographic operations supported by the core provider.
 - [ListOpcodes](list_opcodes.md)
 - [ListAuthenticators](list_authenticators.md)
 
-### Trust
-
-- [ShareTrustBundle](share_trust_bundle.md)
-
 ## PSA Crypto Operations
 
 These operations are all derived from equivalent function definitions in the [**PSA Crypto API
@@ -83,78 +70,29 @@ Most of the documentation in this book directly come from the specification.
 
 - [PsaImportKey](psa_import_key.md)
 - [PsaGenerateKey](psa_generate_key.md)
-- PsaCopyKey
 - [PsaDestroyKey](psa_destroy_key.md)
-- PsaPurgeKey
 - [PsaExportKey](psa_export_key.md)
 - [PsaExportPublicKey](psa_export_public_key.md)
 
 ### Message Digests
 
 - [PsaHashCompute](psa_hash_compute.md)
 - [PsaHashCompare](psa_hash_compare.md)
-- PsaHashOperationInit
-- PsaHashSetup
-- PsaHashUpdate
-- PsaHashFinish
-- PsaHashVerify
-- PsaHashAbort
-- PsaHashSuspend
-- PsaHashResume
-- PsaHashClone
 
 ### Message Authentication Codes (MAC)
 
 - [PsaMacCompute](psa_mac_compute.md)
 - [PsaMacVerify](psa_mac_verify.md)
-- PsaMacOperationInit
-- PsaMacSignSetup
-- PsaMacVerifySetup
-- PsaMacUpdate
-- PsaMacSignFinish
-- PsaMacVerifyFinish
-- PsaMacAbort
 
 ### Unauthenticated Ciphers
 
 - [PsaCipherEncrypt](psa_cipher_encrypt.md)
 - [PsaCipherDecrypt](psa_cipher_decrypt.md)
-- PsaCipherOperationInit
-- PsaCipherEncryptSetup
-- PsaCipherDecryptSetup
-- PsaCipherGenerateIv
-- PsaCipherSetIv
-- PsaCipherUpdate
-- PsaCipherFinish
-- PsaCipherAbort
 
 ### Authenticated Encryption with Associated Data (AEAD)
 
 - [PsaAeadEncrypt](psa_aead_encrypt.md)
 - [PsaAeadDecrypt](psa_aead_decrypt.md)
-- PsaAeadOperationInit
-- PsaAeadEncryptSetup
-- PsaAeadDecryptSetup
-- PsaAeadGenerateNonce
-- PsaAeadSetNonce
-- PsaAeadSetLengths
-- PsaAeadUpdateAd
-- PsaAeadUpdate
-- PsaAeadFinish
-- PsaAeadVerify
-- PsaAeadAbort
-
-### Key Derivation
-
-- PsaKeyDerivationOperationInit
-- PsaKeyDerivationSetup
-- PsaKeyDerivationGetCapacity
-- PsaKeyDerivationSetCapacity
-- PsaKeyDerivationInputBytes
-- PsaKeyDerivationInputKey
-- PsaKeyDerivationOutputBytes
-- PsaKeyDerivationOutputKey
-- PsaKeyDerivationAbort
 
 ### Asymmetric Signature
 
@@ -171,7 +109,6 @@ Most of the documentation in this book directly come from the specification.
 ### Key Agreement
 
 - [PsaRawKeyAgreement](psa_raw_key_agreement.md)
-- PsaKeyDerivationKeyAgreement
 
 ### Random Number Generation
 
diff --git a/src/parsec_client/operations/add_client.md b/src/parsec_client/operations/add_client.md
diff --git a/src/parsec_client/operations/prove_client.md b/src/parsec_client/operations/prove_client.md
diff --git a/src/parsec_client/operations/share_trust_bundle.md b/src/parsec_client/operations/share_trust_bundle.md
diff --git a/src/parsec_client/wire_protocol.md b/src/parsec_client/wire_protocol.md
@@ -59,13 +59,12 @@ protocol itself is neither of these things: it is an entirely bespoke protocol.
 
 ### Synchronous Operation
 
-The wire protocol operation is synchronous: the client initiates a connection and transmits a
-request. It then blocks while the service performs the request and transmits the response on the
-return stream. The protocol therefore only supports short-lived operations (meaning that the
-fulfillment time must be well within any timeout limitations that the transport might impose). The
-protocol can support longer-lived operations, but it is the responsibility of the service API to
-define how these are managed. There could, for example, be a pattern whereby there are separate
-initiation and status polling operations.
+The wire protocol is based on requests and responses, and therefore models synchronous patterns of
+interaction. There is nothing in current versions of the protocol to assist with asynchronous
+patterns of interaction between the client and the service. Future versions of the protocol may
+introduce such concepts. In the meantime, depending on the type of transport used, it may be
+possible for the service or the clients to take advantage of asynchronous features of the transport
+(such as the non-blocking mode of a socket) to provide certain levels of asynchronous control.
 
 ### Separation of Protocol and Transport
 
@@ -115,10 +114,9 @@ encoding is defined for use in the message bodies, and this encoding is based on
 buffers**](https://developers.google.com/protocol-buffers/), also known as **protobuf**.
 
 For each operation in the API, two separate protobuf message definitions will exist: one for that
-operation's inputs, and another for its outputs. The content bytes in a request message can be
-converted through protobuf-generated code into a model object for the inputs. Likewise, the content
-bytes in a response message can be converted through protobuf-generated code into a model object for
-the outputs.
+operation's inputs, and another for its outputs. The body in a request message can be converted
+through protobuf-generated code into a model object for the inputs. Likewise, the body in a response
+message can be converted through protobuf-generated code into a model object for the outputs.
 
 Processing any message is, therefore, a two-phase process: firstly, the header must be processed by
 writing code that is conformant with this specification; and secondly, the content must be processed
@@ -151,8 +149,8 @@ cleanly separated from those of another. But while this identifier string is the
 authentication, there are different ways that it can be used, and consequently there are different
 ways for the authentication field to be populated. One simple method is for the client identifier to
 be passed directly. But it is also possible to use the identifier as input to an HMAC algorithm over
-the content bytes, in which case the authentication field would contain the computed HMAC, rather
-than the identifier itself.
+the body, in which case the authentication field would contain the computed HMAC, rather than the
+identifier itself.
 
 ### Sessions
 
@@ -249,7 +247,7 @@ following diagram, the bytes go left to right from least significant to most sig
 | Content type         | Common         | 1               | Defines how the message body should be processed. The only currently-supported value is `0x01`, which indicates that the message body should be treated as a serialized protobuf message.                                                                                                                                                                                                                                                           |
 | Accept type          | Requests only  | 1               | Defines how the service should provide its response. The only currently-supported value is `0x01`, which indicates that the service should provide a response whose body is a serialized protobuf message.                                                                                                                                                                                                                                          |
 | Auth type            | Requests only  | 1               | Defines how the authentication bytes should be interpreted.                                                                                                                                                                                                                                                                                                                                                                                         |
-| Content length       | Common         | 4               | Provides the exact number of bytes of content.                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Content length       | Common         | 4               | Provides the exact number of bytes of body.                                                                                                                                                                                                                                                                                                                                                                                                         |
 | Auth length          | Requests only  | 2               | Provides the exact number of bytes of authentication.                                                                                                                                                                                                                                                                                                                                                                                               |
 | Opcode               | Common         | 4               | Indicates the operation being performed by this request. See the [section](#opcodes) above on opcodes.                                                                                                                                                                                                                                                                                                                                              |
 | Status               | Responses only | 2               | Indicates the overall success or failure of the operation. A value of zero is used universally to mean success. Other values should be interpreted according to the [API specification](status_codes.md).                                                                                                                                                                                                                                           |
diff --git a/src/parsec_security/rust_client_threat_model/threat_model.md b/src/parsec_security/rust_client_threat_model/threat_model.md
@@ -130,7 +130,7 @@ sensitive information.
 | ID | Justification                                                                                                                                                                            | Details                                                                                                                                                                    |
 |----|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | 0  | Parsec interface uses an IPC mechanism respecting confidentiality and integrity of messages transmitted between the clients and the service (once the initial connection has been made). | Unix Domain Socket: the sockets used on the client and service side for the communication are represented by file descriptors that are only accessible by those processes. |
-| 1  | The Parsec client is coded with safety in mind and is tested extensively.                                                                                                                | [Done](https://github.com/parallaxsecond/parsec-book/issues/35)                                                                                                            |
+| 1  | The Parsec client is coded with safety in mind and is tested extensively.                                                                                                                | [Open](https://github.com/parallaxsecond/parsec-client-rust/issues/49)                                                                                                     |
 
 ## Operational mitigations
 
diff --git a/src/parsec_service/authenticators.md b/src/parsec_service/authenticators.md
@@ -2,7 +2,7 @@
 
 ## Direct Authenticator
 
-The direct authenticator directly parse the authentication field as a UTF-8 string and uses that as
+The direct authenticator directly parses the authentication field as a UTF-8 string and uses that as
 application identity.
 
 ## Unix Peer Credentials Authenticator
diff --git a/src/parsec_service/install_parsec_linux.md b/src/parsec_service/install_parsec_linux.md
@@ -3,12 +3,9 @@
 Parsec can be built and installed as a Linux daemon using systemd. The daemon is a systemd user
 daemon run by the `parsec` user. Some manual steps are needed to make sure that permissions are set
 up correctly so that Parsec is installed respecting the operational mitigations of our [threat
-model](../parsec_security/parsec_threat_model/threat_model.md). Similarly to the threat model, this
-guide proposes different alternatives in case an Identity Provider is available or not. The role and
-description of an Identity Provider in Parsec is described in the [System
-Architecture](https://parallaxsecond.github.io/parsec-book/parsec_service/system_architecture.html)
-page. Currently, Parsec does not support integration with any Identity Provider. To securely install
-Parsec, please follow the steps of deployment **without an Identity Provider**.
+model](../parsec_security/parsec_threat_model/threat_model.md). Currently, Parsec does not support
+integration with any Identity Provider. More installation methods will be added in the future when
+new identity providers/authenticators are supported.
 
 If your Linux system uses systemd to manage daemons, you can follow these steps. `$DESIRED_FEATURES`
 can be a space or comma-separated subset of: `mbed-crypto-provider`, `pkcs11-provider`, and
@@ -21,9 +18,8 @@ Create the Parsec socket directory.
 mkdir /tmp/parsec
 ```
 
-In a deployment **without an Identity Provider**, create the `parsec-clients` group and set the
-correct permissions on the socket folder. Mutually trusted Parsec Clients will need to be in that
-group.
+Create the `parsec-clients` group and set the correct permissions on the socket folder. Mutually
+trusted Parsec Clients will need to be in that group.
 
 ```
 sudo groupadd parsec-clients
@@ -39,12 +35,6 @@ sudo usermod -a -G parsec-clients parsec-client-1
 
 Users just added to that group might need to log-out and log-in again to make sure the change apply.
 
-In a deployment **with an Identity Provider**, set the correct permissions on the socket folder.
-
-```
-sudo chmod 755 /tmp/parsec
-```
-
 Create and log in to a new user named `parsec`.
 
 ```
@@ -81,8 +71,8 @@ systemctl --user enable parsec
 systemctl --user start parsec
 ```
 
-`parsec-clients` users (with no IP) or every one (with IP) can now use Parsec! You can test it
-(having logged in a `parsec-clients` user) going inside the `parsec/e2e_tests` directory and:
+`parsec-clients` users can now use Parsec! You can test it (having logged in a `parsec-clients`
+user) going inside the `parsec/e2e_tests` directory and:
 
 ```
 cargo test normal_tests
diff --git a/src/parsec_service/providers.md b/src/parsec_service/providers.md
@@ -20,13 +20,15 @@ One instance of the core provider must always be running with a provider ID of z
 
 **Provider UUID: 1c1139dc-ad7c-47dc-ad6b-db6fdb466552**
 
-The Mbed Crypto provider is a software-based provider built on top of Mbed Crypto - the reference
-implementation of the PSA cryptography specification. Mbed Crypto is loaded as a static library and
-executes with the rest of the service in user-space.
-
-The software version of the Mbed Crypto provider is meant as a proof-of-concept and should not be
-used in real-world environments. Future improvements will expand the security guarantee of Mbed
-Crypto-based providers.
+The [Mbed Crypto](https://os.mbed.com/docs/mbed-os/v6.3/apis/mbed-crypto.html) provider is a
+software-based provider built on top of Mbed Crypto - the reference implementation of the PSA
+cryptography specification. Mbed Crypto is loaded as a static library and executes with the rest of
+the service in user-space.
+
+As a software provider, Mbed Crypto does not offer the same security guarantees as other
+hardware-based providers and does not store its keys in a secure location in hardware, but directly
+on disk. Because of that, the Mbed Crypto provider should not be used securely for private key
+operations but can be used to simplify proof of concept projects.
 
 ## TPM Provider
 
diff --git a/src/parsec_service/system_architecture.md b/src/parsec_service/system_architecture.md
