Parsec Stability

The work for setting up a stability framework for Parsec was done for the 0.8.0 release, see the related issue for more details.

Why is stability important?

Parsec is a long-running service that will be configured, deployed, upgraded and maintained over a long period of time. The environment will also have client applications that are calling it, and persistent state that is collected on storage. Components will be upgraded over time. For Parsec to be supportable in enterprise system, it must not be brittle against upgrades. If Parsec is upgraded and restarted, client applications should continue working, and all persistent state from prior versions should remain valid and usable.

What does stability mean for the Parsec service?

The following definition of stability is chosen for the Parsec service: whatever two versions A and B of the Parsec binary, B being newer than A, A and B are stable if A can be removed and replaced by B without breaking anything.

Note that we are not looking at stability in the reverse direction: B cannot be replaced by A without breaking anything. The only exception is for the communication channel with clients where any version of the client library can successfully communicate with any version of the service.

The principle of semantic versioning is used to describe the stability of Parsec versions and when breaking changes are done. If parsec version is at 1.3.0 then all future stable version to that will be 1.x.y. Note that, although semver is used to describe Parsec stability, it is a strong goal for Parsec to remain stable at a 1.x.y version. This document introduces the efforts that are made so that a MAJOR version bump should hopefully never happen.

What needs to be stable?

With the above definition, Parsec stays stable if it keeps the exact same communication channels and format with its environment. Those are already described in the dataflow diagram in the threat model.

The communication channels that need to be stable are (some of them are not in the diagram):

Communication with clients
1. Definition of requests/responses (their format)
2. Definition of operation contracts (their intended behavior)
3. Definition of Listeners endpoints (how to contact Parsec)
Communication with authenticators
Communication received from the CLI invocation
Configuration file (including default configuration options)
Persistent data stored internally
1. Key mappings
OS signals
systemd communication
Dynamic libraries dependencies
Environment variables
Hardware backends
Build toolchain

Those will be described as "stability requirement" in the remainder of this document. As new features are added to the codebase, new stability requirements might appear. Those should be added to the list above and looked in detail below.

Stability Review

Let's look at each of the points above and check:

what stability exactly means
how stability is ensured
how stability is tested

Stability Requirement	Stability Definition	Stability Enforcement	Stability Test
Communication with clients (requests/responses)	Requests and responses must be understood correctly by different versions of the service/clients.	The Wire Protocol is stable by design.	Done
Communication with clients (operation contracts)	The behavior of operations must remain the same for all versions of the service.	There is a defined behavior for all operations that is respected.	Done
Communication with clients (listeners endpoint)	Listeners endpoint must be discovered in a stable way.	A service discovery mechanism exists.	Done
Authenticators	Authentication requests sent by future stable versions of Parsec should be understood by the same version of the authenticators present on the system.	Unix Peer Crendentials: based on top of stable C standard library APIs. JWT SVID: authentication is based on the SPIFFE Workload API which is a standard and should remain stable.	Done
CLI invocation	Old CLI invocations of Parsec should still work with for future stable Parsec versions. Optional flags should have the same defaults.	CLI flags should not be removed. Defaults should not be changed. New flags should be optional.	Done
Configuration file	Old configuration files should still work with future stable Parsec versions, with the same default for optional options.	Configuration options should not disappear in future stable Parsec versions. Configuration defaults should remain the same. New options should be optional.	Done
Persistent state (key mappings)	Old key mappings should still be read correctly by future stable Parsec versions.	The way the KIM persistently stores the mappings need to be backward-compatible in regards with reading/writing.	Done for the Mbed Crypto, PKCS11 and TPM providers.
OS signals	OS signals should still have the same behavior in future stable Parsec versions.	Signal handlers must not be removed in Parsec.	Done
systemd communication	systemd should receive the same status information from Parsec in future stable versions.	Status notifications must not be removed.	Done
Dynamic libraries dependencies	Linking and loading the same versions of libraries should still work in future stable versions of Parsec.	Stable versions of Parsec should not require newer dependencies.	Done and see the list
Environment variables	Environment variables should still have the same behavior in future stable Parsec versions.	Environment variable behaviors must not be removed in Parsec.	Done
Hardware backends	Communication with hardware backends for crypto and key management should still work in future Parsec versions.	The communication channels with the hardware backends should remain the same.	Done
Build toolchain	Parsec build should not break for defined versions of the Rust compiler.	Each commit is tested with specific supported versions of the Rust compiler.	Done

Dynamic libraries

We use the specific versions of those dynamic libraries and test it on CI:

PKCS#11 version 2.40
libclang version 6.0
TSS libraries version 2.3.3
CryptoAuthLib version 3.1.0 (not tested on CI, as there is no software mock available)

Mbed Crypto is currently compiled from scratch. When a new LTS version of Mbed TLS ships a PSA Crypto compliant version of Mbed Crypto, stability guarantees will be made on that version.

The Trusted Service provider is currently built using a pre-release version of the Trusted Services library. We aim to keep the Parsec service aligned with recent revisions of the TS code, however since no release has been made, no guarantees can be offered about stability. At the time of writing, no platform is officially supported for Trusted Services deployments.