Partager via

Azure Code Transparency client library for .NET - version 1.0.0-beta.2

  • Article

Azure.Security.CodeTransparency is based on a managed service complying with a draft SCITT RFC. It is a managed service that allows countersigning COSE signature envelopes. Countersignatures are recorded and signed in the immutable merkle tree for any auditing purposes and the receipt gets issued.

Getting started

Install the package

Make sure you have access to the correct NuGet Feed.

Install the client library for .NET with NuGet:

dotnet add package Azure.Security.CodeTransparency --prerelease

Prerequisites

  • A running and accessible Code Transparency Service
  • Ability to create COSE_Sign1 envelopes, an example script
  • Your signer details (CA cert or DID issuer) have to be configured in the running service, about available configuration
  • You can get a valid Bearer token if the service authentication is configured to require 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

You can get a valid Bearer token if the service authentication is configured to require one, see example.

Examples

There are two main use cases for this service: submitting a cose signature envelope and verifying the cryptographic submission receipt. The receipt proves that the signature file was successfully accepted.

Before submitting the cose file, the service must be configured with the relevant Certificate Authority certificate to be able to accept it.

To submit the signature, use the following code:

CodeTransparencyClient client = new(new Uri("https://<< service name >>.confidential-ledger.azure.com"), null);
FileStream fileStream = File.OpenRead("signature.cose");
BinaryData content = BinaryData.FromStream(fileStream);
Operation<GetOperationResult> operation = await client.CreateEntryAsync(content);
Response<GetOperationResult> operationResult = await operation.WaitForCompletionAsync();
Console.WriteLine($"The entry id to use to get the entry and receipt is {{{operationResult.Value.EntryId}}}");
Response<BinaryData> signatureWithReceiptResponse = await client.GetEntryAsync(operationResult.Value.EntryId, true);
BinaryData signatureWithReceipt = signatureWithReceiptResponse.Value;
byte[] signatureWithReceiptBytes = signatureWithReceipt.ToArray();

Once you have the receipt and the signature, you can verify whether the signature was actually included in the Code Transparency service by running the receipt verification logic. The verifier checks if the receipt was issued for a given signature and if the receipt signature was endorsed by the service.

CcfReceiptVerifier.RunVerification(signatureWithReceiptBytes);

If the verification completes without exception, you can trust the signature and the receipt. This allows you to safely inspect the contents of the files, especially the contents of the payload embedded in a cose signature envelope.

To learn more about other APIs, please refer to our samples.

Key concepts

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

Troubleshooting

Response values returned from Azure confidential ledger client methods are Response objects, which contain information about the http response such as the http Status property and a Headers object containing more information about the failure.

Next steps

For more extensive documentation, see the API reference documentation. You may 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 [cla.microsoft.com][cla].

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

Working with the source code of this library. The following just builds on the existing documentation to make it more convenient.

Impressions