How apple-oss-distributions/security_certificates works
Main Components
• Certificate Input Directories – The certificates folder (with subdirectories “roots”, “removed”, “revoked”) is a core input. It contains the certificate files (in DER format) that are processed.
• EV Configuration – The “certificates/evroot.config” file contains EV OID mappings which determine which roots can validate EV chains.
• Configuration Files – The “config” directory (with several plist files, xcconfig, and Makefile) holds build configuration, versioning info (trust store version), and asset descriptor files.
• Build Scripts & Xcode Projects:
• The “CertificateTool” Xcode project and the “security_certificates” Xcode project orchestrate the asset building and signing process.
• The “xcscripts” directory contains shell scripts (e.g., buildTrustStoreAsset.sh, build_and_stage_assets.sh) which automate parts of the build.
• The “BuildOSXAsset” and “BuildiOSAsset” directories hold platform-specific build scripts (Ruby, Python, etc.) for creating macOS and iOS assets.
• Additional Asset Directories – “TrustSupplementalsAsset”, “Pinning”, and “certificate_transparency” give context on ancillary data, possibly representing additional trust-related configurations and transparency logs.
• Valid Database Snapshot – “valid_db_snapshot” shows sample or test data that the built trust store might validate against.
Relationships and Interactions
• Input Flow: Certificate files (and EV mappings) from the certificates/ directory and configuration files from config/ feed into the build process.
• Processing Components: The build scripts (found in xcscripts/ and the Build*Asset directories) process input data, validate version numbers, convert files (e.g., building asset constants, converting certificates, generating asset-specific plists) and output intermediary data.
• Build Orchestration: The Xcode projects (CertificateTool.xcodeproj and security_certificates.xcodeproj) serve as the main build orchestrators, invoking respective build targets (osx_trust_store and ios_trust_store) which compile and sign the final asset bundle.
• Output: The final product is a digitally signed bundle (or asset) containing the trust store. This asset is delivered to the operating system to update its trusted root store.
Architectural Patterns and Design Principles
• Modular Design: The project separates the concerns through different directories. For example, certificate management is separated (by type: active, revoked, removed) from build orchestration.
• Build Pipeline: The layered approach (configuration → processing scripts → Xcode build targets) shows an asset pipeline where raw assets are transformed step by step.
• Platform Specificity: Two main build flows (OSX versus iOS) are supported via dedicated directories and build scripts.
• Configuration-Driven: Critical elements such as trust store versioning are controlled via editable configuration files, making the build reproducible and maintainable.
Technologies, Frameworks, and Tools
• Xcode: The use of .xcodeproj files indicates that the build process is driven by Xcode, and targets are defined explicitly for different platforms.
• Scripting Languages: Ruby, Python, and shell scripts (Makefile, bash scripts) manage various parts of the build and asset generation.
• Plist Management: Multiple plist files indicate that macOS/iOS property lists are used to describe asset versions and metadata.
• Certificate Formats: The project expects certificates in DER format—common in security asset management.
Essential Elements
• Distinct components labeled “Certificate Directories (roots, revoked, removed)”, “EV Mapping Configuration”, “Config Files (plist, xcconfig)”, “Build Scripts (Ruby, Python, Shell)”, “Xcode Projects”, and “Final Trust Store Asset”.
• Annotations that mark critical design principles (for example, “Modular Build Pipeline”, “Platform-Specific Build Paths”, “Configuration-Driven Versioning”).