RFC 8921
Dynamic Service Negotiation: The Connectivity Provisioning Negotiation Protocol (CPNP)
RFC 8921: Dynamic Service Negotiation: The Connectivity Provisioning Negotiation Protocol (CPNP) 🎀
Okay bestie, this is RFC 8921 🦋 It's an Independent Submission, which means it came in through the independent stream and didn't go through a working group. It's Informational, so it's sharing ideas and it's not a Standards Track spec. It was published in October 2020 (ISSN 2070-1721). The authors are M. Boucadair, Ed. and C. Jacquenet from Orange, D. Zhang from Huawei Technologies, and P. Georgatsos from CERTH. The title block doesn't list anything it obsoletes or updates, so there's no drama there 💅
Abstract
okay so the whole point of this doc is defining the Connectivity Provisioning Negotiation Protocol (CPNP), which is built to help services negotiate their parameters dynamically ✨ that's the core of it.
CPNP is a generic protocol, so it's not just for one thing. It can be used for lots of negotiation purposes, including (but not limited to) connectivity provisioning services, storage facilities, Content Delivery Networks, and more 🌈
Status of This Memo
not gonna lie, this section is kinda serious, but it's important 🙈 This document is not an Internet Standards Track specification. It's published just for informational purposes 💜
It's a contribution to the RFC Series, and it's independent of any other RFC stream. The RFC Editor picked to publish it at their discretion, and they make no statement about how valuable it is for implementation or deployment. Documents the RFC Editor approves for publication aren't candidates for any level of Internet Standard. If you want the details, check Section 2 of RFC 7841 🍓
For the current status, any errata, and how to give feedback, go to https://www.rfc-editor.org/info/rfc8921 🔥
Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, since they describe your rights and restrictions with respect to this document 🫶
Table of Contents
1. Introduction
2. Terminology
3. CPNP Functional Elements
4. Order Processing Models
5. Sample Use Cases
6. CPNP Deployment Models
7. CPNP Negotiation Model
8. Protocol Overview
8.1. Client/Server Communication
8.2. Policy Configuration on the CPNP Server
8.3. CPNP Session Entries
8.4. CPNP Transactions
8.5. CPNP Timers
8.6. CPNP Operations
8.7. Connectivity Provisioning Documents
8.8. Child PQOs
8.9. Multi-Segment Service
8.10. Negotiating with Multiple CPNP Servers
8.11. State Management
8.11.1. On the Client Side
8.11.2. On the Server Side
9. CPNP Objects
9.1. Attributes
9.1.1. CUSTOMER_ORDER_IDENTIFIER
9.1.2. PROVIDER_ORDER_IDENTIFIER
9.1.3. TRANSACTION_ID
9.1.4. SEQUENCE_NUMBER
9.1.5. NONCE
9.1.6. EXPECTED_RESPONSE_TIME
9.1.7. EXPECTED_OFFER_TIME
9.1.8. VALIDITY_OFFER_TIME
9.1.9. SERVICE_DESCRIPTION
9.1.10. CPNP Information Elements
9.2. Operation Messages
9.2.1. QUOTATION
9.2.2. PROCESSING
9.2.3. OFFER
9.2.4. ACCEPT
9.2.5. DECLINE
9.2.6. ACK
9.2.7. CANCEL
9.2.8. WITHDRAW
9.2.9. UPDATE
9.2.10. FAIL
9.2.11. ACTIVATE
10. CPNP Message Validation
10.1. On the Client Side
10.2. On the Server Side
11. Theory of Operation
11.1. Client Behavior
11.1.1. Order Negotiation Cycle
11.1.2. Order Withdrawal Cycle
11.1.3. Order Update Cycle
11.2. Server Behavior
11.2.1. Order Processing
11.2.2. Order Withdrawal
11.2.3. Order Update
11.3. Sequence Numbers
11.4. Message Retransmission
12. Some Operational Guidelines
12.1. CPNP Server Logging
12.2. Business Guidelines and Objectives
13. Security Considerations
14. IANA Considerations
15. References
15.1. Normative References
15.2. Informative References
Acknowledgements
Authors' Addresses1. Introduction ✨
okay so this doc defines CPNP, and its whole job is to dynamically exchange and negotiate connectivity provisioning parameters, plus other service-specific parameters, between a Customer and a Provider 💖 CPNP is a tool that automates the service negotiation and activation procedures, which helps the whole service provisioning process glow up 🌸 It can be seen as a component of the dynamic negotiation metadomain described in Section 2.4 of [RFC7149].
CPNP is a generic protocol, so it can be used for negotiation purposes other than connectivity provisioning. For example, it can request extra storage resources, extend the footprint of a Content Delivery Network (CDN), enable additional features from a cloud Provider, and so on 🧚 CPNP can also be extended with new Information Elements (IEs). Sample negotiation use cases are described in Section 5. Section 4 introduces several order processing models and defines the ones that CPNP targets, and then the CPNP negotiation model is detailed in Section 7.
[RFC7297] describes a Connectivity Provisioning Profile (CPP) template for capturing the connectivity requirements that a transport infrastructure has to meet to deliver various services, like Voice over IP (VoIP), IPTV, and Virtual Private Network (VPN) services [RFC4026] 🦋 The CPP document defines the set of IP transfer parameters that reflect the guarantees the underlying transport network can provide, together with reachability scope and capacity needs. CPNP uses the CPP template to encode the connectivity provisioning clauses that are subject to negotiation. The accepted CPP is then passed to other functional elements that handle the actual service activation and provisioning. For example, Network Configuration Protocol (NETCONF) [RFC6241] or RESTCONF [RFC8040] can be used to activate the network features needed to deliver the accepted service. How the outcome of a CPNP negotiation gets translated into service and network provisioning actions is out of scope of this document 🙈
as a reminder, the (research) community has made several proposals in the past, like Common Open Policy Service protocol for supporting Service Level Specification [COPS-SLS], Service Negotiation Protocol [SrNP], Dynamic Service Negotiation Protocol [DSNP], Resource Negotiation and Pricing Protocol [RNAP], and Service Negotiation and Acquisition Protocol [SNAP] 💜 CPNP leverages the authors' experience with SrNP by separating the negotiation primitives from the service under negotiation, which is such a power move 👑 Also, careful examination of the other proposals revealed some deficiencies that were easier to fix by creating a new protocol instead of modifying existing ones. For example:
- COPS-SLS relies upon the COPS usage for policy provisioning (COPS-PR) [RFC3084], which is a Historic RFC.
- DSNP is tightly designed with one specific service in mind (QoS) and doesn't make any distinction between a quotation phase and the actual service-ordering phase.
One of the main motivations for this document is to provide a permanent reference that shows how service negotiation can be automated 🌈
Implementation details are out of scope 🎀 An example of the required modules and interfaces to implement this specification is sketched in Section 4 of [AGAVE], and this specification builds on that effort.
2. Terminology
this doc uses the following terms, so let's get the vocab down first 📚
- Customer: a business role for an entity that's involved in defining and possibly negotiating an order, including a Connectivity Provisioning Agreement, with a Provider. A connectivity provisioning document is captured in a dedicated CPP template-based document, which may specify (among other information) the sites to be connected, border nodes, and outsourced operations (for example, routing and traffic steering). The right to invoke the subscribed service may be delegated by the Customer to third-party end users or brokering services. A Customer can be a Service Provider, an application owner, an enterprise, a user, and so on 💖
- Network Provider (or Provider): owns and administers one or many transport domains (typically Autonomous Systems (ASes)) made up of (IP) switching and transmission resources (for example, routing, switching, forwarding, and so on). Network Providers are responsible for delivering and operating connectivity services, such as offering global or restricted reachability at specific rates. Offered connectivity services aren't necessarily restricted to IP. The policies that the connectivity service delivery components enforce can be derived from the technology-specific clauses that might be included in agreements with the Customers. If no such clauses are included in the agreement, the mapping between the connectivity requirements and the underlying technology-specific policies to be enforced is deployment specific 🫶
- Quotation Order: a request made by the Customer to the Provider that includes a set of requirements. The Customer may express its service-specific requirements by assigning (strictly or loosely defined) values to the information items in the commonly understood template (for example, the CPP template) that describes the offered service. These requirements are the parameters to be mutually agreed upon ✨
- Offer: a response made by the Provider to a Customer's quotation order that describes the Provider's ability to satisfy the order at the time it's received. Offers reflect the Provider's capability to accommodate received Customer orders, beyond monolithic 'yes/no' answers 🌸 An offer may fully or partially meet the requirements of the corresponding order. In the latter case, it may include alternative suggestions that the Customer can take into account by issuing a new order 🙈
- Agreement: an order placed by the Customer and accepted by the Provider. It signals the successful conclusion of a negotiation cycle 🎀
3. CPNP Functional Elements 🧚
there are two functional elements defined here, and they're kinda the main characters of this whole protocol 👑
CPNP client (or client): a software instance that sends CPNP requests and receives CPNP responses. The current operations a CPNP client can perform are:
- Create a quotation order (Section 9.2.1).
- Cancel an ongoing quotation order under negotiation (Section 9.2.7).
- Accept an offer made by a server (Section 9.2.4).
- Withdraw an agreement (Section 9.2.8).
- Update an agreement (Section 9.2.9).
CPNP server (or server): a software instance that receives CPNP requests and sends back CPNP responses accordingly. The CPNP server is responsible for the following operations:
- Process a quotation order (Section 9.2.2).
- Make an offer (Section 9.2.3).
- Cancel an ongoing quotation order (Section 11.2.3).
- Process an order withdrawal (Section 11.2.3).
4. Order Processing Models ✨
okay bestie, so before a Customer can even think about ordering anything, they need to know what's on the menu 🍓 Providers should first announce (or expose) the services they can provide. That announcement can happen in designated global or Provider-specific service markets, or through direct chats with the Providers. How that announcement process works is outside the scope of this document 💅
Whether or not there's a service announcement/exposure mechanism in place, there are two order processing models you should know about:
Frozen model: The Customer cannot actually negotiate the parameters of the service(s) offered by a Provider. After checking out the Provider's service portfolio, the Customer picks the service offer they want to subscribe to and places an order with the Provider. Order handling is super simple on the Provider side because the service isn't customized for each Customer's needs. It's designed for a whole Customer base that shares the same requirements (i.e., these Customers share the same Connectivity Provisioning Profile) 🎀 This mode can be implemented using existing tools such as [RFC8309].
Negotiation-based model: Unlike the frozen model, the Customer writes up their requirements in a request for a quotation, which then gets sent to one or several Providers 🦋 Solicited Providers check whether they can meet those requirements, and get back to the Customer. They might come back with an offer that doesn't exactly match what the Customer asked for (e.g., a 100 Mbps connection cannot be provisioned given the amount of available resources, but an 80 Mbps connection can be provided) 🫶 A negotiation between the Customer and the Provider(s) then follows until both parties reach an agreement (or don't) 😭
Both frozen and negotiation-based models need appropriate service templates, like a CPP template, and their instantiation to express specific Provider offerings and Customer service requirements, respectively 🌸 CPNP can be used in either model to automate the required Customer-Provider interactions. The frozen model can be seen as a special case of the negotiation-based model ✨ This document focuses on the negotiation-based model. Not only 'yes/no' answers but also counterproposals may be offered by the Provider in response to Customer orders 💜
Order processing management on the Network Provider's side usually relies on features supported by the following functional blocks:
- Network provisioning (including order activation, Network Planning, etc.) 🧚
- Authentication, authorization, and accounting (AAA) 🔥
- Network and service management (performance measurement and assessment, fault detection, etc.) 👑
- Sales-related functional blocks (e.g., billing, invoice validation) 💅
- Network impact analysis 🌈
CPNP doesn't assume any specific knowledge about these functional blocks. It draws a very clear line between protocol operation and the logic for handling connectivity provisioning requests 🦋 An order processing logic is typically fed with the information these functional blocks manipulate. For example, the resources that can be allocated to meet the Customer's requirements may depend on network availability estimates calculated by the planning functions and related policies, as well as the number of orders to be processed at the same time over a given period 🍓
This document does not explain how Customers are identified and then managed by the Provider's information system 🙈
5. Sample Use Cases 🌈
okay so here's a non-exhaustive list of CPNP use cases, and some of them are seriously iconic 💖
- [RFC4176] introduces the Layer 3 VPN (L3VPN) Service Order Management functional block, which is responsible for managing the requests initiated by Customers and tracking the status of completion of the related operations. CPNP can be used between the Customer and the Provider to negotiate L3VPN service parameters 💅
A CPNP server could therefore be part of the L3VPN Service Order Management functional block discussed in [RFC4176]. A L3VPN Service YANG data model (L3SM) is defined in [RFC8299]. Once an agreement is reached, the service can be provisioned using, e.g., the L3VPN Network YANG data model specified in [L3VPN-NETWORK-YANG] ✨
Likewise, a CPNP server could be part of the Layer 2 VPN (L2VPN) Service Order Management functional block. A YANG data model for L2VPN service delivery is defined in [RFC8466]. Once an agreement is reached, the L2VPN service can be provisioned using, e.g., the L2VPN Network YANG data model specified in [L2VPN-NETWORK-YANG] 🦋
- CPNP can be used between two adjacent domains to deliver IP interconnection services (e.g., enable, update, disconnect). For example, two Autonomous Systems (ASes) can be connected via several interconnection points. CPNP can be used between these ASes to upgrade existing links, request additional resources, provision a new interconnection point, etc. 🫶
See, for example, the framework documented in [ETICS] 🌸
- An integrated Provider can use CPNP to rationalize connectivity provisioning needs related to its service portfolio. A CPNP server function is used by network operations teams. A CPNP interface to trigger CPNP negotiation cycles is exposed to service management teams 👑
- Service Providers can use CPNP to initiate connectivity provisioning requests towards a number of Network Providers so as to optimize the cost of delivering their services. Although multiple CPNP ordering cycles can be initiated by a Service Provider towards multiple Network Providers, a subset of these orders may actually be put into effect 🧚
For example, a cloud Service Provider can use CPNP to request more resources from Network Providers 💜
- CPNP can also be used in the context of network slicing [NETSLICES-ARCH] to request network resources together with a set of requirements that need to be satisfied by the Provider. Such requirements aren't restricted to basic IP forwarding capabilities, but may also include a characterization of a set of service functions that may be invoked. For the network slicing case, the instances of a CPP template could be derived from the network slice template documented in [TEAS-SLICE-NBI] 🔥
- CPNP can be used in Machine-to-Machine (M2M) environments to dynamically subscribe to M2M services (e.g., access data retrieved by a set of sensors, extend sensor coverage, etc.) 🌈
Also, Internet of Things (IoT) [RFC6574] domains may rely on CPNP to enable dynamic access to data produced by involved objects, according to their specific policies, to various external stakeholders such as data analytics and business intelligence companies. Direct CPNP-based interactions between IoT domains and interested parties enable open access to diverse sets of data across the Internet, e.g., from multiple types of sensors, user groups, and/or geographical areas 💖
- CPNP can be used in the context of Interface to Network Security Functions (I2NSF) [RFC8329] to capture the Customer-driven policies to be enforced by a set of Network Security Functions 🙈
- A Provider offering cloud services can expose a CPNP interface to allow Customers to dynamically negotiate typical data center resources, such as additional storage, processing and networking resources, enhanced security filters, etc. 🎀
Cloud computing Providers typically structure their computation service offerings by bundling CPU, RAM, and storage units as quotas, instances, or flavors that can be consumed in an ephemeral or temporal fashion during the lifetime of the required function. A similar approach is followed by CPNP (see, for example, Section 9.2.11) ✨
- In the inter-cloud context (also called cloud of clouds or cloud federation), CPNP can be used to reserve computing and networking resources hosted by various cloud infrastructures 🦋
- CDN Providers can use CPNP to extend their footprint by interconnecting their respective CDN infrastructures [RFC6770] (see Figure 1) 🌸
,--,--,--. ,--,--,--.
,-' `-. ,-' `-.
(CDN Provider 'A')=====(CDN Provider 'B')
`-. (CDN-A) ,-' `-. (CDN-B) ,-'
`--'--'--' `--'--'--'
Figure 1: CDN Interconnection- Mapping Service Providers (MSPs) [RFC7215] can use CPNP to enrich their mapping database by interconnecting their mapping system (see Figure 2). This interconnection allows the relaxation of the constraints on PxTR (Proxy Ingress/Egress Tunnel Router) in favour of native LISP (Locator/ID Separation Protocol) forwarding [RFC6830]. Also, it prevents the fragmentation of the LISP mapping database. A framework is described in [LISP-MS-DISCOVERY] 🧚
,--,--,--. ,--,--,--.
,-' `-. ,-' `-.
(Mapping System 'A')===(Mapping System 'B')
`-. ,-' `-. ,-'
`--'--'--' `--'--'--'
Figure 2: LISP Mapping System Interconnect- CPNP may also be used between SDN (Software-Defined Networking) controllers in contexts where Cooperating Layered Architecture for Software-Defined Networking (CLAS) is enabled [RFC8597] 💅
6. CPNP Deployment Models 🎀
several CPNP deployment models can be envisaged, and two examples are listed below ✨
- The Customer deploys a CPNP client while one or several CPNP servers are deployed by the Provider. A CPNP client can discover its CPNP servers using a variety of means (static, dynamic, etc.) 💖
- The Customer does not enable any CPNP client. The Provider maintains a Customer Order Management portal. The Customer can initiate connectivity provisioning quotation orders via the portal, and appropriate CPNP messages are then generated and sent to the relevant CPNP server. In this model, both the CPNP client and CPNP server are under the responsibility of the same administrative entity (i.e., Network Provider) 🦋
Once the negotiation of connectivity provisioning parameters is successfully concluded, that is, an order has been placed by the Customer, the actual network provisioning operations are initiated. The specification of related dynamic resource allocation and policy enforcement schemes, as well as how CPNP servers interact with the network provisioning functional blocks on the Provider side, are out of the scope of this document 🌈
This document does not make any assumptions about the CPNP deployment model either 🫶
7. CPNP Negotiation Model ✨
okay so CPNP sits between a Customer and a Provider 🎀, carrying service orders from the Customer and replies from the Provider so they can land on a service provisioning agreement 💖. The services the Provider offers are super well described using the CPP template for connectivity stuff, so the negotiation is basically a value-settlement situation. They just keep agreeing on the values of the commonly understood info items (service parameters) inside the service description template (Section 9.1.9) 🧚
The content CPNP carries, and the negotiation logic running on the Customer and Provider sides that works with that content (the info inside CPNP messages that keeps the negotiation moving), is transparent to the protocol 🫶. CPNP doesn't need to know what's in there.
The protocol's whole job is to make that logic easy to run by handing it the generic communication primitives it needs ✨.
Negotiations are started and mostly driven by the Customer's logic, so it's totally reasonable to assume the Customer is the only one who can call for an agreement 👑. To avoid clogging the protocol with extra messages, it takes an implicit approach. When the Provider's offer gets accepted, that acceptance is the call for agreement from the Customer 🦋. And the Provider is almost certain to say yes to that, since it's literally an offer the Provider made 💅. Of course, either side can bail on the negotiations at any point, each for its own reasons 🙈.
Based on all that, CPNP uses a quotation order/offer/answer model, which goes through these basic steps (Figure 3):
- The CPNP client states its service requirements in a Provisioning Quotation Order (PQO). The order can include strictly or loosely defined values in the clauses that describe service provisioning characteristics.
- The CPNP server either declines the PQO, makes an offer that addresses the PQO's requirements, or suggests a counterproposal that partly addresses them, in case some specific requirements can't be accommodated 🌸.
- The CPNP client either accepts or declines the offer. Accepting implies a call for agreement, and therefore the agreement between both parties and the conclusion of the negotiation 🎉.
+------+ +------+
|Client| |Server|
+------+ +------+
|=====Requested Service=====>|
|<=====Offered Service=======|
|=====Accepted Service======>|
Figure 3: Simplified Service NegotiationMultiple instances of CPNP can run in a Customer's or a Provider's domains 🍓. A CPNP client can be in multiple simultaneous negotiations with the same or different CPNP servers (parallel negotiations, see Section 8.10), and a CPNP server might need to negotiate with other Provider(s) while it's already negotiating with a CPNP client (cascaded negotiations, see Section 8.8) 🔥.
CPNP leans on various timers to run its operations. There are two types: ones specific to CPNP message transmission, and ones specific to the negotiation logic. The second kind guides the negotiation logic on both client and server sides, especially when the client is juggling parallel negotiations with several servers, or when the server is busy negotiating with other Providers to process a Customer-originated quotation order 😭. CPNP lets a CPNP server ask for extra time to proceed with the negotiation, and the CPNP client can accept or reject that request 💜.
Providers may need to publish available services to Customers (see Section 4). CPNP may optionally support this functionality 🌈. Dedicated templates can be defined for service announcement, and CPNP clients will use them to kick off their CPNP negotiation cycles ✨.
For the sake of simplicity, a single offer/answer stage is assumed within one CPNP negotiation cycle. But like we said, a CPNP client can undertake multiple CPNP negotiation cycles (see Figure 4) 💖.
The model is flexible enough to handle changing conditions during the lifetime of a service (e.g., adding an extra VPN site) 🧚.
+------+ +------+ +------+ +------+
|Client| |Server| |Client| |Server|
+------+ +------+ +------+ +------+
|=====Quotation Order=====>| |=====Quotation Order=====>|
|<==========Offer==========| |<==========Offer==========|
|===========Accept========>| |==========Decline========>|
1-Step Successful Negotiation 1-Step Failed Negotiation
Cycle Cycle
+------+ +------+ +------+ +------+
|Client| |Server| |Client| |Server|
+------+ +------+ +------+ +------+
|===Quotation Order(a)====>| |===Quotation Order(i)====>|
|<==========Offer==========| |<==========Offer==========|
|==========Decline========>| |==========Decline========>|
|===Quotation Order(b)====>| |===Quotation Order(j)====>|
|<==========Offer==========| |<==========Offer==========|
|===========Accept========>| |==========Decline========>|
|===Quotation Order(k)====>|
|<==========Offer==========|
|==========Decline========>|
|===Quotation Order(l)====>|
|<==Fail to make an offer==|
N-Step Negotiation Cycle: N-Step Negotiation Cycle:
Successful Negotiation Failed Negotiation
Figure 4: Overall Negotiation ProcessThis document doesn't define how a CPNP client retrieves its list of active/accepted offers 🤷♀️.
An order can be activated implicitly or explicitly. Section 3.11 of [RFC7297] specifies a dedicated clause called Activation Means, which indicates the action(s) needed to activate access to the (IP connectivity) service 🔌. This document defines a dedicated CPNP message that can be used for explicit activation (Section 9.2.11) ✨.
8. Protocol Overview ✨
8.1. Client/Server Communication
CPNP is a client/server protocol that can run over any transport protocol 🚀. The default transport mode is UDP secured with Datagram Transport Layer Security (DTLS) [RFC6347]. No permanent CPNP transport session needs to be maintained between the client and the server 🦋.
The CPNP client can be configured with the CPNP server(s). Usually the client gets an IP address together with a port number through manual or dynamic configuration (e.g., DHCP). Alternatively, a Provider can advertise the port number (CPNP_PORT) it uses to bind the CPNP service using SRV [RFC2782] 🎀.
The CPNP client may be given a domain name of the CPNP server for PKIX-based authentication purposes. CPNP servers should prefer the use of DNS-ID and SRV-ID over CN-ID identifier types in certificate requests (Section 2.3 of [RFC6125]). URI-IDs should not be used for CPNP server identity verification 🔐.
The client sends CPNP requests using CPNP_PORT as the destination port number. The same port number used as the source port number of a CPNP request sent to a CPNP server is used by the server to reply to that request 💜.
CPNP is independent of the IP address family 🌍.
CPNP retransmission for unreliable transports is discussed in Section 11.4 ⏰.
Considerations related to mutual authentication are discussed in Section 13 🫶.
8.2. Policy Configuration on the CPNP Server ✨
okay so the CPNP server isn't making decisions in a bubble 🫧 it can be plugged into a bunch of outside modules, like Customer Profiles, Network Topology, Network Resource Management, Order Repositories, AAA, and the Network Provisioning Manager. Figure 5 shows the whole squad 💅
These modules feed the server info so it can do stuff like:
- Check whether a Customer is entitled to initiate a provisioning quotation request. 🎀
- Check whether a Customer is entitled to cancel an ongoing order.
- Check whether administrative data (e.g., billing-related information) have been verified before the processing of the request starts. 🧾
- Check whether network capacity is available or additional capacity is required. 📶
- Receive guidelines from network design and sales blocks (e.g., pricing, network usage levels, thresholds associated with the number of CPP templates that can be processed over a given period of time as a function of the nature of the service to be delivered, etc.). 💸
- Transfer completed orders to network provisioning blocks (referred to as "Network Provisioning Manager" in Figure 5). For example, the outcome of CPNP may be passed to modules such as Application-Based Network Operations (ABNO) [RFC7491] or network controllers. These controllers will use protocols such as NETCONF [RFC6241] to interact with the appropriate network nodes and functions for the sake of proper service activation and delivery. 🚀
The list above is not the full menu of CPNP server operations, so there could be more 👀
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.Business & Administrative Management .
.+------------------------++---------------------------+.
.| Business Guidelines || Billing & Charging |.
.+-----------+------------++-----------+---------------+.
. | | .
. +-------------------+ | .
. . . . . . . . . . . . . . . . .|. . .|. . . . . . . . .
. . . . . . . . . . . . . . . . .|. . .|. . . . . . . . .
.Order Handling Management | | .
. +-------------------+ +-------+-----+--------------+ .
. |Network Topology DB+--+ CPNP Server | .
. +-------------------+ +-+---+---+---+---+-----+----+ .
. | | | | | | .
. +------------------------+-+ | | | | | .
. | Network Dimensioning | | | | | | .
. | & Planning | | | | | | .
. +--------------------------+ | | | | | .
. +----------------------------+-+ | | | +---+----+ .
. | | | | | | AAA | .
. | Network +------------+ | | | +--------+ .
. | Resource | +------------+-+ | +-+----------+ .
. | Management | | Customer | | | Orders | .
. | | | Profiles | | | Repository | .
. +-----------------+ +--------------+ | +------------+ .
. . . . . . . . . . . . . . . . . . . .|. . . . . . . . .
+--------------------------------------+----------------+
| Network Provisioning Manager |
+-------------------------------------------------------+Figure 5: Order Handling Management Functional Block (Focus on Internal Interfaces)
The server can also be set up in two order-handling modes 🦋
Fully automated mode: no admin has to lift a finger when a service request comes in. The server runs its decision-making on the orders it gets and can spit out matching offers all on its own 🤖✨
Administrative validation checking: some or all of the server's operations go through admin validation. This mode needs an action from the administrator for every request received 🙋♀️ To make that happen, the CPNP methods that the server can handle automatically (or that go through one or several validation checks) can be configured on the server 🍓
8.3. CPNP Session Entries 🌸
A CPNP session entry is a tuple, and it's made up of these bits:
- Transport session (typically, the IP address of the CPNP client, the client's port number, the IP address of the CPNP server, and the CPNP server's port number). 🛣️
- Incremented sequence number (Section 11.3).
- Customer agreement identifier: a unique ID given to the order under negotiation by the CPNP client (Section 9.1.1). The client also uses this ID to refer to the agreement that comes out of a successful negotiation 💜
- Provider agreement identifier: a unique ID given to the order under negotiation by the CPNP server (Section 9.1.2). The server also uses this ID to refer to the agreement that comes out of a successful negotiation 💜
- Transaction-ID (Section 8.4).
8.4. CPNP Transactions 🔁
A CPNP transaction happens between a client and a server to complete, modify, or withdraw a service agreement. It covers every CPNP message swapped between the two, starting from the client's first request and ending with the server's final response. Each transaction is tied to a CPNP session (Section 8.3) 🧵
Since a client can be juggling multiple CPNP transactions at once, it must give each one an identifier that makes it unique. That identifier is the Transaction-ID 🪪
The Transaction-ID must be assigned randomly by the CPNP client, following the current best practice for generating random numbers [RFC4086], so that it can't be guessed easily 🎲 The client uses the Transaction-ID to check that CPNP responses it receives are valid ✅
Within a transaction, the client picks a sequence number at random and assigns it to the first CPNP message it sends. That number goes up by one for each request message sent after that, within the ongoing transaction (see Section 11.3) 🔢
8.5. CPNP Timers ⏰
CPNP keeps retransmission simple. It uses a retransmission timer called RETRANS_TIMER along with a maximum retry threshold. Section 11 explains how RETRANS_TIMER and the retry threshold are used 🔄
The response timer (EXPECTED_RESPONSE_TIME) is set by the client. It's the number of seconds the client will wait for the server to respond to a PQO request (see Section 9.1.6). If that timer runs out, the client cancels that PQO and generates a CANCEL message to match 🙅♀️
The expected offer timer (EXPECTED_OFFER_TIME) is set by the server. It says the point in time by which the CPNP server is expected to make an offer to the CPNP client (see Section 9.1.7). If no offer shows up by then, the CPNP client treats the order as rejected 💔
The offer expiration timer (VALIDITY_OFFER_TIME) is also set by the server. It's the number of minutes after which an offer the server made stops being valid (see Section 9.1.8) ⌛
8.6. CPNP Operations 🎀
Here are the CPNP operations. They can be extended depending on the kind of transaction, or because of security concerns that might call for a separate CPNP client/server authentication phase before negotiation starts 🔐
QUOTATION (Section 9.2.1): the client uses this to kick off a PQO. When the server gets a QUOTATION request, it can reply with a PROCESSING, OFFER, or FAIL message. A QUOTATION-initiated transaction can end with a FAIL message 🚪
PROCESSING (Section 9.2.2): this tells the other side that its message (the order quotation or the offer) arrived and is being worked on. The server can also send it to ask for more time. In that case, the client may answer with an ACK or a FAIL message, depending on whether extra time can or can't be granted ⏳
OFFER (Section 9.2.3): the server uses this to tell the client about an offer that best fits the requirements in the QUOTATION message it got earlier 🎁
ACCEPT (Section 9.2.4): the client uses this to confirm it accepts an offer from the server. It's a call for agreement. The agreement is reached when an ACK comes back from the server. That's likely to happen if the ACCEPT is sent before the offer's validity time runs out, since the server is unlikely to reject an offer it already made 🤝
DECLINE (Section 9.2.5): the client uses this to turn down an offer from the server. The transaction doesn't have to end right away. For example, the client might place another order, or the server might make another offer 🙅♀️
ACK (Section 9.2.6): the server uses this to acknowledge an ACCEPT or WITHDRAW message. The client uses it to confirm the server's request for more time (sent in a PROCESSING message), so the last quotation order can be processed 👍
CANCEL (Section 9.2.7): the client uses this to cancel (quit) the ongoing transaction 🛑
WITHDRAW (Section 9.2.8): the client uses this to withdraw a completed order (in other words, an agreement) 🫗
UPDATE (Section 9.2.9): the client uses this to update an existing agreement. For example, it can be used to add a new VPN site. This operation starts a new negotiation cycle 🌱
FAIL (Section 9.2.10): the server uses this to say it can't meet the requirements in the PQO sent in the QUOTATION message, or to report an error it ran into while handling the received message. Either way, the server can't make offers, so it ends the ongoing transaction 💀
The client also uses FAIL to turn down a time extension request in a PROCESSING message from the server. The message includes a status code that gives an explanation 📝
The CPNP primitives above don't depend on any particular service. CPNP messages can carry service-specific objects transparently, and the negotiation logic on each side handles them 🧚
The document defines the service objects needed for connectivity provisioning negotiation (see Section 8.7). Other service-specific objects, for alternative deployment schemes or other service provisioning needs, can be defined in the future 🔮
8.7. Connectivity Provisioning Documents 📄✨
Okay bestie, so CPNP uses a few different flavors of Connectivity Provisioning Documents (CPD) 💅. They all follow the same CPP template described in [RFC7297] 🎀
Requested CPD: This is the CPD a CPNP client includes in a QUOTATION request 📝
Offered CPD: The server includes this one in an OFFER message 🎁 It's basically the server saying "here's what I can do," covering all or just some of the clauses from the Requested CPD. Every offer also comes with a validity time attached ⏰
Accepted CPD: If the client says yes to an offer, the Offered CPD gets included in an ACCEPT message 🤝 That same CPD shows up again in an ACK message. So there's a three-way handshake to finish the negotiation, and it's giving very organized 💖
Figure 6 shows a typical CPNP negotiation cycle and how each type of CPD shows up in it 👀
+------+ +------+
|Client| |Server|
+------+ +------+
|======QUOTATION (Requested CPD)=====>|
|<============PROCESSING==============|
|<========OFFER (Offered CPD)=========|
|=============PROCESSING=============>|
|=======ACCEPT (Accepted CPD)========>|
|<=======ACK (Accepted CPD)===========|
| |Figure 6: Connectivity Provisioning Documents 🌸
A CPD can have parameters with fixed values, loosely defined values, or any mix of the two 🧁 A CPD counts as concrete if every single clause has a fixed value 🔒
A typical negotiation cycle kicks off with a quotation order that has loosely defined parameters. Then, as offers roll in, it wraps up with a concrete CPD that's used to lock in the agreement 🦋
8.8. Child PQOs 🧸
Sometimes the server realizes that network resources from another Network Provider need to be allocated to meet what a PQO is asking for 🌐 For example, in an inter-domain VPN service, extra Provider Edge (PE) router resources might need to be allocated. In that case, the server can generate child PQOs to request the right network provisioning operations (see Figure 7) 🧚 Here's the plot twist: the server also acts as a CPNP client in this situation 😭 The server links the parent order to its child PQOs. How that gets done is implementation specific. For instance, it could be done by locally adding the reference of the child PQO to the parent order 📎
+------+ +--------+ +--------+
|Client| |Server A| |Server B|
+------+ +--------+ +--------+
| | |
|=====QUOTATION=====>| |
|<====PROCESSING=====| |
| |=====QUOTATION=====>|
| |<====PROCESSING=====|
| |<=======OFFER=======|
| |=====PROCESSING====>|
| |=======ACCEPT======>|
| |<=======ACK=========|
|<=======OFFER=======| |
|=====PROCESSING====>| |
|=======ACCEPT======>| |
|<=======ACK=========| |
| | |Figure 7: Example of Child Orders 🪄
Note that the server must not activate recursion for an order if the client includes a negotiation option that restricts the negotiation scope to the resources of the server's domain (Section 9.1.10.3) 🚫 If recursion isn't explicitly disabled, the server may notify the client when it's appropriate (Section 9.2.2) 🔔 Whether that notification happens can depend on the nature of the service and on regulatory considerations 🏛️
8.9. Multi-Segment Service 🧩
A composite service, like connectivity, requested by a Customer can turn into a multi-segment service. Think multi-segment connectivity that spans an end-to-end scope 🌈 What that means is one single CPNP request gets broken up into multiple connectivity requests on the Provider's side, which creates child orders 👑 The Provider is the one in charge of splitting the generic provisioning order across multiple segments, and all that complexity stays local to the Provider 🫶
8.10. Negotiating with Multiple CPNP Servers 🤹
A CPNP client can run multiple negotiations in parallel with several servers for different reasons, like cost optimization and fail-safety 💰 Those negotiations might end up as one agreement or many 🎉
Here's the big idea behind parallel negotiations: even though the negotiation protocol is strictly between two parties, the negotiation logic doesn't have to be 🧠 The client's negotiation logic may need to drive all the parallel negotiations together, because talking to one server can change how things go with another. For example, the client might use the responses from every server as input for deciding which messages to send next in each individual negotiation, and what goes in them 🧩 So timing matters a lot on the client's side ⏱️ The client needs to be able to synchronize when it receives responses from the servers. CPNP handles this by letting clients specify, in the QUOTATION message, the time by which the server needs to respond (see Section 9.1.6) 💖
8.11. State Management 🗂️
Both the client and the server keep repositories to store ongoing orders 📚 How those repositories get maintained depends on the deployment, and this document doesn't go into that 🙈 Timestamps are also logged to track state changes ⏰ Tracking can be needed for all kinds of reasons, including regulatory or billing ones 💸
In case the client or the server reboots because of a failure, the use of permanent storage is recommended, since it makes state recovery way easier 🔐
8.11.1. On the Client Side 💻
Here's the list of typical states an order can be in on the client's side 👇
Created: The order has been created. It isn't handled by the client until the administrator allows it to be processed 📝AwaitingProcessing: The administrator has approved processing the created order, but nobody has handled it yet ⏳PQOSent: The order has been sent to the server 📤ServerProcessing: The server has confirmed it received the order ✅OfferReceived: An offer has come in from the server 🎁OfferProcessing: The client is currently processing a received offer 🔍AcceptSent: The client has confirmed the offer to the server 🤝Completed: The server has acknowledged the offer 🎀Cancelled: The order has failed or got cancelled 💔
Sub-states may be defined (for example, to tell failed orders apart from cancelled ones), but those aren't shown in Figure 8 🧐
+------------------+
| Created |-----------------+
+------------------+ |
| |
v |
+------------------+ |
|AwaitingProcessing|----------------+|
+------------------+ ||
| ||
QUOTATION/UPDATE ||
v ||
+------------------+ ||
| PQOSent |---CANCEL------+||
+------------------+ vvv
| +-----+
PROCESSING | |
v | |
+------------------+ CANCEL | C |
| ServerProcessing |------------>| A |
+------------------+ FAIL | N |
| | C |
| | E |
OFFER | L |
| | L |
v | E |
+------------------+ | D |
| OfferReceived |---CANCEL--->| |
+------------------+ | |
| PROCESSING +-----+
v ^^^
+------------------+ |||
| OfferProcessing |---DECLINE-----+||
+------------------+ ||
| ACCEPT ||
v ||
+------------------+ ||
| AcceptSent |---CANCEL-------+|
+------------------+ |
| ACK |
v |
+------------------+ |
| Completed |---WITHDRAW------+
+------------------+Figure 8: Example of a CPNP Finite State Machine (Client Side) 🔥
Okay bestie, picking up right where we left off 💅
8.11.2. On the Server Side ✨
Okay so this is the server's version of the state list 🦋 Every order (and its matching offer) has a state the server can be in. Here's the lineup:
- PQOReceived: the server got the order from the client 📩
- AwaitingProcessing: the server is working on the order, and the server admin might need to step in 🧑💻
- OfferProposed: the request got handled and the offer was sent to the client 🎁
- ProcessingReceived: the server got a PROCESSING message for an offer it sent 📨
- AcceptReceived: the server got a confirmation for the offer from the client 🙌
- Completed: the server acknowledged the accepted offer to the client. Going into this state assumes the client got the ACK, and the server can tell that if it gets a retransmitted ACCEPT message from the client 🫶
- Cancelled: the order can't be accommodated, or the client cancelled it. If resources were reserved, they have to be released in the cancel case 💀
- ChildCreated: a child order was made because resources from another Network Provider are needed 🧚
- ChildPQOSent: a child order was sent to the remote server 🚀
- ChildServerProcessing: the remote server is processing a child order 🌈
- ChildOfferReceived: the remote server got an offer to a child order ⭐
- ChildOfferProcessing: a received offer to a child order is being processed 🍓
- ChildAcceptSent: the child offer (the one the remote server sent back for a child order) is confirmed to that remote server 💜
- ChildCompleted: the remote server acknowledged the accepted child offer ✨
Here's the state machine picture, so you can see how everything connects 👑
+------------------+ +------------------+
|AwaitingProcessing|<----------| ChildCreated |
+------------------+ +------------------+
| | ^
v | |
+------------------+ | |
| ChildPQOSent |----------------+| Q
+------------------+ || U
| || O
QUOTATION/UPDATE || T
v || A +--------------------+
+---------------------+ CANCEL || T | PQOReceived |
|ChildServerProcessing|------------+|| I +--------------------+
+---------------------+ FAIL vvv O | |
| +-----+ N CANCEL |
PROCESSING | |<---|-------+ PROCESSING
v | | | v
+------------------+ | | +------------------------+
|ChildOfferReceived|----CANCEL---| C |<--| AwaitingProcessing |
+------------------+ | A | +------------------------+
| | N | ^ | OFFER
OFFER | C | | +------------------+
| | E |<DECLINE-| OfferProposed |
| | L | | +------------------+
v | L | | |
+------------------+ | E | | PROCESSING
|ChildOfferReceived|---CANCEL----| D | | v
+------------------+ | | | +------------------+
| | |<DECLINE-| Proc'ingReceived |
PROCESSING | | |+------------------+
| +-----+ | | ACCEPT
v ^^^^^ | v
+------------------+ ||||| | +------------------+
|ChildOfferProc'ing|---DECLINE----+|||+-CANCEL-|-| AcceptReceived |
+------------------+ ||| | +------------------+
|ACCEPT ||| | |ACK
v ||| | v
+------------------+ ||| | +------------------+
| ChildAcceptSent |---CANCEL------+|+-WITHDRAW|-| Completed |
+------------------+ | | +------------------+
| ACK | |
v | |
+------------------+ | |
| ChildCompleted |---WITHDRAW-----+ |
| +---------------------------+
+------------------+Figure 9: CPNP Finite State Machine (Server Side) 🎀
9. CPNP Objects 🌸
Okay so this section defines the CPNP objects using the Routing Backus-Naur Form (RBNF) format from [RFC5511] 📝 Also, a couple of notes:
Note 1: The message formats are shown in a generic way, so implementors can adapt the RBNF definitions to their favorite message format. For example, JSON [RFC8259] or Concise Binary Object Representation (CBOR) [RFC7049] can be used. 🍓
Note 2: CPNP messages can't be blindly mapped to RESTCONF messages with the target service modelled as configuration data, because that data is only supposed to be changed by a RESTCONF client. In that model, the RESTCONF server can't use a value other than the one the client set (for example, Section 9.2.3), or remove offers on its own initiative (for example, Section 9.1.8). One option might be to map CPNP operations into RESTCONF actions (RPC), but whether that works is out of scope. 🙈
9.1. Attributes 💖
9.1.1. CUSTOMER_ORDER_IDENTIFIER 🎀
The CUSTOMER_ORDER_IDENTIFIER (Customer Order Identifier) is an identifier that the client assigns to identify an agreement. This identifier must be unique to the client.
The rules for assigning it (including its structure and semantics) are specific to the client (Customer). The value of CUSTOMER_ORDER_IDENTIFIER is included in all CPNP messages.
The client (Customer) assigns this identifier to an order that's still being negotiated, before an agreement is reached. It's used to unambiguously identify the resulting agreement on the client side (Customer).
The server treats CUSTOMER_ORDER_IDENTIFIER as an opaque value. 🫶
9.1.2. PROVIDER_ORDER_IDENTIFIER 🦋
The PROVIDER_ORDER_IDENTIFIER (Provider Order Identifier) is an identifier that the server assigns to identify an order. This identifier must be unique to the server.
The rules for assigning it (including its structure and semantics) are specific to the server (Provider). The PROVIDER_ORDER_IDENTIFIER is included in all CPNP messages except QUOTATION messages (because that state only lives on the client side).
The server (Provider) assigns this identifier to an order that's still being negotiated, before an agreement is reached. It's used to unambiguously identify the resulting agreement on the server side (Provider).
The client treats PROVIDER_ORDER_IDENTIFIER as an opaque value. ✨
9.1.3. TRANSACTION_ID 🌈
This object carries the Transaction-ID introduced in Section 8.4. 🧚
9.1.4. SEQUENCE_NUMBER 🔥
The sequence number is a number that gets monotonically incremented in every new CPNP message for a given CPNP transaction. This number is used to avoid replay attacks. 💀
Refer to Section 11.3. 👑
9.1.5. NONCE 💜
The NONCE is a random value assigned by the CPNP server. Assigning a unique NONCE value for each order is recommended. 🍓
It is mandatory to include the NONCE in subsequent CPNP client operations on the associated order (including the resulting agreement), such as withdrawing the order or updating the order. 🫶
If the NONCE validation checks fail, the server rejects the request with a FAIL message that includes the appropriate failure reason code. 🙈
9.1.6. EXPECTED_RESPONSE_TIME ⭐
This attribute indicates the time by which the CPNP client expects to receive a response from the CPNP server to a given PQO. If no offer has arrived by then, the CPNP client considers the quotation order rejected. ✨
The EXPECTED_RESPONSE_TIME follows the date format specified in [RFC3339]. 🎀
9.1.7. EXPECTED_OFFER_TIME 🦋
This attribute indicates the time by which the CPNP server expects to make an offer to the CPNP client. If no offer has arrived by then, the CPNP client considers the order rejected. 💅
The CPNP server may propose an expected offer time that doesn't match the expected response time given in the quotation order message. The CPNP client can accept or reject the proposed expected time, which is the deadline by which the CPNP server will make an offer. 🌸
The CPNP server can always ask for extra time for its processing, but the CPNP client may accept or reject that. 🧚
The EXPECTED_OFFER_TIME follows the date format specified in [RFC3339]. 💖
9.1.8. VALIDITY_OFFER_TIME 👑
This attribute indicates the validity time of an offer made by the CPNP server. If the offer isn't accepted before this time expires, the CPNP server considers the CPNP client to have rejected the offer, and the CPNP server silently removes this order from its base. 💀
The VALIDITY_OFFER_TIME follows the date format specified in [RFC3339]. 🌈
9.1.9. SERVICE_DESCRIPTION 🔥
This document defines a machinery to negotiate any aspect that's subject to negotiation. Service clauses under negotiation are carried in this attribute. 🍓
The structure of the connectivity provisioning clauses is given in the following subsection. 🫶
9.1.9.1. CPD 💜
The RBNF format of the CPD is shown in Figure 10. 🙈
<CPD> ::= <Connectivity Provisioning Component> ...
<Connectivity Provisioning Component> ::=
<CONNECTIVITY_PROVISIONING_PROFILE> ...
<CONNECTIVITY_PROVISIONING_PROFILE> ::=
<Customer Nodes Map>
<SCOPE>
<QoS Guarantees>
<Availability>
<CAPACITY>
<Traffic Isolation>
<Conformance Traffic>
<Flow Identification>
<Overall Traffic Guarantees>
<Routing and Forwarding>
<Activation Means>
<Invocation Means>
<Notifications>
<Customer Nodes Map> ::= <Customer Node> ...
<Customer Node> ::= <IDENTIFIER>
<LINK_IDENTIFIER>
<LOCALIZATION>
Figure 10: The RBNF format of the CPD9.1.10. CPNP Information Elements 🧚
An Information Element (IE) is an optional object that can be included in a CPNP message. ✨
9.1.10.1. Customer Description 🌸
The client may include administrative information such as the following: 💖
- Name 🎀
- Contact Information 🦋
The format of this Information Element is as follows: 💅
<Customer Description> ::= [<NAME>] [<Contact Information>]
<Contact Information> ::= [<EMAIL_ADDRESS>] [<POSTAL_ADDRESS>]
[<TELEPHONE_NUMBER> ...]9.1.10.2. Provider Description ✨
okay so the server can slip some admin info into an offer, like:
- Name
- AS Number [RFC6793]
- Contact Information
and the format of this Information Element goes like:
<Provider Description> ::= [<NAME>][<Contact Information>]
[<AS_NUMBER>]9.1.10.3. Negotiation Options 💅
the client can bring some negotiation options to the table, like:
Setup purpose: bestie, the client can ask for a service (e.g., connectivity) just for testing, for a limited time 🧪. If it ends up vibing with it, the order can be extended to become permanent 💖. This whole move is done with the UPDATE method.
Activation type: the client can ask for a permanent or scheduled activation type 📅. If there's no activation type clause in the negotiation, the order gets activated right away once the negotiation wraps up ✨.
the format of this Information Element is:
<Negotiation Options> ::= [<PURPOSE>]9.2. Operation Messages 🎀
okay so this section is where the RBNF format of the CPNP operation messages lives 📜. here are the operation codes we use:
+======+===================+================+
| Code | Operation Message | Reference |
+======+===================+================+
| 1 | QUOTATION | Section 9.2.1 |
+------+-------------------+----------------+
| 2 | PROCESSING | Section 9.2.2 |
+------+-------------------+----------------+
| 3 | OFFER | Section 9.2.3 |
+------+-------------------+----------------+
| 4 | ACCEPT | Section 9.2.4 |
+------+-------------------+----------------+
| 5 | DECLINE | Section 9.2.5 |
+------+-------------------+----------------+
| 6 | ACK | Section 9.2.6 |
+------+-------------------+----------------+
| 7 | CANCEL | Section 9.2.7 |
+------+-------------------+----------------+
| 8 | WITHDRAW | Section 9.2.8 |
+------+-------------------+----------------+
| 9 | UPDATE | Section 9.2.9 |
+------+-------------------+----------------+
| 10 | FAIL | Section 9.2.10 |
+------+-------------------+----------------+
| 11 | ACTIVATE | Section 9.2.11 |
+------+-------------------+----------------+
Table 1: CPNP Operation Message Codesthese codes are how we unambiguously identify a CPNP operation 🔍. the operation code rides along in the METHOD_CODE attribute, which we'll get to in the subsections below 🦋.
in the following, VERSION refers to the CPNP version number. this attribute must be set to 1 💜.
9.2.1. QUOTATION
the format of the QUOTATION message is:
<QUOTATION Message> ::= <VERSION>
<METHOD_CODE>
<SEQUENCE_NUMBER>
<TRANSACTION_ID>
<CUSTOMER_ORDER_IDENTIFIER>
[<EXPECTED_RESPONSE_TIME>]
<REQUESTED_CPD>
[<INFORMATION_ELEMENT>...]a QUOTATION message must include an order identifier generated by the client (CUSTOMER_ORDER_IDENTIFIER) 🆔. since several orders can go out to several servers, the QUOTATION message must also include a Transaction-ID 🧾.
the message may include an EXPECTED_RESPONSE_TIME, which tells the server by when the client expects to get an offer ⏰. the QUOTATION message must also include a requested service description (that is, a Requested CPD for connectivity services) 📋.
the message may include ACTIVATION_TYPE to ask for a permanent or scheduled activation type (e.g., using the ACTIVATE method defined in Section 9.2.11) 🔌. if no such clause is included, the default is to assume the order will be active once the accepted activation means are successfully invoked (e.g., Section 3.11 of [RFC7297]) ✨.
when the client sends the QUOTATION message to the server, the state of the order changes to "PQOSent" on the client side 🚀.
9.2.2. PROCESSING
the format of the PROCESSING message is:
<PROCESSING Message> ::= <VERSION>
<METHOD_CODE>
<SEQUENCE_NUMBER>
<TRANSACTION_ID>
<CUSTOMER_ORDER_IDENTIFIER>
<PROVIDER_ORDER_IDENTIFIER>
[<EXPECTED_OFFER_TIME>]
[<PROCESSING_SUBCODE>]okay so when a QUOTATION shows up, the server runs the parsing rules (see Section 10) 🔎. if nothing goes wrong, the server sends a PROCESSING response to say "hey, got your PQO and I'm on it" 🙌. the server must generate an order identifier that points to the order in its local order repository 🗄️. it must also copy the CUSTOMER_ORDER_IDENTIFIER and TRANSACTION_ID fields exactly as they came in the QUOTATION message 🪞. the server may include an EXPECTED_OFFER_TIME for when it expects to make an offer to the client ⏳.
when a PROCESSING message arrives, the client checks whether it actually sent a PQO with that CUSTOMER_ORDER_IDENTIFIER and TRANSACTION_ID to that server 👀. if there's no such PQO, the PROCESSING message must be silently ignored 🙈. if there is one, the client may check whether it's okay with the EXPECTED_OFFER_TIME, and then the order state changes to "ServerProcessing" 💅.
if the server needs more time to process the quotation order, it can send a PROCESSING message with a new EXPECTED_OFFER_TIME ⏱️. the client can reply with an ACK if the extra time is granted (Figure 11) 🎉, or with a FAIL if the time extension request is rejected (Figure 12) 💀.
the server may give more detail in the PROCESSING_SUBCODE attribute about why it needs more time 🧠. these codes are defined:
+=========+============================+
| Subcode | Description |
+=========+============================+
| 1 | Upgrade of local resources |
+---------+----------------------------+
| 2 | Request external resources |
+---------+----------------------------+
Table 2: PROCESSING_SUBCODE Codesand here's the vibe in pictures 🎨:
+------+ +------+
|Client| |Server|
+------+ +------+
|=======QUOTATION(Requested CPD)=====>|
|<========PROCESSING(time1)===========|
...
|<========PROCESSING(MoreTime)========|
|============ACK(TimeGranted)========>|
...
|<=========OFFER(Offered CPD)=========|
|=============PROCESSING=============>|
|=========ACCEPT(Accepted CPD)=======>|
|<=========ACK(Accepted CPD)==========|
| |
Figure 11: Request More Negotiation Time: Granted +------+ +------+
|Client| |Server|
+------+ +------+
|=======QUOTATION(Requested CPD)=====>|
|<========PROCESSING(time1)===========|
...
|<========PROCESSING(MoreTime)========|
|=====FAIL(More Time Rejected)=======>|
Figure 12: Request More Negotiation Time: Rejected9.2.3. OFFER
the format of the OFFER message is:
<OFFER Message> ::= <VERSION>
<METHOD_CODE>
<SEQUENCE_NUMBER>
<TRANSACTION_ID>
<CUSTOMER_ORDER_IDENTIFIER>
<PROVIDER_ORDER_IDENTIFIER>
<NONCE>
<VALIDITY_OFFER_TIME>
<OFFERED_CPD>
[<INFORMATION_ELEMENT>...]the server answers a QUOTATION request from the client with an OFFER message 🎁. the offer is considered rejected by the client if no confirmation (i.e., an ACCEPT message sent by the client) reaches the server before the validity time runs out ⌛. ngl that's a hard deadline 😭.
the server may include ACTIVATION_TYPE to say whether the offer is about a permanent or scheduled activation type 🗓️. the message may include ACTIVATION_SCHEDULE to say when the order gets activated ⚡. if no such clause is included, the default is to assume the order will be active once the accepted activation means are successfully invoked (e.g., Section 3.11 of [RFC7297] or Section 9.2.11) 💫.
9.2.4. ACCEPT
the format of the ACCEPT message is:
<ACCEPT Message> ::= <VERSION>
<METHOD_CODE>
<SEQUENCE_NUMBER>
<TRANSACTION_ID>
<CUSTOMER_ORDER_IDENTIFIER>
<PROVIDER_ORDER_IDENTIFIER>
<NONCE>
<ACCEPTED_CPD>
[<INFORMATION_ELEMENT>...]this is the client's "yes, I'm in" message 🫶, used to confirm an offer it got from a server. the fields of this message must be copied from the received OFFER message 📝. this message should not be sent after the offer's validity time has expired, as indicated by the server (Section 9.2.3) ⏳💅.
9.2.5. DECLINE 🙅♀️
okay so DECLINE is the client's way of saying "nah, I'm good" to an offer 💅 the format looks like this:
<DECLINE Message> ::= <VERSION>
<METHOD_CODE>
<SEQUENCE_NUMBER>
<TRANSACTION_ID>
<CUSTOMER_ORDER_IDENTIFIER>
<PROVIDER_ORDER_IDENTIFIER>
<NONCE>
[<REASON>...]the client is totally allowed to send a DECLINE to reject an offer 🫶 the server uses CUSTOMER_ORDER_IDENTIFIER, PROVIDER_ORDER_IDENTIFIER, TRANSACTION_ID, and NONCE as keys to find the right order, kind of like a locker combo 🔐 if it finds a match, it switches that order's state to "Cancelled" and sends back an ACK with a copy of the Requested CPD to the client who asked. iconic behavior, honestly ✨
a DECLINE can also carry an Information Element that explains why the client is passing 💀 these are the codes:
+======+====================================================+
| Code | Description |
+======+====================================================+
| 1 | Unacceptable gap between the request and the offer |
+------+----------------------------------------------------+
| 2 | Conflict with another offer from another server |
+------+----------------------------------------------------+
| 3 | Activation type mismatch |
+------+----------------------------------------------------+Table 3: DECLINE Message Codes
if no order is found, the server sends a FAIL message back to the requesting client 🙈 and to stop DDoS (Distributed Denial of Service) attacks from turning FAIL messages into a flood, the server should restrict how many FAIL messages it sends to one requesting client. it may also rate-limit FAIL messages. not on my watch, attackers 🛡️
a flow example is in Figure 13 🦋
+------+ +------+
|Client| |Server|
+------+ +------+
|=======QUOTATION(Requested CPD)=====>|
|<============PROCESSING==============|
|<=========OFFER(Offered CPD)=========|
|=============PROCESSING=============>|
|===============DECLINE==============>|
|<================ACK=================|
| |Figure 13: DECLINE Flow Example
9.2.6. ACK 🎀
the ACK format is next, and it's giving "closing the loop" energy 🌸
<ACK Message> ::= <VERSION>
<METHOD_CODE>
<SEQUENCE_NUMBER>
<TRANSACTION_ID>
<CUSTOMER_ORDER_IDENTIFIER>
<PROVIDER_ORDER_IDENTIFIER>
[<EXPECTED_RESPONSE_TIME>]
[<CPD>]
[<INFORMATION_ELEMENT>...]this message is sent by the server to close a CPNP transaction, or by a client to give the server more negotiation time ⏳ the server sends it as a reply to an ACCEPT, WITHDRAW, DECLINE, or CANCEL message. in that case the ACK must include the copy of the service description (that's the CPD for connectivity services) that the server has stored. for connectivity provisioning services, these details matter:
- A copy of the Requested/Offered CPD is included by the server if it successfully handled a CANCEL message.
- A copy of the Updated CPD is included by the server if it successfully handled an UPDATE message.
- A copy of the Offered CPD is included by the server if it successfully handled an ACCEPT message in the context of a QUOTATION transaction (refer to "Accepted CPD" in Section 8.7).
- An Empty CPD is included by the server if it successfully handled a DECLINE or WITHDRAW message.
a client may send an ACK as a reply to a time extension request (carried in PROCESSING) from the server 🫧 when it does, the ACK must include an EXPECTED_RESPONSE_TIME that is likely to be set to the time extension the server asked for. bestie, that's a whole vibe 💜
9.2.7. CANCEL 🚫
CANCEL is the "wait, actually, never mind" message 😭 the format goes:
<CANCEL Message> ::= <VERSION>
<METHOD_CODE>
<SEQUENCE_NUMBER>
<TRANSACTION_ID>
<CUSTOMER_ORDER_IDENTIFIER>
[<CPD>]the client can send a CANCEL at any stage of the CPNP negotiation process, as long as no agreement has been reached yet 🌈 the server uses CUSTOMER_ORDER_IDENTIFIER and TRANSACTION_ID as keys to find the matching order. if a quotation order matches, the server flips that order's state to "Cancelled" and sends back an ACK with a copy of the Requested CPD to the requesting client ✨
if no quotation order is found, the server sends a FAIL message to the requesting client 🥲
9.2.8. WITHDRAW 🫣
WITHDRAW is for when the Customer wants to take back an offer they already accepted 💅 here's the format:
<WITHDRAW Message> ::= <VERSION>
<METHOD_CODE>
<SEQUENCE_NUMBER>
<TRANSACTION_ID>
<CUSTOMER_ORDER_IDENTIFIER>
<PROVIDER_ORDER_IDENTIFIER>
<NONCE>
[<ACCEPTED_CPD>]
[<INFORMATION_ELEMENT>...]this message is used to withdraw an offer already accepted by the Customer. Figure 14 shows a typical use of it 🍓
+------+ +------+
|Client| |Server|
+------+ +------+
|============WITHDRAW(CPD)===========>|
|<============PROCESSING==============|
|<===========ACK(Empty CPD)===========|
| |Figure 14: WITHDRAW Flow Example
the WITHDRAW message must include the same CUSTOMER_ORDER_IDENTIFIER, PROVIDER_ORDER_IDENTIFIER, and NONCE that were used when the order was created 🔑
when a WITHDRAW lands, the server checks whether a matching order exists. if it does, the order's state changes to "Cancelled", and the client gets an ACK that includes an Empty CPD. if there's no match, the server sends a FAIL message back to the requesting client 🙃
9.2.9. UPDATE 🔄
UPDATE is how the CPNP client glows up an existing service agreement, like an Accepted CPD 💖 the format is:
<UPDATE Message> ::= <VERSION>
<METHOD_CODE>
<SEQUENCE_NUMBER>
<TRANSACTION_ID>
<CUSTOMER_ORDER_IDENTIFIER>
<PROVIDER_ORDER_IDENTIFIER>
<NONCE>
<EXPECTED_RESPONSE_TIME>
<REQUESTED_CPD>
[<INFORMATION_ELEMENT>...]this message is sent by the CPNP client to update an existing service agreement (for example, the Accepted CPD) ✨ the UPDATE message must include the same CUSTOMER_ORDER_IDENTIFIER, PROVIDER_ORDER_IDENTIFIER, and NONCE that were used when the order was created. the CPNP client includes a new service description (for example, an Updated CPD) that bakes in the requested changes 💅 a new TRANSACTION_ID must be assigned by the client, so every UPDATE gets its own fresh ID 🪪
when the server gets an UPDATE, it checks whether an order matches CUSTOMER_ORDER_IDENTIFIER, PROVIDER_ORDER_IDENTIFIER, and NONCE AND has state "Completed" 👀
- If no order is found, the CPNP server generates a FAIL error with the appropriate error code (Section 9.2.10).
- If an order is found, the server checks whether it can honor the request:
- A FAIL message is sent to the client if the server cannot honor the request. The client may initiate a new PQO negotiation cycle (that is, send a new UPDATE message).
- An OFFER message including the updated clauses (for example, the Updated CPD) is sent to the client. For example, say the server maintains an order for provisioning a VPN service that connects sites A, B, and C. If the client sends an UPDATE message to remove site C, only sites A and B will be included in the OFFER sent by the server to the requesting client 🗺️
note that the cycle triggered by an UPDATE message is also considered a negotiation cycle 🤝
a flow chart showing how UPDATE works is in Figure 15 🦋
+------+ +------+
|Client| |Server|
+------+ +------+
|=========UPDATE(Requested CPD)======>|
|<============PROCESSING==============|
|<=========OFFER(Updated CPD)=========|
|=============PROCESSING=============>|
|==========ACCEPT(Updated CPD)=======>|
|<==========ACK(Updated CPD)==========|
| |Figure 15: UPDATE Flow Example
9.2.10. FAIL ✨
okay so the FAIL message is the one nobody wants to get, but it's SO important 😭 here's the shape of it, bestie 🎀
<FAIL Message> ::= <VERSION>
<METHOD_CODE>
<SEQUENCE_NUMBER>
<TRANSACTION_ID>
<CUSTOMER_ORDER_IDENTIFIER>
<PROVIDER_ORDER_IDENTIFIER>
<STATUS_CODE>the server sends a FAIL in these situations 💀
- the server cannot honor an order it got from the client (so, one that came in a QUOTATION or UPDATE request).
- the server runs into an error while processing a CPNP request from the client.
- the client can't give the server any more time. this is the reply to a time extension request that rode in on a PROCESSING message.
the status code tells you which error happened, and these are the codes that are supported 👇
+========+==================+=====================================+
| Status | Error Code | Description |
| Code | | |
+========+==================+=====================================+
| 1 | Message | The message cannot be validated |
| | Validation Error | (see Section 10). |
+--------+------------------+-------------------------------------+
| 2 | Authentication | The request cannot be handled |
| | Required | because authentication is required. |
+--------+------------------+-------------------------------------+
| 3 | Authorization | The request cannot be handled |
| | Failed | because authorization failed. |
+--------+------------------+-------------------------------------+
| 4 | Administratively | The request cannot be handled |
| | prohibited | because of administrative policies. |
+--------+------------------+-------------------------------------+
| 5 | Out of Resources | The request cannot be honored |
| | | because resources (e.g., capacity) |
| | | are insufficient. |
+--------+------------------+-------------------------------------+
| 6 | Network Presence | The request cannot be honored |
| | Error | because there is no network |
| | | presence. |
+--------+------------------+-------------------------------------+
| 7 | More Time | The request to extend the time for |
| | Rejected | negotiation is rejected by the |
| | | client. |
+--------+------------------+-------------------------------------+
| 8 | Unsupported | The request cannot be handled |
| | Activation Type | because the requested activation |
| | | type is not supported. |
+--------+------------------+-------------------------------------+
Table 4: FAIL Message Error Codes9.2.11. ACTIVATE 🔥
the ACTIVATE message is how the CPNP client asks to switch on an agreement that already exists 🦋 here's the layout:
<ACTIVATE Message> ::= <VERSION>
<METHOD_CODE>
<SEQUENCE_NUMBER>
<TRANSACTION_ID>
<CUSTOMER_ORDER_IDENTIFIER>
<PROVIDER_ORDER_IDENTIFIER>
<NONCE>
<ACTIVATION_SCHEDULE>
[<INFORMATION_ELEMENT>...]the client sends this when it wants an existing service agreement activated 💖 the message must include the same CUSTOMER_ORDER_IDENTIFIER, PROVIDER_ORDER_IDENTIFIER, and NONCE that were used when the order was created. the client can also include a schedule target for when it wants the order activated. and the client has to give the ACTIVATE message a brand new Transaction_ID 🧚
when the server gets an ACTIVATE, it checks whether there's an order in the "Completed" state that matches CUSTOMER_ORDER_IDENTIFIER, PROVIDER_ORDER_IDENTIFIER, and NONCE 👀
- if the server can't find a completed order, it generates a FAIL error with the right error code (Section 9.2.10). 💀
- if it does find an order, the server checks whether it can actually handle the request:
- a FAIL goes back to the client if the server can't honor the request. for example, it's out of resources, or explicit activation was never negotiated with this client.
- an ACK goes back to confirm the activation (or deactivation) of the order right away. if a non-null ACTIVATION_SCHEDULE came in, the ACK confirms the order was scheduled successfully instead. 🌸
okay now this is the part you need to clock 🙈 setting ACTIVATION_SCHEDULE to 0 in an ACTIVATE request means something special. it's the way to ask for a deactivation of an accepted order. 🚨
here's the flow, visualized 🎀
+------+ +------+
|Client| |Server|
+------+ +------+
|================ACTIVATE()==========>|
|<==============ACK()=================|
| |
Figure 16: ACTIVATE Flow Example10. CPNP Message Validation 💅
both the client and the server do CPNP message validation, and the tables below sum up the checks they're supposed to run 🫶
10.1. On the Client Side 🌈
here's the client-side checklist, bestie 💜
+==============+==================================================+
| Operation | Validation Checks |
+==============+==================================================+
| PROCESSING | {Source IP address, source port number, |
| | destination IP address, destination port number, |
| | Transaction-ID, Customer Order Identifier} must |
| | match an existing PQO with a state set to |
| | "PQOSent". The sequence number carried in the |
| | packet must be larger than the sequence number |
| | maintained by the client. |
+--------------+--------------------------------------------------+
| OFFER | {Source IP address, source port number, |
| | destination IP address, destination port number, |
| | Transaction-ID, Customer Order Identifier} must |
| | match an existing order with state set to |
| | "PQOSent", or {Source IP address, source port |
| | number, destination IP address, destination port |
| | number, Transaction-ID, Customer Order |
| | Identifier, Provider Order Identifier} must |
| | match an existing order with a state set to |
| | "ServerProcessing". The sequence number carried |
| | in the packet must be larger than the sequence |
| | number maintained by the client. |
+--------------+--------------------------------------------------+
| ACK | {Source IP address, source port number, |
| (QUOTATION | destination IP address, destination port number, |
| Transaction) | Transaction-ID, Customer Order Identifier, |
| | Provider Order Identifier, Offered Connectivity |
| | Provisioning Document} must match an order with |
| | a state set to "AcceptSent". The sequence |
| | number carried in the packet must be larger than |
| | the sequence number maintained by the client. |
+--------------+--------------------------------------------------+
| ACK (UPDATE | {Source IP address, source port number, |
| Transaction) | destination IP address, destination port number, |
| | Transaction-ID, Customer Order Identifier, |
| | Provider Order Identifier, Updated Connectivity |
| | Provisioning Document} must match an order with |
| | a state set to "AcceptSent". The sequence |
| | number carried in the packet must be larger than |
| | the sequence number maintained by the client. |
+--------------+--------------------------------------------------+
| ACK | {Source IP address, source port number, |
| (WITHDRAW | destination IP address, destination port number, |
| Transaction) | Transaction-ID, Customer Order Identifier, |
| | Provider Order Identifier, Empty Connectivity |
| | Provisioning Document} must match an order with |
| | a state set to "Cancelled". The sequence number |
| | carried in the packet must be larger than the |
| | sequence number maintained by the client. |
+--------------+--------------------------------------------------+
Table 5: Client Side Validation Checks10.2. On the Server Side 🖥️✨
Okay, the server gets its own checklist too 💅 Before it does anything with a message, it runs the validation checks for that method in Table 6. Every method has its own requirements, so read the row for the message you're dealing with.
+============+==================================================+
| Method | Validation Checks |
+============+==================================================+
| QUOTATION | The source IP address passes existing access |
| | filters (if any). The sequence number carried |
| | in the packet must not be lower than the |
| | sequence number maintained by the server. |
+------------+--------------------------------------------------+
| PROCESSING | The sequence number carried in the packet must |
| | be greater than the sequence number maintained |
| | by the server. |
+------------+--------------------------------------------------+
| CANCEL | {Source IP address, source port number, |
| | destination IP address, destination port number, |
| | Transaction-ID, Customer Order Identifier} must |
| | match an order with state set to "PQOReceived" |
| | or "OfferProposed" or "ProcessingReceived" or |
| | "AcceptReceived". The sequence number carried |
| | in the packet must be greater than the sequence |
| | number maintained by the server. |
+------------+--------------------------------------------------+
| ACCEPT | {Source IP address, source port number, |
| | destination IP address, destination port number, |
| | Transaction-ID, Customer Order Identifier, |
| | Provider Order Identifier, Nonce, Offered |
| | Connectivity Provisioning Document} must match |
| | an order with state set to "OfferProposed" or |
| | "ProcessingReceived". The sequence number |
| | carried in the packet must be greater than the |
| | sequence number maintained by the server. |
+------------+--------------------------------------------------+
| FAIL | {Source IP address, source port number, |
| | destination IP address, destination port number, |
| | Transaction-ID, Customer Order Identifier, |
| | Provider Order Identifier} must match an order |
| | with state set to "AwaitingProcessing" and for |
| | which a request to grant more time to process an |
| | offer was requested. The sequence number |
| | carried in the packet must be greater than the |
| | sequence number maintained by the server. |
+------------+--------------------------------------------------+
| DECLINE | {Source IP address, source port number, |
| | destination IP address, destination port number, |
| | Transaction-ID, Customer Order Identifier, |
| | Provider Order Identifier, Nonce} must match an |
| | order with state set to "OfferProposed" or |
| | "ProcessingReceived". The sequence number |
| | carried in the packet must be greater than the |
| | sequence number maintained by the server. |
+------------+--------------------------------------------------+
| UPDATE | The source IP address passes existing access |
| | filters (if any), and {Customer Order |
| | Identifier, Provider Order Identifier, Nonce} |
| | must match an existing order with state |
| | "Completed". |
+------------+--------------------------------------------------+
| WITHDRAW | The source IP address passes existing access |
| | filters (if any), and {Customer Order |
| | Identifier, Provider Order Identifier, Nonce} |
| | must match an existing order with state |
| | "Completed". |
+------------+--------------------------------------------------+
| ACTIVATE | The source IP address passes existing access |
| | filters (if any), and {Customer Order |
| | Identifier, Provider Order Identifier, Nonce} |
| | must match an existing order with a state of |
| | "Completed" and its activation procedure set to |
| | explicit. |
+------------+--------------------------------------------------+
Table 6: Server Side Validation Checks11. Theory of Operation 🧚
Both the CPNP client and server run message validation checks, as specified in Section 10. The checks are the same vibe on both sides 🫶
11.1. Client Behavior 💖
11.1.1. Order Negotiation Cycle
Okay so, to place a PQO, the client first starts a local quotation order object. It gets identified by a unique identifier that the client assigns itself (Client Order Identifier). The state of that quotation order is set to "Created" ✨
Next, the client builds a QUOTATION request. It includes the assigned identifier, possibly an expected response time, a Transaction-ID, and a requested service (e.g., Requested CPD). The client can also add extra Information Elements, like Customer Description or Negotiation Options 🌸
The client may be configured to not enforce negotiation checks on EXPECTED_OFFER_TIME. If it does that, the client should either leave out the EXPECTED_RESPONSE_TIME attribute in the PQO, or set that attribute to infinite 🙈
Once the request is sent to the server, the state of the request becomes "PQOSent". If a response time was included in the quotation order, a timer gets set to the expiration time from the QUOTATION request. The client also keeps a copy of the CPNP session entry details it used to make the QUOTATION request. The CPNP client must listen on the same port number it used to send that QUOTATION request 🦋
If no answer comes back before the retransmission timer expires (that's RETRANS_TIMER, Section 8.5), the client retransmits the message until it hits the maximum retry count (e.g., three times). The same sequence number gets used for every retransmitted packet 🔁
If a FAIL message shows up, the client gets to choose. It can issue another (corrected) request to the same server, cancel the local order, or contact another server. What it does next depends on the error code the server put in the FAIL message 💀
If a PROCESSING message that matches the CPNP session entry (Section 8.3) arrives, the client updates that session entry with the PROVIDER_ORDER_IDENTIFIER info. If the client doesn't accept the expected offer time that might have been indicated in the PROCESSING message, it may decide to cancel the quotation order. If it does accept the EXPECTED_OFFER_TIME, it changes the order's state to "ServerProcessing" and starts a timer set to the value of EXPECTED_OFFER_TIME. If no offer is made before that timer runs out, the client changes the state of the order to "Cancelled" 😭
When the server asks for a time extension (sent in a PROCESSING message that includes a new EXPECTED_OFFER_TIME), the client can grant it by sending an ACK message. Or it can reject the extension by sending a FAIL message with a status code set to "More Time Rejected" 👑
If an OFFER message that matches the CPNP session entry comes in, the client checks whether a PROCESSING message with the same PROVIDER_ORDER_IDENTIFIER was already received from the server. If a PROCESSING message was received for the same order, but its PROVIDER_ORDER_IDENTIFIER doesn't match the identifier in the OFFER message, the client silently ignores the message. If a PROCESSING message with the same PROVIDER_ORDER_IDENTIFIER was already received and matches the CPNP transaction identifier, the client changes the order's state to "OfferReceived" and starts a timer set to the value of VALIDITY_OFFER_TIME from the OFFER message 🍓
If an offer comes in from the server (documented in an OFFER message), the client may accept or reject it. To accept, the client generates an ACCEPT message that confirms it agrees to subscribe to the offer documented in the OFFER message. The order's state then passes to "AcceptSent". The transaction ends if an ACK message comes back from the server. If no ACK arrives, the client keeps retransmitting the ACCEPT message until it reaches the maximum retry (Section 11.4) 🎀
The client can also reject the offer by sending a DECLINE message. The client sets the order's state to "Cancelled". If the offer isn't acceptable, the client may contact a new server or submit another order to the same server. The guidelines for issuing an updated order or ending the negotiation are specific to each client 🧚
An order can be activated (or deactivated) with the ACTIVATE message, or with other accepted activation means (Section 3.11 of [RFC7297]) ✨
11.1.2. Order Withdrawal Cycle
A client may withdraw a completed order. To do that, it issues a WITHDRAW message. This message must include the Customer Order Identifier, Provider Order Identifier, and Nonce that came back during the order negotiation cycle, as specified in Section 11.1.1 🥀
If no ACK is received from the server, the client retransmits the message. If no ACK comes back after the maximum retry is used up, the client should log the information and must send an alarm to the administrator. If the administrator hasn't given any specific instruction, the client should schedule another Withdrawal cycle. The client must not retry this Withdrawal cycle more often than every 300 seconds, and must not retry more often than every 60 seconds ⏰
11.1.3. Order Update Cycle
A client may update a completed order. To do that, it issues an UPDATE message. This message must include the Customer Order Identifier, Provider Order Identifier, and Nonce returned during the order negotiation cycle specified in Section 11.1.1. The client must also include an Updated CPD with the requested changes inside the UPDATE message 💅
The message exchange after that looks a lot like what's in Section 11.1.1 🫶
11.2. Server Behavior 🖥️
11.2.1. Order Processing 💅
okay bestie, when the server gets a QUOTATION message from a client, it sets up a CPNP session, stores the Transaction-ID, and makes its own Provider Order Identifier 🎀. Once the preliminary validation checks are done (Section 10), the server MAY send back a PROCESSING message so the client knows the quotation order was received and is being processed ✨. It MAY also include an expected offer time, so the client knows by when an offer will be proposed ⏰. The server creates an order in the state AwaitingProcessing 🌸. Then it runs its decision-making process to figure out which offer it can make to honor the order 🧠. The offer SHOULD be made before the expected offer time runs out 💖.
If the server can't make an offer, it sends back a FAIL message with the right error code (Section 9.2.10) 😭.
If the server needs more negotiation time, it MUST send a PROCESSING message with a new EXPECTED_OFFER_TIME ⏳. The client MAY grant that extension by sending an ACK message, or it can reject the time extension by sending a FAIL message with the status code set to More Time Rejected 🙅♀️. If the client doesn't grant more time, the server MUST answer before the initial expected offer time, otherwise the client will decline the quotation order 💀.
If the server can honor the request, or if it can make an offer that meets only some of the requirements, it creates an OFFER message 🦋. The server MUST indicate the Transaction-ID, the Customer Order Identifier as indicated in the QUOTATION message, and the Provider Order Identifier generated for this order. The server MUST also include the Nonce and the offered service document (e.g., Offered CPD). The server includes an offer validity time as well. Once it's sent to the client, the server changes the order's state to OfferProposed, and a timer set to the validity time starts ticking ⏱️.
If the server works out that it needs additional network resources from another Network Provider to accommodate a quotation order, it will create child PQO(s) and will behave as a CPNP client to negotiate child PQO(s) with possible partnering Providers (see Figure 7) 🌐.
If no PROCESSING, ACCEPT, or DECLINE message is received before RETRANS_TIMER expires, the server resends the same offer to the client. This is repeated until the maximum retry is reached 🔁.
If an ACCEPT message is received before the offered validity time expires, the server runs the validation checks specified in Section 10. The order's state moves to AcceptReceived, and the server sends back an ACK message to wrap up the order processing cycle 🎉.
If a CANCEL or a DECLINE message is received, the server goes ahead and cancels the order. The state of the order is then passed to Cancelled 🥀.
11.2.2. Order Withdrawal 🫶
A client MAY withdraw a completed order by sending a WITHDRAW message. When the server gets a WITHDRAW message, it runs the validation checks specified in Section 10:
- If the checks fail, a
FAILmessage is sent back to the client with the appropriate error code (e.g., 1 (Message Validation Error), 2 (Authentication Required), or 3 (Authorization Failed)). - If the checks succeed, the server clears the clauses of the CPD, changes the state of the order to
Cancelled, and sends back anACKmessage with anEmpty CPD🧹.
11.2.3. Order Update ✨
A client MAY update an order by sending an UPDATE message. When the server gets an UPDATE message, it runs the validation checks specified in Section 10:
- If the checks fail, a
FAILmessage is sent back to the client with the appropriate error code (e.g., 1 (Message Validation Error), 2 (Authentication Required), 3 (Authorization Failed), or 6 (Network Presence Error)) 🙈. - The exchange of subsequent messages is similar to what is specified in Section 11.1.1. The server SHOULD generate a new
Noncevalue to be included in the offer made to the client 🔄.
11.3. Sequence Numbers 🔢
In each transaction, sequence numbers are used to protect the transaction against replay attacks 🛡️. Each communicating partner in the transaction keeps two sequence numbers: one for incoming packets and one for outgoing packets. When a partner receives a message, it checks whether the sequence number in the message is larger than the incoming sequence number it's keeping locally. If it isn't, the message gets discarded 🗑️. If the message is proven legitimate, the local incoming sequence number is replaced by the sequence number in the message. When a partner sends out a message, it inserts the outgoing sequence number into the message and then increases the local outgoing sequence number by 1 ➕.
11.4. Message Retransmission 🔁
If a transaction partner sends out a message and doesn't get any expected reply before the retransmission timer expires (i.e., RETRANS_TIMER), it will try to retransmit the message. This keeps going until a maximum retry is reached (e.g., three times) ✋. The exception is the last message (e.g., ACK) sent from the server in a transaction. After sending that one, the retransmission timer gets disabled, since no additional feedback is expected 🙌.
In addition, if the partner receives a retransmission of the last incoming packet it handled, the partner can resend the same answer to the incoming packet with a limited frequency. If an answer can't be generated right after the request is received, the partner needs to generate a PROCESSING message as the answer 📨.
To optimize message retransmission, a partner could also store the last incoming packet and the associated answer 💾. Note that the times of retransmission could be decided by the local policy, and retransmission will not cause any change of sequence numbers 🦋.
12. Some Operational Guidelines 📋
12.1. CPNP Server Logging 📝
The CPNP server SHOULD be configurable to log various events and their associated information 🪵. Such information MAY include the following:
- Client's IP address 🌍
- Any event change (e.g., new quotation order, offer sent, order confirmation, order cancellation, order withdrawal, etc.) 📬
- Timestamp ⏰
The exact logging details are deployment specific 🎀.
12.2. Business Guidelines and Objectives 🧭
The CPNP server can operate in the following modes:
Fully automated mode: The CPNP server is provisioned with a set of business guidelines and objectives that will be used as an input to the decision-making process. The CPNP server will service received orders that fall into these business guidelines. Otherwise, requests will be escalated to an administrator that will formally validate or invalidate an order request. The set of policies to be configured to the CPNP server are specific to each administrative entity managing a CPNP server 🤖.
Administrative-based mode: This mode assumes some or all of the CPNP server's operations are subject to a formal administrative validation. CPNP events will trigger appropriate validation requests that will be forwarded to the contact person(s) or department that is responsible for validating the orders. Administrative validation messages are relayed using another protocol (e.g., SMTP) or a dedicated tool 📧.
Business guidelines are local to each administrative entity. How validation requests are presented to an administrator is out of scope of this document. Each administrative entity MAY decide the appropriate mechanism to enable for that purpose 💼.
13. Security Considerations 🔐
okay this section is SERIOUS bestie, like the whole vibe is "protect your stuff or get rekt" 😭🚨
Means to defend the server against denial-of-service attacks MUST be enabled 🛑. For example, access control lists can be enforced on the client, the server, or the network in between, to allow a trusted client to communicate with a trusted server 🧱.
The client and the server MUST be mutually authenticated 🤝. Authenticated encryption MUST be used for data confidentiality and message integrity 🔒.
The protocol does not provide security mechanisms to protect the confidentiality and integrity of the packets transported between the client and the server 🙃. An underlying security protocol such as (e.g., Datagram Transport Layer Security (DTLS) [RFC6347], Transport Layer Security (TLS) [RFC8446]) MUST be used to protect the integrity and confidentiality of protocol messages 🛡️. In this case, if it is possible to provide automated key management (Section 2.1 of [RFC4107]) and associate each transaction with a different key, inter-transaction replay attacks can naturally be addressed ✨. If the client and the server use a single key, an additional mechanism SHOULD be provided to protect against inter-transaction replay attacks between them 🔑. Clients MUST implement DTLS record replay detection (Section 3.3 of [RFC6347]) or an equivalent mechanism to protect against replay attacks 🔁.
DTLS and TLS with a cipher suite offering confidentiality protection and the guidance given in [RFC7525] MUST be followed to avoid attacks on (D)TLS 🧁.
The client MUST silently discard CPNP responses received from unknown CPNP servers 👻. The use of a randomly generated Transaction-ID makes it hard to forge a response from a server with a spoofed IP address belonging to a legitimate CPNP server 🎲. Furthermore, CPNP demands that messages from the server MUST include the correct identifiers of the orders. Two order identifiers are used: one generated by the client and a second one generated by the server. Both the CPNP client and server maintain the local identifier they assigned and the one assigned by the peer for a given order. Means to detect swapping of these identifiers (even when such swapping occurs inadvertently at the client or the server) SHOULD be enabled by CPNP clients/servers 🕵️♀️. For example, the CPNP server SHOULD NOT assign a Provider agreement identifier that is equal to a Customer agreement identifier used by the CPNP client 🚫.
The Provider MUST enforce the means to protect privacy-related information included in the documents (see Section 8.7) exchanged in CPNP messages [RFC6462] 🫣. In particular, this information MUST NOT be revealed to external parties without the consent of Customers 🙅♀️. Providers SHOULD enforce policies to make Customer fingerprinting difficult to achieve (e.g., in a recursion request) 🕶️. For more discussion about privacy, refer to [RFC6462] [RFC6973] 📖.
The Nonce and the Transaction-ID attributes provide sufficient randomness and can effectively tolerate attacks raised by off-path adversaries, who do not have the capability of eavesdropping and intercepting the packets transported between the client and the server 🌸. Only authorized clients MUST be able to modify accepted CPNP orders 👑. The use of a randomly generated Nonce by the server makes it hard to modify an agreement on behalf of a malicious third party 🥷.
14. IANA Considerations 🦄
This document has no IANA actions. 💖
15. References 📚
15.1. Normative References 💖
okay so these are the must-read-first docs, the ones you're basically borrowing definitions from. 📚
- [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, <https://www.rfc-editor.org/info/rfc3339>.
- [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, "Randomness Requirements for Security", BCP 106, RFC 4086, DOI 10.17487/RFC4086, June 2005, <https://www.rfc-editor.org/info/rfc4086>.
- [RFC5511] Farrel, A., "Routing Backus-Naur Form (RBNF): A Syntax Used to Form Encoding Rules in Various Routing Protocol Specifications", RFC 5511, DOI 10.17487/RFC5511, April 2009, <https://www.rfc-editor.org/info/rfc5511>.
- [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, January 2012, <https://www.rfc-editor.org/info/rfc6347>.
- [RFC7297] Boucadair, M., Jacquenet, C., and N. Wang, "IP Connectivity Provisioning Profile (CPP)", RFC 7297, DOI 10.17487/RFC7297, July 2014, <https://www.rfc-editor.org/info/rfc7297>.
- [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2015, <https://www.rfc-editor.org/info/rfc7525>.
- [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/info/rfc8446>.
15.2. Informative References 🦋
these ones are the extra reading: background, related work, and the wild cast of drafts and papers that shaped the whole vibe. ✨
- [AGAVE] Boucadair, M., Georgatsos, P., Wang, N., Griffin, D., Pavlou, G., Howarth, M., and A. Elizondo, "The AGAVE Approach for Network Virtualization: Differentiated Services Delivery", Annals of Telecommunication, Volume 64, 277-288, DOI 10.1007/s12243-009-0103-4, April 2009, <https://rd.springer.com/article/10.1007/s12243-009-0103-4>.
- [COPS-SLS] Nguyen, T., "COPS Usage for SLS negotiation (COPS-SLS)", Work in Progress, Internet-Draft, draft-nguyen-rap-cops-sls-03, 5 July 2002, <https://tools.ietf.org/html/draft-nguyen-rap-cops-sls-03>.
- [DSNP] Chen, J., "Dynamic Service Negotiation Protocol (DSNP)", Work in Progress, Internet-Draft, draft-itsumo-dsnp-03, 2 March 2006, <https://tools.ietf.org/html/draft-itsumo-dsnp-03>.
- [ETICS] EU FP7 ETICS Project, "Economics and Technologies of Inter-Carrier Services", January 2014, <https://cordis.europa.eu/project/id/248567>.
- [L2VPN-NETWORK-YANG] Barguil, S., Dios, O. G. D., Boucadair, M., Munoz, L. A., Jalil, L., and J. Ma, "A Layer 2 VPN Network YANG Model", Work in Progress, Internet-Draft, draft-ietf-opsawg-l2nm-00, 2 July 2020, <https://tools.ietf.org/html/draft-ietf-opsawg-l2nm-00>.
- [L3VPN-NETWORK-YANG] Barguil, S., Dios, O. G. D., Boucadair, M., Munoz, L. A., and A. Aguado, "A Layer 3 VPN Network YANG Model", Work in Progress, Internet-Draft, draft-ietf-opsawg-l3sm-l3nm-05, 16 October 2020, <https://tools.ietf.org/html/draft-ietf-opsawg-l3sm-l3nm-05>.
- [LISP-MS-DISCOVERY] Boucadair, M. and C. Jacquenet, "LISP Mapping Service Discovery at Large", Work in Progress, Internet-Draft, draft-boucadair-lisp-idr-ms-discovery-01, 9 March 2016, <https://tools.ietf.org/html/draft-boucadair-lisp-idr-ms-discovery-01>.
- [NETSLICES-ARCH] Geng, L., Dong, J., Bryant, S., Makhijani, K., Galis, A., Foy, X. D., and S. Kuklinski, "Network Slicing Architecture", Work in Progress, Internet-Draft, draft-geng-netslices-architecture-02, 3 July 2017, <https://tools.ietf.org/html/draft-geng-netslices-architecture-02>.
- [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for specifying the location of services (DNS SRV)", RFC 2782, DOI 10.17487/RFC2782, February 2000, <https://www.rfc-editor.org/info/rfc2782>.
- [RFC3084] Chan, K., Seligson, J., Durham, D., Gai, S., McCloghrie, K., Herzog, S., Reichmeyer, F., Yavatkar, R., and A. Smith, "COPS Usage for Policy Provisioning (COPS-PR)", RFC 3084, DOI 10.17487/RFC3084, March 2001, <https://www.rfc-editor.org/info/rfc3084>.
- [RFC4026] Andersson, L. and T. Madsen, "Provider Provisioned Virtual Private Network (VPN) Terminology", RFC 4026, DOI 10.17487/RFC4026, March 2005, <https://www.rfc-editor.org/info/rfc4026>.
- [RFC4107] Bellovin, S. and R. Housley, "Guidelines for Cryptographic Key Management", BCP 107, RFC 4107, DOI 10.17487/RFC4107, June 2005, <https://www.rfc-editor.org/info/rfc4107>.
- [RFC4176] El Mghazli, Y., Ed., Nadeau, T., Boucadair, M., Chan, K., and A. Gonguet, "Framework for Layer 3 Virtual Private Networks (L3VPN) Operations and Management", RFC 4176, DOI 10.17487/RFC4176, October 2005, <https://www.rfc-editor.org/info/rfc4176>.
- [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2011, <https://www.rfc-editor.org/info/rfc6125>.
- [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, <https://www.rfc-editor.org/info/rfc6241>.
- [RFC6462] Cooper, A., "Report from the Internet Privacy Workshop", RFC 6462, DOI 10.17487/RFC6462, January 2012, <https://www.rfc-editor.org/info/rfc6462>.
- [RFC6574] Tschofenig, H. and J. Arkko, "Report from the Smart Object Workshop", RFC 6574, DOI 10.17487/RFC6574, April 2012, <https://www.rfc-editor.org/info/rfc6574>.
- [RFC6770] Bertrand, G., Ed., Stephan, E., Burbridge, T., Eardley, P., Ma, K., and G. Watson, "Use Cases for Content Delivery Network Interconnection", RFC 6770, DOI 10.17487/RFC6770, November 2012, <https://www.rfc-editor.org/info/rfc6770>.
- [RFC6793] Vohra, Q. and E. Chen, "BGP Support for Four-Octet Autonomous System (AS) Number Space", RFC 6793, DOI 10.17487/RFC6793, December 2012, <https://www.rfc-editor.org/info/rfc6793>.
- [RFC6830] Farinacci, D., Fuller, V., Meyer, D., and D. Lewis, "The Locator/ID Separation Protocol (LISP)", RFC 6830, DOI 10.17487/RFC6830, January 2013, <https://www.rfc-editor.org/info/rfc6830>.
- [RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., Morris, J., Hansen, M., and R. Smith, "Privacy Considerations for Internet Protocols", RFC 6973, DOI 10.17487/RFC6973, July 2013, <https://www.rfc-editor.org/info/rfc6973>.
- [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, October 2013, <https://www.rfc-editor.org/info/rfc7049>.
- [RFC7149] Boucadair, M. and C. Jacquenet, "Software-Defined Networking: A Perspective from within a Service Provider Environment", RFC 7149, DOI 10.17487/RFC7149, March 2014, <https://www.rfc-editor.org/info/rfc7149>.
- [RFC7215] Jakab, L., Cabellos-Aparicio, A., Coras, F., Domingo-Pascual, J., and D. Lewis, "Locator/Identifier Separation Protocol (LISP) Network Element Deployment Considerations", RFC 7215, DOI 10.17487/RFC7215, April 2014, <https://www.rfc-editor.org/info/rfc7215>.
- [RFC7491] King, D. and A. Farrel, "A PCE-Based Architecture for Application-Based Network Operations", RFC 7491, DOI 10.17487/RFC7491, March 2015, <https://www.rfc-editor.org/info/rfc7491>.
- [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/info/rfc8040>.
- [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/info/rfc8259>.
- [RFC8299] Wu, Q., Ed., Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG Data Model for L3VPN Service Delivery", RFC 8299, DOI 10.17487/RFC8299, January 2018, <https://www.rfc-editor.org/info/rfc8299>.
- [RFC8309] Wu, Q., Liu, W., and A. Farrel, "Service Models Explained", RFC 8309, DOI 10.17487/RFC8309, January 2018, <https://www.rfc-editor.org/info/rfc8309>.
- [RFC8329] Lopez, D., Lopez, E., Dunbar, L., Strassner, J., and R. Kumar, "Framework for Interface to Network Security Functions", RFC 8329, DOI 10.17487/RFC8329, February 2018, <https://www.rfc-editor.org/info/rfc8329>.
- [RFC8466] Wen, B., Fioccola, G., Ed., Xie, C., and L. Jalil, "A YANG Data Model for Layer 2 Virtual Private Network (L2VPN) Service Delivery", RFC 8466, DOI 10.17487/RFC8466, October 2018, <https://www.rfc-editor.org/info/rfc8466>.
- [RFC8597] Contreras, LM., Bernardos, CJ., Lopez, D., Boucadair, M., and P. Iovanna, "Cooperating Layered Architecture for Software-Defined Networking (CLAS)", RFC 8597, DOI 10.17487/RFC8597, May 2019, <https://www.rfc-editor.org/info/rfc8597>.
- [RNAP] Wang, X., "A Resource Negotiation and Pricing Protocol (RNAP)", <http://www.cs.columbia.edu/~xinwang/public/projects/protocol.html>.
- [SNAP] Czajkowski, K., Foster, I., Kesselman, C., Sander, V., and S. Tuecke, "SNAP: A Protocol for Negotiating Service Level Agreements and Coordinating Resource Management in Distributed Systems", DOI 10.1.1.19.5907, 2002, <http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.19.5907>.
- [SrNP] Georgatsos, P. and G. Giannakopoulos, "Service Negotiation Protocol (SrNP)", <https://www.ist-tequila.org/presentations/srnp-pipcm.pdf>.
- [TEAS-SLICE-NBI] Contreras, L. M., Homma, S., and J. A. Ordonez-Lucena, "Considerations for defining a Transport Slice NBI", Work in Progress, Internet-Draft, draft-contreras-teas-slice-nbi-02, 13 July 2020, <https://tools.ietf.org/html/draft-contreras-teas-slice-nbi-02>.
Acknowledgements 🫶
Thanks to Diego R. Lopez, Adrian Farrel, Éric Vyncke, Eric Kline, and Benjamin Kaduk for the comments. 💜
Thanks to those that reviewed this document for publication in the Independent Stream. 🌸
Special thanks to Luis Miguel Contreras Murillo for the detailed review. 👑
Authors' Addresses 🎀
okay bestie, these are the people who wrote this whole thing, so here are their contact details 💌
Mohamed Boucadair (editor)
Orange
35000 Rennes
France
Email: mohamed.boucadair@orange.comChristian Jacquenet
Orange
35000 Rennes
France
Email: christian.jacquenet@orange.comDacheng Zhang
Huawei Technologies
Email: dacheng.zhang@huawei.comPanos Georgatsos
Centre for Research and Innovation Hellas
78, Filikis Etairias str.
38334 Volos
Greece
Phone: +302421306070
Email: pgeorgat@gmail.com📦 where this page comes from
- ietf: rfc8921 2020-10
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms