Master Guide: Securing ICF Capsules With SourcePolicy

by Marco 54 views

Introduction to Securing ICF Capsules

In the realm of embedded systems and IoT devices, securing Inter-Component Firmware (ICF) capsules is paramount. This article delves into a robust approach to securing ICF capsules by masking cleartext URLs using a URL_enc field (0x07) and a SourcePolicy (0x08). At runtime, the reader (ESP-IDF) interacts with the authoritySP with attestation. This interaction enables the authority to reveal the source by returning a short, pre-signed URL or a proxy plus token. The core principle here is that the actual URL never traverses in cleartext on the capsule side, significantly enhancing security. This method is crucial for maintaining the integrity and confidentiality of firmware components in connected devices.

The importance of securing ICF capsules cannot be overstated in today's interconnected world. As IoT devices become increasingly prevalent, the risk of malicious actors exploiting vulnerabilities in firmware grows exponentially. By implementing measures such as URL encryption and source policies, we can drastically reduce the attack surface and protect sensitive data. This approach ensures that only authorized devices can access the firmware components, mitigating the risk of unauthorized access and tampering. The use of attestation mechanisms further strengthens security by verifying the identity and integrity of the device requesting access. This multi-layered approach to security is essential for building resilient and trustworthy IoT ecosystems.

The proposed solution introduces several key features that contribute to a more secure system. The URL_enc field encrypts the URL, preventing it from being read directly from the capsule. The SourcePolicy tag specifies the rules and conditions under which the URL can be accessed, adding an additional layer of control. The interaction with the authoritySP ensures that only devices that meet the defined criteria can obtain the URL. By using pre-signed URLs or proxy tokens, the system minimizes the exposure of the actual URL and limits the time window during which it can be accessed. This comprehensive strategy not only secures the ICF capsules but also provides a flexible and scalable framework for managing access to firmware components.

Scope of the Security Implementation

The scope of this security implementation encompasses several key areas to ensure a comprehensive approach to securing ICF capsules. Firstly, it includes the ICF specification itself, introducing new tags and rules that govern how URLs are encrypted and accessed. This ensures that the standard is updated to reflect the latest security best practices. Secondly, the implementation extends to the ESP-IDF reader, which is responsible for handling the mTLS/DPoP client, managing networking flows, ensuring secure storage, and configuring Kconfig. This component is crucial for the runtime execution of the security measures. Thirdly, the backend authoritySP is within the scope, focusing on the /v1/reveal endpoint, validation processes, and response generation. This backend component is responsible for verifying attestations and revealing the source URLs or proxy tokens. Lastly, the scope includes thorough testing, metrics collection, and documentation to ensure the implementation is robust and well-understood. However, it's important to note that this implementation does not include retroactive migration of older capsules, which is considered an optional fallback.

The inclusion of the ICF specification in the scope ensures that the new security features are standardized and can be implemented consistently across different devices and systems. By defining the new tags and rules, the specification provides a clear framework for developers to follow. The ESP-IDF reader's role in the implementation is critical as it is the component that directly interacts with the secured capsules. Its responsibilities include authenticating the device, requesting the URL from the authoritySP, and managing the subsequent data transfer. The backend authoritySP is the central authority that enforces the security policies. It validates the device's attestation, decrypts the URL, and provides the necessary access credentials. The comprehensive testing, metrics, and documentation ensure that the implementation is not only secure but also reliable and maintainable.

The exclusion of retroactive migration of older capsules is a practical decision that allows the focus to be on new implementations while acknowledging the potential for a fallback option. Migrating older capsules can be complex and may introduce compatibility issues. By concentrating on new capsules, the implementation can leverage the latest technologies and security practices. The optional fallback mechanism provides a pathway for integrating older capsules into the secured system at a later stage. This phased approach allows for a smooth transition to a more secure environment without disrupting existing deployments. Overall, the scope of this implementation is well-defined and covers the essential components necessary for securing ICF capsules effectively.

TLV Specification (ICF v1)

0x07 — URL_enc (Binary, ≤ ~240 Bytes)

The 0x07 tag, designated as URL_enc, is a binary field designed to encapsulate the encrypted URL, complete with padding and Additional Authenticated Data (AAD). This tag is crucial for securing the URL within the ICF capsule. The structure of URL_ENC_V1 is as follows:

struct URL_ENC_V1 {
  uint8_t  version;            // 0x01
  uint8_t  alg;                // 1=XChaCha20-Poly1305, 2=AES-256-GCM
  uint8_t  nonce[24];          // 24 if XChaCha20, 12 if AES-GCM (size depends on alg)
  uint8_t  aad_flags;          // bitfield: 0x01=capsule_hash, 0x02=0xF4, 0x04=badge_type…
  uint8_t  key_ref_type;       // 1=authoritySP, 2=inline KID, 3=ECIES-device
  uint8_t  key_ref_len;
  uint8_t  key_ref[key_ref_len]; // ex: KID=sha256(pubkey_sp) (16..32 bytes)
  uint16_t ct_len;
  uint8_t  ciphertext[ct_len]; // URL + padding + tag AEAD
} __attribute__((packed));

Key components of this structure include:

  • version: Indicates the version of the URL_ENC_V1 structure, currently set to 0x01.
  • alg: Specifies the encryption algorithm used, with 1 for XChaCha20-Poly1305 and 2 for AES-256-GCM. These algorithms are chosen for their robust security and performance characteristics.
  • nonce: A non-repeating value used to ensure the uniqueness of the encryption, with a size of 24 bytes for XChaCha20 and 12 bytes for AES-GCM. The use of a nonce is critical for preventing replay attacks and maintaining the confidentiality of the encrypted URL.
  • aad_flags: A bitfield that includes flags for additional authenticated data, such as capsule_hash, 0xF4, and badge_type. AAD ensures the integrity of the data by including it in the encryption process, which is crucial for security.
  • key_ref_type: Specifies the method used to reference the encryption key, such as authoritySP, inline KID, or ECIES-device. This flexibility allows for various key management strategies, enhancing the security of the system.
  • key_ref_len and key_ref: Define the length and value of the key reference, such as the KID (Key Identifier), which could be the SHA-256 hash of the SP's public key. The key reference is used to identify the key needed to decrypt the URL.
  • ct_len and ciphertext: Represent the length and the actual encrypted data, which includes the URL, padding, and the AEAD (Authenticated Encryption with Associated Data) tag. The ciphertext is the core of the encrypted URL, and its integrity and confidentiality are paramount for security.

The rules governing the use of the 0x07 tag are:

  • If 0x07 is present, the 0x01 tag (cleartext URL) MUST be ignored or absent. This ensures that only the encrypted URL is used, enhancing security.
  • AAD MUST include the capsule_hash, which is the canonical TLV hash without 0xF3. This inclusion ensures the integrity of the capsule data.
  • Padding is applied in increments (64/96/128 bytes) to obscure the actual length of the URL, adding an additional layer of security. This helps prevent attackers from inferring information about the URL based on its length.

0x08 — SourcePolicy (CBOR or Compact JSON, ≤ ~160 Bytes)

The 0x08 tag, known as SourcePolicy, encapsulates the policy that governs access to the URL. This policy is typically expressed in CBOR or compact JSON format and is limited to approximately 160 bytes. An example of a JSON-formatted SourcePolicy is:

{
  "sp_id": "kid:sha256(pub_sp)",
  "endpoint": "icfsp://reveal",
  "method": "reveal",          // "reveal" | "proxy" | "keyrelease"
  "alg": "XChaCha20-Poly1305",
  "aud": "icf-device",
  "exp_s": 300,
  "bind": "mTLS"               // "mTLS" | "DPoP"
}

Key fields within the SourcePolicy include:

  • sp_id: The identifier of the Source Policy, often the KID (Key Identifier), such as the SHA-256 hash of the SP's public key. This identifies the security policy that applies to the URL.
  • endpoint: The URL of the authoritySP endpoint, such as icfsp://reveal. This specifies the service that will handle the request to reveal the URL.
  • method: The method used to access the URL, which can be reveal, proxy, or keyrelease. The choice of method impacts the security and access control mechanisms.
  • alg: The encryption algorithm used, matching the one used in URL_enc, such as XChaCha20-Poly1305. This ensures consistency in encryption methods.
  • aud: The intended audience for the URL, such as icf-device. This helps prevent misuse of the URL by unintended recipients.
  • exp_s: The expiration time in seconds, limiting the validity of the policy. This short TTL (Time-To-Live) enhances security by reducing the window of opportunity for attacks.
  • bind: The binding mechanism used, such as mTLS (mutual TLS) or DPoP (Demonstration of Proof-of-Possession). Binding mechanisms ensure that the request is coming from a trusted source.

An option to further reduce the size of the SourcePolicy is to reference a known policy_id that is pre-configured in the reader. This approach reduces the overhead of transmitting the entire policy with each capsule.

AuthoritySP API

The authoritySP API plays a crucial role in securing ICF capsules by managing the process of revealing the encrypted URL under specific conditions. This API defines the communication protocol between the device and the security provider, ensuring that only authorized devices can access the protected content. The primary endpoint for this interaction is /v1/reveal, which handles the request for revealing the secured URL.

POST /v1/reveal

The POST /v1/reveal endpoint is the core of the security mechanism. It receives a JSON payload containing the necessary information to authenticate the device and authorize access to the URL. The request payload includes several key fields, each serving a specific purpose in the security process.

Request (JSON):

{
  "op": "reveal",
  "device_id": "<uuid/serial>",
  "attestation": {
    "fmt": "x509-mTLS|dpop",
    "fw_hash": "<hex>",
    "nonce": "<hex>"
  },
  "capsule_hash": "<hex>",
  "url_enc": "<base64(raw_0x07)>",
  "policy": "<base64(raw_0x08)>"
}
  • op: Specifies the operation being requested, which is reveal in this case. This field clarifies the intent of the request.
  • device_id: A unique identifier for the device, such as a UUID or serial number. This is essential for tracking and managing device access.
  • attestation: Contains information about the device's attestation, including:
    • fmt: The format of the attestation, which can be x509-mTLS (mutual TLS) or dpop (Demonstration of Proof-of-Possession).
    • fw_hash: The hash of the device's firmware, used to verify the integrity of the firmware.
    • nonce: A unique nonce generated by the device to prevent replay attacks, enhancing security.
  • capsule_hash: The hash of the ICF capsule, ensuring the integrity of the capsule being accessed.
  • url_enc: The base64 encoded encrypted URL (raw_0x07). This field carries the encrypted URL that needs to be revealed.
  • policy: The base64 encoded SourcePolicy (raw_0x08), which specifies the conditions under which the URL can be accessed.

Upon receiving a valid request, the authoritySP processes the information, performs the necessary security checks, and responds with either a pre-signed URL or a proxy plus token, depending on the configuration and policy.

The authoritySP can respond in two primary ways, each designed to provide secure access to the content while minimizing the risk of exposure.

Response 200 (JSON) — Option A (Pre-signed URL):

{
  "type": "signed_url",
  "url": "https://cdn.example/…?X-Amz-Signature=…",
  "ttl_s": 180,
  "cache": "no-store"
}
  • type: Indicates the type of response, which is signed_url in this case.
  • url: The pre-signed URL, which includes a signature that allows temporary access to the resource. This URL is valid for a limited time.
  • ttl_s: The Time-To-Live in seconds, specifying how long the URL is valid. A short TTL enhances security.
  • cache: Specifies caching directives, such as no-store, to prevent caching of the URL.

Response 200 (JSON) — Option B (Proxy + Token):

{
  "type": "proxy",
  "proxy_url": "https://sp.example/media/abcd",
  "token": "<jwt-or-opaque>",
  "ttl_s": 180,
  "bind": "mTLS"
}
  • type: Indicates the type of response, which is proxy in this case.
  • proxy_url: The URL of the proxy server, which acts as an intermediary between the device and the content.
  • token: A security token (JWT or opaque) that the device must present to the proxy server to access the content. This adds an extra layer of security.
  • ttl_s: The Time-To-Live in seconds, specifying how long the token is valid. A short TTL enhances security.
  • bind: Specifies the binding mechanism, such as mTLS, ensuring that the request to the proxy server is secured.

In addition to successful responses, the authoritySP API also defines various error responses to handle different failure scenarios. These error responses help the device understand the reason for the failure and take appropriate action.

Errors: 400 (format), 401/403 (attestation/policy KO), 410 (revoked), 429 (rate), 5xx.

  • 400 (Bad Request): Indicates that the request format is invalid.
  • 401 (Unauthorized) / 403 (Forbidden): Indicates that the attestation or policy validation failed, meaning the device is not authorized to access the content.
  • 410 (Gone): Indicates that the URL or device has been revoked and is no longer accessible.
  • 429 (Too Many Requests): Indicates that the device has exceeded the rate limit for requests.
  • 5xx (Server Errors): Indicates a server-side error, which requires further investigation.

To ensure the security of the system, the authoritySP implements several measures on its side. These measures protect the integrity and confidentiality of the secured content and prevent unauthorized access.

Security on the SP Side

  • Attestation Verification: The authoritySP verifies the device's attestation, which includes checking the client's X.509 certificate chain OR validating the DPoP with the device's key. This ensures that only trusted devices can access the content.
  • Device Binding: The response is linked to the device_id, which is obtained from the certificate subject or JWK thumbprint. This prevents the response from being used by other devices.
  • Short TTL: The Time-To-Live for the pre-signed URL or token is kept short (≤ 5 minutes) to minimize the window of opportunity for attacks.
  • Revocation List: The authoritySP maintains a revocation list to quickly revoke access to compromised devices or URLs.
  • Signed Logs: All security-related events are logged and signed to ensure non-repudiation and facilitate auditing.

Reader (ESP-IDF) - Tasks

To effectively implement securing ICF capsules, the ESP-IDF reader must perform several critical tasks. These tasks range from configuration and storage to runtime processing and API handling. By addressing these tasks comprehensively, the reader can ensure the security and integrity of the ICF capsules.

1) Kconfig

Kconfig is a configuration system used in ESP-IDF to manage build-time settings. Several configuration options are essential for securing ICF capsules:

  • CONFIG_ICF_SOURCEPOLICY=y: Enables the SourcePolicy feature, which is crucial for securing ICF capsules. This setting activates the code responsible for processing and enforcing source policies.
  • CONFIG_ICF_SP_BINDING_MTLS=y (or …_DPOP=y): Selects the binding mechanism for communication with the authoritySP. mTLS (mutual TLS) provides secure communication using client certificates, while DPoP (Demonstration of Proof-of-Possession) offers an alternative approach using signed HTTP requests. Choosing the appropriate binding mechanism is critical for security.
  • `CONFIG_ICF_SP_ENDPOINT=