PDXpert/PDXplorer IPC-2570 extensions

PDXpert and PDXplorer offer optional security improvements to the original IPC-2570 specifications.

Last update 2021-12-13

This describes a PDX package that's signed and optionally encrypted. These features were introduced in PDXpert 15.0 and PDXplorer 6.0 releases.

Text styles: IPC element name, IPC attribute name, IPC attribute value, processing and non-IPC code.

Package cryptographic signing§

Feature summary§

PDXpert applies a cryptographic signature to the PDX package content. This signature proves that

• The pdx.xml content has not been changed (data integrity). Because each file attachment name and its digest is included in the pdx.xml file, hashing just the pdx.xml allows detecting a change to an attachment digest.
• The package has been sent by the licensed organization (sender authentication).
• The package has been generated by a licensed PDXpert application (tool authentication).

Package signing is not specified by the IPC-2570 standards. The signed pdx.xml file is fully compliant with IPC-2570, with the cryptographic information contained in a separate signature file.

PDXplorer is designed to verify and authenticate the PDX package. Other PDX package readers will see the expected pdx.xml file and its file attachments, but may not be capable of verifying or authenticating the package contents.

Technical description§

Creating the license§

The software publisher (SP) of PDXpert obtains a cryptographic certificate from a trusted public certificate authority (CA). The CA issues the certificate with (a) a private key (SP-P) to sign the license file; and (b) a public certificate (SP-C) for validating the license signature. SP issues a software license file to the application's Licensed Entity (LE). The SP-C and other cryptograhic elements are used to validate and encrypt PDX packages.

1. SP creates a certificate with the LE's identification (for example, Subject contains organization name, state, country).

   • The generator certificate private key (GC-P) is an encrypted XML string.

   • The generator certificate (GC-C), an XML string equivalent to a .pem file, contains the public key and LE identification.

   • The generator certificate signature (GC-S) is the Base64-encoded SHA-256 digest of the GC-C, encrypted by the SP-P.

2. License is issued as .pdxl file.

   1. A unique hash function uses the license properties to create the alphanumeric license key.

   2. The properties, with the license key, are added to a new XML file.

   3. Crypto objects are added to the XML license file.

      • GC-P encrypted private key, used by PDXpert to sign a PDX package.

      • GC-C certificate (public key), used by a PDX package reader to confirm PDX package integrity and authenticate the sending organization.

      • GC-S encrypted digest of the GC-C, for confirming the certificate integrity using the SP-C.

   4. The entire XML license file is signed using the SP-P, and exported as the final license .pdxl file. The SP-C is enclosed within the Signature (as <KeyInfo><X509Data><X509Certificate>), and used by PDXpert (and later by a PDX package reader) to authenticate the SP.

3. LE imports the license .pdxl file into PDXpert, which confirms the license contents using the SP-C.

Creating a PDX package§

PDXpert can use the license's crypto objects to export a PDX package that's signed and optionally encrypted.

1. Design package construction: The pdx.xml file contains the product data and file attachment metadata.

   • The <?generated_by {publisher}/...> is the same SP as contained in from the SP-C Subject.

   • The <Contact isTopLevel="Yes" {attributes}> is the same LE as contained in the GC-C Subject.

2. Signature additions: The PDXXML-{docID}.sig file contains four elements.

   • The PDXXMLSignature verifies the pdx.xml file content. It's the digest of the pdx.xml file, encrypted using the package generator's private key (GC-P), and saved as a Base64 string.

   • The AppPublicKey contains the package generator's public key (GC-C) for verifying the PDXXMLSignature value, and authenticating the isTopLevel contact as the package generator licensee.

   • The AppKeySignature verifies the AppPublicKey. It's the digest of the generator's public key (GC-S), encrypted using the software publisher's private key (SP-P), and saved as a Base64 string.

   • The RootPublicKey contains the software publisher's public key (SP-C) for verifying the AppKeySignature value, and authenticating the <?generated_by as the software publisher.

3. Signed package compression: The compressed .pdx package contains the pdx.xml file, design file attachments, and the PDXXML-{docID}.sig file.

4. Package file system transfer: The PDXpert client saves the package.

Reading a PDX package§

PDXplorer or other validating PDX reader opens the PDX package.

1. If the package is encrypted, it's decrypted using the AES-256 symmetric key, and the internal PDX package is extracted.

2. The package is identified, verified and authenticated.

   • Identification: The PDX package's thisDocumentIdentifier is used to find the PDXXML-{docId}*.sig signature file.

   • Verification: The PDXXMLSignature is decrypted with GC-C, and matched to the pdx.xml file hash. The AppKeySignature is decrypted with SP-C, and matched to the AppPublicKey GC-S file hash.

   • Authentication: The package <Contact isTopLevel="Yes" {attributes}> is matched to the GC-C Subject. The RootPublicKey is signed by a third-party Certificate Authority, and the package <?generated_by {publisher}/...> processing instruction is matched to the SP-C Subject.

Signature file name format§

To avoid filename collisions with other files, the cryptographic file is named PDXXML-{docID}[-{crc32}].sig, where:

• {docID} thisDocumentIdentifier, with all non-alphanumeric characters removed, confirms that the file contains the package digest

• {crc32} optional CRC-32 prevents a collision with a similarly-named .sig attachment in the package (not needed by PDXpert)

PDXplorer (or another package validator) matches the alphanumeric {docID} to the thisDocumentIdentifier and can compare the file contents to {crc32}.

Examples:

• Without optional sequence:

  PDXXML-145ccb79c45949c8826c6a3092f1e50.sig

• With optional CRC-32 value, where the file name conflicts with another package attachment name:

  PDXXML-20494-82F63B78.sig

To minimize confusion with design file attachments, PDX package readers should not show or export the signature file.

Package encryption§

PDXplorer can be used to encrypt and decrypt PDXpert's cryptographically signed PDX packages using the strong AES-256 cipher. This note describes the internal structure that allows other PDX package readers to read and extract the encrypted PDX package.

How to use a password-protected PDX package§

There are two options:

• Open with PDXplorer 6.0 or later using the password provided to you. See the PDXplorer user guide. You can also save the encrypted file as a decrypted PDX package.

• Open with any PDXplorer release (or another PDX package reader) and a file decrypting tool.

  • Open the PDX package, and copy the thisDocumentIdentifier attribute value. In PDXplorer, this is shown as the Package number, and looks something like 67a4e12334934dae9d74a1a832739de9. This value is called the password salt.

    

  • Close the PDX package file.

  • Open the PDX package file using WinZip®, 7-Zip or similar encrypting compressed file reader.

  • Select and save (export) the encrypted.pdx file. When prompted, enter the password and the salt. Do not add a space or other extra character. For example, if the provided password is myPassw0rd and the password salt is 67a4e12334934dae9d74a1a832739de9, then use myPassw0rd67a4e12334934dae9d74a1a832739de9 to export the file.

  • After the encrypted.pdx file is saved, it can be opened with a PDX package reader, including any PDXplorer release.

Technical goals§

• Unencrypted outer PDX package:

  • Is fully compatible with the IPC-2570 Supply Chain Communication (PDX) standard.

  • Can be opened by an industry-standard archive file reader for extracting the inner PDX package.

  • Uses an outer unencrypted pdx.xml file to describe the inner encrypted PDX package.

  • Contains a unique package identifier that's used as the passphrase salt.

• Inner encrypted PDX attachment:

  • Uses strong ISO/IEC 18033-3 AES-256 encryption.

  • Ensures each package digest is unique, even when user's passphrase is not unique.

  • Is decrypted and viewed using a decrypting PDX reader.

  • Is not extracted into an unencrypted copy of the package.

  • Can be extracted using WinZip® or compatible tool, and then viewed using an older PDX reader.

More information about PDXpert software's IPC-2570 implementation.

Definitions§

Inner PDX package

A PDX package that conforms to the IPC-2570 standards, and is not encrypted. The inner PDX package always contains one pdx.xml file (the inner XML file), and may contain file attachments.

It's recommended that the inner XML file is signed using an externally detached XML signature file. The signature XML file:

• Is named using the PDX package's thisDocumentIdentifier, for example PDXXML-cc74e9fc8f7e49e0b126868b1cc658e7.sig

• Is included in the compressed PDX package

• Is not shown as an attachment in the PDX package's pdx.xml entry

To allow validating the package's file attachments, the signed pdx.xml file should include each file's Attachment checkSum (MD5) or an AdditionalAttribute with other file signature, such as a SHA-1 digest. The digest doesn't have to be cryptographically strong, but must be sufficient to prevent hash collisions.

Inner XML file

The pdx.xml file that is contained within the inner PDX package.

Encrypted PDX package

An inner PDX package that is encrypted using a specified cipher; renamed as encrypted.pdx; and saved in an outer PDX package.

Outer XML file

An unencrypted pdx.xml file that conforms to the IPC-2570 standards, and is saved in a outer PDX package. It describes the encrypted PDX package and selected elements of the inner PDX package. The outer XML file must include a unique thisDocumentIdentifier value. Other elements may be included in the outer XML file, provided they do not conflict with the specifications of this document.

Outer PDX package

A PDX package that contains:

• one outer XML file; and

• one encrypted PDX package.

Other file attachments may be defined and saved in the outer PDX package, provided they do not conflict with the specifications of this document.

IPC-2571 Generic Requirements§

Content topic numbers – such as (3) – refer to the corresponding section in the IPC-2571 standard.

• Product Data eXchange Package DTD (3)
• ProductDataeXchangePackage (6)
• AdditionalAttributes (10) / AdditionalAttribute (10.1)
• Attachments (8) / Attachment (8.1)
• Contacts (9) / Contact (9.1)

Specifications§

The minimal outer PDX package pdx.xml with only required entities:

A more complete outer pdx.xml file:

Product Data eXchange Package DTD (2571:3)§

The outer PDX package conforms to the IPC-2571 standard version 1.0 DTD. All process instructions are required.

Process instruction	Description
<?xml version = "1.0" encoding="UTF-8"?>	Mandatory XML process instruction.
<?pdx_version = "1.0"?>	The outer PDX package conforms to the IPC-2571 standard version 1.0, and can be read by compatible software applications.
<?generated_by SoftwareVendor/SoftwareName/Version/BuildNumber?>	This identifies the encrypting software application and its version. This may or may not match the encrypted.pdx attachment's inner XML file's package generator, which may be shown in the ProductDataeXchangePackage element's dataSource attribute.

ProductDataeXchangePackage (2571:6)§

This is the root node for the outer XML file.

Parent elements

(none)

Element detail & attributes

Attribute name	Required	Data type	Value
thisDocumentIdentifier	required	String	Unique value assigned as the outer PDX package ID by the encrypting application. Example: 2e6f758aa1564161819cc7f86b9c4261 This value is used as the passphrase salt. It ensures a unique encryption digest for each package, even when the same passphrase is used for different PDX packages. The exact case-sensitive string value of the user-provided passord is followed without delimiter by the exact case-sensitive string value of the thisDocumentIdentifier value. Example: If the user's passphrase is pdxPass! and thisDocumentIdentifier is 2e6f758aa1564161819cc7f86b9c4261, then the combined value pdxPass!2e6f758aa1564161819cc7f86b9c4261 is used to encrypt and decrypt the inner PDX package. As noted, do not add, remove, or change the case of any character. The encrypting application should assign thisDocumentIdentifier a value between 8 and 32 characters, and help users create a strong passphrase. A passphrase salt increases the value of a strong passphrase, but can't add security to an empty or weak passphrase.
thisDocumentGenerationDateTime	required	DateTime	UTC date and time of outer PDX package's generation. Example: 2021-12-01T19:56:03Z
thisDocumentModificationDateTime	required	DateTime	UTC date and time of outer PDX package's last update, usually the same as thisDocumentGenerationDateTime.
originatedByContactName	optional	String	The contactName value, as specified in the Contact element. Optionally, this may be copied from the inner PDX package.
originatedByContactUniqueIdentifier	optional	IDREF	The contactUniqueIdentifier value, as specified in the Contact element.
packageType	optional	String	Copied from the inner PDX package.
dataSource	optional	String	The content of the inner PDX package <?generated_by [generator]?> processing instruction. Example: HX3 Solutions Inc/PDXpert/15.0/3000.5
thisDocumentCopyright	optional	String	Copied from the inner PDX package.
description	optional	String	Information about the outer PDX package. May suggest compatible tools that can decrypt the encrypted.pdx package. Example: Encrypted Product Data eXchange (PDX) file. View with PDXplorer 6.0 or later. Or, export 'encrypted.pdx' using WinZip(R)-compatible AES-256 software tool: Enter the assigned password, then add 'thisDocumentIdentifier' value. Do not add a space or extra character.

Child elements

AdditionalAttributes (2571:10)§

The AdditionalAttributes element with the group label Encryption contains one AdditionalAttribute element that descibes the cipher.

To ensure the package is recognized as encrypted, this AdditionalAttributes element must have a groupLabel with Encryption value. The specified attribute name and value are case-sensitive.

Parent element

Element detail & attributes

Attribute name	Required	Data type	Value
groupLabel	required	String	Encryption

Child element

AdditionalAttribute (1, 1)

AdditionalAttribute (2571:10.1)§

There must be exactly one AdditionalAttribute within the AdditionalAttributes parent Encryption group. It describes the encrypted PDX package cipher.

Parent element

AdditionalAttributes

Element detail & attributes

The PDX package's AdditionalAttribute element Cipher confirms that the PDX package is encrypted. Where this element doesn't exist, a file named encrypted.pdx is treated as an normal attachment.

To ensure the package is recognized as encrypted, this AdditionalAttribute element must:

• be the only element in the AdditionalAttributes parent Encryption group; and

• have the specified case-sensitive attribute names and values.

PDXplorer looks only for this AdditionalAttribute element (and its parents) and an encrypted.pdx physical file. If one of these doesn't exist, then the package content is treated as unencrypted. PDXplorer doesn't require the Attachment and Contact elements.

Attribute name	Required	Data type	Value
name	required	String	Cipher
value	required	String	AES  Note 1
dimension	required	String	One of [ 128 | 192 | 256 ]  Notes 2, 3
dataType	required	Enumeration	Binary
dataTypeOther	optional	String	Omitted attribute or empty value.
description	optional	String	Omitted attribute or any value.

Notes

1. Future versions may support other ISO/IEC 18033 block ciphers.
2. Enumeration of options for specified cipher value. The specified dimension must be compatible with the specified value.
3. PDXplorer uses only AES-256 to generate an encrypted package.

Child elements

(none)

Attachments (2571:8)

This element is a collection of one or more files attached to another object in the outer PDX package. The outer XML file contains at least one Attachment element, which is required to describe the encrypted.pdx attachment.

Other attachments may be included in the outer PDX package, but no other universalResourceIdentifier can have the exact value of file://encrypted.pdx

Parent element

Element detail & attributes

(none)

Child elements

Attachment (1, unbounded)

Attachment (2571:8.1)

This element describes the encrypted.pdx file.

Parent element

Element detail & attributes

Attribute name	Required	Data type	Value
isFileIn	required	Enumeration	Yes
universalResourceIdentifier	required	UriReference	file://encrypted.pdx
fileIdentifier	optional	String	encrypted.pdx
referenceName	optional	String	encrypted.pdx
globalMimeTypeQualifierCode	optional	String	application/octet-stream
fileSize	optional	String	Integer byte count of encrypted.pdx before encryption. The value is not formatted and does not have units. Example: 248216
attachmentModificationDate	optional	DateTime	Copied from the inner PDX package ProductDataeXchangePackage thisDocumentGenerationDateTime value. Example: 2021-02-21T14:17:11Z
versionIdentifer	optional	String	Omitted attribute or any value. DTD spelling error retained.
checkSum	optional	String	MD5 digest of encrypted.pdx before encryption. Unless otherwise required by a target system, encode as 32 lowercase hexadecimal digits. Example: 3ac570a8cd347f75d1643db46c1a9ea8
description	optional	String	Encrypted Product Data eXchange (PDX) file. View with PDXplorer 6.0 or later. Or, export 'encrypted.pdx' using WinZip(R)-compatible AES-256 software tool: Enter the assigned password, then add 'thisDocumentIdentifier' value. Do not add a space or extra character.

Child element

(none)

Contacts (2571:9)

This element contains all person & organization contacts within the PDX package. The Contact element is optional; if not specified, then Contacts is also excluded.

Parent element

ProductDataeXchangePackage

Element detail & attributes

(none)

Child element

Contact (1, unbounded)

Contact (2571:9.1)

This element describes one contact within a collection of Contacts. It identifies the originator of the encrypted or unencrypted package. This element is optional, and can be used to identify the package owner, author, or rights holder.

It can be added as

1. the outer package's originator-provided contact information, setting isTopLevel=Yes; if none, then

2. the orignal package's first-listed isTopLevel=Yes contact; if none, then

3. the orignal package's first-listed contact.

Parent element

Contacts

Element detail & attributes (Person)

Attribute name	Required	Data type	PDXpert attribute
contactName	required	String	Copied from inner PDX package, or originator-provided Person name.
contactUniqueIdentifier	required	ID	Copied from inner PDX package, or generated value. Example: ID901c8de3-3ea3-4878-82ab-90355d64dce3
contactIdentifier	required	String	Copied from inner PDX package, or copied from contactUniqueIdentifier
contactStatus	optional	Enumeration	Active
emailAddress	optional	String	Copied from inner PDX package, or originator-provided value.
telephoneNumber	optional	String	Copied from inner PDX package, or originator-provided value.
facsimileNumber	optional	String	Copied from inner PDX package, or originator-provided value.
businessName	optional	String	Copied from inner PDX package, or originator-provided Organization name.
universalResourceIdentifier	optional	UriReference	Copied from inner PDX package, or originator-provided value.
department	optional	String	Copied from inner PDX package, or originator-provided value.
globalBusinessIdentifier	optional	String	Copied from inner PDX package, or originator-provided value.
globalLocationIdentifier	optional	String	Copied from inner PDX package, or originator-provided value.
postOfficeBoxIdentifier	optional	String	Copied from inner PDX package, or originator-provided value.
addressLine1	optional	String	Copied from inner PDX package, or originator-provided value.
addressLine2	optional	String	Copied from inner PDX package, or originator-provided value.
addressLine3	optional	String	Copied from inner PDX package, or originator-provided value.
cityName	optional	String	Copied from inner PDX package, or originator-provided value.
regionName	optional	String	Copied from inner PDX package, or originator-provided value.
nationalPostalCode	optional	String	Copied from inner PDX package, or originator-provided value.
globalCountryCode	optional	String	Copied from inner PDX package, or originator-provided value.
isTopLevel	optional	Enumeration	Copied from inner PDX package, or Yes when contact is specified by outer originator
globalPartnerClassificationCode	optional	Enumeration	Copied from inner PDX package, or originator-provided value.
globalPartnerClassificationCodeOther	optional	String	Copied from inner PDX package, or originator-provided value.
globalPartnerSubClassificationCode	optional	String	Copied from inner PDX package, or originator-provided value.

Child elements

(none)

WinZip® is a registered trademark of Corel Corporation.

This application note was relevant to the PDXpert software release that was current at time of publication. Product changes since that time may affect its utility. We'd be happy to assist you in assessing the applicability of this note to your situation.