The OpenZiti.NET SDK is a project that enables developers to create clients and applications leveraging an OpenZiti overlay network. OpenZiti is a modern, programmable overlay network with associated edge components, for application-embedded, zero trust network connectivity, written by developers for developers. The SDK harnesses that power via APIs that allow developers to imagine and develop solutions beyond what OpenZiti handles by default.
Using an OpenZiti SDK for your application's communication needs makes your application secure-by-default by incorporating zero trust principles directly into the application itself. All communication over an OpenZiti overlay network is performed over a mutual TLS (mtls) secured connection. OpenZiti also implements truly end-to-end encryption (via libsodium) by default. The developer does not need to do more than incorporate the OpenZiti SDK into an application to gain these immediate benefits. The OpenZiti overlay network provides numerous other security features that combine to make a compelling security solution for any application.
If you're new to OpenZiti or overlay networks it might be useful to check out the official documentation or inspect [https://github.com/openziti/ziti](the main repo) and learn a more about OpenZiti and zero trust in general.
To get started you'll need to have an OpenZiti overlay network. Deploy one by running one of the OpenZiti network quickstarts.
With access to an OpenZiti overlay network, there are a few important concepts that are helpful to understand, but are not required for executing the samples:
- What is an Identity
- How are identities created
- What is enrollment and how are identities enrolled
- Using and loading an Identity to create a ZitiContext
- Dialing and Binding
The samples do not reference the OpenZiti.NET NuGet package. Instead, they reference the OpenZiti.NET project in this repository. When you want to add OpenZiti to your dotnet project, you would instead choose to reference and use the OpenZiti.NET NuGet package.
The samples included in this repo are designed to allow you to explore this SDK and explore OpenZiti without fully understanding these concepts. You will of course eventually need to understand these terms to make the most of the SDK, but to get started you won't need to. See the official documentation for more info and engage with our community on Discourse.
Running the samples are designed to be self-bootstrapping. They will use the OpenZiti Management API to create all the required configuration inside the OpenZiti overlay network that is necessary. This means the samples can be run over and over without worrying the sample will fail, but it also means they setup the sample every time. This will become important as you progress with your OpenZiti journey and try to reuse the configuration created by the sample.
There are currently four different samples you can run, each of which outlining a different principle of OpenZiti. Find a sample that seems interesting, and follow the readme to that sample to learn how to run it.
| Sample | Description |
|---|---|
| OpenAPI PetStore | Illustrates how to invoke an HTTP-based API securely |
| Weather | Illustrates how to make an http-based request and output the content to the screen using wttr.in |
| Sample | Illustrates how to use OpenZiti as a server AND a client. Demonstrates true application-embedded zero trust! |
| Enrollment | A simple sample demonstrating how to enroll an OpenZiti Identity |
The latest versions of the ziti CLI contains a command called ziti edge quickstart. This command can be used with
all of the samples to easily setup an environment to test with. You can also run the samples with an overlay generated
by following one of the quickstarts and also works with CloudZiti when
supplying the "noint" parameter to the samples.
The ziti CLI tool is a convinient way to access the OpenZiti overlay network via a command line, instead of by API.
You'll likely want to have the ziti CLI available at times as it's handy to use for exploring the OpenZiti
configuration. If you do not have the ziti CLI, but wish to install it, you can quickly install it by running a single
powershell command (as always, read the script before executing):
iex(iwr -Uri https://get.openziti.io/quick/getZiti.ps1)
If you are looking to contribute to the project you will need to understand what it is and what it and how the pieces all come together. This project provides two nuget packages, designed to make it easy to include OpenZiti into any dotnet project.
- Idiomatic dotnet SDK - OpenZiti.NET on nuget.org
- Native NuGet package - OpenZiti.NET.native on nuget.org
This NuGet package provides the idiomatic SDK implementation. It is built and published to NuGet
using this GitHub workflow. The workflow itself is straightforward and
boils down to invoking dotnet build on the OpenZiti.NET, calling the "NugetPush"
target. You will find that target declared in the project file and pushes to whatever source you pass to dotnet build
with the /p:NUGET_SOURCE=. Building this package with this process should be very straightforward.
The task will use the OpenZiti.NET.nuspec to build the package. This means updates to references MUST be reflected in that file. An automated process occurs when the OpenZiti.NET project completes a successful build which will emit an updated .nuspec file in that folder. If this file changes, you must commit it.
To test changes to the code, it's usually easiest to make a new sample that exercises the functionality you want to change/update and run that sample. This will also set us up for success when trying to illustrate/document the sample to consumers of the package.
It's often vital to enable a deeper loglevel for the native C SDK (provided by the
OpenZiti.NET.native package. You do this by invoking SetLogLevel:
API.SetLogLevel(ZitiLogLevel.INFO);
Some of the samples are based around HTTP. A convenience handler exists to make logging the HTTP request/response easy.
See OpenZiti.Debugging.LoggingHandler and how it is used it samples. You will need to enable the logging before it
produces output by setting:
loggingHttpHandler.LogHttpRequestResponse = true;
The Native NuGet package is built and published by GitHub actions. It currently supports the following architectures:
- Windows - x64 (64bit)
- Windows - x86 (32bit)
- MacOS - x86_64
- MacOS - arm64
- linux - x64
- linux - arm64
- linux - arm
By far, the most complex part of dealing with the dotnet sdk is building the native library. The native library provides
a few helper functions, writting in C that are vital to the dotnet SDK. Building the native library is somewhat complex.
If you're unfamiliar with cmake, you'll need to learn a fair bit about what cmake is and how it works. Also,
the C SDK now uses vcpkg which is also somewhat complex for a new learner. We
leverage a CMakePresets.json which you'll need to learn about. The
cmake CMakeLists.txt is located in the ZitiNativeApiForDotnetCore.
If you are interested in learning how the native library is built, see the
github action file](.github/workflows/native-nuget-publish.yml). For more information about the
ZitiNativeApiForDotnetCore, go to the readme in the project folder.
Once the the native library is published to NuGet, the idiomatic SDK references the NuGet package to provide the single, cross-platform, idiomatic dotnet NuGet package for easy downstream inclusion in projects.
Here's a short set of instructions for how to rotate the NuGet API key for pushing updates
-
go to https://www.nuget.org/account/ApiKeys
Key Name: Expires In: 365 days Package Owner: OpenZiti Select Scopes: Push (checked) Push new packages and package versions (selected) Push only new package versions (unselected) Unlist package (unchecked) Glob Pattern: OpenZiti.* Select Packages: Available Packages: OpenZiti.NET OpenZiti.NET.native -
go to https://github.com/organizations/openziti/settings/secrets/actions
-
find/update: NUGET_API_KEY with the key made above