Skip to content

Latest commit

 

History

History
262 lines (149 loc) · 12.9 KB

contract.negotiation.protocol.md

File metadata and controls

262 lines (149 loc) · 12.9 KB
Raw

Contract Negotiation Protocol

Introduction: Terms

This document outlines the key elements of the contract negotiation protocol. The following terms are used:

  • A message type defines the structure of a message.
  • A message is an instantiation of a message type.
  • The contract negotiation protocol is the set of allowable message type sequences and is defined as a state machine (CNP-SM).
  • A contract negotiation (CN) is an instantiation of the CNP-SM.
  • A provider is a participant agent that offers an asset.
  • A consumer is a participant agent that requests access to an offered asset.

Contract Negotiation Protocol

A contract negotiation (CN) involves two parties, a provider that offers one or more assets under a usage contract and consumer that requests assets. A CN is uniquely identified through an IRI. Each CN requires a newly generated IRI, which may not be used in a CN after a terminal state has been reached. A CN progresses through a series of states, which are tracked by the provider and consumer using messages. A CN transitions to a state in response to an acknowledged message from the counter-party. Both parties have the same state of the CN. In case the states differ, the CN is terminated and a new CN has to be initiated.

The CN states are:

  • REQUESTED - A contract for an asset has been requested by the consumer based on an offer and the provider has sent an ACK response.
  • OFFERED - The provider has sent a contract offer to the consumer and the consumer has sent an ACK response.
  • ACCEPTED - The consumer has accepted the latest contract offer and the provider has sent an ACK response.
  • AGREED - The provider has accepted the latest contract offer, sent an agreement to the consumer, and the consumer has sent an ACK response.
  • VERIFIED - The consumer has sent an agreement verification to the provider and the provider has sent an ACK response.
  • FINALIZED - The provider has sent a finalization message including his own agreement verification to the consumer and the consumer has sent an ACK response. Data is now available to the consumer.
  • TERMINATED - The provider or consumer has placed the contract negotiation in a terminated state. A termination message has been sent by either of the participants and the other has sent an ACK response. This is a terminal state.

Contract Negotiation State Machine

The CN state machine is represented in the following diagram. Note that transitions to the TERMINATED state may occur from any other state and are not shown for simplicity:

Transitions marked with C indicate a message sent by the consumer, transitions marked with P indicate a provider message. Terminal states are final; the state machine may not transition to another state. A new CN may be initiated if, for instance, the CN entered the TERMINATED state due to a network issue.

Message Types

The CN state machine is transitioned upon receipt and acknowledgement of a message. This section details those messages as abstract message types.

Notes

  • Concrete wire formats are defined by the protocol binding, e.g. HTTPS.
  • All policy types (Offer, Agreement) must contain an unique identifier in the form of a URI. GUIDs can also be used in the form of URNs, for instance following the pattern urn:uuid:{GUID}.
  • An ODRL Agreement must have a target property containing the asset id.

1. ContractRequestMessage

Sent by: Consumer

Resulting State: REQUESTED, TERMINATED

Example: ContractRequestMessage

Response: ACK or ERROR.

Schema: ContractRequestMessageShape, ContractRequestMessage JSON Schema, ContractNegotiationShape and ContractNegotiation JSON Schema

Description

The ContractRequestMessage is sent by a consumer to initiate a contract negotiation.

Notes

  • The consumer must include an offer property, which itself must have a @id property. If the message includes a processId property, the request will be associated with an existing contract negotiation and a consumer offer will be created using either the offer or offer.@id properties. If the message does not include a processId, a new contract negotiation will be created using either the offer or offer.@id properties and the provider selects an appropriate processId.

  • An offer.@id will generally refer to an offer contained in a catalog. If the provider is not aware of the offer.@id value, it must respond with an error message.

  • The dataset id is not technically required but included to avoid an error where the offer is associated with a different data set.

  • callbackAddress is a URL indicating where messages to the consumer should be sent in asynchronous settings. If the address is not understood, the provider MUST return an UNRECOVERABLE error.

2. ContractOfferMessage

Sent by: Provider

Resulting State: OFFERED, TERMINATED

Example: ContractOfferMessage

Response: ACK or ERROR.

Schema: ContractOfferMessageShape and ContractOfferMessage JSON Schema

Description

The ContractOfferMessage is sent by a provider to initiate a contract negotiation.

3. ContractAgreementMessage

Sent by: Provider

Resulting State: AGREED, TERMINATED

Example: ContractAgreementMessage

Response: ACK or ERROR.

Schema: ContractAgreementMessageShape and ContractAgreementMessage JSON Schema

Description

The ContractAgreementMessage is sent by a provider when it agrees to a contract. It contains the complete contract agreement with the provider's signature.

A ContractAgreementMessage must contain a processId.

A ContractAgreementMessage must contain an ODRL Agreement.

An Agreement must contain a dspace:timestamp property defined as an XSD DateTime type.

An Agreement must contain a dspace:consumerId and dspace:providerId. The contents of these properties are a dataspace-specific unique identifier of the contract agreement parties. Note that these identifiers are not necessarily the same as the identifiers of the participant agents negotiating the contract (i.e. the "connectors").

4. ContractAgreementVerificationMessage

Sent by: Consumer

Resulting State: VERIFIED, TERMINATED

Example: ContractAgreementVerificationMessage

Response: ACK or ERROR.

Schema: ContractAgreementVerificationMessageShape and the ContractAgreementVerificationMessage JSON Schema

Description

The ContractAgreementVerificationMessage is sent by a consumer to verify the acceptance of a contract agreement. A provider responds with an error if the signature can't be validated or is incorrect.

A ContractAgreementVerificationMessage must contain a processId.

5. ContractNegotiationEventMessage

Sent by: Provider or Consumer

Resulting State: FINALIZED, ACCEPTED, TERMINATED

Example: ContractNegotiationEventMessage

Response: ACK or ERROR.

Schema: ContractNegotiationEventMessageShape and the ContractNegotiationEventMessage JSON Schema

Description

When the ContractNegotiationEventMessage is sent by a provider with an eventType property set to FINALIZED, a contract agreement has been finalized and the associated asset is accessible. The state machine is transitioned to the FINALIZED state. Other event types may be defined in the future. A consumer responds with an error if the signature can't be validated or is incorrect.

It is an error for a consumer to send a ContractNegotiationEventMessage with an eventType FINALIZED to the provider.

When the ContractNegotiationEventMessage is sent by a consumer with an eventType set to ACCEPTED, the state machine is placed in the ACCEPTED state.

It is an error for a provider to send a ContractNegotiationEventMessage with an eventType ACCEPTED to the consumer.

Note that contract events are not intended for propagation of agreement state after a contract negotiation has entered a terminal state. It is considered an error for a consumer or provider to send a contract negotiation event after the negotiation state machine has entered a terminal state.

6. ContractNegotiationTerminationMessage

Sent by: Consumer or Provider

Resulting State: TERMINATED

Example: ContractNegotiationTerminationMessage

Response: ACK or ERROR.

Schema: ContractNegotiationTerminationMessageShape and the ContractNegotiationTerminationMessage JSON Schema

Description

The ContractNegotiationTerminationMessage is sent by a consumer or provider indicating it has cancelled the negotiation sequence. The message can be sent at any state of a negotiation without providing an explanation. Nevertheless, the sender may provide a description to help the receiver.

Notes

  • A contract negotiation may be terminated for a variety of reasons, for example, an unrecoverable error was encountered or one of the parties no longer wishes to continue. A connector's operator may remove terminated contract negotiation resources after it has reached the terminated state.

  • If an error is received in response to a ContractNegotiationTerminationMessage, the sending party may choose to ignore the error.

Response Types

Notes

  • The ACK and ERROR response message types are mapped onto a protocol such as HTTPS. A description of an error might be provided in protocol-dependent forms, e.g. for an HTTPS binding in the request or response body.

ACK - ContractNegotiation

Sent by: Consumer or Provider

Example: ContractNegotiation

Schema: ContractNegotiationShape and the ContractNegotiationErrorMessage JSON Schema

Description

The ContractNegotiation is an object returned by a consumer or provider indicating a successful state change happened.

ERROR - ContractNegotiationError

Sent by: Consumer or Provider

Example: NegotiationError

Schema: ContractNegotiationErrorShape and the ContractNegotiationErrorMessage JSON Schema

Description

The ContractNegotiationError is an object returned by a consumer or provider indicating an error has occurred. It does not cause a state transition.

Hash and Signature Calculations

Hash and Signatures are calculated as defined in the [JWS/CT] of ...

References

JWS Clear Text JSON Signature Option

  • Adopt JWS/CT, an extension to the JSON Web Signature (JWS) standard.
  • Combines the detached mode of JWS with the JSON Canonicalization Scheme (JCS). Detached mode is when the payload section of the JWS is replaced by an empty string: XXXX.PAYLOAD.YYYY becomes XXXX..YYYY. Detached mode is described in the JWS spec.
  • Maintains Signed JSON data in JSON format.