Reference implementations
11th November 2010
Malmö
Thomas Ravnholt
PEPPOL 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/Transport
Library/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/t
ransportlibrary/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/t
ransportLibrary/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/Transport
Library/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/Ser
viceMetadataLocator
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/Ser
viceMetadataPublishing
Deployed .NET Access Points
• START .NET
– https://ec2-174-129-36-72.compute1.amazonaws.com:8444/PeppolAccessPoint1/STARTAccessPoint.svc
– https://ec2-174-129-36-72.compute1.amazonaws.com:8444/PeppolAccessPoint/STARTAccessPoint.svc
• LIME .NET
– https://ec2-174-129-36-72.compute1.amazonaws.com:8081/limeService1.0Even/ResourceService.svc
– https://ec2-174-129-36-72.compute1.amazonaws.com:8081/limeService1.0UnEven/ResourceService.svc
Deployed Java Access Points
• START JAVA
– http://ec2-174-129-190-34.compute-1.amazonaws.com:8080/busdoxtransport-start-server-1.0.1/accesspointService
– http://ec2-174-129-190-34.compute-1.amazonaws.com:8080/busdoxtransport-start-server2-1.0.1/accesspointService
• LIME JAVA
– http://ec2-174-129-190-34.compute-1.amazonaws.com:8080/busdoxtransport-lime-server-1.0.1/wstransferService
– http://ec2-174-129-190-34.compute-1.amazonaws.com:8080/busdoxtransport-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.compute1.amazonaws.com/ServiceMetadataLocatorManagement/
managebusinessidentifier
– http://ec2-174-129-190-34.compute1.amazonaws.com/ServiceMetadataLocatorManagement/
manageservicemetadata
• SMP REST interface
– http://ec2-174-129-190-34.compute1.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
Obtain
metadata
Company X
Company Y
START AP
Country A
START AP
Country B
Steps for sending documents
1) Obtain metadata for the recipient ID
2) Get endpoint from metadata for specific
document and process type
3) Create SOAP message metadata headers
and SAML token
4) 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-docidqns">urn:oasis:names:specification:ubl:schema:xsd:AcceptCatalogue-2::AcceptCatalogue##UBL2.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.compute1.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.compute1.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.busdoxactorid-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-docidqns::urn:oasis:names:specification:ubl:schema:xsd:AcceptCatalogue-2";
• documentIdValue = "AcceptCatalogue##UBL-2.0";
• processIdScheme = "cenbii-procid-ubl";
• processIdValue = "BII01";
• http://B-5d56ef90fea494be06e7f51031c92b56.busdox-actoridupis.sml1.smloc.org/busdox-actoridupis%3A%3A0010%3A5798000000014/services/busdox-docidqns%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-docidqns">urn:oasis:names:specification:ubl:schema:xsd:AcceptCatalogue-2::AcceptCatalogue##UBL2.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.compute1.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.compute1.amazonaws.com:8080/ServiceMetadataLocatorManagemen
t/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.busdoxactorid-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
Obtain
metadata
AP client
START AP 1
START AP 2
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/Sp
ecifications/
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/Sch
ema/1.0/
• https://svn.forge.osor.eu/svn/peppol/Documents/Specifications/XML/WS
DL/
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/wstra/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/wssecuritypolicy/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-docidqns::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;
}