Define M3 APIs

[rjb1000]

Background

TS 26.501 defines reference point M3 between the 5GMS AF and the 5GMS AS. This is intended to be used by a 5GMSd AF to provision Server Certificates, Content Hosting Configurations, Content Preparation Templates, etc. However, TS 26.501 currently (3GPP Rel-16 and Rel-17) indicates that M3 APIs are not further specified:

M3d: (Internal and NOT SPECIFIED): Internal API used to exchange information for content hosting on a 5GMSd AS within the trusted DN.

Therefore, TS 26.512 does not define an API in clause 9:

APIs of this reference point are not specified within this release.

Scope

For the purposes of a 5GMSd reference implementation, it is desirable that a 5GMSd AF can provision a deployment of one or more 5GMSd AS instances to avoid the need for manual configuration of the AS. The M3 API should support:

• M3 Server Certificates Provisioning API.
• M3 Content Hosting Provisioning API.
• (M3 Content Preparation Templates Provisioning API.)

Relevant specifications

The M3 APIs defined here may form the basis for future 3GPP standardisation.

[rjb1000]

Initial commit of candidate M3 YAML: f96e1e4 as part of PR #13.

[davidjwbbc]

While working on 5G-MAG/rt-5gms-application-server#30 I've come across two issues with the current M3_ServerCertificatesProvisioning.yaml.

1. I realised that allowing a certificate to be deleted, while there is an active ContentHostingConfiguration that uses it, was a bad idea. I suggest that the destroyServerCertificate operation also contains a 409 Conflict response when asked to remove an certificate that is in use.
2. The + symbol in the per certificate operations path is not liked by openapi-generator. I suspect that this is because a + in URLs is generally translated as a white space character and the openapi-generator is getting confused as to whether or not the character is a space or a +.

Related to the + issue is this:
In order for the AS to match a certificate Id inside a ContentHostingConfiguration.distributionConfigurations.certificateId, it needs to compare the provisioningSessionId from the URL along with the certificateId from the distributionConfiguration to the joined certificate identifier in the certificates path. This means that in several places the AS needs to either join or split the pair of identifiers in order to perform comparisons or look ups between certificates and content hosting configurations.

It would be easier if these identifiers were kept separate in the certificates interface to match the separation we have in the ContentHostingConfiguration interface, so having them in different path elements might be better than trying to combine them.

[davidjwbbc]

Having had a further think about the character issue for certificates operations (+ not liked by openapi-generator) I think it would be best to drop the two fields, provisioningSessionId and certificateId and replace them with a single afUniqueCertificateId in the M3 interface YAML. State that the afUniqueCertificateId is generated by the application function and is unique across all provisioningSessionIds and certificateIds it has received via M1.

The content-hosting-configurations that are passed to the application server via M3, from the application function, are reduced versions of the ones received via M1 and only contain relevant distributionConfigurations for that application server. These content-hosting-configurations also have their distributionConfigurations.certificateId fields changed to the mapped afUniqueCertificateId.

We can then say for our application function we have chosen to make the afUniqueCertificateId a simple concatenation of provisioningSessionId, '+' and certificateId. This allows the application function implementation to decide how the unique ids are generated and hides the mapping from the application server (e.g. the application function could use a UUID, the certificate fingerprint, a simple counter or a hash of the provisioningSessionId and certificateId instead, and the application server only needs to know that this will be unique).