From 814c82de14ffb844b5e693e48b5c83db06bd157a Mon Sep 17 00:00:00 2001 From: Daniel Adam Date: Tue, 20 Aug 2024 10:47:51 +0200 Subject: [PATCH 1/4] Update device provisioning service documentation --- .../configuration/certificate-authority.md | 1 + .../docs/configuration/cloud2cloud-gateway.md | 1 + content/en/docs/configuration/coap-gateway.md | 1 + .../device-provisioning-service.md | 45 +++++++------------ content/en/docs/configuration/grpc-gateway.md | 1 + content/en/docs/configuration/http-gateway.md | 1 + .../en/docs/configuration/identity-store.md | 1 + .../docs/configuration/resource-aggregate.md | 1 + .../docs/configuration/resource-directory.md | 1 + .../en/docs/configuration/snippet-service.md | 1 + 10 files changed, 26 insertions(+), 28 deletions(-) diff --git a/content/en/docs/configuration/certificate-authority.md b/content/en/docs/configuration/certificate-authority.md index 9429e540..e7cb2de6 100644 --- a/content/en/docs/configuration/certificate-authority.md +++ b/content/en/docs/configuration/certificate-authority.md @@ -63,6 +63,7 @@ gRPC API of the Certificate Authority service as defined [here](https://github.c | `apis.grpc.authorization.endpoints[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` | | `apis.grpc.authorization.endpoints[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` | | `apis.grpc.authorization.endpoints[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` | +| `apis.grpc.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` | ### HTTP API diff --git a/content/en/docs/configuration/cloud2cloud-gateway.md b/content/en/docs/configuration/cloud2cloud-gateway.md index 0a478840..2a812cad 100644 --- a/content/en/docs/configuration/cloud2cloud-gateway.md +++ b/content/en/docs/configuration/cloud2cloud-gateway.md @@ -53,6 +53,7 @@ A configuration template is available in [cloud2cloud-gateway/config.yaml](https | `apis.http.authorization.http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` | | `apis.http.authorization.http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` | | `apis.http.authorization.http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` | +| `apis.http.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` | ### Event Bus diff --git a/content/en/docs/configuration/coap-gateway.md b/content/en/docs/configuration/coap-gateway.md index 91cf4e46..954d4010 100644 --- a/content/en/docs/configuration/coap-gateway.md +++ b/content/en/docs/configuration/coap-gateway.md @@ -79,6 +79,7 @@ OAuth2.0 Client is used to issuing an authorization code used by the Onboarding | `apis.coap.authorization.providers[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` | | `apis.coap.authorization.providers[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` | | `apis.coap.authorization.providers[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` | +| `apis.coap.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` | {{< tip >}} diff --git a/content/en/docs/configuration/device-provisioning-service.md b/content/en/docs/configuration/device-provisioning-service.md index f0b89f27..2a9075d3 100644 --- a/content/en/docs/configuration/device-provisioning-service.md +++ b/content/en/docs/configuration/device-provisioning-service.md @@ -14,12 +14,12 @@ The Device Provisioning Service provides API to provision device to the [plgd/hu Before you use the image you need to setup [K8s access to private registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry). ```bash -docker pull ghcr.io/plgd-dev/device-provisioning-service/device-provisioning-service:latest +docker pull ghcr.io/plgd-dev/hub/device-provisioning-service:latest ``` ## YAML Configuration -A configuration template is available on [config.yaml](https://github.com/plgd-dev/device-provisioning-service/blob/main/config.yaml). +A configuration template is available on [config.yaml](https://github.com/plgd-dev/hub/blob/main/device-provisioning-service/config.yaml). ### Logging @@ -38,7 +38,7 @@ CoAP API as specified in the [workflow](./workflow.puml). | Property | Type | Description | Default | | ---------- | -------- | -------------- | ------- | -| `apis.coap.address` | string | `Listen specification : for coap client connection.` | `"0.0.0.0:5688"` | +| `apis.coap.address` | string | `Listening specification : for coap client connection.` | `"0.0.0.0:15684"` | | `apis.coap.protocols` | []string | `Protocol for coap connection. The supported values are: "tcp", "udp" .` | `["tcp"]` | | `apis.coap.maxMessageSize` | int | `Max message size which can be sent/received via coap. i.e. 256*1024 = 262144 bytes.` | `262144` | | `apis.coap.messagePoolSize` | int | `Defines the maximum preallocated messages in the pool for parse/create coap messages.` | `1000` | @@ -50,27 +50,30 @@ CoAP API as specified in the [workflow](./workflow.puml). ### HTTP API -The plgd device provisioning service REST API is defined by [swagger](https://raw.githubusercontent.com/plgd-dev/device-provisioning-service/main/pb/service.swagger.json). +The plgd device provisioning service REST API is defined by [swagger](https://raw.githubusercontent.com/plgd-dev/hub/main/device-provisioning-service/pb/service.swagger.json). | Property | Type | Description | Default | | ---------- | -------- | -------------- | ------- | | `apis.http.enabled` | bool | `Enable HTTP API.` | `false` | -| `apis.http.address` | string | `Listen specification : for http client connection.` | `"0.0.0.0:9100"` | +| `apis.http.address` | string | `Listening specification : for http client connection.` | `"0.0.0.0:9100"` | | `apis.http.tls.caPool` | string | `File path to the root certificate in PEM format which might contain multiple certificates in a single file.` | `""` | | `apis.http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` | | `apis.http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` | | `apis.http.tls.clientCertificateRequired` | bool | `If true, require client certificate.` | `true` | | `apis.http.authorization.authority` | string | `Authority is the address of the token-issuing authentication server. Services will use this URI to find and retrieve the public key that can be used to validate the token’s signature.` | `""` | +| `apis.http.authorization.ownerClaim` | string | `Claim used to identify owner of the device.` | `"sub"` | | `apis.http.authorization.audience` | string | `Identifier of the API configured in your OAuth provider.` | `""` | -| `apis.http.authorization.http.maxIdleConns` | int | `It controls the maximum number of idle (keep-alive) connections across all hosts. Zero means no limit.` | `16` | -| `apis.http.authorization.http.maxConnsPerHost` | int | `It optionally limits the total number of connections per host, including connections in the dialing, active, and idle states. On limit violation, dials will block. Zero means no limit.` | `32` | -| `apis.http.authorization.http.maxIdleConnsPerHost` | int | `If non-zero, controls the maximum idle (keep-alive) connections to keep per-host. If zero, DefaultMaxIdleConnsPerHost is used.` | `16` | -| `apis.http.authorization.http.idleConnTimeout` | string | `The maximum amount of time an idle (keep-alive) connection will remain idle before closing itself. Zero means no limit.` | `30s` | -| `apis.http.authorization.http.timeout` | string | `A time limit for requests made by this Client. A Timeout of zero means no timeout.` | `10s` | -| `apis.http.authorization.http.tls.caPool` | string | `File path to the root certificate in PEM format which might contain multiple certificates in a single file.` | `""` | -| `apis.http.authorization.http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` | -| `apis.http.authorization.http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` | -| `apis.http.authorization.http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` | +| `apis.http.authorization.endpoints[].authority` | string | `Authority is the address of the token-issuing authentication server. Services will use this URI to find and retrieve the public key that can be used to validate the token’s signature.` | `""` | +| `apis.http.authorization.endpoints[].http.maxIdleConns` | int | `It controls the maximum number of idle (keep-alive) connections across all hosts. Zero means no limit.` | `16` | +| `apis.http.authorization.endpoints[].http.maxConnsPerHost` | int | `It optionally limits the total number of connections per host, including connections in the dialing, active, and idle states. On limit violation, dials will block. Zero means no limit.` | `32` | +| `apis.http.authorization.endpoints[].http.maxIdleConnsPerHost` | int | `If non-zero, controls the maximum idle (keep-alive) connections to keep per-host. If zero, DefaultMaxIdleConnsPerHost is used.` | `16` | +| `apis.http.authorization.endpoints[].http.idleConnTimeout` | string | `The maximum amount of time an idle (keep-alive) connection will remain idle before closing itself. Zero means no limit.` | `30s` | +| `apis.http.authorization.endpoints[].http.timeout` | string | `A time limit for requests made by this Client. A Timeout of zero means no timeout.` | `10s` | +| `apis.http.authorization.endpoints[].http.tls.caPool` | []string | `File paths to the root certificates in PEM format. The file may contain multiple certificates.` | `[]` | +| `apis.http.authorization.endpoints[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` | +| `apis.http.authorization.endpoints[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` | +| `apis.http.authorization.endpoints[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` | +| `apis.http.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` | | `apis.http.readTimeout` | string | `The maximum duration for reading the entire request, including the body by the server. A zero or negative value means there will be no timeout.` | `8s` | | `apis.http.readHeaderTimeout` | string | `The amount of time allowed to read request headers by the server. If readHeaderTimeout is zero, the value of readTimeout is used. If both are zero, there is no timeout.` | `4s` | | `apis.http.writeTimeout` | string | `The maximum duration before the server times out writing of the response. A zero or negative value means there will be no timeout.` | `16s` | @@ -172,17 +175,3 @@ OAuth2.0 Client is used to obtain JWT with ownerClaim an deviceIDClaim via the c You might have one client, but multiple APIs registered in the OAuth2.0 Server. What you might want to prevent is to be able to contact all the APIs of your system with one token. This audience allows you to request the token for a specific API. If you configure it to myplgdc2c.api in the Auth0, you have to set it here if you want to also validate it. {{< /tip >}} - -### Task Queue - -| Property | Type | Description | Default | -| ---------- | -------- | -------------- | ------- | -| `taskQueue.goPoolSize` | int | `Maximum number of running goroutine instances.` | `1600` | -| `taskQueue.size` | int | `Size of queue. If it exhausted, submit returns error.` | `2097152` | -| `taskQueue.maxIdleTime` | string | `Sets up the interval time of cleaning up goroutines. Zero means never cleanup.` | `10m` | - -{{< note >}} - -Note that the string type related to time (i.e. timeout, idleConnTimeout, expirationTime) is decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h". - -{{< /note >}} diff --git a/content/en/docs/configuration/grpc-gateway.md b/content/en/docs/configuration/grpc-gateway.md index 09bc7e47..eda1e24c 100644 --- a/content/en/docs/configuration/grpc-gateway.md +++ b/content/en/docs/configuration/grpc-gateway.md @@ -63,6 +63,7 @@ gRPC API of the gRPC Gateway service as defined [here](https://github.com/plgd-d | `apis.grpc.authorization.endpoints[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` | | `apis.grpc.authorization.endpoints[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` | | `apis.grpc.authorization.endpoints[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` | +| `apis.grpc.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` | ### Identity Store Client diff --git a/content/en/docs/configuration/http-gateway.md b/content/en/docs/configuration/http-gateway.md index 37dd7dda..18581b88 100644 --- a/content/en/docs/configuration/http-gateway.md +++ b/content/en/docs/configuration/http-gateway.md @@ -57,6 +57,7 @@ APIs of the HTTP Gateway service as defined [uri](https://github.com/plgd-dev/hu | `apis.http.authorization.http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` | | `apis.http.authorization.http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` | | `apis.http.authorization.http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` | +| `apis.http.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` | ### GRPC Gateway Client diff --git a/content/en/docs/configuration/identity-store.md b/content/en/docs/configuration/identity-store.md index bc47647c..728f21a1 100644 --- a/content/en/docs/configuration/identity-store.md +++ b/content/en/docs/configuration/identity-store.md @@ -61,6 +61,7 @@ gRPC API of the Identity Store service as defined [here](https://github.com/plgd | `apis.grpc.authorization.endpoints[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` | | `apis.grpc.authorization.endpoints[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` | | `apis.grpc.authorization.endpoints[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` | +| `apis.grpc.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` | ### Event Bus diff --git a/content/en/docs/configuration/resource-aggregate.md b/content/en/docs/configuration/resource-aggregate.md index 3e581abd..71ccc474 100644 --- a/content/en/docs/configuration/resource-aggregate.md +++ b/content/en/docs/configuration/resource-aggregate.md @@ -61,6 +61,7 @@ gRPC API of the Resource Aggregate service as defined [here](https://github.com/ | `apis.grpc.authorization.endpoints[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` | | `apis.grpc.authorization.endpoints[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` | | `apis.grpc.authorization.endpoints[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` | +| `apis.grpc.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` | ### Event Bus diff --git a/content/en/docs/configuration/resource-directory.md b/content/en/docs/configuration/resource-directory.md index 2ef51d2b..5484e44e 100644 --- a/content/en/docs/configuration/resource-directory.md +++ b/content/en/docs/configuration/resource-directory.md @@ -62,6 +62,7 @@ gRPC API of the Resource Directory service. | `apis.grpc.authorization.endpoints[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` | | `apis.grpc.authorization.endpoints[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` | | `apis.grpc.authorization.endpoints[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` | +| `apis.grpc.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` | ### Event Bus diff --git a/content/en/docs/configuration/snippet-service.md b/content/en/docs/configuration/snippet-service.md index ea7bd1a5..e6477761 100644 --- a/content/en/docs/configuration/snippet-service.md +++ b/content/en/docs/configuration/snippet-service.md @@ -61,6 +61,7 @@ gRPC API of the Snippet service as defined [here](https://github.com/plgd-dev/hu | `apis.grpc.authorization.endpoints[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` | | `apis.grpc.authorization.endpoints[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` | | `apis.grpc.authorization.endpoints[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` | +| `apis.grpc.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` | ### HTTP API From 7b335ad3361563057a266c6fcb065100695dd4cb Mon Sep 17 00:00:00 2001 From: Daniel Adam Date: Thu, 22 Aug 2024 12:20:23 +0200 Subject: [PATCH 2/4] fixup! Update device provisioning service documentation --- content/en/docs/deployment/deployment.md | 1 - .../device-provisioning-service.md | 27 +------------------ .../troubleshooting.md | 4 +-- .../verify-device-onboarding.md | 8 +++--- .../disaster-recovery-replica-set.md | 10 +++---- 5 files changed, 9 insertions(+), 41 deletions(-) diff --git a/content/en/docs/deployment/deployment.md b/content/en/docs/deployment/deployment.md index db6f18c1..db403c1d 100644 --- a/content/en/docs/deployment/deployment.md +++ b/content/en/docs/deployment/deployment.md @@ -37,7 +37,6 @@ plgd https://charts.plgd.dev // helm search repo plgd NAME CHART VERSION APP VERSION DESCRIPTION -plgd/plgd-dps 0.9.0 0.9.0 A Helm chart for plgd device provisioning service plgd/plgd-hub 2.7.15 2.7.15 A Helm chart for plgd-hub ``` diff --git a/content/en/docs/deployment/device-provisioning-service/device-provisioning-service.md b/content/en/docs/deployment/device-provisioning-service/device-provisioning-service.md index 1f775907..6c431793 100644 --- a/content/en/docs/deployment/device-provisioning-service/device-provisioning-service.md +++ b/content/en/docs/deployment/device-provisioning-service/device-provisioning-service.md @@ -21,7 +21,7 @@ The basic deployment uses Mock OAuth Server, so it shall be used only for test/d Before deploying the Device Provisioning Service on Kubernetes, make sure to follow the steps in [Hub](/docs/deployment/device-provisioning-service/hub) first. Then apply the changes from this page to the configuration. Once done, you can deploy the hub with the Device Provisioning Service. {{< /note >}} -For Device Provisioning Service, all configuration values are documented [here](https://github.com/plgd-dev/device-provisioning-service/blob/main/charts/device-provisioning-service/README.md#values). +For Device Provisioning Service, all configuration values are documented [here](https://github.com/plgd-dev/hub/blob/main/charts/plgd-hub/README.md#values). Look for values starting with `deviceProvisioningService`. ## Device provider for Device Provisioning Service @@ -61,29 +61,6 @@ mockoauthserver: For production, you need to set the OAuth server client credential flow, as is described in [Customize OAuth server client credential flow](/docs/deployment/device-provisioning-service/advanced). -{{< /warning >}} - -To allow download the Device Provisioning Service docker image by k8s, the following configuration needs to extend the configuration: - -```yaml -deviceProvisioningService: - image: - dockerConfigSecret: | - { - "auths": { - "ghcr.io": { - "auth": "" - } - } - } -``` - -{{< note >}} - -To access ghcr.io, please reach out to us at [connect@plgd.dev](mailto:connect@plgd.dev) in order to request permission for your GitHub account to access the plgd device provisioning server images. You can refer to the [documentation](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) for instructions on how to allow access. - -{{< /note >}} - ## Configure Enrollment Groups The enrollment groups can be configured via deployment, utilizing the setup from the hub configuration to populate the values. @@ -155,14 +132,12 @@ To deploy the hub with the Device Provisioning Service, apply the following comm ```sh helm upgrade -i -n plgd --create-namespace -f withMock.yaml hub plgd/plgd-hub -helm upgrade -i -n plgd --create-namespace -f withMock.yaml dps plgd/plgd-dps ``` You can execute these commands multiple times to update the configuration. In such cases, you will need to restart the pods by deleting them: ```sh kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "hub-plgd") -kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "dps-plgd") ``` ## Final configuration with mock oauth server diff --git a/content/en/docs/deployment/device-provisioning-service/troubleshooting.md b/content/en/docs/deployment/device-provisioning-service/troubleshooting.md index 74526249..ace8e02e 100644 --- a/content/en/docs/deployment/device-provisioning-service/troubleshooting.md +++ b/content/en/docs/deployment/device-provisioning-service/troubleshooting.md @@ -27,14 +27,12 @@ If you encounter issues with the Device Provisioning Service or Hub, follow thes ```sh helm upgrade -i -n plgd --create-namespace -f ./withUpdatedMock.yaml hub plgd/plgd-hub - helm upgrade -i -n plgd --create-namespace -f ./withUpdatedMock.yaml dps plgd/plgd-dps ``` 3. Restart the pods by deleting them: ```sh kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "hub-plgd") - kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "dps-plgd") ``` These steps will enable debug logging and restart the necessary components, providing more detailed information for troubleshooting the issues with the Device Provisioning Service or Hub. @@ -46,7 +44,7 @@ If your device is unable to connect to DPS, follow these steps: 1. Check the DPS logs by running the following command: ```sh - kubectl -n plgd logs $(kubectl -n plgd get pods -o name | grep "dps-plgd") + kubectl -n plgd logs $(kubectl -n plgd get pods -o name | grep "plgd-hub-device-provisioning-service") ``` 2. Check the device logs in the console. diff --git a/content/en/docs/deployment/device-provisioning-service/verify-device-onboarding.md b/content/en/docs/deployment/device-provisioning-service/verify-device-onboarding.md index 2350e8c8..51ffb8f3 100644 --- a/content/en/docs/deployment/device-provisioning-service/verify-device-onboarding.md +++ b/content/en/docs/deployment/device-provisioning-service/verify-device-onboarding.md @@ -75,8 +75,8 @@ These steps will enable you to generate the necessary certificates and configure ```sh cd "$HOME" cat ./withMock.yaml | yq -e ".deviceProvisioningService.enrollmentGroups[0].attestationMechanism.x509.certificateChain=\"$(cat ./plgd_certs/intermediate_ca.crt)\"" > ./withUpdatedMock.yaml - helm upgrade -i -n plgd --create-namespace -f withUpdatedMock.yaml dps plgd/plgd-dps - kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "dps-plgd") + helm upgrade -i -n plgd --create-namespace -f withUpdatedMock.yaml hub plgd/plgd-hub + kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "hub-plgd") ``` Now, you can test the Device Provisioning Service with the following methods depending on the network trust level: @@ -94,7 +94,7 @@ To set up a Zero Trust network, it is essential for the device to authenticate t 2. Run the example device with the device manufacturer certificate (IDevId): ```sh - docker run -it --rm -v $HOME/plgd_certs/device/pki_certs:/dps/bin/pki_certs ghcr.io/plgd-dev/device-provisioning-client/dps-cloud-server-debug:latest test-device "coaps+tcp://example.com:15684" + docker run -it --rm -v $HOME/plgd_certs/device/pki_certs:/dps/pki_certs ghcr.io/iotivity/iotivity-lite/dps-cloud-server-debug:latest test-device "coaps+tcp://example.com:15684" ``` {{< note >}} @@ -122,7 +122,7 @@ In Trusted network device can skip validation of the Device Provisioning Service 1. Run the example device with the device manufacturer certificate (IDevId): ```sh - docker run -it --rm -v $HOME/plgd_certs/device/pki_certs:/dps/bin/pki_certs ghcr.io/plgd-dev/device-provisioning-client/dps-cloud-server-debug:latest test-device "coaps+tcp://example.com:15684" --no-verify-ca + docker run -it --rm -v $HOME/plgd_certs/device/pki_certs:/dps/pki_certs ghcr.io/iotivity/iotivity-lite/dps-cloud-server-debug:latest test-device "coaps+tcp://example.com:15684" --no-verify-ca ``` {{< warning >}} diff --git a/content/en/docs/tutorials/disaster-recovery-replica-set.md b/content/en/docs/tutorials/disaster-recovery-replica-set.md index ac960448..41e7a2ad 100644 --- a/content/en/docs/tutorials/disaster-recovery-replica-set.md +++ b/content/en/docs/tutorials/disaster-recovery-replica-set.md @@ -291,7 +291,7 @@ Ensure that you have cert-manager installed on the standby cluster as well. The primary cluster will deploy the Hub with all APIs exposed on the `primary.plgd.cloud` domain. The CoAP gateway listens on NodePort `15684`, and the device provisioning service listens on NodePort `5684`. The MongoDB replica set is exposed via a LoadBalancer service type, requiring a client certificate (mTLS) to connect to MongoDB. -To deploy the plgd-hub and plgd-dps Helm charts on the primary cluster, use the following Helm command: +To deploy the plgd-hub Helm charts on the primary cluster, use the following Helm command: ```bash # Set variables @@ -387,6 +387,7 @@ resourcedirectory: publicConfiguration: coapGateway: "coaps+tcp://$DOMAIN:15684" deviceProvisioningService: + enabled: true apiDomain: "$DOMAIN" service: type: NodePort @@ -419,7 +420,6 @@ $(sed 's/^/ /' $MANUFACTURER_CERTIFICATE_CA) audience: "https://$DOMAIN" EOF helm upgrade -i -n plgd --create-namespace -f values.yaml hub plgd/plgd-hub -helm upgrade -i -n plgd --create-namespace -f values.yaml dps plgd/plgd-dps ``` Now we need to get the IP addresses of the MongoDB members and set them to the DNS. The external IP address of the LoadBalancer is used to connect to the MongoDB replica set from the other cluster. @@ -556,6 +556,7 @@ resourcedirectory: publicConfiguration: coapGateway: "coaps+tcp://$DOMAIN:15684" deviceProvisioningService: + enabled: true apiDomain: "$DOMAIN" service: type: NodePort @@ -588,7 +589,6 @@ $(sed 's/^/ /' $MANUFACTURER_CERTIFICATE_CA) audience: "https://$DOMAIN" EOF helm upgrade -i -n plgd --create-namespace -f values.yaml hub plgd/plgd-hub -helm upgrade -i -n plgd --create-namespace -f values.yaml dps plgd/plgd-dps ``` Next, we need to get the IP addresses of the MongoDB members and set them to the DNS server running on `192.168.1.1`, similar to the primary cluster. @@ -650,7 +650,6 @@ The final step is to run plgd pods on the standby cluster. Set the `global.stand ```bash helm upgrade -i -n plgd --create-namespace -f values.yaml --set mongodb.standbyTool.mode=active --set global.standby=false --set nats.enabled=true hub plgd/plgd-hub -helm upgrade -i -n plgd --create-namespace -f values.yaml --set mongodb.standbyTool.mode=active --set global.standby=false --set nats.enabled=true dps plgd/plgd-dps ``` After rotating the device provisioning endpoints, the devices will connect to the standby cluster. @@ -661,7 +660,6 @@ When the primary cluster is back up, set the `global.standby` flag to `true`, di ```bash helm upgrade -i -n plgd --create-namespace -f values.yaml --set global.standby=true --set nats.enabled=false hub plgd/plgd-hub -helm upgrade -i -n plgd --create-namespace -f values.yaml --set global.standby=true --set nats.enabled=false dps plgd/plgd-dps ``` ### How to Switch Back to the Primary Cluster @@ -687,7 +685,6 @@ The final step is to run plgd pods on the standby cluster. Set the `global.stand ```bash helm upgrade -i -n plgd --create-namespace -f values.yaml --set mongodb.standbyTool.mode=standby --set global.standby=true --set nats.enabled=false hub plgd/plgd-hub -helm upgrade -i -n plgd --create-namespace -f values.yaml --set mongodb.standbyTool.mode=standby --set global.standby=true --set nats.enabled=false dps plgd/plgd-dps ``` #### Turn On plgd Pods on the Primary Cluster @@ -696,7 +693,6 @@ When the standby cluster is ready for devices, switch back to the primary cluste ```bash helm upgrade -i -n plgd --create-namespace -f values.yaml --set global.standby=false --set nats.enabled=true hub plgd/plgd-hub -helm upgrade -i -n plgd --create-namespace -f values.yaml --set global.standby=false --set nats.enabled=true dps plgd/plgd-dps ``` After rotating the device provisioning endpoints, the devices will connect to the primary cluster. From e2ed731a006b6eb4d94f3342d2235502d601b242 Mon Sep 17 00:00:00 2001 From: Daniel Adam Date: Wed, 18 Sep 2024 14:46:59 +0200 Subject: [PATCH 3/4] fixup! Update device provisioning service documentation --- .../device-provisioning-service.md | 2 +- .../troubleshooting.md | 2 +- .../verify-device-onboarding.md | 2 +- .../client-library.md | 177 +++++++++--------- .../time-synchronization.md | 2 +- 5 files changed, 97 insertions(+), 88 deletions(-) diff --git a/content/en/docs/deployment/device-provisioning-service/device-provisioning-service.md b/content/en/docs/deployment/device-provisioning-service/device-provisioning-service.md index 6c431793..99aa3f84 100644 --- a/content/en/docs/deployment/device-provisioning-service/device-provisioning-service.md +++ b/content/en/docs/deployment/device-provisioning-service/device-provisioning-service.md @@ -137,7 +137,7 @@ helm upgrade -i -n plgd --create-namespace -f withMock.yaml hub plgd/plgd-hub You can execute these commands multiple times to update the configuration. In such cases, you will need to restart the pods by deleting them: ```sh -kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "hub-plgd") +kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "plgd-hub") ``` ## Final configuration with mock oauth server diff --git a/content/en/docs/deployment/device-provisioning-service/troubleshooting.md b/content/en/docs/deployment/device-provisioning-service/troubleshooting.md index ace8e02e..52a7d804 100644 --- a/content/en/docs/deployment/device-provisioning-service/troubleshooting.md +++ b/content/en/docs/deployment/device-provisioning-service/troubleshooting.md @@ -32,7 +32,7 @@ If you encounter issues with the Device Provisioning Service or Hub, follow thes 3. Restart the pods by deleting them: ```sh - kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "hub-plgd") + kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "plgd-hub") ``` These steps will enable debug logging and restart the necessary components, providing more detailed information for troubleshooting the issues with the Device Provisioning Service or Hub. diff --git a/content/en/docs/deployment/device-provisioning-service/verify-device-onboarding.md b/content/en/docs/deployment/device-provisioning-service/verify-device-onboarding.md index 51ffb8f3..50e21cbb 100644 --- a/content/en/docs/deployment/device-provisioning-service/verify-device-onboarding.md +++ b/content/en/docs/deployment/device-provisioning-service/verify-device-onboarding.md @@ -76,7 +76,7 @@ These steps will enable you to generate the necessary certificates and configure cd "$HOME" cat ./withMock.yaml | yq -e ".deviceProvisioningService.enrollmentGroups[0].attestationMechanism.x509.certificateChain=\"$(cat ./plgd_certs/intermediate_ca.crt)\"" > ./withUpdatedMock.yaml helm upgrade -i -n plgd --create-namespace -f withUpdatedMock.yaml hub plgd/plgd-hub - kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "hub-plgd") + kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "plgd-hub") ``` Now, you can test the Device Provisioning Service with the following methods depending on the network trust level: diff --git a/content/en/docs/services/device-provisioning-service/client-library.md b/content/en/docs/services/device-provisioning-service/client-library.md index 46cf347a..24f704f1 100644 --- a/content/en/docs/services/device-provisioning-service/client-library.md +++ b/content/en/docs/services/device-provisioning-service/client-library.md @@ -7,32 +7,20 @@ keywords: [provisioning] weight: 2 --- -## Get Package - -{{< note >}} -Are you interested in testing out the zero-touch provisioning? [Reach out](https://plgd.dev/contact/) to us! -{{< /note >}} - -The Device Provisioning Service is distributed as a `tar.gz` package, which contains the dps shared library, public C headers and an example application. - -{{< warning >}} -Please examine the contents of the provided pkg-config (`.pc`) file and install required dependencies. -{{< /warning >}} +The Device Provisioning Service is part of the [IoTivity-lite client-server library](https://github.com/iotivity/iotivity-lite/wiki/Device-Provisioning-Service). ## DPS Client API -The API is defined in the public header files provided in the distributed package. +The API is defined in the public header file. -- [dps.h](/docs/services/device-provisioning-service/static/dps-release/dps.h) -- [dps_export.h](/docs/services/device-provisioning-service/static/dps-release/dps_export.h) -- [dps_log.h](/docs/services/device-provisioning-service/static/dps-release/dps_log.h) +- [plgd_dps.h](https://github.com/iotivity/iotivity-lite/blob/master/include/plgd/plgd_dps.h) ### Initialize DPS A DPS client device is an extension of an [IoTivity](https://github.com/iotivity/iotivity-lite) device. Define your desired device and add DPS code to automatically provision the device. Start up the DPS initialization by calling the `plgd_dps_init` function, which allocates and initializes required data structures. -Use setters `plgd_dps_set_manager_callbacks`, `plgd_dps_set_skip_verify`, `plgd_dps_set_configuration_resource`, `plgd_dps_time_configure`, `plgd_dps_set_retry_configuration`, `plgd_dps_set_cloud_observer_configuration` and `plgd_dps_pki_set_expiring_limit` to configure the device. +Use setters `plgd_dps_set_manager_callbacks`, `plgd_dps_set_skip_verify`, `plgd_dps_set_configuration_resource`, `plgd_dps_set_retry_configuration`, `plgd_dps_set_cloud_observer_configuration` and `plgd_dps_pki_set_expiring_limit` to configure the device. ### Set DPS Endpoint @@ -78,7 +66,6 @@ typedef enum { PLGD_DPS_RENEW_CREDENTIALS = 1 << 9, PLGD_DPS_GET_OWNER = 1 << 10, PLGD_DPS_HAS_OWNER = 1 << 11, - PLGD_DPS_TRANSIENT_FAILURE = 1 << 14, PLGD_DPS_GET_TIME = 1 << 12, PLGD_DPS_HAS_TIME = 1 << 13, PLGD_DPS_TRANSIENT_FAILURE = 1 << 29, @@ -218,7 +205,8 @@ The application uses the following retry intervals [10s, 20s, 40s, 80s, 120s] an ### Time synchronization -In order for the TLS handshake to verify the server certificate and for certificate rotation to occur, the device must have the correct time. Time synchronization can be achieved by utilizing DPS clients to synchronize with the DPS server. To enable time synchronization, the function `plgd_dps_time_configure(true)` should be called. It's important to note that IoTivity-Lite needs to be compiled with the cmake option `-DPLGD_DEV_TIME_ENABLED=ON` in order to enable the [time synchronization feature](/docs/services/device-provisioning-service/time-synchronization) in the IoTivity-Lite library, and initialized with `plgd_time_init`. +In order for the TLS handshake to verify the server certificate and for certificate rotation to occur, the device must have the correct time. Time synchronization is achieved by utilizing DPS clients to synchronize with the DPS server over a connection that does not verify the validity interval of the certificates. +It's important to note that IoTivity-Lite needs to be compiled with the cmake option `-DPLGD_DEV_TIME_ENABLED=ON` in order to enable the [time synchronization feature](/docs/services/device-provisioning-service/time-synchronization) in the IoTivity-Lite library, and initialized with `plgd_time_configure`. {{< note >}} To compensate for the disabled time verification during the TLS handshake, time synchronization is established through a separate connection. Once synchronization is completed, the connection is terminated and the device's time is adjusted to bring it back into alignment. While this approach may not provide pinpoint accuracy, it is adequate for verifying the server certificate during the TLS handshake and for certificate rotation. For more precise time synchronization, utilizing NTP or another time synchronization protocol would be recommended. @@ -287,7 +275,7 @@ The algorithm can fail, and the possible failures are handled in the following w ## Example application - dps_cloud_server -Part of the package is an example application called `dps_cloud_server`. The following sections describe how DPS client library is integrated in the binary (with code examples). And the finally section shows how to run it. +An example application called `dps_cloud_server` is available among [Iotivity-lite's examples](https://github.com/iotivity/iotivity-lite/tree/master/apps). The following sections describe how DPS client library is integrated in the binary (with code examples). And the final section shows how to run it. ### Bootstrapping device with manufacturer certificates @@ -313,73 +301,74 @@ In code, the application uses [IoTivity's PKI functions to load the certificates static int dps_add_certificates(plgd_dps_context_t *dps_ctx, const char *cert_dir) { - oc_assert(dps_ctx != NULL); - oc_assert(cert_dir != NULL); + assert(dps_ctx != NULL); + assert(cert_dir != NULL); #define CERT_BUFFER_SIZE 4096 char path[PATH_MAX]; - int dpsca_credit = -1; + int dpsca_credid = -1; int mfg_credid = -1; - if (plgd_dps_get_skip_verify(dps_ctx)) { - DPS_DBG("adding of manufacturer trusted root ca skipped"); + if (plgd_dps_get_skip_verify(dps_ctx) || g_dhcp_enabled) { + DPSCS_DBG("adding of manufacturer trusted root ca skipped\n"); } else { unsigned char dps_ca[CERT_BUFFER_SIZE]; - size_t dps_ca_len = sizeof(dps_ca); - memset(path, 0, sizeof(path)); - strncpy(path, cert_dir, sizeof(path)); - strcat(path, "/dpsca.pem"); - if (dps_read_pem(path, (char *)dps_ca, &dps_ca_len) < 0) { - DPS_ERR("ERROR: unable to read %s", path); + size_t dps_ca_size = sizeof(dps_ca) / sizeof(unsigned char); + dps_concat_paths(path, sizeof(path), cert_dir, "/dpsca.pem"); + if (dps_read_pem(path, (char *)dps_ca, &dps_ca_size) < 0) { + printf("ERROR: unable to read %s\n", path); goto error; } - dpsca_credid = oc_pki_add_mfg_trust_anchor(plgd_dps_get_device(dps_ctx), dps_ca, dps_ca_size); + dpsca_credid = oc_pki_add_mfg_trust_anchor(plgd_dps_get_device(dps_ctx), + dps_ca, dps_ca_size); if (dpsca_credid < 0) { - DPS_ERR("ERROR: installing manufacturer trusted root ca"); + printf("ERROR: installing manufacturer trusted root ca\n"); goto error; } - DPS_DBG("manufacturer trusted root ca credid=%d", dpsca_credid); + DPSCS_DBG("manufacturer trusted root ca credid=%d\n", dpsca_credid); } unsigned char mfg_crt[CERT_BUFFER_SIZE]; - size_t mfg_crt_len = sizeof(mfg_crt); - memset(path, 0, sizeof(path)); - strncpy(path, cert_dir, sizeof(path)); - strcat(path, "/mfgcrt.pem"); - if (dps_read_pem(path, (char *)mfg_crt, &mfg_crt_len) < 0) { - DPS_ERR("ERROR: unable to read %s", path); + size_t mfg_crt_size = sizeof(mfg_crt) / sizeof(unsigned char); + dps_concat_paths(path, sizeof(path), cert_dir, "/mfgcrt.pem"); + if (dps_read_pem(path, (char *)mfg_crt, &mfg_crt_size) < 0) { + printf("ERROR: unable to read %s\n", path); goto error; } unsigned char mfg_key[CERT_BUFFER_SIZE]; - size_t mfg_key_len = sizeof(mfg_key); - memset(path, 0, sizeof(path)); - strncpy(path, cert_dir, sizeof(path)); - strcat(path, "/mfgkey.pem"); - if (dps_read_pem(path, (char *)mfg_key, &mfg_key_len) < 0) { - DPS_ERR("ERROR: unable to read %s", path); + size_t mfg_key_size = sizeof(mfg_key) / sizeof(unsigned char); + dps_concat_paths(path, sizeof(path), cert_dir, "/mfgkey.pem"); + if (dps_read_pem(path, (char *)mfg_key, &mfg_key_size) < 0) { + printf("ERROR: unable to read %s\n", path); goto error; } - mfg_credid = oc_pki_add_mfg_cert(plgd_dps_get_device(dps_ctx), mfg_crt, mfg_crt_len, mfg_key, mfg_key_len); + mfg_credid = oc_pki_add_mfg_cert(plgd_dps_get_device(dps_ctx), mfg_crt, + mfg_crt_size, mfg_key, mfg_key_size); if (mfg_credid < 0) { - DPS_ERR("ERROR: installing manufacturer certificate"); + printf("ERROR: installing manufacturer certificate\n"); goto error; } - DPS_DBG("manufacturer certificate credid=%d", mfg_credid); - oc_pki_set_security_profile(plgd_dps_get_device(dps_ctx), OC_SP_BLACK, OC_SP_BLACK, mfg_credid); + DPSCS_DBG("manufacturer certificate credid=%d\n", mfg_credid); + oc_pki_set_security_profile(plgd_dps_get_device(dps_ctx), OC_SP_BLACK, + OC_SP_BLACK, mfg_credid); return 0; error: - if (dpsca_credit != -1) { - if (oc_sec_remove_cred_by_credid(dpsca_credit, plgd_dps_get_device(dps_ctx))) { - DPS_DBG("certificate(%d) removed", dpsca_credit); + if (dpsca_credid != -1) { + if (oc_sec_remove_cred_by_credid(dpsca_credid, + plgd_dps_get_device(dps_ctx))) { + DPSCS_DBG("certificate(%d) removed\n", dpsca_credid); } else { - DPS_WRN("failed to remove trusted root certificate(%d)", dpsca_credit); + printf("WARNING: failed to remove manufacturer trusted root ca(%d)\n", + dpsca_credid); } } if (mfg_credid != -1) { - if (oc_sec_remove_cred_by_credid(mfg_credid, plgd_dps_get_device(dps_ctx))) { - DPS_DBG("certificate(%d) removed", mfg_credid); + if (oc_sec_remove_cred_by_credid(mfg_credid, + plgd_dps_get_device(dps_ctx))) { + DPSCS_DBG("certificate(%d) removed\n", mfg_credid); } else { - DPS_WRN("failed to remove manufacturer certificate(%d)", mfg_credid); + printf("WARNING: failed to remove manufacturer certificate(%d)\n", + mfg_credid); } } return -1; @@ -405,7 +394,7 @@ manufacturer_setup(plgd_dps_context_t *dps_ctx) oc_device_info_t *dev = oc_core_get_device_info(plgd_dps_get_device(dps_ctx)); if (dev != NULL) { oc_free_string(&dev->name); - oc_new_string(&dev->name, dps_device_name, strlen(dps_device_name)); + oc_new_string(&dev->name, g_dps_device_name, strlen(g_dps_device_name)); } plgd_dps_manager_callbacks_t callbacks = { .on_status_change = dps_status_handler, @@ -418,16 +407,21 @@ manufacturer_setup(plgd_dps_context_t *dps_ctx) plgd_dps_pki_set_expiring_limit(dps_ctx, (uint16_t)g_expiration_limit); } if (g_observer_max_retry != -1) { - plgd_dps_set_cloud_observer_configuration(dps_ctx, (uint8_t)g_observer_max_retry, 1); + plgd_dps_set_cloud_observer_configuration(dps_ctx, + (uint8_t)g_observer_max_retry, 1); } plgd_dps_set_skip_verify(dps_ctx, g_skip_ca_verification != 0); - size_t dps_endpoint_len = strlen(g_dps_endpoint); - if (dps_endpoint_len > 0 && !plgd_dps_add_endpoint_address(dps_ctx, g_dps_endpoint, dps_endpoint_len, /*name*/NULL, /*name_len*/0)) { - printf("ERROR: failed to add endpoint address\n"); - return -1; + for (int i = 0; i < g_dps_endpoint_count; i++) { + size_t dps_endpoint_len = strlen(g_dps_endpoint[i]); + if (dps_endpoint_len > 0 && + !plgd_dps_add_endpoint_address(dps_ctx, g_dps_endpoint[i], + dps_endpoint_len, NULL, 0)) { + printf("ERROR: failed to add endpoint address\n"); + return -1; + } } - if (dps_add_certificates(dps_ctx, dps_cert_dir) != 0) { - DPS_ERR("failed to add initial certificates on factory reset"); + if (dps_add_certificates(dps_ctx, g_dps_cert_dir) != 0) { + printf("ERROR: failed to add initial certificates on factory reset\n"); return -1; } plgd_dps_force_reprovision(dps_ctx); @@ -452,20 +446,20 @@ factory_presets_cb(size_t device_id, void *data) (void)data; plgd_dps_context_t *dps_ctx = plgd_dps_get_context(device_id); if (dps_ctx == NULL) { - DPS_DBG("skip factory reset handling: empty context"); + DPSCS_DBG("skip factory reset handling: empty context\n"); return; } if (plgd_dps_on_factory_reset(dps_ctx) != 0) { - DPS_ERR("cannot handle factory reset"); + printf("ERROR: cannot handle factory reset\n"); return; } if (manufacturer_setup(dps_ctx) != 0) { - DPS_ERR("failed to configure device"); + printf("ERROR: failed to configure device\n"); return; } if (plgd_dps_manager_start(dps_ctx) != 0) { - DPS_ERR("failed to start dps manager"); + printf("ERROR: failed to start dps manager\n"); return; } } @@ -485,17 +479,21 @@ Now we have all the parts necessary to do the full initialization of the DPS cli plgd_dps_context_t *dps_ctx = plgd_dps_get_context(g_device_id); if (dps_ctx == NULL) { - DPS_ERR("cannot start dps manager: empty context"); - ret = -1; - goto finish; + printf("ERROR: cannot start dps manager: empty context\n"); + ... // cleanup + return -1; } if (parsed_options.retry_configuration_size > 0 && - !plgd_dps_set_retry_configuration(dps_ctx, parsed_options.retry_configuration, - parsed_options.retry_configuration_size)) { - DPS_ERR("cannot start dps manager: invalid retry configuration"); - ret = -1; - goto finish; + !plgd_dps_set_retry_configuration( + dps_ctx, parsed_options.retry_configuration, + parsed_options.retry_configuration_size)) { + printf("ERROR: cannot start dps manager: invalid retry configuration\n"); + ... // cleanup + return -1; } + + ... + if (!plgd_dps_manager_is_started(dps_ctx)) { if (g_expiration_limit != -1) { plgd_dps_pki_set_expiring_limit(dps_ctx, (uint16_t)g_expiration_limit); @@ -504,16 +502,22 @@ Now we have all the parts necessary to do the full initialization of the DPS cli plgd_dps_set_cloud_observer_configuration(dps_ctx, (uint8_t)g_observer_max_retry, 1); } plgd_dps_set_skip_verify(dps_ctx, g_skip_ca_verification != 0); - plgd_dps_set_manager_callbacks(dps_ctx, dps_status_handler, /* on_change_data */ NULL, cloud_status_handler, - /* on_cloud_change_data */ NULL); + plgd_dps_manager_callbacks_t callbacks = { + .on_status_change = dps_status_handler, + .on_status_change_data = NULL, + .on_cloud_status_change = cloud_status_handler, + .on_cloud_status_change_data = NULL, + }; + plgd_dps_set_manager_callbacks(dps_ctx, callbacks); if (plgd_dps_manager_start(dps_ctx) != 0) { - DPS_ERR("failed to start dps manager"); - ret = -1; - goto finish; + printf("ERROR: failed to start dps manager\n"); + ... // cleanup + return -1; } } + + ... run(); // start run loop -finish: ... ``` @@ -530,9 +534,14 @@ OPTIONS: -h | --help print help -c | --create-conf-resource create DPS configuration resource -e | --expiration-limit set certificate expiration limit (in seconds) - -h | --no-verify-ca skip loading of the DPS certificate authority - -r | --retry-configuration retry timeout configuration (array of non-zero values delimited by ',', maximum of 8 values is accepted; example: 1,2,4,8,16) + -l | --log-level set runtime log-level of the DPS library (supported values: disabled, trace, debug, info, notice, warning, error) + | --oc-log-level set runtime log-level of the IoTivity library (supported values: disabled, trace, debug, info, notice, warning, error) + -n | --no-verify-ca skip loading of the DPS certificate authority + -f | --dhcp-leases-file path to the dhcp leases file (default: /var/lib/dhcp/dhclient.leases) + -x | --dhcp-enabled pull dhcp leases file every 5sec -o | --cloud-observer-max-retry maximal number of retries by cloud observer before forcing reprovisioning + -r | --retry-configuration retry timeout configuration (array of non-zero values delimited by ',', maximum of 8 values is accepted; example: 1,2,4,8,16) + -s | --set-system-time use plgd time to set system time (root required) -w | --wait-for-reset don\'t start right away, but wait for SIGHUP signal diff --git a/content/en/docs/services/device-provisioning-service/time-synchronization.md b/content/en/docs/services/device-provisioning-service/time-synchronization.md index c5e4da65..bfedabd1 100644 --- a/content/en/docs/services/device-provisioning-service/time-synchronization.md +++ b/content/en/docs/services/device-provisioning-service/time-synchronization.md @@ -49,7 +49,7 @@ current time = lastSyncTime + elapsed time ### C-API -When initializing the time feature via the `plgd_time_init` function in the C-API, there are several parameters that can be set. These include specifying whether to use the time in MbedTLS time callback for TLS certificate verification and specifying a callback function to set the device clock. For more information about these parameters and other functions in the C-API such as set/get time, please refer to the [doxygen documentation](http://iotivity.org/iotivity-lite-doxygen/group__time__synchronization.html). +When initializing the time feature via the `plgd_time_configure` function in the C-API, there are several parameters that can be set. These include specifying whether to use the time in MbedTLS time callback for TLS certificate verification and specifying a callback function to set the device clock. For more information about these parameters and other functions in the C-API such as set/get time, please refer to the [doxygen documentation](http://iotivity.org/iotivity-lite-doxygen/group__time__synchronization.html). {{< note >}} For an example of how to implement this feature, please refer to the [cloud_server.c](https://github.com/iotivity/iotivity-lite/blob/cf33fe739a640c301735ca60d5ac390194a430fb/apps/cloud_server.c#L915) file in the iotivity-lite repository. From 1e92d7df00c1d1781e6f0aad6670085a36d9f68a Mon Sep 17 00:00:00 2001 From: Daniel Adam Date: Wed, 25 Sep 2024 11:01:19 +0200 Subject: [PATCH 4/4] fixup! Update device provisioning service documentation --- .../static/dps-release/VERSION | 1 - .../static/dps-release/dps.h | 724 ------------------ .../static/dps-release/dps_compiler.h | 55 -- .../static/dps-release/dps_log.h | 99 --- .../sztp-via-dhcp.md | 2 +- 5 files changed, 1 insertion(+), 880 deletions(-) delete mode 100644 content/en/docs/services/device-provisioning-service/static/dps-release/VERSION delete mode 100644 content/en/docs/services/device-provisioning-service/static/dps-release/dps.h delete mode 100644 content/en/docs/services/device-provisioning-service/static/dps-release/dps_compiler.h delete mode 100644 content/en/docs/services/device-provisioning-service/static/dps-release/dps_log.h diff --git a/content/en/docs/services/device-provisioning-service/static/dps-release/VERSION b/content/en/docs/services/device-provisioning-service/static/dps-release/VERSION deleted file mode 100644 index 570c7965..00000000 --- a/content/en/docs/services/device-provisioning-service/static/dps-release/VERSION +++ /dev/null @@ -1 +0,0 @@ -v1.0.2 diff --git a/content/en/docs/services/device-provisioning-service/static/dps-release/dps.h b/content/en/docs/services/device-provisioning-service/static/dps-release/dps.h deleted file mode 100644 index d511422c..00000000 --- a/content/en/docs/services/device-provisioning-service/static/dps-release/dps.h +++ /dev/null @@ -1,724 +0,0 @@ -/** - * @file dps.h - * - * Device provisioning service API functions. - * - * - * Copyright (C) 2022 plgd.dev, s.r.o. - All Rights Reserved - * - * Unauthorized distribution of this library is strictly prohibited - * - * Proprietary and confidential - */ - -#ifndef PLGD_DPS_H -#define PLGD_DPS_H - -#include "oc_config.h" - -#ifndef OC_SECURITY -#error "OC_SECURITY must be defined" -#endif - -#ifndef OC_PKI -#error "OC_PKI must be defined" -#endif - -#ifndef OC_CLOUD -#error "OC_CLOUD must be defined" -#endif - -#ifndef OC_IPV4 -#error "OC_IPV4 must be defined" -#endif - -#ifndef OC_STORAGE -#error "OC_STORAGE must be defined" -#endif - -#include "plgd/dps_compiler.h" - -#include -#include -#include -#include -#include -#include -#include -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -typedef struct plgd_dps_context_t plgd_dps_context_t; - -/** - * @brief DPS provisioning status flags. - */ -typedef enum { - /* UNINITIALIZED = 0 */ - PLGD_DPS_INITIALIZED = 1 << 0, - PLGD_DPS_GET_CREDENTIALS = 1 << 1, - PLGD_DPS_HAS_CREDENTIALS = 1 << 2, - PLGD_DPS_GET_ACLS = 1 << 3, - PLGD_DPS_HAS_ACLS = 1 << 4, - PLGD_DPS_GET_CLOUD = 1 << 6, - PLGD_DPS_HAS_CLOUD = 1 << 7, - PLGD_DPS_CLOUD_STARTED = 1 << 8, - PLGD_DPS_RENEW_CREDENTIALS = 1 << 9, - PLGD_DPS_GET_OWNER = 1 << 10, - PLGD_DPS_HAS_OWNER = 1 << 11, - PLGD_DPS_GET_TIME = 1 << 12, - PLGD_DPS_HAS_TIME = 1 << 13, - PLGD_DPS_TRANSIENT_FAILURE = 1 << 29, - PLGD_DPS_FAILURE = 1 << 30, -} plgd_dps_status_t; - -/** - * @brief DPS errors. - */ -typedef enum { - PLGD_DPS_OK = 0, - PLGD_DPS_ERROR_RESPONSE = 1, - PLGD_DPS_ERROR_CONNECT = 2, - PLGD_DPS_ERROR_GET_CREDENTIALS = 3, - PLGD_DPS_ERROR_GET_ACLS = 4, - PLGD_DPS_ERROR_SET_CLOUD = 5, - PLGD_DPS_ERROR_START_CLOUD = 6, - PLGD_DPS_ERROR_GET_OWNER = 7, - PLGD_DPS_ERROR_GET_TIME = 8, -} plgd_dps_error_t; - -/** - @brief A function pointer for handling the dps status. - @param ctx dps context - @param status Current status of the dps. - @param data user data provided to the callback -*/ -typedef void (*plgd_dps_on_status_change_cb_t)(plgd_dps_context_t *ctx, plgd_dps_status_t status, void *data); - -/** - * @brief Allocate and initialize data. - * - * @return int 0 on success - * <0 on failure - */ -DPS_EXPORT -int plgd_dps_init(void); - -/** - * @brief Stop all devices and deallocate data. - */ -DPS_EXPORT -void plgd_dps_shutdown(void); - -/// Get context for given device -DPS_EXPORT -plgd_dps_context_t *plgd_dps_get_context(size_t device); - -/** - * @brief Get device from context. - * - * @param ctx dps context (cannot be NULL) - * - * @return size_t index of device - */ -DPS_EXPORT -size_t plgd_dps_get_device(const plgd_dps_context_t *ctx) OC_NONNULL(); - -typedef struct -{ - plgd_dps_on_status_change_cb_t on_status_change; ///< callback executed on DPS status change - void *on_status_change_data; ///< user data provided to DPS status change callback - oc_cloud_cb_t on_cloud_status_change; ///< callback executed when cloud status change - void *on_cloud_status_change_data; ///< user data provided to cloud status change callback -} plgd_dps_manager_callbacks_t; - -/** - * @brief Set DPS manager callbacks. - * - * @param ctx dps context (cannot be NULL) - * @param callbacks callbacks with data - * - * Example of plgd_dps_on_status_change_cb_t function: - * @code{.c} - * static void - * on_change_cb(plgd_dps_context_t *ctx, plgd_dps_status_t status, void *on_change_data) { - * printf("DPS Manager Status:\n"); - * if (status & PLGD_DPS_INITIALIZED) { - * printf("\t-Initialized\n"); - * } - * ... - * } - * @endcode - * - * Example of oc_cloud_cb_t function: - * @code{.c} - * static void - * on_cloud_change_cb(oc_cloud_context_t *ctx, oc_cloud_status_t status, void *on_cloud_change_data) { - * printf("Cloud Manager Status:\n"); - * if (status & OC_CLOUD_REGISTERED) { - * printf("\t-Registered\n"); - * } - * ... - * } - * @endcode - */ -DPS_EXPORT -void plgd_dps_set_manager_callbacks(plgd_dps_context_t *ctx, plgd_dps_manager_callbacks_t callbacks) OC_NONNULL(1); - -/** - * @brief Start DPS manager to provision device. - * - * Setup context, global session handlers and start DPS manager. - * - * Starting DPS also starts the retry mechanism, which will remain active until the device is successfully provisioned. - * If a provisioning step fails, it will be tried again after a time interval. The time interval depends on the retry - * counter (which is incremented on each retry) and uses the following values [ 10, 20, 40, 80, 120 ] in seconds. - * Meaning that the first retry is scheduled after 10 seconds after a failure, the second retry after 20 seconds, etc. - * After the interval reaches the maximal value (120 seconds) it resets back to the first value (10 seconds). - * - * @note Before starting the DPS manager, an endpoint must be added by plgd_dps_add_endpoint_address (if you add - * multiple endpoints then use plgd_dps_select_endpoint_address to select the endpoint that will be used to provision). - * Without an endpoint selected the provisioning will not start. - * - * @note The function examines the state of storage and some provisioning steps might be skipped if the stored data is - * evaluated as still valid. To force full reprovisioning call plgd_force_reprovision before this function. At the end - * of this call forced reprovisioning is disabled. - * @see plgd_force_reprovision - * - * @param ctx dps context (cannot be NULL) - * @return 0 on success - * @return -1 on failure - */ -DPS_EXPORT -int plgd_dps_manager_start(plgd_dps_context_t *ctx) OC_NONNULL(); - -/** - * @brief Check whether DPS manager has been started. - * - * @param ctx dps context (cannot be NULL) - * @return true DPS manager has been started - * @return false DPS manager has not been started - * - * @see plgd_dps_manager_start - */ -DPS_EXPORT -bool plgd_dps_manager_is_started(const plgd_dps_context_t *ctx) OC_NONNULL(); - -/** - * @brief Stop DPS manager. - * - * Deregister handlers, clear context, stop DPS manager, close connection to DPS endpoint and remove identity - * certificates retrieved from DPS endpoint. - * - * @param ctx dps context (cannot be NULL) - */ -DPS_EXPORT -void plgd_dps_manager_stop(plgd_dps_context_t *ctx) OC_NONNULL(); - -/** - * @brief Restart DPS manager to provision device by given server. - * - * A convenience function equivalent to calling plgd_dps_manager_stop and plgd_dps_manager_start. - * - * @param ctx dps context (cannot be NULL) - * @return 0 on success - * @return -1 on failure - * - * @see plgd_dps_manager_start - * @see plgd_dps_manager_stop - */ -DPS_EXPORT -int plgd_dps_manager_restart(plgd_dps_context_t *ctx) OC_NONNULL(); - -/** - * @brief Start cloud manager with previously set server and callbacks. - * - * @param ctx dps context (cannot be NULL) - * @return true on success - * @return false otherwise - */ -DPS_EXPORT -bool plgd_cloud_manager_start(const plgd_dps_context_t *ctx) OC_NONNULL(); - -/** - * @brief Clean-up of DPS provisioning on factory reset. - * - * The function must be called from the factory reset handler to clean-up data that has been invalidated by a factory - * reset. - * The clean-up includes: - * - stopping of DPS provisioning and resetting the provisioning status - * - disconnecting from DPS endpoint and resetting the endpoint address - * - resetting data in storage and committing the empty data to storage files - * - removing identifiers of identity certificates that have been deleted by factory reset - * - * @param ctx dps context (cannot be NULL) - * @return 0 on success - * @return -1 on failure - */ -DPS_EXPORT -int plgd_dps_on_factory_reset(plgd_dps_context_t *ctx) OC_NONNULL(); - -/** - * @brief Controls whether a dps client verifies the device provision service's certificate chain against trust anchor - * in the device. To set skip verify, it must be called before plgd_dps_manager_start. - * - * @param ctx dps context (cannot be NULL) - * @param skip_verify skip verification of the DPS service - */ -DPS_EXPORT -void plgd_dps_set_skip_verify(plgd_dps_context_t *ctx, bool skip_verify) OC_NONNULL(); - -/** - * @brief Get `skip verify` value from context. - * - * @param ctx dps context (cannot be NULL) - * @return true `skip verify` is enabled - * @return false `skip verify` is disabled - * - * @see plgd_dps_set_skip_verify - */ -DPS_EXPORT -bool plgd_dps_get_skip_verify(const plgd_dps_context_t *ctx) OC_NONNULL(); - -/** - * @brief Force all steps of the provisioning process to be executed. - * - * A step that was successfully executed stores data in the storage and on the next start this data is still valid the - * step would be automatically skipped. - * - * @param ctx dps context (cannot be NULL) - * - * @see plgd_dps_manager_start - */ -DPS_EXPORT -void plgd_dps_force_reprovision(plgd_dps_context_t *ctx) OC_NONNULL(); - -/** - * @brief Check if force reprovision flag is set. - * - * @param ctx dps context (cannot be NULL) - * @return true force reprovision is set - * @return false force reprovision is not set - */ -DPS_EXPORT -bool plgd_dps_has_forced_reprovision(const plgd_dps_context_t *ctx) OC_NONNULL(); - -/** - * @brief Configuration resource - * - * Description: - * - Resource type: x.plgd.dps.conf - * - Resource structure in json format: - * { - * endpoint: string; - * lastErrorCode: int; - * provisionStatus: string; - * forceReprovision: bool; - * } - */ -#define PLGD_DPS_URI "/plgd/dps" - -/** - * @brief Controls whether a dps client creates configuration resource for managing dps client via COAPs API. - * - * @param ctx dps context (cannot be NULL) - * @param create set true for creating resource. set false to free memory of created resource. - */ -DPS_EXPORT -void plgd_dps_set_configuration_resource(plgd_dps_context_t *ctx, bool create) OC_NONNULL(); - -/** - * @brief Maximal size of the retry configuration array - */ -enum { PLGD_DPS_MAX_RETRY_VALUES_SIZE = 8 }; - -/** - * @brief Configure retry counter. - * - * @param ctx dps context (cannot be NULL) - * @param cfg array with new timeout values (must have [1, PLGD_DPS_MAX_RETRY_VALUES_SIZE> number of non-zero values) - * @param cfg_size size of the array with timeout values - * @return true on success - * @return false on failure - */ -DPS_EXPORT -bool plgd_dps_set_retry_configuration(plgd_dps_context_t *ctx, const uint8_t cfg[], size_t cfg_size) OC_NONNULL(1); - -/** - * @brief Callback invoked by the dps manager when the dps wants to schedule - * an action. - * - * @param ctx dps context - * @param action One of PLGD_DPS_GET actions or PLGD_DPS_RENEW_CREDENTIALS to schedule, or 0 for - * reinitialization. - * @param retry_count Retries count - 0 means the first attempt to perform the - * action. - * @param delay Delay the action in milliseconds before executing it. - * @param timeout Timeout in seconds for the action. - * @param user_data User data passed from the caller. - * - * @return true if the dps manager should continue to schedule the action, - * false if the dps manager should restarts from the beginning. - */ -typedef bool (*plgd_dps_schedule_action_cb_t)(plgd_dps_context_t *ctx, plgd_dps_status_t action, uint8_t retry_count, - uint64_t *delay, uint16_t *timeout, void *user_data) OC_NONNULL(1, 4, 5); - -/** - * @brief Set a custom scheduler for actions in the cloud manager. By default, - * the cloud manager uses its own scheduler. - * - * This function allows you to set a custom scheduler to define delay and - * timeout for actions. - * - * @param ctx Cloud context to update. Must not be NULL. - * @param on_schedule_action Callback invoked by the cloud manager when the - * cloud wants to schedule an action. - * @param user_data User data passed from the caller to be provided during the - * callback. - * - * @note The provided cloud context (`ctx`) must not be NULL. - * @see oc_cloud_schedule_action_cb_t - */ -DPS_EXPORT -void plgd_dps_set_schedule_action(plgd_dps_context_t *ctx, plgd_dps_schedule_action_cb_t on_schedule_action, - void *user_data) OC_NONNULL(1); - -/** - * @brief Get retry counter configuration. - * - * @param ctx dps context (cannot be NULL) - * @param[out] buffer output buffer into which the configuration will be copied (cannot be NULL, and must be large - * enough to contain the current configuration) - * @param buffer_size size of the output buffer - * @return >0 the size of the configuration array copied to buffer - * @return <0 on failure - */ -DPS_EXPORT -int plgs_dps_get_retry_configuration(const plgd_dps_context_t *ctx, uint8_t *buffer, size_t buffer_size) OC_NONNULL(); - -/** - * @brief Get last provisioning error. - * - * @param ctx dps context (cannot be NULL) - * @return plgd_dps_error_t last provisioning error - */ -DPS_EXPORT -plgd_dps_error_t plgd_dps_get_last_error(const plgd_dps_context_t *ctx) OC_NONNULL(); - -/** - * @brief Get provision status. - * - * @param ctx dps context (cannot be NULL) - * @return uint16_t current provision status - */ -DPS_EXPORT -uint32_t plgd_dps_get_provision_status(const plgd_dps_context_t *ctx) OC_NONNULL(); - -/** - * @brief Check whether the device has been provisioned at least once since the last DPS reset initiated by a factory - * reset or by setting the endpoint to an empty value in the DPS resource. - * - * @param ctx dps context (cannot be NULL) - * @return true if DPS has been successfully provisioned at least once since the DPS context reset. - * @return false for otherwise - */ -DPS_EXPORT -bool plgd_dps_has_been_provisioned_since_reset(const plgd_dps_context_t *ctx) OC_NONNULL(); - -typedef struct -{ - uint8_t max_count; ///< the maximal number of retries with the same endpoint before retrying is stopped; if a - ///< previously untried endpoint is available then it is selected and the retrying is restarted - ///< with it; if no previously untried endpoint is available then a full reprovisioning of the - ///< client is triggered (default: 30) - uint8_t interval_s; ///< retry interval in seconds (default: 1) -} plgd_cloud_status_observer_configuration_t; - -/** - * @brief Configure cloud observer. - * - * @param ctx dps context (cannot be NULL) - * @param max_retry_count maximal number of retries, set to 0 to disable cloud status observer - * @param retry_interval_s retry interval in seconds (must be >0) - * @return true on success - * @return false on error caused by invalid parameters - */ -DPS_EXPORT -bool plgd_dps_set_cloud_observer_configuration(plgd_dps_context_t *ctx, uint8_t max_retry_count, - uint8_t retry_interval_s) OC_NONNULL(); - -/** - * @brief Get cloud observer configuration - * - * @param ctx dps context (cannot be NULL) - * @return plgd_cloud_status_observer_configuration_t current cloud observer configuration - */ -DPS_EXPORT -plgd_cloud_status_observer_configuration_t plgd_dps_get_cloud_observer_configuration(const plgd_dps_context_t *ctx) - OC_NONNULL(); - -/** - * @brief Set expiring-in limit of DPS certificates. - * - * If a certificate's valid-to timestamp is within the expiring-in limit (current time < valid_to and current time + - * expiring-in limit > valid_to) then the certificate is considered as expiring. - * Expiring certificates are not accepted during the get credentials step of DPS provisioning. If a expiring - * certificates is received then the step is retried to receive a newer certificate with longer expiration. - * - * @param ctx dps context (cannot be NULL) - * @param expiring_limit limit value in seconds - */ -DPS_EXPORT -void plgd_dps_pki_set_expiring_limit(plgd_dps_context_t *ctx, uint16_t expiring_limit) OC_NONNULL(); - -/** - * @brief Get expiring-in limit of DPS certificates - * - * @param ctx dps context (cannot be NULL) - * @return expiring-in limit in seconds - */ -DPS_EXPORT -uint16_t plgd_dps_pki_get_expiring_limit(const plgd_dps_context_t *ctx) OC_NONNULL(); - -/** - * @brief Set certificate fingerprint of the provisioning server. - * - * If the fingerprint is set then the DPS client - * will verify the fingerprint of the provisioning server certificate during the TLS handshake. If any certificate - * matching the fingerprint in the chain is found then the handshake is successful. - * - * @param ctx dps context (cannot be NULL) - * @param md_type hash algorithm used for fingerprint - * @param fingerprint fingerprint of the provisioning server certificate - * @param size size of the fingerprint - * @return true on success - */ -DPS_EXPORT -bool plgd_dps_set_certificate_fingerprint(plgd_dps_context_t *ctx, mbedtls_md_type_t md_type, - const uint8_t *fingerprint, size_t size) OC_NONNULL(1); - -/** - * @brief Copy certificate fingerprint of the DPS service to output buffer. - * - * @param ctx dps context (cannot be NULL) - * @param[out] md_type hash algorithm used for fingerprint - * @param[out] buffer output buffer (cannot be NULL and must be large enough to contain the endpoint in a string format) - * @param buffer_size size of output buffer - * @return >0 on success, number of copied bytes to buffer - * @return 0 endpoint is not set, thus nothing was copied - * @return <0 on error - */ -DPS_EXPORT -int plgd_dps_get_certificate_fingerprint(const plgd_dps_context_t *ctx, mbedtls_md_type_t *md_type, uint8_t *buffer, - size_t buffer_size) OC_NONNULL(); - -/** - * @brief Set the vendor encapsulated option code for the DPS endpoint. Used during call - * plgd_dps_set_dhcp_vendor_encapsulated_option_code_dps_certificate_fingerprint. - * - * @param ctx dps context (cannot be NULL) - * @param code vendor encapsulated option code for the DPS endpoint - */ -DPS_EXPORT -void plgd_dps_dhcp_set_vendor_encapsulated_option_code_dps_endpoint(plgd_dps_context_t *ctx, uint8_t code) OC_NONNULL(); - -/** - * @brief Get the vendor encapsulated option code for the DPS endpoint. Used during call - * plgd_dps_set_dhcp_vendor_encapsulated_option_code_dps_certificate_fingerprint. - * - * @param ctx dps context (cannot be NULL) - * @return uint8_t vendor encapsulated option code for the DPS endpoint - */ -DPS_EXPORT -uint8_t plgd_dps_dhcp_get_vendor_encapsulated_option_code_dps_endpoint(const plgd_dps_context_t *ctx) OC_NONNULL(); - -/** - * @brief Set the vendor encapsulated option code for the DPS certificate fingerprint. Used during call - * plgd_dps_set_dhcp_vendor_encapsulated_option_code_dps_certificate_fingerprint. - * - * @param ctx dps context (cannot be NULL) - * @param code vendor encapsulated option code for the DPS certificate fingerprint. - */ -DPS_EXPORT -void plgd_dps_dhcp_set_vendor_encapsulated_option_code_dps_certificate_fingerprint(plgd_dps_context_t *ctx, - uint8_t code) OC_NONNULL(); - -/** - * @brief Get the vendor encapsulated option code for the DPS certificate fingerprint. Used during call - * plgd_dps_set_dhcp_vendor_encapsulated_option_code_dps_certificate_fingerprint. - * - * @param ctx dps context (cannot be NULL) - * @return uint8_t vendor encapsulated option code for the DPS certificate fingerprint. - */ -DPS_EXPORT -uint8_t plgd_dps_dhcp_get_vendor_encapsulated_option_code_dps_certificate_fingerprint(const plgd_dps_context_t *ctx) - OC_NONNULL(); - -/** - * @brief Convert isc-dhcp leases file vendor encapsulated options to byte array. - * - * @param hex_string input hex string (cannot be NULL) in format "01:a:3:14" or "010a0314" - * @param hex_string_size vendor encapsulated options size in dhcp leases file. - * @param buffer output buffer into which the byte array will be copied or NULL to get the needed size - * @param buffer_size size of the output buffer - * @return >0 the size of used or needed to copy to buffer, -1 on error - */ -DPS_EXPORT -ssize_t plgd_dps_hex_string_to_bytes(const char *hex_string, size_t hex_string_size, uint8_t *buffer, - size_t buffer_size) OC_NONNULL(1); - -/** - * @brief DPS dhcp plgd_dps_dhcp_set_values_from_vendor_encapsulated_options return values. - */ -typedef enum { - PLGD_DPS_DHCP_SET_VALUES_ERROR = -1, // error or parsing values failed - PLGD_DPS_DHCP_SET_VALUES_NOT_CHANGED = 0, // nothing changed - PLGD_DPS_DHCP_SET_VALUES_UPDATED = 1, // just updated - PLGD_DPS_DHCP_SET_VALUES_NEED_REPROVISION = 2, // need to force reprovision with restart manager -} plgd_dps_dhcp_set_values_t; - -/** - * @brief Set DPS endpoint and certificate fingerprint that will be used in establishment of secure connection. - * - * @param ctx dps context (cannot be NULL) - * @param vendor_encapsulated_options vendor encapsulated options in byte array - * @param vendor_encapsulated_options_size vendor encapsulated options size in byte array - * @return one of plgd_dps_dhcp_set_values_t - */ -DPS_EXPORT -plgd_dps_dhcp_set_values_t plgd_dps_dhcp_set_values_from_vendor_encapsulated_options( - plgd_dps_context_t *ctx, const uint8_t *vendor_encapsulated_options, size_t vendor_encapsulated_options_size) - OC_NONNULL(); - -/** - * \defgroup dps_endpoints Support for multiple DPS endpoint addresses - * @{ - */ - -/** - * @brief Set endpoint address of the DPS service. - * - * Expected format of the endpoint is "coaps+tcp://${HOST}:${PORT}". For example: coaps+tcp://localhost:40030 - * - * If there are multiple endpoint addresses set then a successful call to this function will remove all other - * endpoint addresses and set the new endpoint address as the only one in the list of DPS endpoint addresses. - * - * @param ctx dps context (cannot be NULL) - * @param endpoint endpoint of the provisioning server (cannot be NULL) - * - * @deprecated Use plgd_dps_add_endpoint_address instead. - */ -DPS_EXPORT -void plgd_dps_set_endpoint(plgd_dps_context_t *ctx, const char *endpoint) OC_NONNULL() - OC_DEPRECATED("Use plgd_dps_add_endpoint_address instead."); - -/** - * @brief Copy the selected endpoint address of the DPS service to output buffer. - * - * @param ctx dps context (cannot be NULL) - * @param[out] buffer output buffer (cannot be NULL and must be large enough to contain the endpoint in a string format) - * @param buffer_size size of output buffer - * @return >0 on success, number of copied bytes to buffer - * @return 0 endpoint is not set, thus nothing was copied - * @return <0 on error - */ -DPS_EXPORT -int plgd_dps_get_endpoint(const plgd_dps_context_t *ctx, char *buffer, size_t buffer_size) OC_NONNULL(); - -/** - * @brief Check if no DPS service endpoint is set. - * - * @param ctx dps context (cannot be NULL) - * @return true if no endpoint is set - * @return false otherwise - */ -DPS_EXPORT -bool plgd_dps_endpoint_is_empty(const plgd_dps_context_t *ctx) OC_NONNULL(); - -/** - * @brief Allocate and add an address to the list of DPS endpoint addresses. - * - * @param ctx dps context (cannot be NULL) - * @param uri endpoint address (cannot be NULL; the uri must be at least 1 character long and less than - * OC_ENDPOINT_MAX_ENDPOINT_URI_LENGTH characters long, otherwise the call will fail) - * @param uri_len length of \p uri - * @param name name of the DPS endpoint - * @param name_len length of \p name - * - * @return oc_endpoint_address_t* pointer to the allocated DPS endpoint address - * @return NULL on failure - */ -DPS_EXPORT -oc_endpoint_address_t *plgd_dps_add_endpoint_address(plgd_dps_context_t *ctx, const char *uri, size_t uri_len, - const char *name, size_t name_len) OC_NONNULL(1, 2); - -/** - * @brief Remove an address from the list of DPS endpoint addresses. - * - * @param ctx dps context (cannot be NULL) - * @param address endpoint address to remove - * - * @return true if the endpoint address was removed from the list of DPS endpoints - * @return false on failure - * - * @note The endpoints are stored in a list. If the selected server address is removed, then next server address in the - * list will be selected. If the selected server address is the last item in the list, then the first server address in - * the list will be selected (if it exists). - * - * @note The server is cached in the DPS context, so if you remove the selected endpoint address during provisioning - * then it might be necessary to restart the DPS manager for the change to take effect. - * @see plgd_dps_manager_restart - */ -DPS_EXPORT -bool plgd_dps_remove_endpoint_address(plgd_dps_context_t *ctx, const oc_endpoint_address_t *address) OC_NONNULL(); - -/** - * @brief Iterate over DPS endpoint addresses. - * - * @param ctx dps context (cannot be NULL) - * @param iterate_fn callback function invoked for each DPS endpoint address (cannot be NULL) - * @param iterate_fn_data custom user data provided to \p iterate_fn - * - * @note The callback function \p iterate_fn must not modify the list of DPS endpoint addresses. - */ -DPS_EXPORT -void plgd_dps_iterate_server_addresses(const plgd_dps_context_t *ctx, oc_endpoint_addresses_iterate_fn_t iterate_fn, - void *iterate_fn_data) OC_NONNULL(1, 2); - -/** - * @brief Select an address from the list of DPS endpoint addresses. - * - * @param ctx dps context (cannot be NULL) - * @param address DPS endpoint address to select (cannot be NULL; must be in the list of DPS endpoints) - * - * @return true if the address was selected - * @return false on failure to select the address, because it is not in the list of DPS endpoint addresses - * - * @note The server is cached in the DPS context, so if you remove the selected endpoint address during provisioning - * then it might be necessary to restart the DPS manager for the change to take effect. - * @see plgd_dps_manager_restart - */ -OC_API -bool plgd_dps_select_endpoint_address(plgd_dps_context_t *ctx, const oc_endpoint_address_t *address) OC_NONNULL(); - -/** - * @brief Get the selected DPS endpoint address. - * - * @param ctx dps context (cannot be NULL) - * @return oc_endpoint_address_t* pointer to the selected DPS endpoint address - * @return NULL if no DPS endpoint address is selected - */ -DPS_EXPORT -const oc_endpoint_address_t *plgd_dps_selected_endpoint_address(const plgd_dps_context_t *ctx) OC_NONNULL(); - -/** @} */ // end of dps_endpoints - -#ifdef __cplusplus -} -#endif - -#endif /* PLGD_DPS_H */ diff --git a/content/en/docs/services/device-provisioning-service/static/dps-release/dps_compiler.h b/content/en/docs/services/device-provisioning-service/static/dps-release/dps_compiler.h deleted file mode 100644 index b974def3..00000000 --- a/content/en/docs/services/device-provisioning-service/static/dps-release/dps_compiler.h +++ /dev/null @@ -1,55 +0,0 @@ -/** - * @file dps_compiler.h - * - * Cross-compiler attributes used in code. - * - * - * Copyright (C) 2022 plgd.dev, s.r.o. - All Rights Reserved - * - * Unauthorized distribution of this library is strictly prohibited - * - * Proprietary and confidential - */ - -#ifndef PLGD_DPS_COMPILER_H -#define PLGD_DPS_COMPILER_H - -#ifdef __cplusplus -extern "C" { -#endif - -#ifdef _WIN32 -#define DPS_EXPORT __declspec(dllexport) -#define DPS_IMPORT __declspec(dllimport) -#elif (defined __GNUC__ && __GNUC__ >= 4) -#define DPS_EXPORT __attribute__((visibility("default"))) -#define DPS_IMPORT -#else /* !__GNUC__ || __GNUC__ < 4 */ -#warning "Shared libraries not supported" -#define DPS_EXPORT -#define DPS_IMPORT -#endif /* _WIN32 */ - -#ifdef DPS_SHARED_LIBRARY -#ifdef DPS_SHARED_LIBRARY_EXPORT -#define DPS_API OC_EXPORT -#else /* !DPS_SHARED_LIBRARY_EXPORT*/ -#define DPS_API OC_IMPORT -#endif /* DPS_SHARED_LIBRARY_EXPORT */ -#else /* !DPS_SHARED_LIBRARY */ -/// Annotation of the API functions that are exported by the library. -#define DPS_API -#endif /* DPS_SHARED_LIBRARY */ - -#if defined(__GNUC__) || defined(__clang__) -#define DPS_UNREACHABLE __builtin_unreachable() -#else /* !GNUC && !__clang__ */ -/// Mark unreachable code. -#define DPS_UNREACHABLE -#endif /* GNUC || __clang__ */ - -#ifdef __cplusplus -} -#endif - -#endif /* PLGD_DPS_COMPILER_H */ diff --git a/content/en/docs/services/device-provisioning-service/static/dps-release/dps_log.h b/content/en/docs/services/device-provisioning-service/static/dps-release/dps_log.h deleted file mode 100644 index 8537c9c8..00000000 --- a/content/en/docs/services/device-provisioning-service/static/dps-release/dps_log.h +++ /dev/null @@ -1,99 +0,0 @@ -/** - * @file dps_log.h - * - * Global logging functions. - * - * - * Copyright (C) 2022 plgd.dev, s.r.o. - All Rights Reserved - * - * Unauthorized distribution of this library is strictly prohibited - * - * Proprietary and confidential - */ - -#ifndef PLGD_DPS_LOG_H -#define PLGD_DPS_LOG_H - -#include "plgd/dps_compiler.h" - -#include -#include - -#include -#include -#include -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -/** - * Log component determines the source of the message. - */ -typedef enum { - PLGD_DPS_LOG_COMPONENT_DEFAULT = 1 << 0, ///< default, non-specific component -} plgd_dps_log_component_t; - -/** - * @brief Custom logging function - * - * @param level log level of the message - * @param component log component of the message - * @param file file of the log message call - * @param line line of the log message call in \p file - * @param func_name function name in which the log message call is invoked - * @param format format of the log message - */ -typedef void (*plgd_dps_print_log_fn_t)(oc_log_level_t level, plgd_dps_log_component_t component, const char *file, - int line, const char *func_name, const char *format, ...) OC_PRINTF_FORMAT(6, 7) - OC_NONNULL(); - -/// @brief Set global logging function -DPS_EXPORT -void plgd_dps_set_log_fn(plgd_dps_print_log_fn_t log_fn); - -/// @brief Get global logging function -DPS_EXPORT -plgd_dps_print_log_fn_t plgd_dps_get_log_fn(void) OC_RETURNS_NONNULL; - -/** - * @brief Set log level of the global logger, logs with lower importance will be - * ignored. It is thread safe. - * - * @param level Log level - * @note If log level is not set, the default log level is OC_LOG_LEVEL_INFO. - */ -DPS_EXPORT -void plgd_dps_log_set_level(oc_log_level_t level); - -/** - * @brief Get log level of the global logger. It is thread safe. - * - * @return Log level - */ -DPS_EXPORT -oc_log_level_t plgd_dps_log_get_level(void); - -/** - * @brief Set enabled log components of the global logger. It is thread safe. - * - * @param components mask of enabled log components - */ -DPS_EXPORT -void plgd_dps_log_set_components(uint32_t components); - -/** - * @brief Get enabled log components of the global logger. It is thread safe. - * - * @return uint32_t mask of enabled log components - */ -DPS_EXPORT -uint32_t plgd_dps_log_get_components(void); - -#ifdef __cplusplus -} -#endif - -#endif /* PLGD_DPS_LOG_H */ diff --git a/content/en/docs/services/device-provisioning-service/sztp-via-dhcp.md b/content/en/docs/services/device-provisioning-service/sztp-via-dhcp.md index 667ddd8e..d73d1f86 100644 --- a/content/en/docs/services/device-provisioning-service/sztp-via-dhcp.md +++ b/content/en/docs/services/device-provisioning-service/sztp-via-dhcp.md @@ -33,7 +33,7 @@ However, the root certificate authority via DHCP is too large. Therefore, the us This is the simplest way to configure the device, but an intruder can steal the device when it is connected to the network with an untrusted DHCP server and replace the DPS endpoint with the intruder's server. {{< /warning >}} -When using the Skip Certificate Verification (TLS) option, the device trusts any certificates sent by the DPS service, but the DPS service still verifies the device's certificate during the TLS handshake. This option should only be used when the device is connected to a trusted network, since an untrusted network could allow an attacker to steal the device and replace the DPS endpoint with their own server. If you want to skip the certificate verification to the DPS service, you can set the `skip_verify` parameter to true using the `plgd_dps_set_skip_verify` function. More details on this function can be found in the [dps.h](/docs/services/device-provisioning-service/static/dps-release/dps.h). +When using the Skip Certificate Verification (TLS) option, the device trusts any certificates sent by the DPS service, but the DPS service still verifies the device's certificate during the TLS handshake. This option should only be used when the device is connected to a trusted network, since an untrusted network could allow an attacker to steal the device and replace the DPS endpoint with their own server. If you want to skip the certificate verification to the DPS service, you can set the `skip_verify` parameter to true using the `plgd_dps_set_skip_verify` function. More details on this function can be found in the header [plgd_dps.h](https://github.com/iotivity/iotivity-lite/blob/master/include/plgd/plgd_dps.h). ## How to configure Zero Touch Provisioning via DHCP