Update pki.api.v1.json

[thesimmermon]

No description provided.

[thesimmermon]

I was not able to get Stoplight Studio to read the sub-files in the specification (pki.api.v1.cacerts.json, pki.api.v1.simpleenroll.json), so I put this all under one json file. This may make it easier to consume by automation for Visual Studio and other code editors since it is one single file.

Also, I added Simple ReEnroll, ServerKeyGen, and CSR Attributes to the specification. These are part of the RFC 7030 and adding them here will make the PKI component more robust. I have not added security schemes or servers portion as these should be consistent across all modules. I thought I would wait until we all get on the same page to add that.

[cpalbr]

Hi @thesimmermon ,

Thnak you for your contribution. I also realized that Stoplight isn't able to handle more than one level of abstraction. Although their preview in Visual Studio can handle it. Nevertheless, I still recommend to kepp the files separated. That increases the readability a lot. What do you think?

[thesimmermon]

@cpalbr
I think as an implementer, it is easier to use only a single file. It's not likely that the developer will read these files as json. I always put these into a reader like Swagger in order to view them. In that case, it will be easier to utilize only the single file. If it were a shared resource, then I would see a need for multiple files. But, as everything in this section relates to PKI, I would keep it as a single file. Please let me know if we still want to split these up and I'll do so.

[MKeCharIN]

Not to be changed in this actual version.
To be discussed before future releases

[guillaumeFRANCOIS]

I have installed redocly to bundle and see the APIs in a friendly interface

You need to get the source on your PC, to put yourself in the desired api folder and enter preview-docs command.

[danisoler-charin]

This is ready for peer review.

[thesimmermon]

Here is information regarding the addition of /simplereenroll and the expected behavior:

tldr;- The implementer can call simpleenroll or simplereenroll to reenroll a certificate. Therefore there is no need to change existing code.

When using the EST interface, the /simplereenroll endpoint facilitates the renewal of an existing certificate without the need for a complete enrollment process. It essentially allows the client to request an extension of the certificate's term. Once the client provides its existing certificate, the server verifies the information (including the client's identity) and, if everything checks out, returns a new certificate with an updated validity period.
What if the certificate doesn’t match?
The /simplereenroll method fails if the client attempts to use it, but there is no certificate on record that matches the request. This might happen because the client is mistaken about what it possesses or because the server's records don't reflect the client's expectations. In any case, the server has no valid starting point from which to authenticate the client's request, and it typically returns an error. It's like trying to renew a membership card you never signed up for—the system has nothing to validate against.

When a client opts to use /simpleenroll on an existing certificate, the server does not require any linkage to that certificate. This means the request is treated as a new enrollment, and the existing certificate the client holds is not referenced at all. The server determines whether the client is sufficiently authenticated to be issued a certificate, and if so, the server will supply one that the client can use to replace the old certificate.

[thesimmermon]

To be RFC 7030 compliant, /cacerts, /simpleenroll, and /simplereenroll are mandatory.
/csrattrs, /fullcmc, /serverkeygen are optional although /csrattrs is a recommended endpoint as it can be used by the caller to indicate which attributes to include in the CSR.

[guillaumeFRANCOIS]

OPNC does not really respect RFC3070, which states that the authentication of incoming requests must be done via a client certificate (mTLS). OPNC rely i believe on single authent mechanism for all its services via OAUTH2 tokens.

From what I understand, /simplereenroll allows the client to use the initially generated certificate as a TLS client certificate to authenticate itself rather than using an external client certificate as with /simpleenroll. This may also cause some issues in our PnC context. To be recognized as a valid client certificate, a certificate must normally have the extended key usage “Client Authentication (1.3.6.1.5.5.7.3.2)”. However, this usage is not defined in ISO-15118 certificates and is therefore not allowed. This could therefore cause a lot of connexion issues with the PKI platforms.

We can add an endpoint /simplereenroll to comply a little more with the RFC, but if we use it with an OAUTH2 authentication like for /simpleenroll, it doesn't really bring much value for the user and is just to comply a little more with the RFC.

[steffenrhinow]

Idea: change the desciption in a way like - APIs are RFC3070 compliant but the authentication is achieved with Oauth - so we are clear?