Add a Parsec Stability page

[hug-dev]

This page describes what stability is for the Parsec service and how it is enforced/tested.

This is a work-in-progress page to put the framework in place.

I think the plan would be:

• create a stability label for issues
• for each one of the stability requirement, create a dedicated issue to make sure that stability is currently ensured in Parsec and add tests.
• add a link to the specific stability tests in the page per requirement

I think the ideal plan would be to have a stable Parsec version at the end of this, 0.X.0 for people/packagers to try out. After a few months of fixing stability problems, if they arise, we should then be confident enough to tag Parsec 1.0.0.

I am still worried about the C-STABLE rule and not sure yet what it means for Parsec, a binary application. I think it would translate to the exact content of the stability document.

Please feel free to review the vocabulary I used and let's discuss it. For example the stability definition, "communication channel", "stability requirement", "stability enforcement", etc...
Feel free to indicate if I missed anything.

Fix #83

[ionut-arm]

One other question I had was on the relationship between version numbers: the Parsec service version number, wire protocol version number, and provider/authenticator version numbers. Do we need to define how these relationships work and how they relate to the whole Stability goal?

[paulhowardarm]

One other question I had was on the relationship between version numbers: the Parsec service version number, wire protocol version number, and provider/authenticator version numbers. Do we need to define how these relationships work and how they relate to the whole Stability goal?

I think I would avoid getting into anything like that, because it has the potential to create an entirely unnecessary set of additional constraints on what is already quite a difficult problem. I am comfortable with letting different aspects of versioning drift and evolve at their own pace. I'd be wary of getting into situations where we need to artificially bump numbers or massage them to suit some over-arching schema.

[paulhowardarm]

Not wanting to inflict scope-creep on this PR, but somewhere along the line I think we need to address the story of how Parsec and Mbed TLS versioning intersect, both in the back-end (Mbed provider) and the front-end (C client using the SE driver). What are our goals here? As soon as there's an Mbed LTSR containing the PSA interfaces, should we expect Parsec to "just work" with whatever is installed in a distro, rather than grabbing specific versions as we do now? For the back-end, it would be nice to not have to link statically to Mbed Crypto, because it creates a maintenance burden within Parsec - we have to update to new versions to get patches for bugs/CVEs. For the front-end, the question is whether a client application could do something similar - just use whatever MBed Crypto is sitting on the target platform, and successfully register the SE driver. I don't think Parsec can solve this problem in isolation. It would have to be a dialogue with Mbed about what stability looks like on their side as well, both for API and ABI. But I can appreciate that this document might not be the place to try to address that question. It needs to be on the overall stability goals radar, however.

[paulhowardarm]

I think that "Key mappings" needs to be generalised to any persistent state stored internally by the service, of which key mappings are an example (and I guess the only example today, but this could change).

[hug-dev]

Fair enough!

[hug-dev]

Actually, I think it is better to limit the document to what is there in Parsec today. If there is a need in the future for the service to store other kind of persistent data, then we should address the stability of that separately. The reason is that the methods we are going to use to store the key mappings in a stable way might be different to what we use for other kind of data.

[paulhowardarm]

I'm not sure that I agree - this feels like letting details get in the way of the goal. If the aim of this stability document is to describe what we mean by stability for the service, then I think we need scope that in terms of all possible persistent state that might be stored and read back later. This doesn't preclude having a clear statement of how this would be achieved for individual pieces like the key mappings - I just think that we need a very strong top-level statement that covers all avenues.

[hug-dev]

then I think we need scope that in terms of all possible persistent state that might be stored and read back later.

I see your thinking. I also think that this document should describe what we mean by stability for the service. I guess my methodology here was to list all current and used communication channels as opposed as the ones we could/will have in the future. That way for each of them we can actually link a specific issue to do the work to make sure stability is enforced and tested.

I am happy to modify this item as you suggest though: a top-level "Internally stored persistent states" statement and then indivual items like key mappings and the ones we add in the future.

[paulhowardarm]

I think it is a reasonable simplification to not worry about rollbacks, at least in terms of the service itself. But one thing I feel we're not quite capturing here is about up-version and down-version communication between a client and the service. Newer clients should be able to talk to older services, and vice versa. Or is this document intentionally limited in scope to just service upgrades?

[hug-dev]

That's true! I guess I can put this as an exception on this note that although rollbacks are not considered, new clients should still be able to communicate with old versions of the Parsec service. So that this document considers only service upgrades for all communication channels except for (1) where both upgrades and downgrades are stable.

[paulhowardarm]

Not sure about this adoption of semver for the service. It seems to imply that a version 2.x.y could come along arbitrarily at any time and carry as many breaking changes as it likes. For something like a client library, where you're compiling against the API, that model probably works well. But I think that service stability needs to go further than that. No breaking changes should mean no breaking changes, and I think it has to hold pretty much forever. I don't think it's okay to bring along a breaking change, and just rationalise it by saying we bumped the major number. For one thing, it shouldn't be necessary. We've already designed lots of dynamic versioning into the wire protocol and API to keep things very decoupled. If it ever proves to be necessary, then I think it has to be managed with lots of communication and a very long-fuse deprecation strategy.

[hug-dev]

I agree that other than describing stability, being stable for a long time is the main goal here. With that paragraph I did not want to imply that using semver would be a reason for us to submit breaking changes often but more as a way to describe our stability. Even if it never happens (what is our goal), the semver definition allows us to prepare for that eventuality.
Moreover I would say that it would be a good sign for stakeholders to see that Parsec is still at 1.x.y after a very long time.

I will add a clarification sentence that staying stable in the same 1.x.y is indeed the goal here.

[hug-dev]

One other question I had was on the relationship between version numbers: the Parsec service version number, wire protocol version number, and provider/authenticator version numbers. Do we need to define how these relationships work and how they relate to the whole Stability goal?

I think I would avoid getting into anything like that, because it has the potential to create an entirely unnecessary set of additional constraints on what is already quite a difficult problem. I am comfortable with letting different aspects of versioning drift and evolve at their own pace. I'd be wary of getting into situations where we need to artificially bump numbers or massage them to suit some over-arching schema.

I think this only defines the service version. As everything is linked together it would also be including the providers. Note that the core provider's version is the same as the service currently (the one in the Cargo.toml file). The wire protocol version is used as part of the stability in between the service and clients.

[hug-dev]

Not wanting to inflict scope-creep on this PR, but somewhere along the line I think we need to address the story of how Parsec and Mbed TLS versioning intersect, both in the back-end (Mbed provider) and the front-end (C client using the SE driver).

The stability document I wrote was only focusing on the Parsec service but not the clients. I thought that the semver rules where enough there to describe staiblity. I guess things are a bit more complicated for the SE driver, and we should maybe open a separate issue there.
This makes we think that we would also need one on the parsec-tool.

What are our goals here? As soon as there's an Mbed LTSR containing the PSA interfaces, should we expect Parsec to "just work" with whatever is installed in a distro, rather than grabbing specific versions as we do now? For the back-end, it would be nice to not have to link statically to Mbed Crypto, because it creates a maintenance burden within Parsec - we have to update to new versions to get patches for bugs/CVEs.

For the Mbed Crypto provider, Parsec is relying on the psa-crypto crate. Currently, Mbed Crypto is compiled and linked statically during the build of this crate but if it is given the MBEDTLS_LIB_DIR and MBEDTLS_INCLUDE_DIR environment variables it will dynamically link with that instead. Ideally we would like something more robust like for the tss-esapi crate where pkg-config is used to find the Mbed Crypto library location so that no environment variable is needed.
Because the ABI of Mbed Crypto is not stable between versions, Parsec will have to be recompiled with the newer version of Mbed Crypto in order to generate the good mappings.

For the front-end, the question is whether a client application could do something similar - just use whatever MBed Crypto is sitting on the target platform, and successfully register the SE driver. I don't think Parsec can solve this problem in isolation. It would have to be a dialogue with Mbed about what stability looks like on their side as well, both for API and ABI. But I can appreciate that this document might not be the place to try to address that question. It needs to be on the overall stability goals radar, however.

That is currently possible for the SE driver, it can be compiled by passing the MBEDTLS_INCLUDE_DIR environment variable poiting to the header of the current Mbed Crypto version used. Because of the similar ABI stability, it would have to be recompiled if the Mbed Crypto version changes.

[hug-dev]

Im creating the 10 specific issues and will make a PR with their link here after.