Git Product home page Git Product logo

wifi-ztp's Introduction

Wi-Fi Zero Touch Provisioning (ZTP)

ZTP Penguin

This project provides a Wi-Fi zero touch provisioning library and daemon for Linux. It supports provisioning of Wi-Fi credentials using Wi-Fi Easy Connect, also known as the Device Provisioning Protocol (DPP).

Building

Ubuntu (focal)

Install package dependencies:

sudo apt install build-essential cmake git libboost-filesystem-dev libboost-random-dev libboost-regex-dev libboost-system-dev libboost-thread-dev libbrotli-dev libgpiod-dev libjson-c-dev libssl-dev libsystemd-dev pkg-config zlib1g-dev

Checkout and build:

git clone [email protected]:microsoft/wifi-ztp.git
cd wifi-ztp
mkdir build && cd $_
cmake ..
make -j $(nproc)

Usage

The daemon usage is driven primarily by configuration files whose path is passed to the daemon as a command line flag. The daemon accepts the following command line flags:

Flag Presence Description Supported Values Examples
-c Required Configuration file path Absolute path to the primary configuration file -c /etc/ztpd/config.json
-d Optional Daemonize flag (run in background) None (unary flag) -d
-v Optional Version output flag. Program exits immediately. None (unary flag) -v

Configuration files

Primary configuration file

This file controls global daemon options, including the Wi-Fi EasyConnect device roles (enrollee, configurator) that are supported and activated. For each of these roles, a separate configuration file is specified by providing its absolute path. Each configuration file option is specified in config.json.schema, and an example configuration file can be found here.

Enrollee configuration file

When the primary configuration file specifies that the Wi-Fi EasyConnect enrollee device role is supported, it also specifies its configuration file. This file describes enrollee options, including information about the bootstrapping key. Each configuration file option is specified in config-enrollee.schema.json, and an example configuration file can be found here.

Configurator configuration file

When the primary configuration file specifies that the Wi-Fi EasyConnect configurator device role is supported, it also specifies its configuration file. This file describes configurator options, including information regarding enrollee bootstrapping information. Each configuration file option is specified in config-enrollee.schema.json, and an example configuration file can be found here. Enrollee bootstrapping information is provided by bootstrapping information providers (BIPs), which are specified in the configuration file. Currently, there are two built-in providers:

Azure Device Provisioning Service (DPS)

This bootstrapping information provider sources enrollee bootstrapping records from an Azure Device Provisioning Service (DPS) instance. The bootstrapping information is contained in device records under a top-level object property called optionalDeviceInformation. The object structure expected is as follows:

"optionalDeviceInformation": {
    "ZeroTouchProvisioning": {
        "WiFi": {
            "Interfaces": [
                {
                    "DppUri": "DPP:V:2;M:d8c0a65935ed;K:MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgACE0vdn8KsfXKHusJPcEscx+naQyQJLSob1VjuqPsP6r8=;;"
                },
                {
                    "DppUri": "DPP:V:2;M:70665509b591;K:MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgACiLN+2Rk4tRlwl4CKYkSEdheJIEbZO5UBr9SPoPFI394=;;"
                }
            ]
        }
    }
}

Each supported wireless interface can be specified and must contain a child property with key DppUri. The value is a string describing a valid Device Provisioning Protocol (DPP, EasyConnect) URI for an enrollee device.

The provider will periodically retrieve the device records from the instance and cache them in a local view. Each provider can optionally define the DPS instance record expiration time. The daemon will consider the local device record view as consistent with the remote instance view until the expiry time elapses, at which point the local view will be re-synchronized.

File

This bootstrapping information provider sources enrollee bootstrapping records from a json-formatted file. It may be configured to point to the enrollee bootstrapping records using json pointers. The example configuration file shows an example of this provider where the file config-bootstrapinfo.json contains the enrollee records, amongst other unrelated information.

This bootstrap provider is not meant to scale to a large number of records. It is meant more for small scale deployments or for testing and debugging purposes.

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.opensource.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., status check, 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 [email protected] with any additional questions or comments.

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.

wifi-ztp's People

Contributors

abeltrano avatar forwardpointer avatar microsoft-github-operations[bot] avatar microsoftopensource avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

wifi-ztp's Issues

Implement --version option

Is your feature request related to a problem? Please describe.
.

Describe the solution you'd like
I would like ztpd --version to output the version that the ztpd binary is. To my knowledge there is no other way to check the version of the binary. Having this information outputted in the logs would also help debugging.

Describe alternatives you've considered
.

Additional context
.

possible memory leak in the future if we switch to a multithreaded ztpd

I noticed that if ztpd_run() returns a negative error code then nothing will be deinitialized before the main() function exits. Currently ztpd is all single-threaded, so this isn't an issue, as when the process exits all memory the process used will be released by the kernel. However, if in the future someone decides to add multi-threaded or multi-process capabilities to ztpd this will result in a possible memory leak. I thought I'd make note of this here just in case that happens.

Replace custom event loop with open-source alternative

Is your feature request related to a problem? Please describe.
The code to manage the event loop was written from scratch. During early development, there were not many event loop features that were needed, so a hand-written one allowed rapid prototyping. However, the event loop has become more complicated and so, it may be a better idea to replace the hand-written event loop code with a publicly available, well documented and tested event library.

Describe the solution you'd like
The hand-written event code should be replaced with a well-tested, open-source event library for C. Many popular event libraries available, the following libraries are a good start for consideration:

Describe alternatives you've considered

  • Leave the event loop as it is. This risks more complicated maintenance and requires more bootstrap time for onboarding.

Additional context

  • None

Add option to specify static DPP bootstrap key for role=enrollee

Is your feature request related to a problem? Please describe.
Enrollee configuration currently only supports bootstrapping type qrcode. Internally, this requires/forces the use of the TPM openssl engine which means systems without a TPM cannot be used for testing.

Describe the solution you'd like
An option should be configurable for enrollees to specify a static DPP bootstrapping key for use with bootstrapping type qrcode. For example, the json configuration could look something like this:

{
    "bootstrap.info": {
        "type": "qrcode",
        "keyType": "static",
        "key": "30570201010420777fc55dc51e967c10ec051b91d860b5f1e6c934e48d5daffef98d032c64b170a00a06082a8648ce3d030107a124032200020c804188c7f85beb6e91070d2b3e5e39b90ca77b4d3c5251bc1844d6ca29dcad"
    }
}

There could even be an auto-generation method where ztpd auto-generates a bootstrapping key and outputs it somewhere that is easy to be found (eg. journald logs or a file). Eg.

{
    "bootstrap.info": {
        "type": "qrcode",
        "keyType": "generate"
    }
}

wpa_supplicant already supports this when creating a new bootstrapping key without also providing private key (it get's auto-generated on first use). The public key can be obtained later using the bootstrapping id and the DPP_BOOTSTRAP_GET_URI <ID> control socket command.

Describe alternatives you've considered
Alternatives are currently to program wpa_supplicant manually using cli tools (eg. wpa_cli). This is clunky and disrupts instrumentation between ztpd and wpa_supplicant, and is annoying for our partners to use since they then have to mess with systemd unit configuration resets and custom configuration.

Additional context
Our partner engineering teams need a better method to test their configurator against our enrollee without too much effort/ramp-up/setup. A similar method exists for the configurator, the file based BIP, which allows specification of static DPP URIs for supported enrollees. The request here is to provide an analogous option for enrollee testing.

Enable static code analysis as part of CI/CD

Is your feature request related to a problem? Please describe.
Static code analysis is needed to detect easy/obvious bugs. PR completion should be gated based on the analysis output (no new issues introduced).

Describe the solution you'd like
Enable basic static code analysis tools to scan the code as part of the PR process and gate PR completion on it. CodeQL is supported out-of-box by github so should be the top priority. cppcheck is also a good option but is not supported out-of-box so can be a future addition.

Describe alternatives you've considered
Manual static code analysis is already a soft requirement for PRs. However, it would be better to gate PR completion by an automated check.

Additional context
None.

Undefined behavior because null terminator was not explicitly set before strtoul uses it

Describe the bug
In src/wpas/wpa_controller.c:wpa_controller_qrcode() the reply buffer doesn't have a null terminator set so when strtoul reads it, sometimes it reads past the reply_length. This causes ztpd to believe the id is something other than what wpa sent it, meaning the configurator will not be able to provision any enrollee.

To Reproduce
Steps to reproduce the behavior:

  1. Whenever the code calls wpa_controller_qrcode() you have a chance to see this undefined behavior.
  2. See error

Expected behavior
strtoul should read exactly reply_length bytes from the reply buffer.

Desktop (please complete the following information):

  • OS: Azure Percept Device

ztpd exit code is always 0 regardless of exit condition

Describe the bug
The ztpd daemon always returns a 0 exit code from its main process, regardless of whether the process exited cleanly or not. This is due to ztpd_run() having a void return type.

To Reproduce
Steps to reproduce the behavior:

  1. ztpd -c /path/to/ztpd/config.json -d
  2. kill -9 $(pidof -s ztpd)

Expected behavior
ztpd exits with a non-zero exit code.

Desktop (please complete the following information):

  • OS: Azure Percept Device
  • ztp v0.4.0.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.