-
Notifications
You must be signed in to change notification settings - Fork 46
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This refactors the `docs/` directory into `docs/` and `docs-dev/` for user documentation and developer documentation, with the following overall motivations: - Remove developer documentation from HTML documentation so that users do not land on it. Ideally this would be something like `docs/user/` and `docs/dev/` but GitHub does not allow using anything except `docs/` for the root. - Change PKCS#11 library documentation to focus exclusively on the case of users installing it in production. This means replacing mentions of "the user you will run aziot-keyd as" with "aziotks", etc. - Don't link to HTTP API docs from the index since they're only useful for host module authors. They're linked from the host-module doc instead. Also, the TPM service is exclusively an internal service, so move it to developer docs. - Move `packaging.md` to developer docs since the user does not need the level of detail it provides about what the package contains. The user docs only cover the super-config and a new page about the `aziotctl` binary. - Hard-code the nav bar instead of letting Jekyll generate it, so that it preserves the order of pages rather than sort them alphabetically.
- Loading branch information
Showing
60 changed files
with
480 additions
and
395 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
# Developer documentation | ||
|
||
These docs are meant for developers working on this repository who need to build the services from source, deploy in testing environments, etc. | ||
|
||
If you are not a developer working on this repository, please go to user docs at <https://azure.github.io/iot-identity-service/> instead. | ||
|
||
- [Building the services](building.md) | ||
|
||
- [Running the services locally](running/index.md) | ||
|
||
- [Building the packages](packages.md) | ||
|
||
- [End-to-end tests](e2e-tests.md) | ||
|
||
- [Provisioning using EST, with certificates issued by EST (On-prem PKI)](est-ca.md) | ||
|
||
- [TPM Service API docs](tpm-service.md) | ||
|
||
- [OpenSSL engine internals](openssl-engine-internals.md) |
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,91 @@ | ||
# Provisioning using EST, with certificates issued by EST (private PKI) | ||
|
||
--- | ||
|
||
![Cloud Setup](img/est-ca-cloud-setup.svg) | ||
|
||
--- | ||
|
||
![Device Setup](img/est-ca-device-setup.svg) | ||
|
||
--- | ||
|
||
![Provisioning](img/est-ca-provisioning-simple.svg) | ||
|
||
[(Click here for detailed version)](img/est-ca-provisioning-detailed.svg) | ||
|
||
--- | ||
|
||
![Runtime operation](img/est-ca-runtime-operation-simple.svg) | ||
|
||
[(Click here for detailed version)](img/est-ca-runtime-operation-detailed.svg) | ||
|
||
--- | ||
|
||
1. KS configuration | ||
|
||
```toml | ||
[pkcs11] | ||
"lib_path" = "/usr/lib/hardware-specific-pkcs11-library.so" | ||
"base_slot" = "pkcs11:slot-id=0?pin-value=1234" | ||
|
||
[preloaded_keys] | ||
"bootstrap" = "pkcs11:slot-id=0;object=device%20id?pin-value=1234" | ||
``` | ||
|
||
1. CS configuration | ||
|
||
```toml | ||
"homedir_path" = "/var/lib/iotedge/cs" | ||
|
||
[cert_issuance] | ||
device-ca = "est" # Only needed if one of the others has the value "device-ca" | ||
device-id = "est" # or "device-ca" for minting locally | ||
module-id = "est" # or "device-ca" for minting locally | ||
module-server = "est" # or "device-ca" for minting locally | ||
|
||
[cert_issuance.est] | ||
"method" = "x509" | ||
"identity_cert" = "est-id" | ||
"identity_pk" = "est-id" | ||
"bootstrap_identity_cert" = "bootstrap" #optional | ||
"bootstrap_identity_pk" = "bootstrap" #optional | ||
|
||
[cert_issuance.est.urls] | ||
# Default EST endpoint URL | ||
default = "https://estendpoint.com/.well-known/est/simpleenroll" | ||
|
||
# EST endpoint URL specifically for the est-id cert | ||
"est-id" = "https://estendpoint.com/.well-known/est/est-id/simpleenroll" | ||
|
||
# EST endpoint URL specifically for the device-id cert | ||
"device-id" = "https://estendpoint.com/.well-known/est/device-id/simpleenroll" | ||
|
||
# EST endpoint URL specifically for the device-ca cert | ||
"device-ca" = "https://estendpoint.com/.well-known/est/device-ca/simpleenroll" | ||
|
||
[preloaded_certs] | ||
"bootstrap" = "/var/secrets/bootstrap.cer" | ||
"est-ca" = "/var/secrets/est-ca.cer" | ||
"trust-bundle" = [ | ||
"est-ca", | ||
] | ||
``` | ||
|
||
1. IS configuration | ||
|
||
```toml | ||
[provisioning] | ||
"source" = "dps" | ||
"scope_id" = "<ADD dps SCOPE ID HERE>" | ||
|
||
[provisioning.attestation] | ||
"method" = "x509" | ||
"identity_cert" = "device-id" | ||
"identity_pk" = "device-id" | ||
|
||
``` | ||
|
||
The elements in the `trust-bundle` array and the `provisioning.attestation.identity_cert` value are certificate IDs defined in the CS's `preloaded_certs` table. | ||
|
||
The `provisioning.attestation.identity_pk` value is a key ID defined in the KS's `preloaded_keys` table. |
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
2 changes: 1 addition & 1 deletion
2
docs/openssl-engine-internals.md → docs-dev/openssl-engine-internals.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
# Setting up your PKCS#11 library | ||
|
||
Follow the user steps at <https://azure.github.io/iot-identity-service/pkcs11/> | ||
|
||
If you want to use tpm2-pkcs11 with the TPM simulator, see [`ibmswtpm2`](ibmswtpm2.md) | ||
|
||
To verify your HSM and its PKCS#11 library with aziot-keyd, see [Testing the openssl engine.](aziot-keyd.md#testing-the-openssl-engine) | ||
|
||
If the script mentioned there completes successfully, then the hardware and PKCS#11 library ought to be suitable for `aziot-keyd` to use. If there are errors such as crashes or signature verification failures, then it might be a problem with the hardware configuration, a bug in the PKCS#11 library, or a bug in the PKCS#11-related code in this repository. |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
# HTTP API of the services | ||
|
||
These pages document the HTTP API of the services, for use by host module authors. | ||
|
||
- [Identity Service](identity-service.md) | ||
|
||
- [Keys Service](keys-service.md) | ||
|
||
- [Certificates Service](certificates-service.md) |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,32 @@ | ||
# Managing the Azure Iot Identity Service | ||
|
||
The `aziotctl` CLI tool is used to manage and interact with the services. | ||
|
||
See `aziotctl --help` for the full help. A few notable commands are listed below. | ||
|
||
Note that most `aziotctl` commands need to be run as root. | ||
|
||
|
||
## Applying changes in the super-config to the services | ||
|
||
```sh | ||
sudo aziotctl config apply | ||
``` | ||
|
||
By default, this command expects the super-config to be at `/etc/aziot/config.toml`. To use a different path, specify the `-c / --config` parameter. | ||
|
||
|
||
## Stop all services | ||
|
||
```sh | ||
sudo aziotctl system stop | ||
``` | ||
|
||
|
||
## Restart all services | ||
|
||
```sh | ||
sudo aziotctl system restart | ||
``` | ||
|
||
Note: Since the services use systemd socket activation, this command starts all the socket units but does not start any service except the Identity Service (`aziot-identityd.service`). The other services (`aziot-keyd.service`, `aziot-certd.service`, etc) will automatically start if they need to. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
# Configuring the Azure IoT Identity Service | ||
|
||
The Azure IoT Identity Service package installs four different services - the Identity Service, Keys Service, Certificates Service, and TPM Service. All of these services can be configured from a single configuration file, called the "super-config". | ||
|
||
A template of this file is installed at `/etc/aziot/config.toml.template`. Copy it to a new file `/etc/aziot/config.toml`, and edit the file with the details of your device, IoT Hub, etc, based on the comments in the file. Then, run the command `sudo aziotctl config apply` to apply the configuration to the services. | ||
|
||
```sh | ||
# Copy the template to a new file | ||
sudo cp /etc/aziot/config.toml.template /etc/aziot/config.toml | ||
|
||
# Edit the new empty config and fill in your provisioning information, | ||
# plus anything else you want to customize. See the comments in the file for details. | ||
sudo $EDITOR /etc/aziot/config.toml | ||
|
||
# Apply the configuration to the services | ||
sudo aziotctl config apply | ||
``` | ||
|
||
If you need to make any changes to the `/etc/aziot/config.toml` file, do so, then re-run `sudo aziotctl config apply` to re-apply those changes to the services. |
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.