FSC - Core 1.0.0

FSC Core specifies the basics for setting up and managing connections in a Group. Auxiliary functionality for either an FSC Peer or an entire FSC Group can be realized with extensions. An Extension performs a well scoped feature enhancing the overall working of FSC.

It is RECOMMENDED to use FSC Core with the following extensions, each specified in a dedicated RFC:

• FSC Logging, keep a log of requests to Services.

FSC Core provides the foundation for cooperation between organizations (Peers). However, in practice additional decisions have to be made to guarantee a functioning Group within a broader context. For example, it may be needed for an Group to have additional restrictions or agreements within the Group. This set of agreements is called the Profile. Every Group MUST have at least one Profile in order te operate. A Group MAY use multiple Profiles to further enhance the rules and restrictions within the Group. It is the responsibility of the Group to prevent conflicts between the Profiles used by the Group.

The following decisions MUST be part of the Profile:

1. Select a Trust Anchor
2. Select a Group ID
3. Select what determines the Peer ID
4. Select what determines the Peer name
5. Select a Peer who acts as the Directory of the Group
6. Decide what ports are used for management traffic
7. Determine requirements for allowed TLS versions and Cipher Suites

In addition to the mandatory decisions, a Profile MAY also contain additional agreements or restrictions. These are not technically required for the operation of FSC Core, but can become mandatory within a Group. An example would be a set of additional rules in order to comply with local legislation. Below are a few examples listed of these additional decisions for inspirational purposes:

1. Any extensions required by Peers within the Group
2. Agreements on data retention
3. The specifics of the retry mechanism used for Contract synchronization
4. Additional restrictions on Certificate revocation by mandating OCSP or CRL checks

A typical use case is a cooperation of many organizations that use APIs to exchange data or provide other business services to each other.

Organizations can participate in multiple Groups at the same time. Reasons for participating in multiple Groups could be the use of different environments for production and test deployments or when participating in different ecosystems like health industry and government industry.

An organization can offer the same API in multiple Groups. When doing so, the organization will be a Peer in every Group, and define the API as a Service in the Directory of each Group using a different Inway for each Group.

Any Peer can submit a Contract to other Peers. This Contract becomes valid when the Peers mentioned in the Contract accept the Contract by placing an accept signature.

A Contract becomes invalid when at least one Peer mentioned in the Contract revokes the Contract.

A Contract becomes invalid when at least one Peer mentioned in the Contract rejects the Contract.

A Contract becomes invalid when the validity period of the Contract expires.

Accepting, rejecting and revoking is done by adding a digital signature.

The content of a Contract is immutable. When the content of a Contract is subject to change, the Contract is invalidated and replaced by a new one.

A connection on behalf of another Peer (delegation) can only be established if the Peer connecting to the Service has a valid Contract containing a DelegatedServiceConnectionGrant with the Peer providing the Service. The connection Grants contains information about the Service, the public key of the Outway that is authorized to connect to the Service and the Peer acting as Delegator.

The Contract is distributed among the three Peers. Once the Contract is signed by all the Peers, the Outway of the Delegatee can connect to the Inway offering the Service on behalf the Delegator.

1. The Delegator creates a Contract with a Delegated Service Connection Grant which contains the details of the Service and the Peer who will be acting as Delegatee (who will consume the Service).
2. The Delegator adds its own accept signature to the Contract.
3. The Delegator sends the Contract and accept signature to the Delegatee.
4. The Delegatee adds its own accept signature.
5. The Delegatee sends the accept signature to the Delegator.
6. The Delegatee sends the accept signature to the Service Provider.
7. The Delegator sends the Contract and accept signature to the Service Provider.
8. The Service Provider adds its own accept signature.
9. The Service Provider sends the accept signature to the Delegatee.
10. The Service Provider sends the accept signature to the Delegator.

When the Service is being offered on behalf of another Peer the Contract is distributed among four Peers. The Peer acting as Delegator in the Service publication will also receive the Contract. Once the Contract is signed by all the Peers, the Outway of the Delegatee can connect to the Inway offering the Service on behalf the Delegator.

1. The Delegator creates a Contract with a Delegated Service Connection Grant which contains the details of the Service and the Peer who will be acting as Delegatee (who will consume the Service).
2. The Delegator adds its own accept signature to the Contract.
3. The Delegator sends the Contract and accept signature to the Delegatee.
4. The Delegator sends the Contract and accept signature to the Service provider.
5. The Delegator sends the Contract and accept signature to the Delegator of the Service publication.
6. The Delegatee adds its own accept signature.
7. The Delegatee sends the accept signature to the Delegator.
8. The Delegatee sends the accept signature to the Service provider.
9. The Delegatee sends the accept signature to the Delegator of the Service publication.
10. The Service provider adds its own accept signature.
11. The Service provider sends the accept signature to the Delegatee.
12. The Service provider sends the accept signature to the Delegator.
13. The Service provider sends the accept signature to the Delegator of the Service publication.
14. The Delegator of the Service publication adds its own accept signature.
15. The Delegator of the Service publication sends the accept signature to the Delegatee.
16. The Delegator of the Service publication sends the accept signature to the Delegator.
17. The Delegator of the Service publication sends the accept signature to the Service provider.

In order to provide a predictable network configuration FSC limits the selection of network ports to be used by components. The ports used by FSC components MUST be 443 or 8443.

Port 443 is RECOMMENDED for data traffic i.e. HTTP requests to a Service.
Port 8443 is RECOMMENDED for management traffic i.e. submitting/signing Contracts.

Data traffic: Inway, Outway
Management Traffic: Directory, Manager

The Group ID is the identifier of the Group. This identifier is chosen by the Group upon creation of the Group.
The Group ID MUST match the following regular expression ^[a-zA-Z0-9./_-]{1,100}$

Each Peer MUST have a unique identifier within the Group, this identifier is called the PeerID. The PeerID is determined by at least one element from the subject field section 4.1.2.6 of [RFC5280] of an X.509 certificate. Each Group MUST define which element(s) of the subject field of the X.509 certificate act as PeerID. The TA(s) issuing the certificates must ensure that PeerID is always the same for a Peer in each issued certificate for said Peer.

Each Peer MUST have a human-readable name which can be used to identify a Peer. Unlike the PeerID the name does not have to be unique. The name of Peer is determined by an element in the subject field section 4.1.2.6 of [RFC5280] of an X.509 certificate. The Group MUST define which element of the subject field is used.

The Trust Anchor (TA) is an authoritative entity for which trust is assumed and not derived. In the case of FSC, which uses an X.509 architecture, it is the root certificate from which the whole chain of trust is derived.

Each Group can have multiple TAs.

Every Peer in a Group MUST accept the same TA(s).

The TA SHOULD validate a Peers identity, i.e. the TA MUST preform Organization Validation.

Connections between Inways, Outways, Managers of a Group are mTLS connections based on X.509 certificates as defined in [RFC5280].

The certificate guarantees the identity of a Peer.

FSC places specific requirements on the subject fields of a certificate. section 4.1.2.6 of[RFC5280] which are listed below

• Subject Alternative Name section 4.1.2.6 of[RFC5280]: This should contain the Fully Qualified Domain Names (FQDN) of a Manager, Inway or Outway. For an Outway this FQDN does not have to resolve externally.
• Subject Organization: This should contain to the name of the Organization.

The representation and verification of domains specified in the X.509 certificate MUST adhere to [RFC6125]

The Inway and Outway both have a single endpoint which proxies HTTP requests. In case of an error within the scope of FSC these components MUST return the HTTP header Fsc-Error-Code which MUST contain the code specifying the error.

The response body must contain an object as described in .components/schemas/error of the OpenAPI Specification.

The HTTP status codes that MUST be used in combination with the HTTP header Fsc-Error-Code are defined in the sections 3.7.1.4 and 3.8.2.2.

• A UUID MUST be provided in the field contract.iv. The value must be unique. Each Peer is responsible for ensuring that only one Contract can exist with a given iv.
• A hash algorithm is provided in the field contract.content.hash_algorithm.
• The date provided in contract.content.created_at can not be in the future.
• The Group ID of the Manager matches the Group ID defined in the field contract.group_id.
• A valid date is provided in contract.content.validity.not_before.
• A valid date is provided in contract.content.validity.not_after.
• The date provided in contract.content.validity.not_after must be greater than the date provided in the field contract.validity.not_before.
• The date provided in contract.content.validity.not_after must be in the future.
• At least one Grant is set in the field contract.content.grants.
• A ServicePublicationGrant or DelegatedServicePublicationGrant cannot be mixed with other Grants. Mixing Grant types with different use-cases is prohibited to prevent the creation of Contracts that are hard to maintain and validate.

Per Grant type different validation rules apply.

A signature MUST follow the JSON Web Signature (JWS) format specified in [RFC7515]

A signature on a Contract SHOULD only be accepted if the Peer is present in one of the Grants as:

ServicePublicationGrant

• grant.data.directory.peer_id
• grant.data.service.peer_id

DelegatedServicePublicationGrant

• grant.data.directory.peer_id
• grant.data.service.peer_id
• grant.data.delegator.peer_id

ServiceConnectionGrant

• grant.data.outway.peer_id
• grant.data.service.peer_id
• grant.data.service.delegator.peer_id

DelegatedServiceConnectionGrant

• grant.data.outway.peer_id
• grant.data.service.peer_id
• grant.data.delegator.peer_id
• grant.data.service.delegator.peer_id

The JWS MUST specify the certificate thumbprint of the keypair used to create the digital signature using the x5t#S256 section 4.1.8 of [RFC7515] field of the JOSE Header section 4 of [RFC7515].

The JWS MUST use the JWS Compact Serialization described in section 7.1 of [RFC7515]

The JWS MUST be created using one of the following digital signature algorithms:

• RS256
• RS384
• RS512
• ES256
• ES384
• ES512

The JWS Payload as defined in section 2 of [RFC7515], MUST contain a hash of the contract.content as described in the section Content Hash, one of the signature types described in the signature type section and a Unix timestamp of the sign date.

JWS Payload example:

{
  "contract_content_hash": "--------",
  "type": "accept",
  "signed_at": 1672527600
}

A Peer should ensure that a signature is intended for the Contract.
This validation is done by comparing the hash of the received Contract with the hash in the signature.
The Validation MUST be done every time a Peer receives a signature.

The contract_content_hash of the signature payload contains the signature hash. The algorithm to create a contract_content_hash is described below. The algorithm ensures that the content hash is unique for a specific Contract content. Because a signature contains the content hash it becomes possible to guarantee that a signature is intended for a specific Contract.

1. Create a byte array called contentBytes.
2. Convert contract.content.group_id to bytes and append the bytes to contentBytes.
3. Append contract.content.iv to contentBytes.
4. Convert contract.content.validity.not_before to bytes and append the bytes to contentBytes.
5. Convert contract.content.validity.not_after to bytes and append the bytes to contentBytes.
6. Convert contract.content.created_at to bytes and append the bytes to contentBytes.
7. Create an array of bytes arrays called grantByteArrays
8. For each Grant in contract.content.grants
   1. Create a Grant Hash for the Grant as documented in the Grant Hash section.
   2. Convert the Grant Hash from string to bytes and store them in a byte array named grantBytes.
   3. Append grantBytes to grantByteArrays.
9. Sort the byte arrays in grantByteArrays in ascending order.
10. Append the bytes of grantByteArrays to contentBytes.
11. Hash the contentBytes using the hash algorithm described in contract.content.algorithm.
12. Encode the bytes of the hash using Base64 URL encoding with all trailing '=' characters omitted and without the inclusion of any line breaks, whitespace, or other additional characters.
13. Convert the value of contract.content.algorithm to an int32 and surround it with dollar signs ($). When using the SHA3-512 algorithm this would result in $1$. To convert the hash algorithm to an integer see the type mapping
14. Add 1$ as suffix to the string created in step 13. This is the enum HASH_TYPE_CONTRACT as defined in the field .components.schemas.HashType of the OpenAPI Specification as int32. If the string created in step 13 is $1$, the result should now be $1$1$
15. Add the Base64 generated in step 12 as suffix to the string generated in step 14.

The Grant hash is used in the access token request to identify the Contract and Grant which contain the authorization for the connection to the Service. The iv (Initialization vector) field is included in the Grant hash to create a Grant hash that references to a single Contract. The Grant hash can be created by executing the following steps:

1. Create a byte array named grantBytes
2. Convert contract.content.group_id to bytes and append the bytes to grantBytes.
3. Convert contract.content.iv to bytes and append the bytes to grantBytes.
4. Convert the value of each field of the Grant to bytes and append the bytes to the grantBytes in the same order as the fields are defined in the OpenAPI Specification. To convert the Grant type to an integer see the type mapping
5. Hash the grantBytes using the hash algorithm described in contract.content.algorithm
6. Encode the bytes of the hash using Base64 URL encoding with all trailing '=' characters omitted and without the inclusion of any line breaks, whitespace, or other additional characters.
7. Convert the value of contract.content.algorithm to an int32 and enclose it with $. The int32 value per hash algorithm type is defined in the type mapping.. E.g. The enum HASH_ALGORITHM_SHA3_512 becomes $1$.
8. Determine the HashType that matches with value of Grant.type and convert it to an int32 and add a $ as suffix. The int32 value per hash type is defined in the type mapping. E.g. The enum HASH_TYPE_SERVICE_PUBLICATION_GRANT becomes 2$.
9. Combine the strings containing the hash algorithm (step 6) and Hash type (step 7). E.g. The hash algorithm HASH_ALGORITHM_SHA3_512 and Grant Type GRANT_TYPE_SERVICE_CONNECTION should result in the string $1$2$
10. Prefix the Base64 string generated in step 5 with the string generated in step 8.

The payload of the JWT:

• gth(string):
  The hash of the Grant that serves as basis for the authorization
• gid(string): The ID of the Group
• sub(string): The subject section 4.1.2 of [RFC7519]. This should be the ID of the Peer for whom the token is intended
• iss(string): The issuer section 4.1.1 of [RFC7519]. The ID of the Peer who issued the token. I.e. the Peer who is offering the Service
• svc(string): Name of the Service
• aud(string): The audience section 4.1.3 of [RFC7519]. This should be URI [RFC3986] of the Inway providing the Service. The URI is a URL that MUST contain the scheme and port number used by the Inway
• exp(int): Expiration time section 4.1.4 of [RFC7519]
• nbf(int): Not before section 4.1.5 of [RFC7519]
• cnf(object):
  • x5t#S256(string): The thumbprint of the certificate that is allowed ot use the access token. [section 3.1] of [RFC8705]
• act(object):
  • sub(string): The ID of the Peer connecting to the Service on behalf of another Peer. The field grant.data.delegator.peer_ID of the DelegatedServiceConnectionGrant.
• pdi(string): The ID of the Peer delegating the publication of the Service to another Peer. The field grant.data.service.delegator.peer_ID of the ServiceConnectionGrant or DelegatedServiceConnectionGrant.
• add(object): An object which can be used to provide additional data

Example payload of a JWT for a Peer (sub: 1234567890) connecting to a Service (svc: serviceName) offered by a Peer(iss: 1234567891):

{
    "gth": "$1$4$+PQI7we01qIfEwq4O5UioLKzjGBgRva6F5+bUfDlKxUjcY5yX1MRsn6NKquDbL8VcklhYO9sk18rHD6La3w/mg",
    "gid": "fsc.group.example.id",
    "sub": "1234567890",
    "iss": "1234567891",
    "svc": "serviceName", 
    "aud": "https://inway.com",
    "exp": 1493726400,
    "nbf": 1493722800,
    "cnf": {
      "x5t#S256": "DpAyDYakmVAQ4oOJC3UYLRk/ONRCqMj00TeGJemMiLA"
    },
    "add": {}
}

Example payload of a connection of a Peer (sub: 1234567890) to a Service (svc: serviceName) offered by a Peer (iss: 1234567891) on behalf of another Peer(pdi: 1234567892):

{
    "gth": "$1$4$+PQI7we01qIfEwq4O5UioLKzjGBgRva6F5+bUfDlKxUjcY5yX1MRsn6NKquDbL8VcklhYO9sk18rHD6La3w/mg",
    "gid": "fsc.group.example.id",
    "sub": "1234567890",
    "iss": "1234567891",
    "pdi": "1234567892",
    "svc": "serviceName", 
    "aud": "https://inway.com",
    "exp": 1493726400,
    "nbf": 1493722800,
    "cnf": {
      "x5t#S256": "DpAyDYakmVAQ4oOJC3UYLRk/ONRCqMj00TeGJemMiLA"
    },
    "add": {}
}

Example payload for a JWT of a Peer (act.sub: 1234567892) who is connecting on behalf of Peer (sub: 1234567890) to a Service (svc: serviceName) offered by a Peer (iss: 1234567891):

{
    "gth": "$1$4$+PQI7we01qIfEwq4O5UioLKzjGBgRva6F5+bUfDlKxUjcY5yX1MRsn6NKquDbL8VcklhYO9sk18rHD6La3w/mg",
    "gid": "fsc.group.example.id",
    "sub": "1234567890",
    "iss": "1234567891",
    "svc": "serviceName", 
    "aud": "https://inway.com",
    "exp": 1493726400,
    "nbf": 1493722800,
    "act": {
      "sub": "1234567892"
    },
    "cnf": {
      "x5t#S256": "DpAyDYakmVAQ4oOJC3UYLRk/ONRCqMj00TeGJemMiLA"
    },
    "add": {}
}

The announce is used to share the Manager address and Peer information among Peers. The announce is also used by the Directory to obtain the Manager addresses of all Peers in the Group. Each Peer MUST call the announce endpoint of the Directory to register themselves as participant of the Group.

In addition to announcing to the Directory a Manager SHOULD call the announce endpoint of the Peers with whom the Peer has negotiated Contracts when the address of Manager changes.

The Manager functionality MUST implement an HTTP interface as specified in the OpenAPI Specification.

The Manager is required to include its public address as HTTP Header Fsc-Manager-Address in each POST or PUT request sent to another Manager.

The Manager implements two error formats