General overview
When you apply for code signing, we take a look at our project and do an initial review of your source code to ensure it meets our Project Rules. This review is always performed by a person and covers the entire codebase at the current tag or commit.
We then create a companion repository under the OSSign organization, which will hold a workflow and some general information.
When everything is set up, you will have the ability to trigger the workflow from your repository. Depending on the amount and type of changes, you might pass our review process automatically or the changes might require a manual review by a person to make sure everything is in order.
The workflow for signing does the following:
- Checks out your source code from the tag or commit you requested
- Builds the project according to the workflow steps defined in the companion repository, which are originally from your repository's build process.
- Signs the resulting artifacts using the OSSign certificates
- Publishes the signed artifacts alongside the receipt from the review as a release in that repository
- Responds to the workflow request with the names and URLs of the signed artifacts
This process is designed to ensure that both parties can trust the full integrity of the build process and that the resulting artifacts always contain the exact sources that were reviewed.
The application process
When your application starts its review process, we will generally do a thorough review of your source code in your repository. Things we look for at this stage are, among others:
- Potential leaked secrets in the commit history
- Risk factors that could cause potential future issues (included binary blobs of unknown origin, build scripts that fetch insecure or malicious external dependencies, or other suspicious patterns)
- OSV-scanner results are checked against vulnerability databases to identify known security issues with your dependencies
- Other security and quality checks as deemed necessary by the reviewers
During this process, we might ask you to change certain parts of your code or configuration to address the issues identified in the review. This could include removing leaked secrets, fixing insecure dependencies, or making other adjustments to meet our project rules and security standards.
Once all issues are resolved and the reviewers are satisfied, your project will be approved and we will set up the companion repository for your project in OSSign.
When the configuration is done, we will create an initial build of your project using the OSSign workflow to ensure everything works smoothly, and that the signing process is correctly integrated with your build. You will then get the opportunity to fetch and review the signed artifacts to make sure everything is in order.
Once you have reviewed and approved the process and initial build, you will be able to set up requests for signing from your repository.
These requests will trigger the OSSign workflow in the mirror repository, which will build your project, sign the resulting artifacts, and publish them alongside the review receipt. You will then be notified with the names and URLs of the signed artifacts, completing the signing process.
Every Release After That
- Request. Your repository asks the OSSign server to sign a tag or branch, usually from a workflow on every version tag. See Requesting a Signed Build.
- Pin and review. The server pins the ref to a commit and reviews what changed since the last approved commit. Low-risk changes, such as documentation, renamed functions, corrected bugs and other small changes can be approved automatically. Larger sets of changes will require a manual review by a member of the OSSign Team.
- Build and sign. The server starts the workflow in your OSSign repository. The signing job is held by a GitHub deployment protection rule until the review is approved, then builds the pinned commit and signs the files.
- Release. The signed files are published as a release in your OSSign repository, together with a signed review report. See Reviews and Reports.
- Fetch. Your workflow, or you by hand, downloads the signed files and publishes them wherever you distribute your project.
Reviews by a person can take from a few hours up to a day or two depending on the complexity of the changes, especially for the first few releases of a project. Plan for this rather than keeping a paid runner waiting, you can find more information about this in the Your Workflow section.
FAQ
Why can't I build the files myself and send them to you for signing?
The simple answer to this is because it is much harder to verify that a binary came from those exact sources without a controlled build process. There are a number of subtle ways in which a build process can introduce harmful code along the way, and we have a responsibility to ensure that this does not happen.
Why not just trust the developer to sign the build?
Because access to the signing certificate is considered a highly sensitive operation, and malicious access can cause a great deal of damage. There is simply no easy way for us to guarantee that a single developer in one of our signed-for projects has not been compromised and is signing malicious binaries.
How can I fully trust that the signed files match the source?
This answer is twofold.
The first part is the public build process in itself. We take great care to ensure that every part of the process is publicly auditable, from fetching the source code to running the build, signing the artifacts, and their publication.
The second part is that the actual signature on the resulting files is ours, which means the project we would be harming the most by introducing malicious code is our own.
What happens if I discover a discrepancy between the signed files and the source?
If you find that the signed files do not match the source code, it is crucial to report this immediately. Our process is designed to ensure that such discrepancies should not be possible,, but if they occur, we will investigate and take appropriate action to maintain the integrity of the signing process.
While not perfect, we do have the ability to recall a signature* if a discrepancy is found, malicious code is detected, or any other issue arises that compromises the integrity of the signed files.