Share via

Azure Signing Transparency client library for .NET - version 1.0.0-beta.5

Azure.Security.CodeTransparency is based on a managed service that complies with a draft SCITT RFC. The service stores COSE signature envelopes in the Merkle tree and issues signed inclusion proofs as receipts.

Getting started

Install the package

Ensure you have access to the correct NuGet feed.

Install the client library via NuGet:

dotnet add package Azure.Security.CodeTransparency --prerelease

Prerequisites

  • A running, accessible Signing Transparency service
  • Ability to create COSE_Sign1 envelopes (see example script)
  • Your signer details (CA certificate) must be configured in the running service (see configuration options)
  • Obtain a valid bearer token if service authentication requires one (see example)

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Authenticate the client

Obtain a valid bearer token if the service requires authentication (see example).

Examples

There are two main use cases: submitting a COSE signature envelope and verifying the cryptographic submission receipt, which proves that the signature file was accepted.

Before submitting the COSE file, ensure the service is configured with the appropriate policy.

Use the following code to submit the signature:

CodeTransparencyClient client = new(new Uri("https://<< service name >>.confidential-ledger.azure.com"));
FileStream fileStream = File.OpenRead("signature.cose");
BinaryData content = BinaryData.FromStream(fileStream);
Operation<BinaryData> operation = await client.CreateEntryAsync(WaitUntil.Started, content);

Then obtain the transparent statement:

Response<BinaryData> operationResult = await operation.WaitForCompletionAsync();
string entryId = CborUtils.GetStringValueFromCborMapByKey(operationResult.Value.ToArray(), "EntryId");
Console.WriteLine($"The entry ID to use to retrieve the receipt and transparent statement is {{{entryId}}}");
Response<BinaryData> transparentStatementResponse = await client.GetEntryStatementAsync(entryId);
byte[] transparentStatementBytes = transparentStatementResponse.Value.ToArray();

After obtaining the transparent statement, you can distribute it so others can verify its inclusion in the service. The verifier checks that the receipt was issued for the given signature and that its signature was endorsed by the service. Because users might not know which service instance the statement came from, they can extract that information from the receipt to create the client for verification.

try
{
    var verificationOptions = new CodeTransparencyVerificationOptions
    {
        AuthorizedDomains = new string[] { "<< service name >>.confidential-ledger.azure.com" },
        AuthorizedReceiptBehavior = AuthorizedReceiptBehavior.RequireAll,
        UnauthorizedReceiptBehavior = UnauthorizedReceiptBehavior.FailIfPresent
    };
    CodeTransparencyClient.VerifyTransparentStatement(transparentStatementBytes, verificationOptions);
    Console.WriteLine("Verification succeeded: The statement was registered in the immutable ledger.");
}
catch (Exception e)
{
    Console.WriteLine($"Verification failed: {e.Message}");
}

If verification completes without exception, you can trust the signature and the receipt. You can then safely inspect the files, especially the payload embedded in the COSE signature envelope.

To learn more about other APIs, see the samples.

Key concepts

Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime

Troubleshooting

Response values returned from client methods are Response objects, which contain information about the HTTP response such as the HTTP Status property and a Headers collection with more details.

Next steps

For more extensive documentation, see the API reference documentation. You can also read more about Microsoft Research's open-source Confidential Consortium Framework.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

  • Last updated on