optiga_trust_helpers.h

Go to the documentation of this file.

/******************************************************************************
* File Name:   optiga_trust_helpers.h
*
* Description: This file contains helping fucntions to read a certificate or 
*              change some default parameter
*
* Related Document: See README.md
*
*
*******************************************************************************
* Copyright 2020-2025, Cypress Semiconductor Corporation (an Infineon company) or
* an affiliate of Cypress Semiconductor Corporation.  All rights reserved.
*
* This software, including source code, documentation and related
* materials ("Software") is owned by Cypress Semiconductor Corporation
* or one of its affiliates ("Cypress") and is protected by and subject to
* worldwide patent protection (United States and foreign),
* United States copyright laws and international treaty provisions.
* Therefore, you may use this Software only as provided in the license
* agreement accompanying the software package from which you
* obtained this Software ("EULA").
* If no EULA applies, Cypress hereby grants you a personal, non-exclusive,
* non-transferable license to copy, modify, and compile the Software
* source code solely for use in connection with Cypress's
* integrated circuit products.  Any reproduction, modification, translation,
* compilation, or representation of this Software except as specified
* above is prohibited without the express written permission of Cypress.
*
* Disclaimer: THIS SOFTWARE IS PROVIDED AS-IS, WITH NO WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, NONINFRINGEMENT, IMPLIED
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Cypress
* reserves the right to make changes to the Software without notice. Cypress
* does not assume any liability arising out of the application or use of the
* Software or any product or circuit described in the Software. Cypress does
* not authorize its products for use in any products where a malfunction or
* failure of the Cypress product may reasonably be expected to result in
* significant property damage, injury or death ("High Risk Product"). By
* including Cypress's product in a High Risk Product, the manufacturer
* of such system or application assumes all risk of such use and in doing
* so agrees to indemnify Cypress against all liability.
*******************************************************************************/
 
/******************************************************************************
* TESAIoT Platform Extensions
*******************************************************************************
* This file has been extended through collaboration between:
* - Infineon Technologies AG (OPTIGA Trust M expertise)
* - TESAIoT Platform Developer Team (AIoT platform integration)
*
* Extensions added:
* - Certificate validation and expiry checking functions
* - CSR generation with OPTIGA Trust M integration
* - Protected Update data set helpers
* - TESAIoT Platform-specific certificate lifecycle management
*
* Original work Copyright 2020-2025 Cypress Semiconductor Corporation (Infineon)
* Extensions developed jointly by Infineon Technologies AG and TESAIoT Team
*
* This file is part of the TESAIoT AIoT Foundation Platform, developed in
* collaboration with Infineon Technologies AG for PSoC Edge E84 + OPTIGA Trust M.
*
* Contact: Wiroon Sriborrirux <sriborrirux@gmail.com>
*******************************************************************************/
 
#ifndef OPTIGA_TRUST_HELPERS_H_
#define OPTIGA_TRUST_HELPERS_H_
 
#include <stdlib.h>
#include <stdio.h>
#include <stdbool.h>
#include "include/common/optiga_lib_common.h"
#include "include/optiga_crypt.h"
#include "include/optiga_util.h"
#include "include/pal/pal_os_timer.h"

typedef struct optiga_protected_update_manifest_fragment_configuration {
    uint8_t manifest_version;
    const uint8_t *manifest_data;
    uint16_t manifest_length;
    const uint8_t *continue_fragment_data;
    uint16_t continue_fragment_length;
    const uint8_t *final_fragment_data;
    uint16_t final_fragment_length;
} optiga_protected_update_manifest_fragment_configuration_t;

typedef struct optiga_protected_update_data_configuration {
    uint16_t target_oid;
    const uint8_t *target_oid_metadata;
    uint16_t target_oid_metadata_length;
    const optiga_protected_update_manifest_fragment_configuration_t *data_config;
    const char *set_prot_example_string;
} optiga_protected_update_data_configuration_t;
 
 
 
void read_certificate_from_optiga(uint16_t optiga_oid, char * cert_pem, uint16_t * cert_pem_length);
 
void read_trust_anchor_from_optiga(uint16_t oid, char * cert_pem, uint16_t * cert_pem_length);
 
void write_data_object (uint16_t oid, const uint8_t * p_data, uint16_t length);
 
bool optiga_trust_init(void);
 
/* Proves that the private key in key_oid belongs to the certificate in cert_oid,
 * by signing a challenge in the chip and verifying it against the certificate's
 * public key. 1 = match, 0 = mismatch, negative = could not run.
 * Not used by the connect path — reachable as optiga.verify_pair(). */
int optiga_verify_cert_key_pair(uint16_t cert_oid, uint16_t key_oid);
 
/* Put a data object's change access condition back to "an ordinary write is
 * accepted", clearing the Int(anchor) that Protected Update set. Reversible by
 * design — see the definition. */
bool optiga_clear_manifest_lock(uint16_t target_oid);

typedef struct {
    uint16_t oid;
    bool     valid;
    uint16_t manifest_anchor_oid;  
    uint32_t payload_version;      
    uint16_t used_size;            
    uint8_t  data_type;            
} optiga_slot_info_t;
 
bool     optiga_slot_info(uint16_t oid, optiga_slot_info_t *info);
bool     optiga_slot_info_raw(uint16_t oid, uint16_t *anchor, uint32_t *version,
                              uint16_t *used, uint8_t *type);
uint16_t optiga_slot_manifest_anchor(uint16_t oid);
uint32_t optiga_slot_payload_version(uint16_t oid);
 
/* Opens the OPTIGA application, recovering from one left open by a previous
 * host session. Returns false when the secure element is unusable. */
bool optiga_trust_open_application(void);
 
/* Releases one reference taken above; the application closes only when the last
 * owner lets go. */
void optiga_trust_close_application(void);
 
void optiga_util_callback(void *context, optiga_lib_status_t return_status);
 
/* Global async status - can be polled by other modules for operation completion */
extern volatile optiga_lib_status_t optiga_lib_status;
 
void trustm_close(optiga_util_t *util);
 
optiga_lib_status_t trustm_gen_ecc_keypair(uint16_t optiga_key_id, optiga_ecc_curve_t curve_id,uint8_t key_usage, bool export_private, uint8_t * pub, uint16_t *pub_len);
 
/* Verify a store-signed Edge AI model blob, in the secure element.
 *
 * Returns 1 when the signature is good; negative otherwise, and the codes are
 * distinct on purpose -- "no signature", "malformed", "the chip said no" and
 * "could not ask the chip" call for different responses, and collapsing them
 * would make a bus failure look like an attack. See ipc_model_stage_defs.h. */
int optiga_verify_staged_model(const uint8_t *blob, uint32_t blob_len);
 
optiga_lib_status_t trustm_ecdsa_sign(optiga_key_id_t oid, const uint8_t *digest, uint16_t digest_len, uint8_t *sig_raw, uint16_t *sig_raw_length);
 
bool optiga_read_factory_uid(char *uid_hex, size_t uid_hex_len);
 
bool optiga_read_factory_certificate(char *cert_pem, uint16_t *cert_pem_length);
 
bool optiga_read_device_certificate(char *cert_pem, uint16_t *cert_pem_length);
 
bool trustm_use_factory_certificate(void);
 
bool trustm_use_device_certificate(void);
 
bool optiga_generate_device_keypair(uint16_t key_oid, uint8_t *public_key_der, uint16_t *public_key_der_len);
 
/*******************************************************************************
 * TESAIoT Platform Extensions - Types and Functions
 *******************************************************************************
 * REFACTORING NOTE (2026-01-18):
 * The following types and functions (lines 139-217) are TESAIoT extensions
 * added to this Infineon file. They are candidates for extraction to a
 * separate file: tesaiot_cert_utils.h (planned for v0.9)
 *
 * TESAIoT-specific additions:
 * - cert_validation_result_t struct
 * - cert_source_t enum
 * - optiga_check_certificate_validity()
 * - optiga_get_cert_days_until_expiry()
 * - optiga_generate_csr_pem()
 *
 * See: IMPROVEMENTS/2026.01/01_header_organization_analysis.md
 ******************************************************************************/

typedef struct {
    bool is_valid;              
    bool is_expired;            
    bool cert_exists;           
    uint32_t days_until_expiry; 
    time_t valid_from;          
    time_t valid_to;            
    char subject[256];          
    char issuer[256];           
} cert_validation_result_t;

typedef enum {
    CERT_SOURCE_DEVICE = 0xE0E1,    
    CERT_SOURCE_FACTORY = 0xE0E0    
} cert_source_t;

bool optiga_check_certificate_validity(uint16_t oid, cert_validation_result_t *result);

uint32_t optiga_get_cert_days_until_expiry(uint16_t oid);
 
bool optiga_generate_csr_pem(uint16_t key_oid, const uint8_t *public_key_der, uint16_t public_key_der_len, const char *subject, char *csr_pem, size_t csr_pem_len);
 
/* Where write_device_certificate_and_verify() puts the certificate: Cert 2,
 * the slot this project's pre-provisioning plan pairs with ECC Key 2 (0xE0F1).
 * Defined here as well as in the .c so callers can verify the pair afterwards
 * without hardcoding the number a second time. */
#ifndef DEVICE_CERTIFICATE_OID
#define DEVICE_CERTIFICATE_OID (0xE0E1U)
#endif
 
optiga_lib_status_t write_device_certificate_and_verify();
optiga_lib_status_t protected_update(uint16_t trust_anchor_oid, uint16_t target_key_oid, uint16_t confidentiality_oid);

optiga_lib_status_t test_metadata_operations(void);
 
#endif /* OPTIGA_TRUST_HELPERS_H_ */