Configuring FCU

Factory Configurator Utility (FCU) requires a configuration file in YAML format.

When you download FCU from the Device Management Portal, you get a ZIP archive, which contains the configuration file fcu.yml.

The configuration file controls FCU's behavior, and contains information relevant to multiple devices. Device-specific information is provided through the APIs (most notably, prepare_device_configuration).

FCU consults the configuration file whenever an FCU API is called, so you can modify it between calls; however, you are not likely to require modifications in daily use.

Values in the downloaded configuration file

Most of the fields in this file are empty, but some account information and default security values are populated:

# Defines whether FCU is set up as an intermediate Certificate Authority:
# - false: The setup command creates a self signed certificate to be used by FCU for signing the device certificates.
# - true: The setup command creates a CSR. The customer should use its Certificate Authority to sign the CSR and provide the certificate to FCU as 'fcu.crt' file.
# Note: If the 'fcu.crt' is a certificate chain, you must specify the 'device-certificate-chain-depth' when using FCU as a certificate authority.
setup-ca-as-intermediate: false

# Use bootstrap server (true/false). Required
use-bootstrap: true

# First to claim mode (true/false)- Relevant when 'use-bootstrap' is set to true.
# If true- the Bootstrap server URL used is the Bootstrap server first-to-claim URL.
first-to-claim: false

# Include time synchronization parameters in device configuration  (true/false)
time-sync: true

# Enable/disable verification of configuration on device side (true/false)
verify-on-device: true

device-info:
  # Device timezone
  timezone: UTC

# Device key generation modes:
# Defines the source of 'device keys' (Device DTLS private key and certificate)
#  - 'by_device': The device generates the private key and signs a CSR, and
#             FCU signs the CSR and creates a certificate, which it passes to the device
#  - 'by_tool': The tool generates device keys (default)
#  - 'externally_supplied': The user supplies device keys and provides them to the tool as files
#             under 'device-keys-location', which is provided as a command-line parameter
#  - 'preprovisioned': The device has been pre-provisioned with DTLS keys; therefore, FCU does not generate, provision, or validate DTLS keys
device-key-generation-mode: by_tool

# Device entropy generation modes:
# Defines the source of 'device entropy'
#  - 'by_device': The device generates the entropy; FCU does not pass entropy to the device (default)
#  - 'by_tool': The tool generates device entropy
#  - 'externally_supplied': The user supplies device entropy and provides it to the tool as
#             "entropy.bin" file under 'device-keys-location', which is provided as a command-line parameter
entropy-generation-mode: by_device

# Secure storage types:
# Defines the device storage type
#  - 0: Unspecified
#  - 1: Externally inaccessible storage
#  - 2: Secure storage with protected local root of trust
#  - 3: Secure storage with externally inaccessible local root of trust
secure-storage-type: 0

# Secure hardware components:
secure-hardware-components:
  non-secure-hardware: true
  uVisor: false
  trust-zone-M: false
  trust-zone-A: false
  crypto-with-lrot: false


# Device private keys in field generation:
# Controls the method in which keys are generated, in field
#  - 'by_cloud': Device private keys are never generated on the device in the field; the private keys are generated only by the cloud.
#             This option is less secure. This setting cannot be overridden by the cloud when the device is in the field (default).
#  - 'by_device': Device private keys can be generated on the device in the field.
#             This option must be used to generate LwM2M device private keys on the device as part of the bootstrap flow (also known as the EST flow).
#             You must also set the `use-bootstrap` value to `true`.
#             The Enrollment over Secure Transport (EST) feature must be enabled in your account.
#             The MBED_CLIENT_DISABLE_EST_FEATURE flag must be off on the device to enable the EST feature.
#             This option is recommended from a security perspective.
device-private-keys-in-field-generation: by_cloud   

The file also includes your account ID and certificate information that is specific to your account; for example, if your account ID were 123456abcd015867c96c2202420a1234:

# File location for bootstrap server CA certificate.
bootstrap-server-ca-certificate-file: <%= ENV['FCU_RESOURCES_DIR'] %>/bootstrap_server_ca_cert.pem
# Bootstrap server URL, for example coaps://bootstrap.arm.com
bootstrap-server-uri: coaps://auto_generated_uri.com?aid=123456abcd015867c96c2202420a1234
# Bootstrap server first-to-claim URL.
# Same URL as bootstrap-server-uri, omitting the account-id.
bootstrap-server-uri-first-to-claim: coaps://auto_generated_uri.com

# File location for LwM2M server CA certificate.
lwm2m-server-ca-certificate-file: <%= ENV['FCU_RESOURCES_DIR'] %>/lwm2m_server_ca_cert.pem
# LwM2M server URL, for example coaps://connector.arm.com
lwm2m-server-uri: coaps://auto_generated_uri.com?aid=123456abcd015867c96c2202420a1234

Environment variables

You can reference environment variables in the FCU configuration file using the following syntax:
<%= ENV['ENVVAR_NAME'] %>, where ENVVAR_NAME is the name of your environment variable.

For example:

bootstrap-server-ca-certificate-file: <%= ENV['FCU_RESOURCES_DIR'] %>/bootstrap_server_ca_cert.pem

FCU expects (and reserves) some environment variables. When these variables are absent, FCU uses default values:

Keys, certificates, and configurations

The sections below detail the various FCU configuration parameters for injecting keys, certificates and other configurations.

For more information about the parameters, see Provisioning information.

Key generation and bootstrap modes

The following parameters define how device keys are generated and whether and how your devices bootstrap.

The bootstrap mode you select in use-bootstrap dictates which files and configuration values you must provide.

Bootstrap mode

To use bootstrap mode, set use-bootstrap: true.

• Configuration values:

  • bootstrap-server-ca-certificate-file: File location for the bootstrap server's CA certificate.

  • bootstrap-server-uri: The bootstrap server's URL. For example, coaps://bootstrap.arm.com?aid=123456abcd015867c96c2202420a1234.

    The fcu.yml configuration file you download from Device Management Portal is pre-populated with a bootstrap server URI that supports both the TCP and the UDP protocols.

    To can change the pre-populated bootstrap server URI to a protocol-specific URI:

    1. In Device Management Portal, select Device identity > Server to open the Server credentials page.

    2. Copy one of the available URIs:

       • TCP URI for bootstrap server - For devices that connect to the bootstrap server using the TCP protocol.
       • Alternative TCP URI for bootstrap server - For devices that connect to the bootstrap server using the TCP protocol, if the devices are behind a firewall that blocks non-standard secure ports.
       • UDP URI for bootstrap server - For devices that connect to the bootstrap server using the UDP protocol.

  • bootstrap-server-uri-first-to-claim: Mandatory when first-to-claim is enabled (otherwise unused). Similar to bootstrap-server-uri, where the URL must not contain aid query parameter. For example, coaps://bootstrap.arm.com.

• Files - if device-key-generation-mode is externally_supplied:

  • BootstrapDeviceCert.der or BootstrapDeviceCert.pem: The device's bootstrap certificate.
  • BootstrapDevicePrivateKey.der or BootstrapDevicePrivateKey.pem: The device's bootstrap private key.

LwM2M mode

To use LwM2M mode, set use-bootstrap: false.

• Configuration values:

  • lwm2m-server-uri: The LwM2M server's URL. For example, coaps://connector.arm.com.

    The fcu.yml configuration file you download from Device Management Portal is pre-populated with a LwM2M server URI that supports both the TCP and the UDP protocols.

    To can change the pre-populated LwM2M server URI to a protocol-specific URI:

    1. In Device Management Portal, select Device identity > Server to open the Server credentials page.

    2. Copy one of the available URIs:

       • TCP URI for LwM2M server - For devices that connect directly to the LwM2M server using the TCP protocol.
       • Alternative TCP URI for LwM2M server - For devices that connect directly to the LwM2M server using the TCP protocol, if the devices are behind a firewall that blocks non-standard secure ports.
       • UDP URI for LwM2M server - For devices that connect directly to the LwM2M server using the UDP protocol.
       • WebSocket tunnel URI for LwM2M server - For devices that connect directly to the LwM2M server using UDP DTLS over WebSocket.
       • WebSocket SSL tunnel URI for LwM2M server - For devices that connect directly to the LwM2M server using UDP DTLS over WebSocket, if the devices are behind a firewall that blocks non-standard secure ports.

    Note: WebSocket URIs are account-specific and not available to other customers.

  • lwm2m-server-ca-certificate-file: File location for the LwM2M server's CA certificate.

• Files - if device-key-generation-mode is externally_supplied:

  • LwM2MDeviceCert.der or LwM2MDeviceCert.pem: The device's LWM2M certificate.
  • LwM2MDevicePrivateKey.der or LwM2MDevicePrivateKey.pem: The device's LWM2M private key.

For information about the format of DTLS certificates, see device certificates.

Using certificate chains

In addition to injecting certificates, you can also inject a certificate chain to the device. Certificate chains can also be defined as trusted in Device Management.

When a device performs bootstrap or connects to Device Management, the server can verify the validity of the certificate that the device presents by validating the chain of certificates.

When you inject a certificate chain, define the chain's length using the device-certificate-chain-depth parameter (integer, 1-10). If you do not define the certificate chain depth, it is assumed to be 1 (a single certificate).

Note: The length of the certificate chain depends on the device's capability. By default, a device supports up to five certificates. You can change this by modifying the KCM_MAX_NUMBER_OF_CERTIFICATES_IN_CHAIN compilation flag in the kcm_defs.h file. The default value is 5.

Note: When FCU loads a certificate chain file (as an external device certificate, or when FCU is a CA and its CA certificate is a chain), it expects the file to be in PEM format, and the certificates in the file should be in the following order:

1. The end-entity certificate
   
2. The intermediate certificate(s)
   
3. The root certificate
   

-----BEGIN CERTIFICATE-----
(End-entity certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate)
-----END CERTIFICATE-----
...
-----BEGIN CERTIFICATE-----
(Intermediate certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate)
-----END CERTIFICATE-----

FCU as CA

The subject of the generated CA certificate consists of the following parameters, which are aggregated under the certificate-authority section in the fcu.yml file:

Additional certificate authorities

The subject of the CA certificate generated for each additional CA consists of the following parameters, which are aggregated under the additional-certificate-authorities section in the fcu.yml file:

To add multiple additional CAs, copy and populate the parameters for each CA.

Note: FCU creates a folder in the keystore directory for each additional CA that you add in the additional-certificate-authorities section. FCU names these folders using the <CA name> values that you define in the additional-certificate-authorities section. Each of these folders holds a private key and the CA certificate or a CSR (for an intermediate CA).

Example:

additional-certificate-authorities:
  sample-ca-1:
    certificate-authority:
      common-name: CN-sample-1
      organization-name: ON
      organizational-unit-name: OUN
      locality-name: LN
      state-or-province-name: SN
      country-name: NO
    setup-ca-as-intermediate: true
  sample-ca-2:
    certificate-authority:
      common-name: CN-sample-2
      organization-name: ON
      organizational-unit-name: OUN
      locality-name: LN
      state-or-province-name: SN
      country-name: NO
    setup-ca-as-intermediate: false

Firmware update authentication

For firmware update:

Note: If update-auth-certificate-file is configured, you must also configure the vendor-id and class-id parameters.

LwM2M Device Object information

These parameters are aggregated under the device-info YAML section:

Device certificates configuration

These parameters make up the subject of the generated device certificate. They are aggregated under the device-certificate section in the fcu.yml file:

FCU automatically uses the endpoint name you give the device as the Common Name of the device certificate.

Trust level parameters

Use these configuration parameters to enable FCU to calculate and set the trust level extension in the device certificate:

• secure-storage-type: Defines the device storage type. Valid values:
  • 0: Unspecified.
  • 1: Externally inaccessible storage.
  • 2: Secure storage with protected local root of trust.
  • 3: Secure storage with externally inaccessible local root of trust.
• secure-hardware-components: Parameters that specify the secure hardware components in the device:
  • non-secure-hardware: true/false.
  • uVisor: true/false.
  • trust-zone-M: true/false.
  • trust-zone-A: true/false.
  • crypto-with-lrot: true/false.
• device-private-keys-in-field-generation: Controls the method of generating the keys in field. Valid values:
  • by_cloud: Device private keys are never generated on device in field – the private keys are generated only by the cloud. This option is less secure. This setting cannot be overridden by cloud once the device is in the field (default).

The trust level is embedded in the generated device certificate, in an X.509 extension.

Device Entropy

This parameter defines the source of the entropy that the device receives. The entropy is 48 bytes of random data.

Using the device to generate entropy

To get the device to generate entropy itself in the injection process, in the fcu.yml file, set entropy-generation-mode to by_device.

If entropy-generation-mode does not exist in the fcu.yml, this is default behavior.

Using your own entropy file

In this mode, you use your own entropy file as a resource:

1. In fcu.yml, set entropy-generation-mode to externally_supplied.
2. Under path used for device_keys_location provide entropy.bin file.
   • entropy.bin shall be binary file with 48 bytes.
   • It is good practice to use a True Random Number Generator (TRNG) to generate such entropy.

Using FCU to generate entropy

To get FCU to generate entropy and pass it to the device in the injection process, in the fcu.yml file, set entropy-generation-mode to by_tool. This scenario is used when the device does not have enough entropy and you do not have a TRNG. FCU generates 48 random bytes.

Secure device access

The trust anchor public keys that need to be put on the device, so that it can validate that the access tokens have been signed by a known trust anchor.

Each trust anchor public key is stored on the device as a single DER under mbed.ta.<key-sha256-fingerprint-uppercase> key.

Custom properties

You can provision custom properties to a batch of devices by defining them in the FCU configuration file (fcu.yml).

You can also provision device-specific custom properties by creating a custom properties section, as explained in this section, in a separate YAML file and passing the --device-config-file argument when you provision the device. For more information, see Injecting the configuration onto the device.

If the device-specific custom properties YAML file contains a property with the same name and type as a property in the fcu.yml FCU configuration file, FCU injects the device-specific custom property.

This section describes the parameters these properties must have:

Available types:

certificate: 
  certificate-authority:
 
       (optional - the name of certificate authority to sign the certificate. default: fcu) 
  subject:
        common-name: string
        organization-name: string
        organizational-unit-name: string
        locality-name: string
        state-or-province-name: string
        country-name: string (two letters)
  key-usage:
        digital-signature: boolean
        non-repudiation: boolean
        key-cert-sign: boolean
  extended-key-usage:
        any-extended-key-usage: boolean
        server-auth: boolean
        client-auth: boolean
        code-signing: boolean
        email-protection: boolean
        time-stamping: boolean
        ocsp-signing: boolean
  validity-period-months: int (1-360)
  chain-depth-on-device: int (1-10)
       (optional- required when FCU signs with certificate-chain)

Sample configurations for custom properties:

custom-properties:
  -
    type: certificate
    name: Sample.TrustedPartnerCert
    data-file: <%= ENV['FCU_RESOURCES_DIR'] %>/trusted-partner.crt

custom-properties:
  -
    name: Sample.InlineDerCertificate
    type: certificate
    data: !binary |
        MIICMDCCAdWgAwIBAgIQJvkI/PHARqRKTSzxlCf5HzAKBggqhkjOPQQDAjBv
        MQswCQYDVQQGEwJHQjEXMBUGA1UECBMOQ2FtYnJpZGdlc2hpcmUxEjAQBgNV
        BAcTCUNhbWJyaWRnZTEQMA4GA1UEChMHQVJNIEx0ZDEhMB8GA1UEAxMYQVJN
        IEludGVncmF0aW9uIExXTTJNIENBMCAXDTE3MDIxMjEwMzc1MloYDzIwNTIw
        MjEyMTA0NzUyWjBvMQswCQYDVQQGEwJHQjEXMBUGA1UECBMOQ2FtYnJpZGdl
        c2hpcmUxEjAQBgNVBAcTCUNhbWJyaWRnZTEQMA4GA1UEChMHQVJNIEx0ZDEh
        MB8GA1UEAxMYQVJNIEludGVncmF0aW9uIExXTTJNIENBMFkwEwYHKoZIzj0C
        AQYIKoZIzj0DAQcDQgAEuuqAAS3w4bbFX/l2hDGpKaHHqP2grdmU5+xaM6Es
        jjZDmxjfznEUJLH7FjQOQ/wjd9QT1xGqOWCrot8ks+ugxaNRME8wCwYDVR0P
        BAQDAgGGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFHuhpZSl5Y+VXdTO
        3A+Kvq2aa2Y+MBAGCSsGAQQBgjcVAQQDAgEAMAoGCCqGSM49BAMCA0kAMEYC
        IQDSBijFMToRjbbLKz/dKpoTMFJ3qtray865XOQyHAL6MAIhALOCJKKxZ2tp
        Bw7Nd3SZBpxZsgDAs7s3W8Ab+9lwmLke

custom-properties:
  -
    type: private-key
    name: Sample.SomeFeatureSigningPrivateKey
    data-file: <%= ENV['FCU_RESOURCES_DIR'] %>/signing-priv.pem
  -
    type: public-key
    name: Sample.SomePublickKey
    data-file: <%= ENV['FCU_RESOURCES_DIR'] %>/some-pub-key.der

custom-properties:
  -
    type: generated-certificate-key-pair
    name: Sample.InlineGeneratedCertificateKeyPair
    data:
        certificate:
          certificate-authority:  # Optionally provide CA name here.
          subject:
                common-name: inline_common_name
                organization-name: inline_organization
                organizational-unit-name: inline_organizational
                locality-name: inline_local
                state-or-province-name: inline_state
                country-name: GB
          key-usage:
                digital-signature: true
                non-repudiation: true
                key-cert-sign: true
          extended-key-usage:
                any-extended-key-usage: true
                server-auth: true
                client-auth: true
                code-signing: true
                email-protection: false
                time-stamping: false
                ocsp-signing: false
          chain-depth-on-device: 2
          validity-period-months: 24
        private-key-storage: device
        public-key-storage: device  

custom-properties:
  -
    type: general-data
    name: Factory.SwManufacturerName
    data: SomeManufacturer
  -
    type: general-data
    name: Sample.IntValue
    data: 35458

custom-properties:
  -
    type: general-data
    name: Sample.GeneralDataBytes
    data-file: <%= ENV['FCU_RESOURCES_DIR'] %>/some-data.bin
  -
    type: certificate
    name: Sample.TrustedOnlineServiceCert
    data: |
      -----BEGIN CERTIFICATE-----
      MIIDsjCCApqgAwIBAgIQAeao0CRBMj9YWf0vWw1u0jANBgkqhkiG9w0BAQsFADA4
      MRMwEQYDVQQKEwpHbG9iYWxTaWduMSEwHwYDVQQDExhHbG9iYWxTaWduIG1UTFMg
      SW5mcmEgQ0EwHhcNMTcxMjE0MTAyODUyWhcNMTgxMjE0MTYxNzM4WjAzMREwDwYD
      VQQDEwhBUk0gTWJlZDELMAkGA1UEBhMCR0IxETAPBgNVBAoTCEFSTSBNYmVkMIIB
      IjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtJcENDq/V9xI+J/AYmEmTqym
      Qw3eeOOnhVNo2tATI9fNR99qnBTUMFwfmKxt8uZQ2oE55FlrBZOqVfj60WB51NB0
      e0cSMvZlq4Gwx7cBkMjCfLf14TngeDoXWdA00px1SYH5pXOtIIPRn1YXIXjXDQkd
      41R4dKeFEOlk84HBwb/lnBQRycVWPPP/n5ucsVzm+7zSw8d3jSNPe4IK5fjqUhfu
      mzISNZx9qa6zkA6YlDfAlpzN66Ot4kr6dXLUqEkQyKo7lLDY5TvJTVpvOBYy6P33
      Ba5LHmNOrr2bpy+lVxQkeBQ2ZGG1XjtmaF9BLZsAfM0ILnR+4DGF37T3TT6ikwID
      AQABo4G8MIG5MB0GA1UdDgQWBBTbMxrEWKPQ9nDgYw7fucfRPsPJsDAJBgNVHRME
      AjAAMB8GA1UdIwQYMBaAFD3Y0AtxC2Afj5Jt6zaf2lHr8uVWMEcGA1UdHwRAMD4w
      PKA6oDiGNmh0dHA6Ly9jcmwuZ2xvYmFsc2lnbi5jb20vY2EvR2xvYmFsU2lnbm1U
      TFNJbmZyYUNBLmNybDAOBgNVHQ8BAf8EBAMCBaAwEwYDVR0lBAwwCgYIKwYBBQUH
      AwIwDQYJKoZIhvcNAQELBQADggEBACPZvmuJi27r7ksZ8Xmk87JzzlgmFKTJN436
      +Q5oK9iGtuguIC5COjsJLped9gRFEUH7BrmK5spW3bJqB7KHuRt9pB3Xf5Q9MFem
      Ysf23TkjmKLi3cQdEVdzYOYrjAu3RTuN44O/1qfjb/SSR7X+9WMKykGJd8gl8RTL
      s7K1pnF2Zpptm8XU40VXzNH45cPyrmXtEOPU+UTtAhE7MfE6bbOrxazV6ncC3Ybe
      Xf2hRuSiO2MaSbwtYZCcSjC79if4HOu5P1qvLjWyVkebNkTOb2OR0TxQTLnCLAit
      sLGO4z4MKdDSO4VNlj1qDXgOExwIPnhS16h/jHDOLbpOKVdnR8c=
      -----END CERTIFICATE-----

custom-properties:
  -
    type: general-data
    name: network_address
    data: 2001:2345::1
  -
    type: general-data
    name: network_secret
    data: !!binary |
      c23tZSBzZWNyZXQgZGF1YSBoZXJlLi4=

Sample configuration file

############################################################
# Factory Configurator Utility Configuration
#  Used for configuring FCU library
############################################################


############################################################
# Configuration used for setting up the tool as a
# Certificate Authority
############################################################

certificate-authority:
  common-name: Sample Cert
  organization-name: Company Ltd.
  organizational-unit-name: Mbed Factory
  locality-name: Madison
  state-or-province-name: Wisconsin
  country-name: US

# Defines whether FCU is set up as an intermediate Certificate Authority:
# - false: The setup command creates a self signed certificate to be used by FCU for signing the device certificates.
# - true: The setup command creates a CSR. The customer should use its Certificate Authority to sign the CSR and provide the certificate to FCU as 'fcu.crt' file.
# Note: If the 'fcu.crt' is a certificate chain, you must specify the 'device-certificate-chain-depth' when using FCU as a certificate authority.
setup-ca-as-intermediate: false

############################################################  
# Configuration used for setting up additional certificate authorities.  
# Used for custom properties of type 'generated-certificate-key-pair'  
#  
# additional-certificate-authorities:  
#   <CA name>:  
#     certificate-authority:  
#       common-name:  
#       organization-name:  
#       organizational-unit-name:  
#       locality-name:  
#       state-or-province-name:  
#       country-name:  
#     setup-ca-as-intermediate: true/false  
############################################################  


############################################################
# Device General Information
############################################################

# Use bootstrap server (true/false). Required
use-bootstrap: true
# Include time synchronization parameters in device configuration  (true/false)
time-sync: true


############################################################
# Bootstrap Configuration
#  Relevant when 'use-bootstrap' is set to true
############################################################

# Bootstrap server URL, for example coaps://bootstrap.arm.com
bootstrap-server-uri: coaps://auto_generated_uri.com?aid=123456abcd015867c96c2202420a1234
# File location for bootstrap server CA certificate.
bootstrap-server-ca-certificate-file: <%= ENV['FCU_RESOURCES_DIR'] %>/bootstrap-server-certificate.crt

# First to claim (true/false).
# If true, the Bootstrap server URL used is the Bootstrap server first-to-claim URL.
first-to-claim: false
# Bootstrap server first-to-claim URL.
# Same URL as bootstrap-server-uri, omitting the account-id.
bootstrap-server-uri-first-to-claim: coaps://auto_generated_uri.com
############################################################
# LwM2M Configuration
#  Relevant when 'use-bootstrap' is set to false
############################################################

# LwM2M server URL, for example coaps://connector.arm.com
lwm2m-server-uri: coaps://auto_generated_uri.com?aid=123456abcd015867c96c2202420a1234
# File location for LwM2M server CA certificate.
lwm2m-server-ca-certificate-file: <%= ENV['FCU_RESOURCES_DIR'] %>/lwm2m-server-certificate.crt

############################################################
# Update auth  (for firmware update)
############################################################

# File location for Update auth certificate
update-auth-certificate-file: <%= ENV['FCU_RESOURCES_DIR'] %>/update-auth-certificate.crt
# Vendor-Id - UUID string that represents the vendor (for example, "fa6b4a53-d5ad-5fdf-be9d-e663e4d41faf")
vendor-id: 'fa6b4a53-d5ad-5fdf-be9d-e663e4d41faf'
# Class-Id - UUID string that represents the device class (for example, "4a5fa6b3-5fef-fe9d-bee4-66e41f3e4daf")
class-id: '4a5fa6b3-5fef-fe9d-bee4-66e41f3e4daf'

############################################################
# LwM2M Device Object Information
############################################################

device-info:
  # Manufacturer name (String)
  manufacturer-name: SomeManufacturer
  # Device type (String)
  device-type: Sensor-A
  # Model Number (String)
  model-number: TEMP-SENSOR-MVMF7IF
  # Hardware version (String)
  hardware-version: 1A
  # Memory total size in kilobytes. (Integer)
  memory-total: 10240
  # Device timezone
  timezone: GMT


############################################################
# Configuration used for generation of device certificates
############################################################

# Device key generation modes:
# Defines the source of 'device keys' (Device DTLS private key and certificate)
#  - 'by_device': The device generates the private key and signs a CSR,
#             the FCU signs the CSR and creates a certificate to be passed to the device
#  - 'by_tool': The tool generates device keys (default)
#  - 'externally_supplied': The user supplies device keys and provides them to the tool as files
#             under 'device-keys-location', which is provided as a command-line parameter
device-key-generation-mode: by_tool

device-certificate:
  organization-name: Sample Org Ltd.
  organizational-unit-name: IoT-Temp-Sensors
  locality-name: Texas City
  state-or-province-name: Texas
  country-name: US

# If certificate chains used: defines the length of the certificate chain to be stored on device (Integer between 1-10)
# Note: The length of the certificate chain that will be stored depends on device capability, by default devices support only up to 5 certificates.
#       The device capability can be changed by modifying compilation flag KCM_MAX_NUMBER_OF_CERTITICATES_IN_CHAIN. Its' default value is 5 and it's located in `kcm_defs.h` file
device-certificate-chain-depth: 2

############################################################
# Configuration used for generation of device entropy
############################################################

# Device entropy generation modes:
# Defines the source of 'device entropy'
#  - 'by_device': The device generates the entropy; FCU does not pass entropy to the device (default)
#  - 'by_tool': The tool generates device entropy
#  - 'externally_supplied': The user supplies device entropy and provides it to the tool as
#             "entropy.bin" file under 'device-keys-location', which is provided as a command-line parameter
entropy-generation-mode: by_device


############################################################
# Trust Level
############################################################

# Secure storage types:
# Defines the device storage type
#  - 0: Unspecified
#  - 1: Externally inaccessible storage
#  - 2: Secure storage with protected local root of trust
#  - 3: Secure storage with externally inaccessible local root of trust
secure-storage-type: 0

# Secure hardware components:
# Multiple values can be set
secure-hardware-components:
  non-secure-hardware: true
  uVisor: false
  trust-zone-M: false
  trust-zone-A: false
  crypto-with-lrot: false

# Device Private Keys in field generation:
# Controls the method in which keys are generated, in field
#  - 'by_cloud': Device private keys are never generated on device in field – the private keys are generated only by the cloud.
#             This option is less secure. This setting cannot be overridden by cloud once device is in the field (default)  
device-private-keys-in-field-generation: by_cloud


############################################################
# Secure Device Access
############################################################

# Trust Anchors:
trust-anchors-public-key-files:
    - <%= ENV['FCU_RESOURCES_DIR'] %>/ta.367E98852E.pem

Logging

FCU uses Python’s built-in logging module to perform system logging as a sub-logger.

Configuring logs is a two-step process performed when you implement your factory tool:

1. Configure the Python root logger (as you can see in the factory tool demo).

   For details about the usage and configuration of this module, see the official Python documentation.

2. Configure the FCU sub-logger. For example:

   You can set FCU's log level to error, so that warnings and messages aren't logged:

   logging.getLogger('fcu').setLevel(logging.ERROR)
   

   You can rotate the log file at a set time interval:

   file_handler = logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount, encoding=None, delay=False, utc=False, atTime=None)
   

   For more information, see the official Python documentation.

FCU logs

FCU generates two types of logs: debug logs, which monitor the system, and audit logs, which you can use to analyze system usage.

• FCU debug log format:

  <OPERATION>: <ENDPOINT_NAME>; <ACCOUNT_ID> - <MESSAGE>

  Where <OPERATION> can be:

  • PREP: Prepare device configuration API.
  • VER: Verify device response API.
  • STAT: Get setup status API.
  • SETUP: Set up the Factory Configurator Utility API.

  <ENDPOINT_NAME> and <ACCOUNT_ID> are not mandatory, and are only set in APIs that have or need access to them.

• FCU audit log format:

  <OPERATION>: <ENDPOINT_NAME>; <ACCOUNT_ID> - AUDIT: <API> <AUDIT_MESSAGE>

  Where <AUDIT_MESSAGE> can be:

  • Operation completed successfully
  • Operation completed with warnings
  • Operation completed with errors: <fcu_error_code>; <fcu_error_message>

  For errors, the audit log message prints the FCU error number and message as listed in FCU error codes.

Log file rotation

We recommend setting log file rotation so that your factory tool server does not halt or fail because of insufficient free disk space.

To configure the log file rotation:

file_handler = logging.handlers.RotatingFileHandler(log_file, mode, maxBytes, backupCount)
handlers.append(file_handler)
# where the maxBytes and backupCount values to allow the file to rollover at a predetermined size.

For more information about log file rotation and other logging configuration, see the official Python documentation.