diff --git a/docs/_static/digital_app_auth_invalid.png b/docs/_static/digital_app_auth_invalid.png new file mode 100644 index 00000000..a767a982 Binary files /dev/null and b/docs/_static/digital_app_auth_invalid.png differ diff --git a/docs/_static/digital_app_auth_na.png b/docs/_static/digital_app_auth_na.png new file mode 100644 index 00000000..d0ed85da Binary files /dev/null and b/docs/_static/digital_app_auth_na.png differ diff --git a/docs/_static/digital_app_auth_process_overview.jpg b/docs/_static/digital_app_auth_process_overview.jpg new file mode 100644 index 00000000..e65f5958 Binary files /dev/null and b/docs/_static/digital_app_auth_process_overview.jpg differ diff --git a/docs/_static/digital_app_auth_valid.png b/docs/_static/digital_app_auth_valid.png new file mode 100644 index 00000000..e45210a5 Binary files /dev/null and b/docs/_static/digital_app_auth_valid.png differ diff --git a/docs/ref/digital-app-auth/implementation.md b/docs/ref/digital-app-auth/implementation.md new file mode 100644 index 00000000..2e5b9485 --- /dev/null +++ b/docs/ref/digital-app-auth/implementation.md @@ -0,0 +1,122 @@ +## Implementation Guidelines for Developers + +### Overview of the Signature Process + +The digital authentication process for IFC files involves generating a hash of the file's content, encrypting this hash +with a vendor's private key, and appending the resulting signature along with the public certificate to the IFC file. +The Validation Service, or any consuming application, can then decrypt the signature using the vendor's public key, +re-hash the file content, and compare the two hashes to verify integrity and authenticity. + +![Figure – Signature Process Overview](./signature-process-overview.jpg) +```{image} ../../_static/digital_app_auth_process_overview.png +:alt: Digital Application Authentication process overview +:scale: 100 % +:align: center +``` +*Figure 1 – Signature Process Overview* + +The table below explains the terms used in the figure above. + +| Term | Meaning | Location | +|----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------| +| Certificate Authority (CA) Private Key | The private key of the Certificate Authority (CA). It is used to **sign other CA certificates** (e.g., vendor or leaf certs). Highly secure, never exposed. | Private and stays with the issuing vendor | +| CA Certificate | The **public certificate** of the CA. It includes the CA's public key and is used to **verify signatures** created with the CA key. This certificate is **trusted by default.** | Published on the buildingSMART GitHub repo | +| Leaf Private Key | The private key of the actual **end-entity** (e.g., a specific software tool or product). It signs the actual IFC file. | In the signature comment block of the IFC file | +| Leaf CSR (Certificate Signing Request) | A request generated using the leaf key, containing the public key and identity info. It's sent to a CA to obtain a signed certificate (Leaf certificate). | — | +| Leaf Certificate | A certificate issued to the leaf entity (the signer of the IFC file), signed by a CA (or intermediate CA). It includes the public key that the IFC Validation Service uses to verify the IFC file signature. | Bundled in the IFC signature block (CMS format) | + +### Signature Block Structure + +- **Placement in IFC File**: The digital signature block is appended to the end of the IFC file, specifically after the + `END-ISO-10303;` line. + +- **Syntax**: To remain compliant with the IFC standard (ISO 16739-1), which specify the ISO 10303-21:**2002** (Step + Physical File Format) as primary exchange format, the signature is wrapped within a comment block. The general + structure is as follows: + +``` +1. ENDSEC; +2. /* +3. SIGNATURE; +4. +5. ENDSEC; +6. */ +``` + +In the future, if IFC will change its reference to newer versions of the STEP standard ( +e.g. [ISO 10303-21:2016](https://www.iso.org/standard/63141.html), where anchors, references and signature sections are +supported), a proper signature section can be considered. For now, the comment mimics the exact format of the STEP +signature section. + +### File Content for Hashing + +- **Ignoring Line Endings**: When computing the hash for the digital signature, carriage return (`0x0D`) and new line ( + `0x0A`) characters are ignored — as well as all characters that are not valid according to the 10303-21 syntax. This + addresses potential issues arising from different operating systems (e.g., Windows vs. Linux) handling line endings + differently, which would otherwise invalidate signatures upon re-saving. + +- **Strict Interpretation of File Content**: The hash should be calculated on the file content up to the start of the + commented signature block. A strict interpretation suggests treating the file content as a binary BLOB (Binary Large + Object) for hashing. This means that any semantic or non-semantic changes (e.g., changes in instance order, white + space, or character encoding shifts) will likely invalidate the signature unless explicitly ignored. The current + consensus leans towards being strict: if a user opens an IFC file in a text editor and re-saves it, potentially + altering the content, the breaking of the signature is considered an acceptable indication of tampering. + +### Key and Certificate Management + +- **Generating Private Keys**: Software vendors are responsible for generating and securely storing their private keys. + The process can be straightforward; for example, generating a key using SSH-keygen or similar tools can take mere + minutes for a skilled engineer. + +- **Submitting Public Certificates to buildingSMART**: Once a private key is generated, the corresponding public + certificate (which includes metadata like the vendor's name) should be submitted to buildingSMART. This is done by + opening a pull request to the designated GitHub + folder ([buildingsmart-certificates/validation-service-vendor-certificates](https://github.com/buildingsmart-certificates/validation-service-vendor-certificates)). + +- **Chain of Trust (Optional Advanced Usage)**: While a simple direct trust model (vendor provides public key, + buildingSMART trusts it) is initially sufficient, the framework supports longer chains of trust. This means a root + certificate (e.g., from a vendor like Autodesk) could sign subsidiary certificates (e.g., for specific products like + Revit). The Validation Service can then verify these chains, and allows the root keys to remain private, especially as + the signing of subsidiary keys happens on vendor infrastructure. + +### Cryptographic Standards and Tools + +- **Hashing Algorithms**: The underlying hash function and encryption method for digital signatures can be implemented + using widely available open-source tools. The OpenSSL library is a common choice for proof-of-concept prototypes due + to its native C++ support. + +- **Signature Encoding**: Discussions have revolved around using PKCS #1 versus PKCS #7 for signature encoding. After + careful consideration, PKCS #7 (corresponding to CMS — Cryptographic Message Syntax) has been adopted — mainly because + it is more suitable for API exchange, it is the one suggested in the STEP 10303-21 standard, and it supports + additional metadata and can bundle other public certificates. + +- **Utilising Existing Libraries**: The [step-authorize](https://github.com/steptools/STEPAuthorize) GitHub repository + offers code that can be modified to generate comments before and after the signature. It also provides compiled + binaries and supports different modes for signature and certificate output (e.g., separate blobs or a combined CMS + BLOB). This can be a useful starting point for developers. + +### Important Considerations and Best Practices + +- **Cumulative Signatures**: Digital signatures, as implemented, are cumulative. This implies that removing an earlier + signature in a sequence will invalidate all subsequent signatures. + +- **Handling Leaked Private Keys**: In the event of a private key leak, the ability to "unauthorise" or revoke the key + is crucial. buildingSMART aims to establish procedures for this, akin to a Certificate Authority. + +- **Serialization Agnosticism**: As noted, minor changes to an IFC file (like white space or instance order) will break + a signature. The decision to ignore carriage returns and new lines helps, but strict adherence to file content for + hashing is generally preferred to maintain integrity. + +- **IFC SPF vs. IFC XML**: This digital signature feature is currently designed for IFC SPF (Standard Physical File) + format, not IFC XML, as XML is not within the current scope of the Validation Service. + +- **Adding Comments to Signatures**: Currently, the agreed signature structure doesn't allow for any data besides the + command open/close, signature begin/end markers and the payload. Implementers can always add data as a separate + comment that *precedes* the signature comment — if needed — or embed data in the CMS message structure. + +### Additional resources + +A 30 minutes video containing a detailed demo of the feature can be +found [here](https://app.box.com/s/x2nft1hfyzp7kzhj3xulrp2drhtubl5g). + +For support, email diff --git a/docs/ref/digital-app-auth/purpose.md b/docs/ref/digital-app-auth/purpose.md new file mode 100644 index 00000000..03e0c991 --- /dev/null +++ b/docs/ref/digital-app-auth/purpose.md @@ -0,0 +1,65 @@ +## Purpose and Use Cases + +### Problem Statement: Why Digital Authenticity in the Validation Service? + +IFC files (`.ifc`) are serialised as plain text, which, while beneficial for accessibility, makes them highly +susceptible to unintentional or intentional modification. It is easy for files to become invalid, or for the originating +organisation and application information to be altered. This poses a significant challenge for automated systems like +the buildingSMART IFC Validation Service, which relies on accurate and untampered file data for verification and +assessment. Even more so when buildingSMART uses the metrics derived from the assessment of these files to provide a +judgment on the tools that produced them. While simple hashing can detect if a file has been changed, it does not +confirm the origin of the file. + +### Ensuring File Integrity and Authenticity + +The primary, and sole, purpose of integrating digital authentication support into the IFC Validation Service is to +address concerns regarding file integrity and authenticity. + +- **Integrity**: ensures that the content of an IFC file has not been tampered with since its original signing. +- **Authenticity**: verifies that an IFC file truly originates from the software tool and vendor it claims to be from. + This prevents misjudgment of software tools during automated assessments. + +### Key Use Cases + +Digital authentication is a powerful and widely adopted technology. It can serve multiple use cases, and its complexity +can vary accordingly. To avoid making its adoption and implementation overly complicated, buildingSMART has agreed with +the implementers on a clear, restricted scope for which bSI is going to use such technology. + +- **buildingSMART Software Certification and Assessment**: This is the principal driver for the digital application + authentication initiative. By validating digitally authenticated IFC files, buildingSMART can reasonably assume — + under a framework of trusted keys and good-faith use — that the files used for the Scorecard assessments originate + from the claimed tool and have not been tampered with. This provides a robust foundation for judging software + performance. The Validation Service will be able to check if incoming files are signed according to agreed-upon + standards and provide results to users. + +- **Vendor's Internal File Verification**: Equally, software vendors can use digital authentication to verify that IFC + files received from their customers, which are claimed to be generated by their applications, are indeed authentic and + have not been tampered with post-export. This can help reduce the burden on support desks dealing with corrupted or + falsely attributed files. + +- **Supporting Multiple Signatures**: The system is designed to accommodate multiple digital signatures within a single + IFC file. This allows for a chain of custody, where a file might first be signed by the software vendor, then by an + architectural firm, and subsequently by the buildingSMART Validation Service to attest to its compliance or checks. + Such cumulative signatures provide a verifiable history of the file. + +### The Role of buildingSMART as an Authority + +buildingSMART is positioned as the central reference point and authority for this digital application authentication +framework. This means: + +- **Standardisation**: buildingSMART will establish guidelines for the hashing and cryptographic mechanisms to be used. + That is the second part of this document. + +- **Public Key Management**: buildingSMART will host a GitHub + repository ([buildingsmart-certificates/validation-service-vendor-certificates](https://github.com/buildingsmart-certificates/validation-service-vendor-certificates)) + where vendors can submit their public certificates. This repository will serve as the trusted source for public keys, + enabling anyone — including the Validation Service — to verify signatures. + +- **Private Key Responsibility**: Vendors will be responsible for generating and maintaining their private keys, + according to their key management policies on (e.g.) retention, renewal periods, and leaked key handling. + +### Feature Availability + +The Validation Service feature to check digitally authenticated IFC files is released, for the first time, in **version +0.7.6, on 28th May 2025**. The Validation Service team is responsible for maintaining, and when needed improving, the +feature. diff --git a/docs/ref/digital-app-auth/user-interface.md b/docs/ref/digital-app-auth/user-interface.md new file mode 100644 index 00000000..94033d7e --- /dev/null +++ b/docs/ref/digital-app-auth/user-interface.md @@ -0,0 +1,38 @@ +## User Interface + +The status of Digital Application Authentication checking will be displayed on the dashboard next to the icon +for the header check. + +Models that do not include Digital Application Authentication will not display an additional icon: + +```{image} ../_static/digital_app_auth_na.png +:alt: User interface for passing check of digital application authentication +:scale: 100 % +:align: center +``` + +Models from software tools that have correctly implemented Digital Application Authentication +and have not been modified downstream since export +will display an additional icon indicating a valid check: + +```{image} ../_static/digital_app_auth_valid.png +:alt: User interface for passing check of digital application authentication +:scale: 100 % +:align: center +``` + +Models from software tools that have incorrectly implemented Digital Application Authentication and/or +have been modified downstream since export +will display an additional icon indicating a failed check: + +```{image} ../_static/digital_app_auth_invalid.png +:alt: User interface for passing check of digital application authentication +:scale: 100 % +:align: center +:border: 4px +``` + +```{include} ./digital-app-auth/index.md +:heading-offset: 1 +:relative-images: +``` diff --git a/docs/ref/index.md b/docs/ref/index.md index d1991f5e..9c4e7b25 100644 --- a/docs/ref/index.md +++ b/docs/ref/index.md @@ -1,7 +1,31 @@ # Reference Information +Reference information is primarily aimed at software vendors and solutions providers that wish to implement the IFC standard. +Typically, this audience is interested in software certification as well. + +## Digital Application Authentication + +```{include} ./digital-app-auth/purpose.md +:heading-offset: 1 +:relative-images: +``` + +```{include} ./digital-app-auth/implementation.md +:heading-offset: 1 +:relative-images: +``` + +```{include} ./digital-app-auth/user-interface.md +:heading-offset: 1 +:relative-images: +``` + ## Additional Information for Normative Rules +Occasionally, the Validation Service team will receive inquiries regarding a specific rule that requires +a detailed explanation above and beyond existing documentation in the IFC specification and Validation Service documentation. +The responses to these inquiries are provided here for the benefit of the entire community. + ```{include} ./normative-rules/ALB021.md :heading-offset: 1 :relative-images: