Signing and Validation of TSEP signatures [Reason: Mandatory legislation changes]

Definition: Signing provides a mechanism for end users to verify the legitimacy and origin of the content they are consuming

Due to mandatory industry regulations changes, see Code signing changes in 2023 (digicert.com), the current way of signing files - which would rely on users holding private keys outside FIPS compliant devices - is effectively not possible after May 2023. 

Current Implementation

Relies on a custom encryption algorithm that requires physically passing a private key (pfx) to the TSEP tooling. Going forward, PFX cannot be trusted to be available since that's the sole purpose of the change in regulation where private keys must at all time be included in stores compliant with the regulation and effectively non exportable.

The second aspect of the current implementation is that the current implementation relies on .net full framework and windows apis which are not available in .NET. Making it limited where it actually can run.

Removal of current signing option

TSEP is simply a zip file with content, the proposal would replace the current implementation, and delegate the signing to external tools like Nuget, or AzureSignTool which already do a better and more comprehensive signing support. 

Technically, a signature file is calculated from the hash key and added to the package itself. Confirmation of the validity is done by ensuring that the final hash key and the signature file match.

This method ensures that the current signing requirements are met while using more standard industry methods. See Annex 1. For signing examples with the Nuget tool.

Validation of signature

Validation is done using standard Nuget apis, which provides validity of the file and origin of the file. Signature will be present in the relevant UIs available for the users

[Removal] : Warning message for validity of signature in current implementation is removed from all supported versions. Instead, if a signature exists the UI simply shows it. If it doesn’t, the UI is showing “TSEP does not contain a signature”.

Signing Recommendation

Going forward we recommend Trusted Signing documentation | Microsoft Learn to sign TSEP in a quick and cost effective way. In practice the steps to use this service are

1. Microsoft checks your identity and users can order either a basic subscription  at 9.99usd per month or premium at 99.9usd per month
2. Users generate their one signing code certificates directly in azure and assign permissions to users that are allowed to sign.

To use the service, we suggest using the NuGet Gallery | AzureTrustedSignTool 1.0.0 since it automates the all process. To sign a TSEP run the following commands:

1. dotnet tool install --global AzureTrustedSignTool
2. dotnet tool install Knapcode.CertificateExtractor --global
3. dotnet tool install --global sign --prerelease
4. AzureTrustedSignTool sign --filePath --accountname AccountName --profilename ProfileName

This wrapper internally uses dotnet/sign: Code Signing CLI tool supporting Authenticode, NuGet, VSIX, and ClickOnce (github.com) and if you can’t use Azure Trusted Signing service, you can directly use dotnet/sign and use different methods like hardware signing keys. In this case, you likely need to rename the .tsep file to .nupkg perform the signing and then rename it back to .tsep - remember that tsep is just a zip file, same as nuget package files.

Command line refactorings [Reason: Technical debt and end user usage simplification]

Append switch [Removal]

Why: there is very little benefit for end users to allowing customizing the output file, when a rename can be an issue after production

Benefis: Standardization allows less maintenance regarding handling of produced content.

Implementation: -a option removed and now ignored - warning show -, output files are produced in format of ProductId.ProductVersion.tsep. Example ConcretTools.1.0.2.tsep

Warn on missing Product Type [Removed and make it mandatory]

Why: current TSEP files all have product type, so we can enforce it from the tooling side.

Benefis: less user options on command line, simplification

Implementation: Warning simply removed and TSEPs will fail to create if product type not defined

Output Path behavior [-o option no longer required and no longer requires a full path]

Why: -o option was mandatory causing additional complexity and confusion to end users

Benefits: easy to use, one less option to input

Implementation: when omitted, the TSEP will be created in the same location of the manifest xml file. 

Verbose switch [New : --verbose]

Why: current implementation lacking better command line feedback

Benefits: errors can be immediately visible after the tool runs, simplifies user experience and allows automated builds to be diagnosed faster without the need to download and open external logs.

Implementation: Standard logger used along with File Logger, all messages that go to log are visible in the command line. By default some improvements have been made also so that critical errors are always displayed on the command line output for quicker feedback.

For the future: Evaluate the need for a log file. Redirect can be done with verbose to get the full information as needed. But in principle none of those are actually needed since information is readily available in the console to the user. 

Logging conformance  [Reason: Technical debt and end user usage simplification]

To improve support to our users, logs generated during installation of TSEP by Tekla Structures will be saved in %LOCALAPPDATA%\Trimble\Tekla Structures\2025.0 Daily\Logs. They will also be rotated by process id, and 5 logs will always be available in logs folder. 

Batch builder will continue to save logs in the same location as before, in the location of the generated TSEP file. Builder will display the log generated during creation of TSEP

TSEP Shortcuts Removal [Reason: Technical debt and end user usage simplification]

From evaluation it was gathered that shortcuts are not present in any of the extensions we ship to customers. This served as the decision factor to remove shortcuts from TSEP.

Why was it removed: Shortcuts were using COM components which have earlier been deprecated in Tekla Structures. Also the current implementation was non portable and cannot be replicated in .NET therefore making it not suitable in many different targets we would be using TSEP

Implementation: All code related with Shortcuts has been removed, warning is displayed in logs that these features are no longer supported.  

Standardization of TSEP version - Sem Version 2.0 compliance  [Reason: Standardization]

TSep 2025 will support version scheme of X.Y.Z-OPTIONALALPHA (Major.Minor.Patch), see Semantic Versioning 2.0.0 | Semantic Versioning (semver.org), 

Limitations for the version align with standard. And limitations of current implementation removed, such as max version of 255, non Path numbers support. 

Why: Standardization and support for patch versions and pre release versions.

Implementation 1: No limitations are now forced to the version except if the version does not conform with SEM version2.0. Upgrade path for extensions follows the same guidelines as in standard. 

Implementation 2: The different tools will now output file names more in accordance with this. Example if version is 5.0.1 the TSEP will be called PrecastProductionExport.5.0.1.tsep

TSEP environment isolation - environment in clouds

Currently the TSEP system installs directly all content under Tekla default system files which causes general issues for our own default files and also makes it complicated to ensure a consistent install/uninstall experience for extensions. For example, if a TSEP is installed before an environment exists, some critical files provided by the extension might be left out and never became available when the environment then installs, users first need to install the environment and only after that TSEP can be installed. 

Applications and plugins can also be installed in the default extensions folder without limitation which in practice can cause clashes between plugins or at least a wider effort to ensure something is running properly.

The new implementation in TSEP 2025 - Launcher isolated mode

Launcher requires more control over how extensions are loaded, in 2025 and specifically on launcher TSEPs are now loaded from an isolated environment in ~/.tsep folder. 

Extensions are each deployed into their own folders and the launcher generates the environment definitions via bypass to support its loading. 

The process is illustrated in the next diagram

Role injection mechanism

TSEP will auto detect advanced options provided by each extensions and build a dictionary of them that later are injected into the role file which TS uses during initialization

A temporary role file will be created for each execution in the Runtime folder in localappdata. 

Advance options are injected in the end of the role file, with the following format set:

XS_APPLICATIONS_PATH=%XS_APPLICATIONS_PATH%;c:\users\jcosta1\.tsep\cimsteelimportexport.2.1.0\environments\common\extensions\rpcapps

Tekla Structures will simply extend the folders where things get read accordingly to ensure all extensions are correctly handled.

Advanced options can hold size_t characters or 232 - 1 or 4294967295 which should suffice.

Tekla Warehouse Download Support

Tekla Warehouse is only supported in the new Tekla Launcher - the reason for this is  we are required to know all needed configuration before a model can be opened. This includes, environment information and model information. 

Having this information available before a model is open we can download all needed files the model requires to be more complete, and it ensures all users using the model also use the same files when modeling in TS.

The new TSEP recipe warehouse download file - tsep-dependencies.json

Each environment, model or model templates can provide a tsep-dependencies.json placed in the root of each folder file with the following format:

{
  "name": "ModelName",
  "version": "1.0",
  "tsepDependencies": [
    {
      "name": "ToolName",
      "version": "^X.Y.z",
      "guid": "ucf5de403-9487-42ba-8333-dab5302ed449"
    },
    {
      "name": "ToolName2",
      "version": "X.Y.Z",
      "guid": "u572366a7-aa30-42b0-96c8-53ac730c793e"
    },
    {
      "name": "ToolName3",
      "version": "latest",
      "guid": "u572366a7-aa30-42b0-96c8-53ac730c793e"
    }
  ]
}

The name and version before the tsep deps are user defined fields meant only for user information. They are not used during download.

tsepDependencies:

Name:

• This is just a field for users to better organize their files and track the guid and the tsep name - this is not used for retrieving the package

Guid:

• This is the guid of a collection in Warehouse, it can be found from the url in the browser when you open a relevant TSEP package. This is a mandatory field and download will not work unless this is defined correctly

Version :

• ^X.Y.z - means it will update to latest version of the current Major X
• X.Y.Z - this is exact version
• Latest - means the latest version of any version will be used

Note: We follow strictly sem version 2.0 to download the defined version the definition file. Therefore Tekla Warehouse contains versioning schemes that do not follow sem ver 2.0 it might be possible that the incorrect version will be downloaded. Example, if the tseps have earlier version like 2022* and changes to use a versioning starting from 1.x then using “latest” will download the incorrect package. It is recommended to review the versioning of the extensions and possibly enforce version immutability - a new feature in Tekla Warehouse. 

TSEP package types [new]

Extensions packages [Already in earlier versions]

These are user controlled packages, they can be imported by the user and are deployed to c:\ProgramData\Trimble\TeklaStructures\Version\Environment. This folder is used in isolation mode and users can use it to override TSEPs that may exist in environment, model, organization. 

Installing these folders from the warehouse is possible by using the Warehouse service plugin. Or downloading manually from Warehouse and using normal TSEP dispatcher to install to Tekla Structures.

Organization packages [New]

Organizations, small or big, can after 2025 define a single folder location where the TSEP subsystem will read and synchronize with user computers a defined set of extensions. 

This is fully supported in all different operating methods, like in launcher, or in the legacy startup TS operation. 

To use this, in users.ini file, orgs admins or users can define XS_TSEP_TO_BE_INSTALLED_ORG_DIR and point to an existing network shared folder accessible to all users.

Environment packages [New]

Packages defined in the environment folder under tsep dep json file will be downloaded and used in isolated mode by the new Tekla Launcher. No support in legacy mode exists, since Tekla Structures is unable to perform these operations while loading a model.

These packages can be used to customize a given user environment more easily. 

Model Packages [New]

Similarly to the environment packages, users can also have a tsep definition file in the model folder. While opening a model using the new Tekla Launcher we will download and install the tsep files and use them for the opened model.

Model Sharing is fully supported, and recommended. Since the tsep definitions are uploaded to the service ensure everyone uses the same set of extensions

Model Templates are also supported, users can have a tsep definition in the template and bootstrap new models with a certain set of extensions 

Constraints and Package Conflict Resolution

TSEP system will install packages from multiple locations, in case the same package exists with different versions then TSEP will always pick the latest version. This ensures that users can overwrite the organization setup in case they need to test a new version.

Annex 1 : Nuget signing examples

Signing NuGet Packages | Microsoft Learn