eDelivery Services
eDelivery BDXL 1.6
Status | eDelivery Specification |
Publication date |
|
Obsoletes | |
Obsoleted by | eDelivery BDXL 1.7 |
1. Description
eDelivery uses this eDelivery profile of the OASIS Business Document Metadata Service Location Version 1.0 specification [BDX-Location-v1.0], usually referred to as the "BDX Location" or BDXL specification, as its technical specification for Service Location. BDX Location specifies a method to query DNS resource records to retrieve a URL for metadata services. The result of a query is a full URI, which can use HTTPS and supports server (and optionally client) authentication.
The eDelivery BDX Location profile is intended to be used in conjunction with the eDelivery SMP profile [eDelivery-SMP]. The retrieved URL is a URL for an SMP XML document that can be obtained using the SMP HTTP binding. This process is visualized in the following diagram:
Together, eDelivery BDXL and eDelivery SMP MAY be used as a discovery infrastructure for the eDelivery AS4 Dynamic Sender Profile Enhancement, defined in section 4.4 of the eDelivery AS4 specification [eDelivery-AS4].
2. Base Specification
This specification is based on the following OASIS specification:
- [BDX-Location-v1.0] Business Document Metadata Service Location Version 1.0. OASIS Standard, 01 August 2017. http://docs.oasis-open.org/bdxr/BDX-Location/v1.0/
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [RFC2119].
3. Implementation Guidelines
3.1. General Guidelines
Client and server components implementing this specification MUST conform to the OASIS Business Document Metadata Service Location Version 1.0 specification.
Server deployments of eDelivery BDX Location MUST use the "Service Provider Domains" option, defined in section 2.3.2 of [BDX-Location-v1.0]. The value of the provider domain name MAY differ for different sectors or communities and MUST also encode the communication environment, to separate "production" from other (e.g. "test" or "acceptance") environments.
3.2. Constructing the DNS query
To retrieve U-NAPTR resource records, the DNS query string MUST be created as follows:
- The party identifier is encoded in a canonical form. Sections 4.1 and 4.2 provide examples of two such forms. A canonical form MAY be a complete standalone identifier or an identifier that can only be interpreted in combination with a separate catalog or scheme value.
- The canonical party identifier is processed using the SHA256 algorithm.
- The digest obtained in (2) is BASE32 encoded.
- Any trailing '=' padding characters added in (3) in the encoded digest are removed.
- If the BDXL service provider provides resource records for separate environments, a label identifying the applicable environment MUST be used in combination with value obtained in (4) for all environments other than production. For example, the service provider may provide resource records for the environments “acceptance” and “production”. In this case, a label MUST be added to records that are to be looked up in the “acceptance” environment.
- The values obtained in (4) and (5) are used as parameters in a service provider-specific formatting function that produces the final query domain string. Details of the formatting function are left to the service provider. If the canonical form needs to be combined with a separate catalog or scheme parameter, that parameter is another input to this formatting function. Furthermore, the service provider MAY also include other parameters (such as parameters to group the records for business domains, or for use with particular services) in the format.
Note that the query string does not include a B- prefix, unlike the convention specified in [SML]. Also note that labels in Domain Name System (DNS) names are case insensitive [RFC4343].
The service provider could adopt a simple concatenation of the values. For the “bdxl.example.com” domain and the “acceptance” environment, this would result in a query domain that has the suffix .acceptance.bdxl.example.com whereas for the production environment, the resulting domain suffix would have the value .bdxl.example.com. However, the service provider MAY also use different formatting conventions.
3.3. U-NAPTR Resource Records
BDX Location servers MUST set the service field of U-NAPTR records that link to metadata services based on the OASIS SMP to the value "meta:smp". BDX Location clients that retrieve SMP-based metadata MUST restrict record searches to U-NAPTR records of this type. Note that the service field is case-insensitive, according to [RFC4848].
If the metadata service supports access using secure HTTP, URI values stored in BDXL U-NAPTR records MUST use the secure HTTP URL scheme ("https"). URI values MAY include path, query or fragment parts, in addition to the "authority" part. Note that scheme and host name are case insensitive. All other URI components MUST be treated as case sensitive.
3.4. Use with eDelivery SMP
When used in combination with [eDelivery-SMP] to locate SMP servers that expect to be accessed using the OASIS SMP HTTP binding, the URI returned by the BDXL server MUST NOT include the URI suffixes defined by the SMP HTTP binding. These suffixes MUST instead be appended by the SMP client to the URI returned by the BDXL server before the SMP server is queried.
Note that SMP uses the term Participant as a synonym of Party.
4. Examples
This section provides non-normative examples showing the use of eDelivery BDXL with ebCore and PEPPOL party identifiers and a sample BDXL U-NAPTR record.
4.1. Use with ebCore Party Identifiers
The eDelivery ebCore Party Identifier profile [eDelivery-EBCORE] uses and profiles the canonical party identifier defined in section 2.7 of [PARTYIDTYPE], which follows the pattern: urn:oasis:tc:ebcore:partyid-type:<<catalog-identifier>>:<<scheme-incatalog>>:<<scheme specific identifier>>. This identifier format therefore incorporates the catalog identifier and scheme identifier, in addition to the party-specific identifier.
For example, the GS1 Global Location Number (GLN) scheme [GLN] is registered in the ISO 6523 catalog under the "0088" code.
- The canonical eDelivery ebCore Party Identifier for a company with GLN 4035811991021 therefore has the value urn:oasis:names:tc:ebcore:partyid-type:iso6523:0088:4035811991021.
- Application of SHA256 and BASE32 encoding, followed by removal of padding characters yields the following value: I3QYB36CTAYRFGTHBYCQZDTOJFHGAZJEGLFOOE7727EGVDWRK5QQ.
For the production and acceptance environments of the bdxl.example.com service provider introduced as example in section 3.2, this will result in the following names
- I3QYB36CTAYRFGTHBYCQZDTOJFHGAZJEGLFOOE7727EGVDWRK5QQ.bdxl.example.com
- I3QYB36CTAYRFGTHBYCQZDTOJFHGAZJEGLFOOE7727EGVDWRK5QQ.acceptance.bdxl.example.com
Note that these values are hypothetical examples only. For a specification of the domain name values to use with a specific BDXL service provider, consult the documentation of that service provider.
4.2. Use with PEPPOL Identifiers
The PEPPOL network also uses the ISO 6523 scheme catalog and identifies parties using schemes in this catalog and a scheme specific identifier. The value iso6523-actorid-upis is used to indicate the use of the ISO 6523 scheme catalog. This is combined with a party identifier value that is a combination of the ISO 6523 scheme code and the scheme specific identifier, concatenated using a single colon. The sample GLN number in section 4.1 therefore corresponds to the party identifier value 0088:4035811991021.
Application of SHA256 and BASE32 encoding, followed by removal of padding characters yields the following value: LZMEDSMZXYD37YC74TZVPYCMUANFCMN667JHGBFQDDRVMSE6NYTA. Again using the bdxl.example.com service provider introduced as example in section 3.2, this value can be combined with a suffix that includes the catalog identifier, an indicator of the environment and service provider specific labels:
- LZMEDSMZXYD37YC74TZVPYCMUANFCMN667JHGBFQDDRVMSE6NYTA.iso6523-actorid-upis.bdxl.example.com
- LZMEDSMZXYD37YC74TZVPYCMUANFCMN667JHGBFQDDRVMSE6NYTA.iso6523-actorid-upis.acceptance.bdxl.example.com
Note that these values are hypothetical examples only. For a specification of the domain name values to use with a specific BDXL service provider, consult the documentation of that service provider.
4.3. Sample U-NAPTR Record
The following non-normative example provides a BDXL U-NAPTR record served by BDXL service provider bdxl.example.com for a party with ebCore Party Identifier urn:oasis:names:tc:ebcore:partyid-type:iso6523:0088:4035811991021 for use in production.
I3QYB36CTAYRFGTHBYCQZDTOJFHGAZJEGLFOOE7727EGVDWRK5QQ.bdxl.example.com. ;; order pref flags service regexp replacement IN NAPTR 100 10 "U" "meta:smp" "!.*!https://www.anotherexample.com/smp/prod!" ""
The returned URL does not contain the Party Identifier, as it is a URL for an SMP resource for which the client is expected to use the SMP REST binding. That binding defines how the party and document identifier are to be encoded and appended to the URL.
5. Conformance
An implementation conforms to this version of the eDelivery BDXL Profile if it:
- Is a conformant OASIS BDXL 1.0 implementation, where conformance is defined in section 4 of [BDX-Location-v1.0].
- Conforms to all normative statements in section 3 of this specification.
6. Ownership
The BDX Location technical specification is Copyright © OASIS Open 2017. All Rights Reserved.
The BDX Location technical specification is created by the OASIS BDXR Technical Committee which operates under the Non-Assertion Mode of the OASIS IPR Policy. OASIS is not aware of any statements or declarations regarding IPR related to the work of this technical committee.
OASIS BDX Location is similar to the PEPPOL SML [SML], but is based on a type of DNS resource records called URI-enabled Naming Authority Pointer records [RFC4848]. U-NAPTR supports discovery of full URLs, which are not limited to an "authority" part but may also include path, query or fragment parts.
This specification was originally created in the former EU e-SENS project. The e-SENS project completed in March 2017. The EU e-SENS project formally transferred ownership of its specifications to the European Commission, which accepted it for further maintenance in the context of the CEF Programme and then of the Digital Europe Programme. Information on governance and procedures for eDelivery is available from Governance and Procedures.
7. References
[BDX-Location-v1.0] Business Document Metadata Service Location Version 1.0. OASIS Standard, 01 August 2017. http://docs.oasis-open.org/bdxr/BDX-Location/v1.0/
[eDelivery-AS4] https://ec.europa.eu/digital-building-blocks/sites/display/DIGITAL/eDelivery+AS4
[eDelivery-SMP] https://ec.europa.eu/digital-building-blocks/sites/display/DIGITAL/eDelivery+SMP
[eDelivery-EBCORE] https://ec.europa.eu/digital-building-blocks/sites/display/DIGITAL/eDelivery+ebCore+Party+Id
[GLN] Global Location Number https://www.gs1.org/gln
[PARTYIDTYPE] OASIS ebCore Party ID Type Technical Specification. September 2010. http://docs.oasis-open.org/ebcore/PartyIdType/v1.0/PartyIdType-1.0.pdf.
[RFC2119] A. Ramos. Key words for use in RFCs to Indicate Requirement Levels. IETF RFC 2119. January 1998. http://www.ietf.org/rfc/rfc2119.txt
[RFC4343] Domain Name System (DNS) Case Insensitivity Clarification. IETF RFC 4343. https://tools.ietf.org/html/rfc4343.
[RFC4848] Domain-Based Application Service Location Using URIs and the Dynamic Delegation Discovery Service (DDDS). IETF RFC 4848. https://tools.ietf.org/html/rfc4848.
[SML] Service Metadata Locator. https://peppol.eu/downloads/the-peppol-edelivery-network-specifications/
[SMP-v1.0] Service Metadata Publishing (SMP) Version 1.0. OASIS Standard, 01 August 2017. http://docs.oasis-open.org/bdxr/bdx-smp/v1.0/.
8. Contributors
The eDelivery team is in charge of maintaining the current version of the eDelivery BDX Location specification. Information on governance and procedures for eDelivery is available from Governance and Procedures.
Details about contributors of previous versions can be consulted on the e-SENS website.
9. History
Ver. |
Date |
Changes made |
Modified By |
---|---|---|---|
1.5 |
|
Minor update as part of the migration of the specification to CEF Digital, not requiring external review. Layout changed to match CEF Digital template Content copied from e-SENS architecture, with the following editorial changes and bibliographic updates:
|
Gianmarco Piva, Pim van der Eijk |
1.6 |
|
Changes:
Updated after CEF team meeting 15.12.2017:
Updated after CEF team meeting 25.12.2017
Updated on 30.05.2018
|
Pim van der Eijk |
Details about previous versions of the specifications can be consulted on the e-SENS website.