microsoft / cosesigntool

CoseSignTool is a platform-agnostic command line application to COSE sign files and validate COSE signatures. CoseHandler is a library of functions for COSE signing and validation for use by .NET applications.

CoseSignTool and the CoseHandler libraries

CoseSignTool is a platform-agnostic command line application to create and validate COSE signatures.

CoseHandler is a .NET library of static functions that mirror the functionality of CoseSignTool. Or to put it more accurately, CoseSignTool is a command line shell for CoseHandler.

CoseSignTool and CoseHandler support three commands/methods:

1. Sign: Creates a COSE signature for a file or stream. This signature is saved in a separate file from the source payload, but you may optionally include a copy of the source payload in the signature file.
2. Validate: Validates that a COSE signature is properly formed, has a valid certificate chain, and matches the source payload or its hash.
3. Get: Reads the source payload from a COSE signature and returns the original text, or writes it to file or console.

The CoseSign1, CoseSign1.Abstractions, and CoseSign1.Certicates libraries provide the underlying functionality for CoseSignTool and CoseHandler, and can be called directly for more advanced scenarios.

What is COSE?

'COSE' refers to CBOR Object Signing and Encryption, which is the de-facto standard for signing Software Bills of Materials (SBOM). It is also used to provide secure authentication for web and Internet Of Things(IOT) application, and is suitable for for signing scripts and other text content. CBOR refers to the Concise Binary Object Representation Internet standard.

Why would I use this?

The US Executive Order on Improving the Nation’s Cybersecurity of May 12, 2021 requires an SBOM for any software or firmare product in use by the US government. This also includes the libraries and tools those products are built with. Even in consumer software, an SBOM helps you protect your customers from supply chain attacks by enabling you to quickly check the version numbers of all the products in your software supply chain. CoseSignTool, CoseHandler, and the CoseSign1 libraries are the Microsoft solution for signing SBOMs and, we believe, the most powerful and convenient solution currently on the market.

How do I get started?

First, download the latest release from GitHub. There will be a fully signed version on NuGet.org soon, but this is just a pre-release, so there's only the open source version available for now.

If you have the option of calling it from a .NET application, go to CoseHandler.md

Otherwise, go to CoseSignTool.md

How do I make this better?

You would like to help? Great! First check to make sure the work isn't already planned, then...

• If you find a bug or have a feature reccomendation, log an issue.
• If you would like to contribute actual code to the repo or comment on the pull requests of others, read our contributor guidelines and style guidelines, and then make your contribution.

State of the project

This is an alpha release, so there are some planned features that are not yet in the product, and you may encounter some bugs. If you do, please report them here.

The planned work is currently tracked only in an internal Microsoft ADO instance but will be moved to Github Issues soon. In the meantime, here is some of the work currently planned.

New features

• Investigate adding suport for RFC3161 timestamp counter signatures
• Enable specifying a mandatory cert chain root for validation
• Simplify digest signing scenario
• Support batch operations in CoseSignTool to reduce file and cert store reads
• Publish single file version of CoseSignTool

Security, performance, and reliability improvements

• Cache certificate store reads for faster performance
• Ensure type saftey on cert store and file reads
• Investigate specific compilation by platform for possible performance gains
• Expand code coverage in unit and integration tests

Other

• Move work item tracking to public Github repo
• Re-organize the CoseSignTool unit tests for better readability

Requirements

CoseSignTool runs on .NET 7. It depends on the libraries from this package and Microsoft.Extensions.Configuration.CommandLine from NuGet package version 7.0.0.

The libraries depend on System.Formats.Cbor version 7.0.0, System.Security.Cryptography.Cose version 7.0.0, and System.Runtime.Caching version 7.0.0 via NuGet package. Do not attempt to use later versions of System.Formats.Cbor or System.Security.Cryptography.Cose, as this breaks some of the fundamental data structures the libraries depend on.

The underlying libraries run on .NET Standard 2.1 but will shortly be released on 2.0 for compatibility with legacy .NET Framework environments. CoseHandler currently builds on .NET 7 but will be switched to .NET Standard 2.0 soon to match the other libraries.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.

cosesigntool's Issues

CoseSignTool.exe `validate` incorrectly passes validation

CoseSignTool.exe validate appears to falsely report successful validation when the certificate chain does not lead to a known root.

This appears to be isolated to just the CoseSignTool.exe validate command line tool and not the CoseHandler API.

Repro steps:

1.) Produce a detached COSE signature (See: Sign command)
1.) Make sure that the root CA of the signing certificate is not installed in trusted root store
2.) Attempt to call CoseSignTool.exe validate on the payload and previously produced .cose file with no /Roots specified
3.) Observe "Validation succeeded message"

Running the CoseSignTool without any arguments hits an exception rather than printing the helptext

I downloaded the 1.1.0 version of the CoseSignTool and the required .NET dependencies. When I ran the CoseSignTool.exe without any arguments it hit an exception:

%> CoseSignTool.exe
Unhandled exception. System.IndexOutOfRangeException: Index was outside the bounds of the array.
   at CoseSignTool.CoseSignTool.Main(String[] args) in D:\a\CoseSignTool\CoseSignTool\CoseSignTool\CoseSignTool.cs:line 27

This is unexpected, I expected the tool to print out it's help text.

Note that when I passed in --help it worked as expected:

%> CoseSignTool.exe --help

*** CoseSignTool ***
A tool for signing, validating, and getting payload from Cose signatures.

Usage:
    ...

.Pfx passwords should be prompted and taken in as a secure string.

Currently CoseSignTool.exe sign supports signing with password protected .pfx certificates with the /Password argument. The user should be prompted for the password at runtime so we can consume it as a secure string.

Action required: self-attest your goal for this repository

It's time to review and renew the intent of this repository

An owner or administrator of this repository has previously indicated that this repository can not be migrate to GitHub inside Microsoft because it is going public, open source, or it is used to collaborate with external parties (customers, partners, suppliers, etc.).

Action

👀 ✍️ In order to keep Microsoft secure, we require repository owners and administrators to review this repository and regularly renew the intent whether to opt-in or opt-out of migration to GitHub inside Microsoft which is specifically intended for private or internal projects.

❗Only users with admin permission in the repository are allowed to respond. Failure to provide a response will result to your repository getting automatically archived. 🔒

Instructions

❌ Opt-out of migration

If this repository can not be migrated to GitHub inside Microsoft, you can opt-out of migration by replying with a comment on this issue containing one of the following optout command options below.

@gimsvc optout --reason <staging|collaboration|delete|other>

Example: @gimsvc optout --reason staging

Options:

• staging : My project will ship as Open Source
• collaboration : Used for external or 3rd party collaboration with customers, partners, suppliers, etc.
• delete : This repository will be deleted because it is no longer needed.
• other : Other reasons not specified

✅ Opt-in to migrate

If the circumstances of this repository has changed and you decide that you need to migrate, then you can specify the optin command below. For example, the repository is no longer going public, open source or require external collaboration.

@gimsvc optin --date <target_migration_date in mm-dd-yyyy format>

Example: @gimsvc optin --date 03-15-2023

Click here for more information about optin and optout command options and examples

Opt-in

@gimsvc optin --date <target_migration_date>

When opting-in to migrate your repository, the --date option is required followed by your specified migration date using the format: mm-dd-yyyy

@gimsvc optin --date 03-15-2023

Opt-out

@gimsvc optout --reason <staging|collaboration|delete|other>

When opting-out of migration, you need to specify the --reason.

• staging
  • My project will ship as Open Source
• collaboration
  • Used for external or 3rd party collaboration with customers, partners, suppliers, etc.
• delete
  • This repository will be deleted because it is no longer needed.
• other
  • Other reasons not specified

Examples:

@gimsvc optout --reason staging

@gimsvc optout --reason collaboration

@gimsvc optout --reason delete

@gimsvc optout --reason other

Need more help? 🖐️

• Email [email protected]. ✉️
• Post your questions in GitHub inside Microsoft Team in Microsoft Teams.

Question: How to use certificate with password?

I tried to use this tool to sign SBOM for our driver package with PFX certificate with password and got error.

>"H:\Program Files\Windows Kits\10\Tools\10.0.26063.0\x64\CoseSignTool.exe" sign /PayloadFile NetKVM.sbom.json /PfxCertificate VirtIOTestCertPass.pfx
COSE Sign failed.
The specified network password is not correct.

If I try to use a certificate without a password, everything works.
How should I specify the password for the certificate? How can I use this tool to sign SBOM with an EV Code Signing token certificate?

Best regards