WPC Provisioning API

WPC Provisioning API#

WPC provisioning consists of two major parts:

Service adapter
Target adapter

Service adapter’s responsibility is to provide WPC Certificate chain. Target adapter is then responsible to injecting said chain into the target.

Out-of-the-box SPSDK provides one Service adapter using EL2GO and one Target adapter using MBoot/BLhost.

WPC Service adapter using EL2GO#

class spsdk.wpc.service_el2go.WPCCertificateServiceEL2GO(url, qi_id, api_key, family, timeout=60)#

Bases: WPCCertificateService

EdgeLock2GO adapter providing WPC Certificate Chain.

Initialize the EL2GO adapter.

Parameters:

url (str) – URL to EL2GO WPC service
qi_id (Union[str, int]) – Customer’s Qi ID
api_key (str) – Customer’s EL2GO REST API access token
correlation_id – Customer’s EL2GO Correlation ID, defaults to None
timeout (int) – REST API request timeout in seconds

classmethod from_config(config_data, search_paths=None)#

Create instance of this class based on configuration data.

__init__ method of this class will be called with data from config_data. To limit the scope of data, set cls.CONFIG_PARAMS (key in config data).

Parameters:

config_data (dict) – Configuration data
search_paths (Optional[list[str]]) – Paths where to look for files referenced in config data, defaults to None

Return type:

Self

Returns:

Instance of this class

classmethod get_validation_schema()#

Get JSON schema for validating configuration data.

Return type:: dict

get_wpc_cert(wpc_id_data)#

Obtain the WPC Certificate Chain.

Return type:: WPCCertChain

identifier: str = 'el2go'#

WPC Target adapter using MBoot#

class spsdk.wpc.target_mboot.WPCTargetMBoot(family, **kwargs)#

Bases: WPCTarget

WPC Target adapter using MBoot interface.

Initialize WPC Target adapter.

Parameters:

family (str) – Target family name
kwargs (str) – Dictionary containing interface definition. Examples: “port”: “com4”, “usb”:”0x1fc9:0x014f”, “plugin”: “identifier=my_plugin,param1=value1”

get_low_level_wpc_id()#

Get the lower-level WPC ID from the target.

Return type:: bytes

classmethod get_validation_schema()#

Get JSON schema for validating configuration data.

Return type:: dict

identifier: str = 'mboot'#

sign(data)#

Sign data by the target.

Return type:: bytes

wpc_insert_cert(cert_chain, reset=True)#

Insert the WPC Certificate Chain into the target.

Parameters:

cert_chain (WPCCertChain) – Certificate chain to insert into the target
reset (bool) – Perform reset if the target requires it. With this option you may disable required reset (for testing purposes)

Raises:

SPSDKWPCError – Error during certificate chain insertion

Return type:

bool

Returns:

True if operation finishes successfully

Creating your own WPC Service/Target adapters#

To create your own Service adapter, create new class derived from WPCCertificateService. To create your own Target adapter, create new class derived from WPCTarget.

Service is responsible to provide WPC Certificate Chain as WPCCertChain via get_wpc_cert(). Target adapters then injects said certificate chain into the target using wpc_insert_cert().

Both WPCCertificateService and WPCTarget base-classes are using common approach regarding regarding instantiation via configuration data defined in BaseWPCClass. Each derived class should implement get_validation_schema(). This method should return a JSON validation schema which is used for both configuration template creation and validating configuration data specific for each class. Derived class can be then instantiated via from_config() Method validates configuration data and passes the data into the __init__ method

To see a practical example on how to create your own Service, please see Creating a custom WPC Service adapter

class spsdk.wpc.utils.WPCCertificateService(family)#

Bases: BaseWPCClass

Base class for service adapters providing the WPC Certificate Chain.

Initialize WPC target.

Parameters:: family (str) – Target family name
Raises:: SPSDKWPCError – Family is not supported as WPC target

CONFIG_PARAMS: str = 'service_parameters'#

abstract get_wpc_cert(wpc_id_data)#

Obtain the WPC Certificate Chain.

Parameters:: wpc_id_data (bytes) – WPC ID provided by the target
Return type:: WPCCertChain
Returns:: WPC Certificate Chain

class spsdk.wpc.utils.WPCTarget(family)#

Bases: BaseWPCClass

Base class for adapters providing connection to a target.

Initialize WPC target.

Parameters:: family (str) – Target family name
Raises:: SPSDKWPCError – Family is not supported as WPC target

CONFIG_PARAMS: str = 'target_parameters'#

abstract get_low_level_wpc_id()#

Get the lower-level WPC ID from the target.

Return type:: bytes

get_wpc_id()#

Get the WPC ID from the target.

Return type:: bytes

sign(data)#

Sign data by the target.

Return type:: bytes

abstract wpc_insert_cert(cert_chain)#

Insert the WPC Certificate Chain into the target.

Parameters:: cert_chain (WPCCertChain) – Certificate chain to insert into the target
Raises:: SPSDKWPCError – Error during certificate chain insertion
Return type:: bool
Returns:: True if operation finishes successfully

class spsdk.wpc.utils.BaseWPCClass(family)#

Bases: ABC

Base abstract class for both WPC Service and Target.

Initialize WPC target.

Parameters:: family (str) – Target family name
Raises:: SPSDKWPCError – Family is not supported as WPC target

CONFIG_PARAMS: str#

classmethod from_config(config_data, search_paths=None)#

Create instance of this class based on configuration data.

__init__ method of this class will be called with data from config_data. To limit the scope of data, set cls.CONFIG_PARAMS (key in config data).

Parameters:

config_data (dict) – Configuration data
search_paths (Optional[list[str]]) – Paths where to look for files referenced in config data, defaults to None

Return type:

Self

Returns:

Instance of this class

classmethod get_providers()#

Get available WPC Service/Target Providers.

Return type:: dict[str, Type[Self]]

classmethod get_supported_families()#

Get family names supported by WPCTarget.

Return type:: list[str]

classmethod get_validation_schema()#

Get JSON schema for validating configuration data.

Return type:: dict

identifier: str#

legacy_identifier_name = 'NAME'#

classmethod validate_config(config_data, search_paths=None)#

Validate configuration data using JSON schema specific to this class.

Parameters:

config_data (dict) – Configuration data
search_paths (Optional[list[str]]) – Paths where to look for files referenced in config data, defaults to None

Return type:

None

class spsdk.wpc.utils.WPCCertChain(root_ca_hash, manufacturer_cert, product_unit_cert)#

Bases: object

WPC Certificate Chain.

root_ca_hash: bytes#

manufacturer_cert: Certificate#

product_unit_cert: Certificate#

get_puk_offset(pu_cert_only=False)#

Get offset to the Product Unit Certificate public key.

Parameters:: pu_cert_only (bool) – Get the offset relative to start of the Product Unit Certificate, defaults to False
Return type:: int
Returns:: Offset to the Product Unit Certificate public key.

get_rsid_offset(pu_cert_only=False)#

Get offset to the Revocation Sequential Identifier.

Parameters:: pu_cert_only (bool) – Get the offset relative to Product Unit Certificate, defaults to False
Return type:: int
Returns:: Offset to the Revocation ID.

get_rsid()#

Get the Revocation Sequential Identifier.

Return type:: bytes

export()#

Export WPC Certificate Chain into bytes.

Return type:: bytes

classmethod parse(data)#

Parse data into WPC Certificate Chain object.

Return type:: Self

classmethod load(path)#

Load WPC Certificate Chain from a file.

Parameters:: path (str) – Path to a file
Return type:: Self
Returns:: WPC Certificate Chain object

save(chain_path=None, root_hash_path=None, manufacturer_path=None, product_unit_path=None)#

Save WPC Certificate Chain into file(s).

Parameters:

chain_path (Optional[str]) – Path where to store the whole chain, defaults to None
root_hash_path (Optional[str]) – Path where to store only the WPC Root Cert hash, defaults to None
manufacturer_path (Optional[str]) – Path where to store only the Manufacturer Certificate, defaults to None
product_unit_path (Optional[str]) – Path where to store only the Product Unit Certificate, defaults to None

Return type:

None

Utilities for generating/validating configuration files#

spsdk.wpc.utils.generate_template_config(family, service, target)#

Generate configuration YAML template.

Parameters:

family (str) – Name of the target family
service (Type[WPCCertificateService]) – WPC Service adapter class
target (Type[WPCTarget]) – WPC Target adapter class

Return type:

str

Returns:

Configuration template in YAML format

spsdk.wpc.utils.check_main_config(config_data, search_paths=None, scope=ConfigCheckScope.FULL)#

Check top layer of config data.

Parameters:

config_data (dict) – Configuration data from config file
search_paths (Optional[list[str]]) – List of paths where to look for files and directories in config data, defaults to None
scope (ConfigCheckScope) – Scope of the config file check

Raises:

SPSDKError – Configuration contains invalid data or some data is missing

Return type:

None

WPC Provisioning API

Contents

WPC Provisioning API#

WPC Service adapter using EL2GO#

WPC Target adapter using MBoot#

Creating your own WPC Service/Target adapters#

Utilities for generating/validating configuration files#