cppa3 0.43
Libraries for processing ebCore CPPA version 3 documents
License: mit

=====
cppa3
=====

A package to process ebCore CPPA3 documents.

Description
===========

The CPPA3 package provides a collection of Python modules to process OASIS
ebCore CPPA3 documents and related functionality.  CPPA3 is version 3 of
the ebXML Collaboration Protocol Profile and Agreement specification. A CPP is an
XML document representing a party's technical and business collaboration
capabilities.  A CPA is an XML document representing the agreed collaboration
parameters of two parties.  It can be used to configure B2B messaging systems
used to exchange messages between two parties using the agreed settings.
The ebCore Technical Committee (ebXML Core) is maintaining and enhancing the CPPA
specification.

The development of this package tracks the
development of the ebCore CPPA3 schema and specification. This release of the
package is compatible with: 

 * the latest draft version 2018-12-27, available 
   https://www.oasis-open.org/committees/download.php/64485/cppa-v3.0-wd12.odt (specification WD12)
 * the XML schema of 2017-11-16 
   https://www.oasis-open.org/committees/download.php/64482/cppa3.xsd (XML schema draft #22)

Those versions of the specification and schema support:

 * the complete ebMS 3.0 Core OASIS Standard (docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/os/)
 * the complete AS4 OASIS Standard (http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/profiles/AS4-profile/v1.0/)
 * all of the ebMS 3.0 Part 2 Advanced Features specification (http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/part2/201004/).
 * the ebMS3 SAML Conformance Clause (http://docs.oasis-open.org/ebxml-msg/ebms-v3.0-saml-conformance/v1.0/)
 * the ENTSOG, CEF and SuperAnnuation usage profiles of ebMS3/AS4.
 * ebMS 2.0 (https://www.oasis-open.org/standards#ebxmlmsgv2)
 * SOAP 1.1 and 1.2 messaging
 * WS-ReliableMessaging 1.1, 1.2 (http://docs.oasis-open.org/ws-rx/wsrm/v1.2/) and WS-Reliability 1.1 (http://docs.oasis-open.org/wsrm/2004/06/ws-reliability-1.1.xsd)
 * the AS1, AS2 (https://tools.ietf.org/html/rfc4130) and AS3 IETF EDIINT specifications.
 * AMQP messaging, transport and SASL security
 * and the HTTP 1.1, HTTP/2, FTP, SMTP, SFTP and WebSocket transports.

Currently, eight modules are provided:

 * unify.py provides functionality to automatically form a CPA from two CPPs.
 * match.py provides functionality to match a CPA with a CPP it is based on
 * profile.py allows CPPs or CPAs that reference "ChannelProfile" to pull in defaults specified for those profiles
 * pmode.py provides functionality to generate a (set of) P-Modes from a CPA.
 * cppa23 is a new module that converts v2 CPP or CPA documents to the version 3 schema.
 * schema.py has utilities to work with the CPPA3 schema.
 * smp.py provides functionality to map between CPP3 and SMP XML.
 * view.py provides functionality to create a view on a CPP for a particular viewer.

An earlier version of this library include an incomplete 
experimental module that converts a subset of v3 CPAs to version 2.0 CPA. But ability to upconvert seems to 
make more sense, so this module is no longer maintained.

As the CPPA3 schema is still under development,  it may change in backward-incompatible
ways, and this library will be updated accordingly.

Both Python 2.7.* and CPython 3.7.1 are supported.

unify.py
========

This module defines a single function:

 * *unify*.

This function operates on two CPP XML documents, parsed into element trees using
the Python lxml library, and returns a CPA, if one exists.  If no CPA can be created,
a *UnificationException* is thrown instead.

Internally in the module, the unify function instantiates an object of the CPABuilder
class, and invokes the unify method of that object with the specified CPP documents.
CPA formation is similar to unification in logic programming and involves exploring many (successful
or unsuccessful) paths, possibly repeatedly.  The unify function
memoizes partial search results, and the class provides data structures to locally
store those results (which are specific to the two input CPPs and therefore not
useful in other contexts).  The purpose of memoization is to some extent optimization,
but also keeps the logging human-readable.

This function could be used by one of the two parties in data exchange,  or a third party
management service provider, to create a configuration for the exchange that is
compatible with the profiles of the individual parties.

match.py
========

This module defines a single function

 *  *match*

This function takes a CPA and a CPP and determines whether the CPA matches the CPP. A CPA
matches a CPP if it could have been derived from it by unifying it with some other 
(unspecified) CPP.  This means that one of the two parties in the CPA relates to the 
party in the CPP.  Also,  all other structures, such as service and action bindings, channels,
transport etc. all need to be linkable to a structure in the CPP. As in unification, 
presented party certificates can be checked against specified trust anchor sets.

This function could be used by a party to verify, before accepting it, that a presented CPA
(possibibly created by a communication partner or by a third party service provider) is
compatible with its own configuration, whether related to networking, messaging, security,
business content or process.
 

profile.py
==========

This module defines a ChannelProfileHandler class, which has two main methods: 

 * *load_profile_config* 

This method loads XML files containing definitions of Channels with a ChannelProfile element. The other content is 
interpreted as default values for that profile. 

 * *apply_profile_config*

This method processes a CPP or CPA file and adds, for each Channel with a configured ChannelProfile, the relevant defaults. 
The CPP or CPA can override these values. 

cppa23.py
=========

This module provides a basic automated conversion from CPPA2 to CPPA3.  

 * *cpp23*

This function converts an lxml.etree.Element or lxml.etree.ElementTree representing a version 2 *CollaborationProtocolProfile* 
document to a version 3 *CPP* document.  Since there is no counterparty role information in a version 2 document, the
counterparty role is set to a default role value.

 * *cpa23*

This function converts an lxml.etree.Element or lxml.etree.ElementTree representing a version 2 *CollaborationProtocolAgreement* 
document to a version 3 *CPA* document.

It supports the full *CollaborationRole* hierarchy, with HTTP and SMTP transport, signing, encryption, reliable messaging, and 
partial support for packaging.  It supports asynchronous user messages and asynchronous or synchronous signals.  Nested 
*CanSend* and *CanReceipt* structures are not supported, only flat action bindings.

Version 2 packaging is supported, provided the document references the ebXML header as a *Constituent* in a *Composite* element
that is the last item in a *CompositeList*.  For the payload parts, *PayloadProfile* elements are generated and 
*SOAPWithAttachmentsEnvelope* elements that reference the related payload parts.  This function is tested for (minor variants of)
the samples provided in the CPPA2 standard, and for an anonimized large real-life sample. 

An earlier version of this library included a module that downconverted v3 to v2.  As upconversion makes more
sense, this module is now deprecated.  It is still included in the library but should not be used as it was incomplete.

pmode.py
========

This module defines the following functions:

 * *load_pmodes_from_cpa*
 * *validate_pmode*

The *load_pmodes_from_cpa* function operates on
a CPA document and returns a list of processing modes. Using optional parameters,
the function can be restricted to processing modes involving a particular
named or identified party. If *partyname* is specified, it
will skip any definitions not involving a party with that name.
If *partyid* is specified, it will skip any definitions not involving a party with that name.


The *validate_pmode* function operates on list of processing modes and validates this list
against a JSON schema for processing modes that is part of the library.


smp.py
======

This module defines the following function:

 * *cpp2smp*

The *cpp2smp* function exports a subset of the content of a CPPA3 CPP document to a list of SMP (Service 
Metadata Publisher) XML documents (as *lxml.etree* objects), the first of which is an SMP ServiceGroup and 
the others are SignedServiceMetadata elements.

view.py
=======

This module defines the function:

 * *view_cpp*

The *view_cpp* functions takes as arguments a list of viewer parties and a parsed CPP, where viewer parties
is a list of Party ID,  Party Type pairs.  It returns a view on that CPP that takes into account the
allowed and denied authorization attributes and the supplied party identies, or a *ViewException* if at 
least one of the party identifies is block at CPP top level.  Unreferenced structures are removed from 
the output. An anonymous view is created by passing an empty viewer list as parameter.

Test Suite
==========

Test suites are provided for all modules.  When you run a test suite, you can optionally
validate the CPP or CPA documents against the draft CPPA3 XML schema. To do this,
you must download the schema to a readable location on the filesystem, and set the
*CPPA3XSDDIR* environment variable to this location. If the variable is not set, no validation
is done.

History
=======

v0.43 updated to WD12.

v0.42, full support for CPython 3.7.1.  (Previously we worked with 2.7.10)

v0.39, some cleanups to SMP export.

v0.38, view now omits unreferenced structures (channels, transports, certs etc.)

v0.37, 2017-11-25,  new "view" module and "view_cpp" function.

v0.35, 0.36   2017-11-16 Packaging fixes

v0.34  2017-11-16   AMQP messaging, transport and security;  SFTP transport and SSH keys; StartTLS and
TLS SNI; bug fix in part property matching; leaf certificate presence requirement checks; schema validation 
in tests uses a catalog to load local copies of schemas.  More and more interesting examples,  clean up.

v0.33  2017-09-29   PayloadProfileId element; multiple alternative PayloadProfileId elements; multiple 
ActionBinding elements with same direction and action name supported; CertificateDefauls always retained 
in CPA;  some clean up.

v0.32  2017-09-19   WebSocket transport support in unify. Match module functionality adds delegation, named channel, 
payload profile, authorization (allowed/denied) features. 

v0.31  2017-08-25   First release of match module

v0.30  2017-08-19   First release of new SMP module

v0.29  2017-08-15   PKI updates: clean up of redundant code, CertificateRequired, Trust Anchors in CPA if no 
Cert at unification time; naming consistent with current draft XSD. Added missing CanonicalizationMethod unification.  

v0.28  2017-07-07   Updates for ebBP attribute support. Better support for AS2 in the profile and unify modules. 

v0.27  2017-07-25   Completed module cppa23 up to good enough status. 

v0.26  2017-06-09   First release with new module cppa23

v0.25  2017-06-01   Activation and expiration intervals can now be set a ServiceBinding level.

v0.23  2017-05-10   Unreferenced certificates are not in CPA; bug in trust anchor checks fixed; more tests for ebMS2.

v0.22  2017-04-02   Improvements in profile handler in combination with channel features. Updated tests. New schema.py.

v0.21  2017-03-30   Some fixes and more test samples, covering DATA AND PAYMENT STANDARDS
MESSAGE ORCHESTRATION AND PROFILES from https://www.ato.gov.au/uploadedFiles/Content/SPR/downloads/SPR26583msgorchest.pdf

v0.20  2017-03-27   Fix to pmode.py for AS4 compression

v0.19  2017-03-27   More flexibile profiling: separate templates for "send" en "receiving" channel profiles;
default certificates for signing, encryption, client and server authentication; ebMS3 Split/Join/Compress
feature; IPv4 and IPv6 checks; HTTP configuration covers HTTP 1.1 and HTTP/2.  Support for Web Services
Reliable Messaging protocols (WS-ReliableMessaging and WS-Reliability).

v0.18  2017-03-18   Delegation,  CertificateDefaults. Aligned with OASIS spec WD05 and 
ebCore schema #14.

v0.17  2017-02-09   EDIINT (AS1, AS2, AS3) support including features. WS-Addressing support.

v0.16  2017-01-31   SAML token supports and WS-Addressing improvements

v0.15.1 2017-01-27  Multihop improvements

v0.14, 2017-01-04  Support SecurityPolicy in unify.py

v0.13, 2016-12-27  Fixed a bug in the JSON Pmode generator. Also fixed some tests that had expiration
or activation around 2017-01-01. ..

v0.12, 2016-12-14  Support for the "allowed" and "denied" control attributes.

v0.11, 2016-11-07  Payload security;  bug in handling of cppa:Expression

v0.10, 2016-11-01  New module "profile.py" for ChannelProfile.

v0.9 2016-10-06 Renamed agreementid to agreementidfun. Updated to do list.

v0.8 2016-10-02.  Various Fixes, more tests.

v0.7.8 2016-09-21.  Updated readme.  PullHandling. More Channel Features.

v0.7.1 2016-09-20.  Channel feature support for security and reliable messaging. Tests added correspondingly.

v0.6.1, 2016-08-31.  Customizable AgreementIdentifier; JSON schema fixes.

v0.5.3, 2016-08-26.  Some changes to ensure generated CPAs are schema-valid;  cleaned up test suite.

v0.4,  2016-04-01.  Experimental CPA2 module;  fixes to certificates and trust anchor handling.

v0.3.9, 2016-03-16.  First public release.