Reference implementations

11th November 2010Malmö

Thomas RavnholtPEPPOL Reference Implementation team

Reference Implementation team

• Team of 5 experienced developers – some from NemHandel (Danish eProcurement)

• Developed 20+ solutions/libraries • Approximately 6 months of development time– A lot of changes in the specifications– Complete rewrite from 0.8 to 0.9

• Created a test infrastructure with live Access Points etc.

Reference Implementations

• START AP: The Secure Trusted Asynchronous Reliable Transport (Java, .NET)– The main protocol for sending messages

• LIME AP: The Lightweight Message Exchange Transport (Java, .NET)– A lighter protocol towards senders

• SMP: Service Metadata Publisher (Java)• SML: Service Metadata Locator (Java)• DNS: A PEPPOL domain has been set up

Technology (Java)

• Java– JDK 6– Java Metro 2.0 https://metro.dev.java.net/– Ant 1.7.x+ http://ant.apache.org – Apache Tomat 6.0.x – http://tomcat.apache.org

• Tested on – Windows Vista– Ubuntu 8.10

Technology (.NET C#)

• Microsoft .NET Framework 3.5• Windows Identity Foundation • Internet Information Services (IIS) • Custom build from MS– System.IdentityModel.dll and

System.ServiceModel.dll

• Tested on– Windows XP, Windows Vista, Windows 7

PEPPOL repository

• PEPPOL implementations is stored in Subversion at– svn.forge.osor.eu

• Everyone can check out the source code

• Need certificate to commit source code

• Each project contains a trunk and several tags

Java START projects

• busdox-transport-start-library– Core classes for building a START client

• busdox-transport-start-client– A sample START client

• busdox-transport-start-server– Implementation of a START Access Point

• busdox-transport-commons– Generic busdox classes shared by LIME and START

• https://svn.forge.osor.eu/svn/peppol/java/TransportLibrary/START/tags/

.NET START projects

• STARTLibrary– Core types for building START Access Points and

Clients + WSDL and scheams• STARTAccessPoint– Implementation of the START Access Points

• SampleSTARTClient– A sample START client

• https://svn.forge.osor.eu/svn/peppol/dotnet/transportlibrary/tags/

.NET LIME projects

• LIMELibrary– Core types for building LIME Access Points and

Clients + WSDL and Schemas • LIMEService– Implementation of the LIME Access Points

• IOLayerLibrary– Message store

• https://svn.forge.osor.eu/svn/peppol/dotnet/transportLibrary/tags

Java LIME projects

• busdox-transport-lime-library– Core classes for building a LIME client

• busdox-transport-lime-client– A sample LIME client

• busdox-transport-lime-server– Implementation of a LIME Access Point

• busdox-transport-commons– Generic busdox classes shared by LIME and START

• https://svn.forge.osor.eu/svn/peppol/java/TransportLibrary/LIME/tags/

Service Metadata Locator (Java)

• Management service – A webservice for manipulating SML records

• Management client library– Core classes for building a Management Client

• Management console client– A sample Management client

• https://svn.forge.osor.eu/svn/peppol/java/ServiceMetadataLocator

Service Metadata Publisher (Java)

• RESTBinding– Service Metadata Publisher REST service

• RESTBindingLibrary– A Service Metadata Publisher client library

• CommonLibrary– Generic classes and schemas

• https://svn.forge.osor.eu/svn/peppol/java/ServiceMetadataPublishing

Deployed .NET Access Points

• START .NET– https://ec2-174-129-36-72.compute-1.amazonaws.com:8444/

PeppolAccessPoint1/STARTAccessPoint.svc– https://ec2-174-129-36-72.compute-1.amazonaws.com:8444/

PeppolAccessPoint/STARTAccessPoint.svc

• LIME .NET– https://ec2-174-129-36-72.compute-1.amazonaws.com:8081/

limeService1.0Even/ResourceService.svc – https://ec2-174-129-36-72.compute-1.amazonaws.com:8081/

limeService1.0UnEven/ResourceService.svc

Deployed Java Access Points

• START JAVA– http://ec2-174-129-190-34.compute-1.amazonaws.com:8080/busdox-

transport-start-server-1.0.1/accesspointService– http://ec2-174-129-190-34.compute-1.amazonaws.com:8080/busdox-

transport-start-server2-1.0.1/accesspointService

• LIME JAVA– http://ec2-174-129-190-34.compute-1.amazonaws.com:8080/busdox-

transport-lime-server-1.0.1/wstransferService– http://ec2-174-129-190-34.compute-1.amazonaws.com:8080/busdox-

transport-lime-server2-1.0.1/wstransferService

Deployed DNS, SML and SMP

• A PEPPOL DNS has been configured– Used by reference implementations and demonstrator

clients

• SML Mangement interfaces– http://ec2-174-129-190-34.compute-1.amazonaws.com/

ServiceMetadataLocatorManagement/managebusinessidentifier

– http://ec2-174-129-190-34.compute-1.amazonaws.com/ServiceMetadataLocatorManagement/manageservicemetadata

• SMP REST interface– http://ec2-174-129-190-34.compute-

1.amazonaws.com:8080/

Test data

• Test data have been created for id’s in the range– 1-16 (0010:5798000000001..16)– 100-250 (0010:5798000000100..250)– 500-650 (0010:5798000000500..650)

• A lot of document types and process types for each identifier

• Endpoints point to reference implementation AP’s (but can be changed)

• Obtain Identifier for development and testing from thorkild@peppolinfrastructure.com

PEPPOL release 1.0.0

• Changes to come– Update of namespaces when moving under OASIS– Upgrade to new PEPPOL certificate infrastructure– Optimizing RM endpoint handling• RM endpoint bug accepted by Metro (priority 2)

– Support for tokentype on SecurityTokenReference– Better protocol test tools (only ping now)– Generel improvements (performance, caching

etc.)

Purpose of Reference Implementation

• Use the Reference Implementations– as a fast way to get started building you

own AP’s• Source code available• Complete test infrastructure deployed• Testdata ready

– as inspiration– a quick way to test compliance of AP clients

Using the SMP and SML

Sending documents

SMP Registry

Company X

START AP Country A

START AP Country B

Company Y

Obtain metadata

Steps for sending documents

1) Obtain metadata for the recipient ID2) Get endpoint from metadata for specific

document and process type3) Create SOAP message metadata headers

and SAML token4) Send message to AP

What is a START message

• A message from one AP to another

• SOAP headers– Sender and Recipient (participant id)– Document type (order, invoice,…)– Process type (ordering, billing, payment, …)– Message ID

• SOAP body– The CEN BII UBL XML payload

Participant identifiers

• Senders and receivers of message are addressed by participant identifiers

• In URI’s– {identifier scheme}::{type id:id}– busdox-actorid-upis::0010:5798000000001

• Participant identifiers logically consist of a scheme identifier and the business identifier itself and a type– Type is 4-digit number indicating the type of participant id

such as GLN, DUNS, CVR – Scheme indicates the textual format of the participant id

Service Metadata Publisher (SMP)

• Holds info on message receivers

• Several SMP’s in the PEPPOL infrastructure

• Each SMP hold metadata for a unique subset of identifiers

• SMP’s are located using a DNS scheme with participant identifiers– avoids having a central server for locating SMP’s

Service Metadata Publishers (SMP)

• Metadata contains– Document and process types accepted by a receiver– Address of receivers Access Point

• Metadata can be read using plain HTTP (REST interface)

• Metadata can be updated using a management API (webservice)

SMP metadata XML<?xml version="1.0" encoding="UTF-8"?><ns3:SignedServiceMetadataType xmlns:ns3="http://busdox.org/serviceMetadata/publishing/1.0/"

xmlns="http://busdox.org/transport/identifiers/1.0/" xmlns:ns2="http://www.w3.org/2005/08/addressing" xmlns:ns4="http://www.w3.org/2000/09/xmldsig#">

<ns3:ServiceMetadata> <ns3:ServiceInformation> <ParticipantIdentifier scheme="busdox-actorid-upis">0010:5798000000014</ParticipantIdentifier> <DocumentIdentifier scheme="busdox-docid-

qns">urn:oasis:names:specification:ubl:schema:xsd:AcceptCatalogue-2::AcceptCatalogue##UBL-2.0</DocumentIdentifier>

<ns3:ProcessList> <ns3:Process> <ProcessIdentifier scheme="cenbii-procid-ubl">BII01</ProcessIdentifier> <ns3:ServiceEndpointList> <ns3:Endpoint transportProfile="busdox-transport-start"> <ns2:EndpointReference> <ns2:Address>https://ec2-174-129-36-72.compute-1.amazonaws.com:8444/

PeppolAccessPoint/STARTAccessPoint.svc</ns2:Address> </ns2:EndpointReference>

…..<ns3:Certificate>test-0000000003</ns3:Certificate></ns3:Endpoint>…..

-----

Tools: SMP Registration Site

• Developer tool (RegistrationSite)– View, update and delete SMP Metadata

• Reference implementation of SMP contains a RegistrationSite– http://ec2-174-129-190-34.compute-

1.amazonaws.com/RegistrationSite/

Locating the SMP

Locating the SMP using DNS• All recipients have a CNAME in the DNS

• Host names are constructed using info on the recipient

• SMP host = ”B-”+MD5(id)+scheme+base domain

• http://B-e49b223851f6e97cbfce4f72c3402aac.busdox-actorid-upis.sml1.smloc.org/....– 0010:5798000000001 MD5’ed is e49b223851f6e97cbfce4f72c3402aac

Is the recipient ID in the DNS?

Getting metadata on runtime

• SMP REST interface– http://host/{identifier scheme}::{id}/services/{docType}

• recipient scheme= "busdox-actorid-upis”;• recipient= "0010:5798000000014";• documentIdScheme = "busdox-docid-

qns::urn:oasis:names:specification:ubl:schema:xsd:AcceptCatalogue-2";• documentIdValue = "AcceptCatalogue##UBL-2.0";• processIdScheme = "cenbii-procid-ubl";• processIdValue = "BII01";

• http://B-5d56ef90fea494be06e7f51031c92b56.busdox-actorid-upis.sml1.smloc.org/busdox-actorid-upis%3A%3A0010%3A5798000000014/services/busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3AAcceptCatalogue-2%3A%3AAcceptCatalogue%23%23UBL-2.0

SMP metadata XML<?xml version="1.0" encoding="UTF-8"?><ns3:SignedServiceMetadataType xmlns:ns3="http://busdox.org/serviceMetadata/publishing/1.0/"

xmlns="http://busdox.org/transport/identifiers/1.0/" xmlns:ns2="http://www.w3.org/2005/08/addressing" xmlns:ns4="http://www.w3.org/2000/09/xmldsig#">

<ns3:ServiceMetadata> <ns3:ServiceInformation> <ParticipantIdentifier scheme="busdox-actorid-upis">0010:5798000000014</ParticipantIdentifier> <DocumentIdentifier scheme="busdox-docid-

qns">urn:oasis:names:specification:ubl:schema:xsd:AcceptCatalogue-2::AcceptCatalogue##UBL-2.0</DocumentIdentifier>

<ns3:ProcessList> <ns3:Process> <ProcessIdentifier scheme="cenbii-procid-ubl">BII01</ProcessIdentifier> <ns3:ServiceEndpointList> <ns3:Endpoint transportProfile="busdox-transport-start"> <ns2:EndpointReference> <ns2:Address>https://ec2-174-129-36-72.compute-1.amazonaws.com:8444/

PeppolAccessPoint/STARTAccessPoint.svc</ns2:Address> </ns2:EndpointReference>

…..<ns3:Certificate>test-0000000003</ns3:Certificate></ns3:Endpoint>…..

-----

Obtaining the AP url from SMP (C#) public static string BuildAccesspointUrl(string SMLDomain, string RecipientIdentifierValue, string RecipientIdentifierScheme, string DocumentIdentifierValue, string DocumentIdentifierScheme) { var url = "http://" + string.Format("b-{0}.{1}.{2}/{1}::{3}/services/{4}", Utilities.GetMD5Hash(RecipientIdentifierValue), RecipientIdentifierScheme, SMLDomain, RecipientIdentifierValue, DocumentIdentifierScheme + "::" +

DocumentIdentifierValue ).Replace(":", "%3A").Replace("#", "%23"); return url; }

Service Metadata Locator (SML)

• Think of the SML as the interface to the PEPPOL DNS

• Management interface for DNS CNAME records– Create, update, delete

• SMP’s uses the SML interface for– Registering a new company/business

Metadata life cycle

Developer tool: listdns

• http://ec2-174-129-36-64.compute-1.amazonaws.com:8080/ServiceMetadataLocatorManagement/listdns

Typical SMP/DNS errors

• Host not found – Check ID with nslookup or listdns tool– Is the ID scheme right?, the MD5?• http://B-e49b223851f6e97cbfce4f72c3402aac.busdox-

actorid-upis.sml1.smloc.org/....

• The SMP responds with a HTTP 404 error– Check the document type and scheme

• No access point URL– Check the process type and scheme

Building Access Points

Infrastructure

Sending documents

SMP Registry

AP clientSTART AP 1 START AP 2

Obtain metadata

START message flow

START Access Points

• START AP’s can send and recieve documents• Enables reliable and secure transport of

documents between START AP’s• START transport layer does not inspect the doc

in soap payload (only SOAP headers are used and verified)

• START AP is resembles a router• START AP’s may offer the LIME interface

towards senders

WS-Addressing

• Transport neutral addressing of web services• No final spec release yet. • Both LIME and START uses WS-Adr• SOAP Headers:<wsa:MessageID> xs:anyURI </wsa:MessageID> <wsa:RelatesTo>xs:anyURI</wsa:RelatesTo> <wsa:To>xs:anyURI</wsa:To>

<wsa:Action>xs:anyURI</wsa:Action> <wsa:From>endpoint-reference</wsa:From> <wsa:ReplyTo>endpoint-reference</wsa:ReplyTo><wsa:FaultTo>endpoint-reference</wsa:FaultTo>

WS-Transfer

• Protocol for accessing and uploading resources• Core Protocol– CREATE (allocate Id and endpoint for a ressource)– PUT (upload the ressource)– GET (a ressource)– DELETE

• PEPPOL LIME: CREATE, PUT, GET, DELETE• PEPPOL START: CREATE, PUT

WS-Reliable Messaging

• Helps ensuring messages are delivered• Core Protocol– CreateSequence + response– Messages in the sequence– Acknowledgement– Resend of unacknowledged message– TerminateSequence + reponse

• Only START uses RM

WS-Security and SAML

• A few security specs are involved– WS-Security– WS-SecurityPolicy– SAML 2.0

• START uses SSL, SAML, Signatures, X509• LIME uses SSL, Basic Authentication

Specifications

• CommonDefinitions.doc • PEPPOL_Identifiers.doc • STARTProfile.doc • LIMEProfile.doc • ServiceMetadataLocator.doc • ServiceMetadataPublishing.doc

• https://svn.forge.osor.eu/svn/peppol/Documents/Specifications/

WSDL and schemas

• Identifiers-1.0.xsd – Core identifiers like ParticipanIdentifier and DocumentType

• LIME-Types-1.0.xsd – PageList

• START-Types-1.0.xsd – Ping type

• ServiceMetadataLocatorTypes-1.0.xsd – CreateParticipantIdentifier, PublisherEndpoint and more

• ServiceMetadataPublishingTypes-1.0.xsd – Endpoint, ServiceInformation, Process and more

• ws-tra.wsdl– Draft version of WS-transfer with PEPPOL security policy

• https://svn.forge.osor.eu/svn/peppol/Documents/Specifications/XML/Schema/1.0/

• https://svn.forge.osor.eu/svn/peppol/Documents/Specifications/XML/WSDL/

Identifiers-1.0.xsd <?xml version="1.0" encoding="utf-8" ?> - <xs:schema id="Identifiers" targetNamespace="http://busdox.org/transport/identifiers/1.0/"

elementFormDefault="qualified" xmlns="http://busdox.org/transport/identifiers/1.0/" xmlns:xs="http://www.w3.org/2001/XMLSchema">

- <xs:annotation> <xs:documentation>Common identifiers for WSDLs and Schemas</xs:documentation> </xs:annotation> <xs:element name="ParticipantIdentifier" type="ParticipantIdentifierType" /> <xs:element name="DocumentIdentifier" type="DocumentIdentifierType" /> <xs:element name="ProcessIdentifier" type="ProcessIdentifierType" /> <xs:element name="RecipientIdentifier" type="ParticipantIdentifierType" /> <xs:element name="SenderIdentifier" type="ParticipantIdentifierType" /> <xs:element name="MessageIdentifier" type="MessageIdentifierType" /> <xs:element name="ChannelIdentifier" type="ChannelIdentifierType" /> - <xs:complexType name="ParticipantIdentifierType">- <xs:simpleContent>- <xs:extension base="xs:string"> <xs:attribute name="scheme" type="xs:string" /> </xs:extension> </xs:simpleContent> </xs:complexType>…

ws-tra.wsdl

• Simple wsdl with 4 methods (CREATE,PUT,GET, DELETE)

• Snippet:…… <wsdl:portType name="Resource"> <wsdl:operation name="Get"> <wsdl:input message="tns:GetMessage" wsam:Action="http://www.w3.org/2009/02/ws-

tra/Get"/> <wsdl:output message="tns:GetResponseMessage"

wsam:Action="http://www.w3.org/2009/02/ws-tra/GetResponse" /> </wsdl:operation></wsp:Policy>…..

ws-tra.wsdl with policy in START<wsp:Policy>…. <sp:SignedSupportingTokens>…. <wsp:Policy> <sp:SamlToken sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-

securitypolicy/200702/IncludeToken/AlwaysToRecipient"> <wsp:Policy> <sp:WssSamlV20Token11/> </wsp:Policy> </sp:SamlToken> </wsp:Policy> </sp:SignedSupportingTokens> <wsrm:RMAssertion> <wsp:Policy> <wsrm:DeliveryAssurance> <wsp:Policy> <wsrm:InOrder/> </wsp:Policy> </wsrm:DeliveryAssurance> </wsp:Policy> </wsrm:RMAssertion>…</wsp:Policy>

START SAML Token<saml:Assertion ID="a123“ IssueInstant="2001-12-31T12:00:00“ Version="2.0" <saml:Issuer Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"> http://SomeAcessPoint.busdox.org</saml:Issuer> <ds:Signature>….</ds:Signature> <saml:Subject> <!-- Here comes a NameID indicating the participant identifier of the sender --> <saml:NameID Format="http://busdox.org/profiles/serviceMetadata/1.0/UniversalBusinessIdentifier/1.0/"> 0010:5798000000001 </saml:NameID> <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:sender-vouches"/> </saml:Subject> <saml:AuthnStatement AuthnInstant="2009-01-31T12:00:00Z"> <saml:AuthnContext> <saml:AuthnContextClassRef> urn:oasis:names:tc:SAML:2.0:ac:classes:X509 </saml:AuthnContextClassRef> </saml:AuthnContext> </saml:AuthnStatement> <saml:AttributeStatement> <!-- Assurance Level Attribute --> <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="urn:eu:busdox:attribute:assurance-level"> <saml:AttributeValue xsi:type="xs:string">3</saml:AttributeValue> </saml:Attribute> </saml:AttributeStatement></saml:Assertion>

LIME Access Points

• Does the same as START AP’s– Looks up the destination AP (by receiver ID)– Sends the message to destination AP– Sends a receipt to the sender

• Added functionality– Stores incomming messages– Allows message polling – like an POP3 email box

• SSL and Basic Authentication– No SAML, no RM– Easy to implement clients

LIME schemas and WSDL’s

• Bussiness ID, document and process type– Identifiers-1.0.xsd

• Paging in LIME– LIME-Types-1.0.xsd

• WS-Transfer (CREATE,PUT,GET,DELETE)– ws-tra.wsdl

• WS-Transfer types– ws-tra.xsd

LIME message flow

LIME code sample (GET-LIST)

private void getMessageList(EndpointReferenceInterface endpointReference)

throws Exception { Factory factory = new Factory(); Inbox inbox = factory.createInbox(); List<MessageReferenceInterface> messageReferences =

inbox.getMessageList(createCredentials(), endpointReference); if (messageReferences != null && messageReferences.size() > 0) { for (MessageReferenceInterface messageReference : messageReferences) { System.out.println("INBOX - MESSAGE: " +

messageReference.getMessageID()); } } else { System.out.println("INBOX - NO MESSAGES"); } }

LIME code sample (GET)private void getMessage(String messageID, EndpointReferenceInterface

endpointReference) throws Exception { Factory factory = new Factory(); MessageReferenceInterface messageReference =

factory.createMessageReference(); messageReference.setMessageId(messageID); messageReference.setEndpointReference(endpointReference); MessageInterface fetchedMessage =

factory.createInbox().getMessage(createCredentials(), messageReference); if (fetchedMessage != null) { System.out.println("INBOX - MESSAGE: " + messageID); System.out.println(fetchedMessage); streamMessage(fetchedMessage, System.out); } else { System.out.println("INBOX - MESSAGE NOT FOUND: " + messageID); } }

LIME code sample (CREATE/PUT) private MessageInterface createSampleMessage(Factory factory, String xmlFilename, String

senderID, String receiverID) throws Exception {

String businessIdScheme = "busdox-actorid-upis"; String documentIdScheme = "busdox-docid-

qns::urn:oasis:names:specification:ubl:schema:xsd:AcceptCatalogue-2"; String documentIdValue = "AcceptCatalogue##UBL-2.0"; String processIdScheme = "cenbii-procid-ubl"; String processIdValue = "BII01";

MessageInterface message = factory.createMessage(); if (xmlFilename != null) { message.setDocument(loadXMLFromFile(xmlFilename)); } message.setDocument(loadXMLFromFile(xmlFilename)); …. message.getSender().setBusinessIdentifier(senderID); message.getSender().setScheme(businessIdScheme);

….. return message; }

LIME code sample (CREATE/PUT)

private String testSendMessage(MessageInterface message, EndpointReferenceInterface endpointReference) throws Exception {

Outbox outbox = Factory().createOutbox();

String messageid = new outbox.sendMessage(createCredentials(), message, endpointReference);

System.out.println("OUTBOX - MESSAGE DELIVERED: " + messageid); return messageid; }