SZTPD Release Notes

1 Introduction

The sections below cover what is and is not working in this release of the SZTPD product.

Most everything listed as “not working” will be implemented before FCS.

2 Implemented / Tested

This section describes what is working in SZTPD. All of the following has been tested1:

  • All APIs work: ‘native’, ‘tenant’, and ‘rfc8572’.
  • Each listening port is HTTP with or without TLS.
  • For client auth: TLS client certs and/or HTTP basic auth (TLS certs tested again to match against specific TA)
  • RESTCONF HEAD, GET, POST, PUT, and DELETE work over entire tree.
  • The ./well-known/host-meta, RESTCONF root (i.e., {+restconf}), and the YANG-library resources are all accessible.
  • Tested using in-memory, mysql, and postgres databases (99.5% testing with in-memory DB)
  • Product modes: 1 and x both work.
  • Bootstrapping log (including information about SZTPD’s relay to remote systems)
  • Audit log (including per-tenant audit log)
  • Plugin-based callouts for response manager2.
  • Webhook-based callouts for notifications
  • Database-level transactions.
  • Both Python 3.7 and 3.8.

3 Should Work

This section regards things that should work, but haven’t been tested yet.

  • IPv6: The default port binds to “127.0.0.1”, but this can be changed by setting the FIXME “SZTPD_DEFAULT_ADDR” environment variable. Other than this, there is no other IPv4-only code in the product as everything is handled by Python modules.

  • UTF-8: Python string types support both ASCII and unicode, like UTF-8. Presumably string handling is ambivalent, but this in isn’t tested yet.

  • RDBMSs: The unit tests currently only use the in-memory database. The RDBMS code development and testing was done using curl scripts.

  • Windows: the software has been developed and tested exclusively in UNIX based systems. Python is very portable, and SZTPD has almost no interaction with the filesystem, so running on Windows might work, but this has not been tested.

4 Not Yet Implemented:

The following features are sorted by the expected release they might show up in. Please let us know if there is something out of place or missing.

4.1 Alpha-3

  • Testing against AWS Aurora Serverless database.

  • Concurrent write access requests. While the database has transactions (i.e., an exception will never leave the DB in a corrupt state), the RESTCONF server has other structures that are unprotected to simultaneous access.

4.2 Alpha-4

  • Authenticating the RDBMS’s TLS certificate. Currently, the “–cacert” parameter is ignored.

  • Client certificate-based authentication to the database. Currently the “–key” parameter is ignored.

  • Fronting SZTPD with an TLS-terminator. While SZTPD can be configured to listen for HTTP (without TLS), doing so behind a TLS-terminator is not implemented yet. This feature enables the client’s original source address and client-certificate to be passed as a parameters into SZTPD, rather than read from the accepted socket.

4.3 Alpha-5

  • Device-ownership callout. Currently the callout can be configured, but it is not used by the code yet.

  • Tenant view device types. Currently, tenants can set a valid ‘device-types’ value only if provided to them out-of-band. These values are only set at the “host” level, (on purpose) outside the tenant’s purview. A tenant’s clients should be able use either an RPC/action to get the supported device-types from the host, or have that information exposed as opstate (i.e., read-only “config false” values)3.

4.4 Alpha-6

  • Validating the end-entity certificates, when being configured, match the associated private key. Currently the system trusts that the user passes in valid key/cert pairs.

  • Validating base64 contents (CMS). Currently trusts that valid structures are configured. Only later, when using the structures will SZTPD decode them and potentially find errors. Exceptions will be thrown, but the error messages are not always helpful. Tests would include, e.g., that a CMS containing a sequence of certificates does not contain any spurious certificates.

4.5 Alpha-7

  • RESTCONF error messages bodies. RESTCONF describes the error message bodies as being formatted a specific way (https://tools.ietf.org/html/rfc8040#section-3.6.3). Currently all error message, except authentication errors (i.e., HTTP status code 401)4, return a plain text string in the message-body (not the structured response).

4.6 Alpha-X

  • Remove support for mode ‘1’. This change would affect the NBI only (no impact on the device-facing ‘rfc8572’ SBI).

    • Reasons to also remove mode ‘1’:

      1. It may be important for non-production use environments (e.g., those used for evals and demos) to exactly mimic production environments.

      2. Eliminates an artificial constraint for Mode ‘1’ deployments, in they can easily configure an additional “tenant” for whatever reason. It also eliminates need to ever have to migrate mode-1 deployments to a mode-x deployment, which would require a database migration..

      3. The tenant-view provided by Mode ‘x’ quite nicely isolates system-level configuration enabling IT organizations to do the system-level install and then pass an “application” view that excludes the system-level install to another organization within the company.

      4. Only supporting Mode-x could greatly simplify the YANG modules. This could be important to developers as they might need to look at the YANG modules in order to understand the data model exposed by the API. While the current YANG is navigable, it could be even more so if only supporting Mode-x.

      5. Further simplify the YANG modules. Note that mode ‘0’ is already almost completely phased out, and yet the YANG modules have yet to be simplified…somewhat due to waiting to determine if also phasing out mode ‘1’.

    • Reasons to not remove mode ‘1’:

      1. It is unclear what the market expectations are regarding metered based subscriptions versus flat-rate tiers for enterprises and service providers. Hesitant to change anything without some feedback.
  • Remove support for debug messages. Currently the “–debug” parameter is ignored, serious errors produce Python exceptions, which seem to satisfy all debugging needs.

  • Remove support for more than one API interface per listening port. Currently the ‘use-for’ leaf-list has ‘max-elements’ set to ‘1’. (Update Adminstrator’s Guide too).

  • RESTCONF entity-tag (ETag) Support. The HEAD and GET operations would return the “ETag” HTTP header field. The POST, PUT, and DELETE operations would inspect request headers for the “If-Match”, and “If-None-Match” fields. Support for Etag is a MUST in RFC 8040 only on the top-level datastore resource, and unspecified for inner-resources.

  • The RESTCONF/HTTP “OPTIONS” method. This needs to be added in order to notify clients that XML is NOT supported.

  • The RESTCONF query parameters. RESTCONF describes query parameters that can be used when interacting with the data (see Section 4.8 of RFC 8040). Notably the ‘depth’ and ‘fields’ parameters can prune that which is returned, and the ‘point’ and ‘insert’ parameters enable maintaining user-ordered lists.

  • Paging (offset + limit) query parameters. It is desirable to introduce proprietary query parameters for interacting with potentially long lists (i.e., audit-log, bootstrapping log, devices, tenants, etc.)

  • Authorization / access-control. It is planned to implement the admin-account “access” node, which sets an enumerated value being one of “unrestricted”, “typical”, and “minimal”.

  • Implicit change tracking. This is needed to support a few of the features listed below. It is also needed to detect when any part of the “transport” configuration changes, so that a SIGHUP can be issued. Currently SIGHUP is issued only when an “endpoint” is added or removed.

  • Device record counters. It is planned to track when the device records are created, last modified, and the total number of modifications. Similarly, to track when the bootstrapping device first connected, last connected, and the total number of connections.

  • Reference tracking. It is desired to track references to objects in the system. In YANG terms, these are the ‘leafref’ statements that reference a ‘list’ statement’s ‘key’ node. Tracking includes the current number of references and the time of last reference.

  • Automated purging with notifications. It is desired to send notifications when unreferenced objects have been without a reference, for some configurable amount of time. A series of notifications with escalating urgency can be to sent to configurable notification receivers. A final notification is sent when the purging occurs.

  • Password expirations with notifications. This feature goes with the previously mentioned “automated purging with notifications” feature, but has its own “preferences” setting for when the timeouts should be.

  • Email-based admin activations. It is intended that SZTPD will send email based notifications to newly created admins when their accounts are first created. It is important to validate the email address because the same email address may be emailed later when the password expiration date is approaching. This is why the email address is the primary key for the admin accounts.

  • Password minimum length constraints. Currently the “preference” setting for the admin account password’s minimum length constraint is ignored.

  • Client certificate based auth to NBIs. Currently SZTPD implements client cert based auth to the SBI (i.e, ‘rfc8572-interface’). This is to extend that configuration into the NBIs also (i.e., ‘native’ and ‘tenant’). This would provide 2FA to the NBI. However, perhaps it’s more important to support an SSO standard?

  • Webhook-based callouts for response manager (Callback-based callouts can be used as a workaround until supported).

  • Plugin-based callout for notifications (Webhook-based callouts can be used as a workaround until supported).

4.7 Beta

  • Run performance and soak tests. Only address issues found.

4.8 FCS

  • Nothing new
  • Stress tests
  • Soak tests

4.9 Post 1.0

  • RESTCONF “Last-Modified” support. The HEAD and GET operations would return the “Last-Modified” HTTP header field. The POST, PUT, and DELETE operations would inspect request headers for the “If-Modified-Since” and “If-Unmodified-Since” fields. Support for timestamps is a SHOULD in RFC 8040.

  • The RESTCONF/HTTP “PATCH” method. Though a MUST in RFC 8040, it seems mostly like a nice-to-have in SZTPD…

  • XML-based messages in SBI. RESTCONF enables the Content-Type to be “application/yang.data+xml” signaling that the server supports encoding XML messages. Currently, SZTPD only supports “application/yang.data+json” for a JSON-only SBI interface. There is a question of market-demand as for if needed. All clients (both NBI and SBI) must use JSON-encoded RESTCONF messages.

  • Support a callout to retrieve an ownership voucher from an external system. This would implement the “supply-ownership-voucher” RPC defined in the “wn-sztpd-callbacks” module. The RPC is currently protected by a ‘feature’ statement called “supply-ownership-voucher”, thus programmatically signalling that it is not supported, though visible in the YANG.

  • Support signing conveyed information sent from SZTPD using the private key associated with a configured owner certificate.

  • Support encrypting conveyed information sent from SZTPD using the device’s public key from its identity certificate (e.g., IDevID).

  • Support stapling revocation responses to CMS objects returned to devices.

    • only needed for signed data? (what about the redirect-info’s trust-anchor CMS?)
  • Private key encryption. It is desirable for SZTPD to have an ability to encrypt private keys via a “root” key. Note that this is above and beyond DB-level encryption; it purpose to to shield keys even from administrators having appropriate access. This root key would be protected by access control and/or an HSM.

  • Actions: None of the ‘action’ statements defined in the YANG modules are implemented yet. Primarily this effects the ability to create keys, and generate certificate signing requests. The workaround is to generate the keys and certs using an external PKI and then pass those values in as configuration.

5 Internal Work

  • In DAL, rebase persistence encoding for documents to not include self envelop. Mostly to simplify code, but might improve performance.

  • Fully remove mode ‘0’ by 1) restructuring YANG modules (all relative paths can be same) and 2) in DAL, optimize code bits having mode ‘0’ handling. Mostly to simplify code, but might improve performance.

  • In DAL, remove “singleton” lookups - replace all with ‘/’ path. This provides more consistency and simplifies code.

  • Factor out app-layer into its own modular package.

6 Known Limitations

  • Due to an issue in the Python TLS support, client certificates (IDevID) sent from devices must either only contain the end-entity certificate (no intermediates) or a TBD flag to disable the app-level test ensuring the device’s cert matched the specific ‘device-type’ trust-anchor. This is only an issue when SZTPD terminates the TLS connection, using an exteernal TLS terminator will bypass the Python TLS logic.

  • Python (currently) is unable to staple OSCP Responses to the TLS Handshake. Workaround, if needed at all, is to front SZTPD with an external TLS Terminator, which is better for perfomance anyway.

7 Change Log

7.1 0.0.2

  • callback-based callouts updated to support draft-kwatsen-netconf-sztp-csr.
  • fixed bugs related to bootstrapping-log and audit-log not cleaning up correctly when deleted.

7.2 0.0.1

  • initial public release

  1. There is more than twice the number of lines of test code than code in SZTPD itself.↩︎

  2. Plugin-based callouts have been used to test support for draft-kwatsen-netconf-sztp-csr.↩︎

  3. Current plan is to do the latter, but due to limitations in YANG, need to split the sztpd-1 schema into two: one for ‘native’ view and another for the ‘tenant’ view.↩︎

  4. Not returning any text in the body of an authentication error (e.g., 401) response is a Security measure. The audit log will contain the specific error.↩︎