@@ -59,17 +59,17 @@ configuration that is applied at service-deployment time.
5959While the service can be composed from multiple providers, any given API operation needs to be
6060implemented by a single provider. This means that client code needs to specify the target provider
6161when it makes an operation request. To achieve this, the service assigns an 8-bit integer value
62- (from 0 to 255) to each available provider. In practice, the numer of providers would be very small:
63- probably just two or three. This integer value is the ** provider identifier** . Client code must set
64- a single provider identifier in each API request. The [ ** wire protocol
62+ (from 0 to 255) to each available provider. In practice, the number of providers would be very
63+ small: probably just two or three. This integer value is the ** provider identifier** . Client code
64+ must set a single provider identifier in each API request. The [ ** wire protocol
6565specification** ] ( wire_protocol.md ) explains how a request header field is used to route the request
6666to the correct provider.
6767
6868In order to set a provider identifier in an API request, the client must first be able to determine
6969what providers are available, what their identifiers are, and what their characteristics are (such
7070as whether they are hardware-backed or software-backed). This is done by first referencing the
7171** core provider** . The core provider is the only provider that is guaranteed to be available in any
72- deployment of the service. It has a provider identifier of zero (the only reserved value for
72+ deployment of the service. It has a provider identifier of zero (` 0x00 ` , the only reserved value for
7373provider identifiers). The core provider is special in that it doesn't implement any security or
7474cryptographic operations. The core provider is used to represent the service as a whole. The
7575operations of the core provider can be used to gather information about the health and configuration
@@ -182,10 +182,12 @@ permitted numerical values for this field are given as follows:-
182182 it indicates improper coding or a possible defect on the client side). See the section below on
183183 unauthenticated operations.
184184- A value of 1 (` 0x01 ` ) indicates direct authentication. The service will expect the
185- ** authentication** field to contain a cleartext copy of the application identity.
186- - A value of 2 (` 0x02 ` ) indicates authentication tokens. The service will expect the
187- ** authentication** field to contain a JWT token. Tokens must be signed with the private key of
188- the identity provider and their validity period must cover the moment when the check is done.
185+ ** authentication** field to contain a cleartext copy of the application identity, encoded as a
186+ UTF-8 string.
187+ - A value of 2 (` 0x02 ` ) indicates authentication tokens. This authentication type is not currently
188+ supported. The service will expect the ** authentication** field to contain a JWT token. Tokens
189+ must be signed with the private key of the identity provider and their validity period must cover
190+ the moment when the check is done.
189191- A value of 3 (` 0x03 ` ) indicates Unix peer credentials authentication. The service expects the
190192 ** authentication** field to contain the Unix user identifier (UID, ** not** username) of the
191193 connecting process as a zero-padded little-endian 32-bit unsigned integer. The Parsec service
@@ -207,7 +209,7 @@ set to 0 (`0x00`).
207209
208210As per the [ ** wire protocol specification** ] ( wire_protocol.md ) , API request headers contain fields
209211for ** content type** and ** accept type** , which respectively indicate how the request body and
210- response body are encoded. Currently, the only supported value for these fields is 1 (` 0x01 ` ),
212+ response body are encoded. Currently, the only supported value for these fields is one (` 0x01 ` ),
211213meaning that all request and response bodies contain serialized protobuf messages. All other values
212214are unsupported and will be rejected by the service.
213215
@@ -232,20 +234,15 @@ While this API is closely aligned with the PSA Crypto API, there are some differ
232234difference is in the conventions used to name and reference cryptographic keys.
233235
234236In the PSA Crypto API, every key has a 32-bit numerical identifier. This identifier is set by the
235- caller when the key is created. Client code then uses this 32-bit identifier to ** open** the key. A
236- key must be opened before it can be used in any cryptographic operations. An open key is referenced
237- using a ** handle** (which is distinct from the identifier). The handle is the only way that the
238- client code can involve the key in cryptographic functions. Once the client has finished using the
239- key, it ** closes** the handle.
240-
241- This API differs in two ways. Firstly, the key names are not 32-bit numerical values: they are
242- ** strings** . Secondly, there is no notion of key handles. Keys are always referenced by name. There
243- is no operation to open or close a key. Cryptographic operations are all specified in terms of the
244- key name string. However, while the notion of a key handle is absent, it is important to understand
245- that the opacity of keys - one of the critical design characteristics of the PSA Crypto API - is
246- preserved here. Key names are used to reference keys for cryptographic operations, but the actual
247- key material is * never* exposed to the caller of the API unless an explicit operation is invoked to
248- export the key (and the key's usage policy permits for such an export to occur).
237+ caller when the persistent key is created. Client code then uses this 32-bit identifier to refer to
238+ the key for use in any cryptographic operation.
239+
240+ This API is different: the key names are not 32-bit numerical values, they are ** UTF-8 strings** .
241+ Cryptographic operations are all specified in terms of the key name string. It is important to
242+ understand that the opacity of keys - one of the critical design characteristics of the PSA Crypto
243+ API - is preserved here. Key names are used to reference keys for cryptographic operations, but the
244+ actual key material is * never* exposed to the caller of the API unless an explicit operation is
245+ invoked to export the key (and the key's usage policy permits for such an export to occur).
249246
250247The use of string names offers greater flexibility in how names can be chosen and structured. It
251248allows for names to be readable and meaningful. It also allows for names to follow a structured
0 commit comments