buildingSMART · civilx64 · Mar 30, 2026
diff --git a/docs/_static/digital_app_auth_invalid.png b/docs/_static/digital_app_auth_invalid.png
diff --git a/docs/_static/digital_app_auth_na.png b/docs/_static/digital_app_auth_na.png
diff --git a/docs/_static/digital_app_auth_process_overview.jpg b/docs/_static/digital_app_auth_process_overview.jpg
diff --git a/docs/_static/digital_app_auth_valid.png b/docs/_static/digital_app_auth_valid.png
diff --git a/docs/ref/digital-app-auth/implementation.md 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. <Actual Digital Signature Data>
+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 <validate@buildingsmart.org>
diff --git a/docs/ref/digital-app-auth/purpose.md 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
@@ -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
@@ -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: