Steps to register a prefix and code signing certificate to obtain a Tachyon license
Decide your Instruction Name Prefix
You should choose a prefix that will be used to name all the instructions created by your TIMS developers.
By default, TIMS will use your logged-on account's domain name as your chosen prefix.
Obtain a code signing certificate
Tip
Use this step if you and your fellow TIMS developers do not already have a code signing certificate.
Skip this step if you already have a PFX; the PFX is also useful way to share the certificate with each of your developers.
Log on to the 1E Server using the 1E Server installation account.
Start Certificate Manager for Local User (CertMgr.msc) and request (enroll) a new code signing certificate, ensuring you set the option to allow the private key to be exported.
Warning
Enrolling on the Server using the Server installer account means only that account will be able to access the certificate on the Server, and perform the remaining steps including signing instructions using TIMS. You will need to export the certificate with private key if you need to use the certificate elsewhere or others need access it.
This is why you must enable the Export Private Key when you enroll. If you don't then you will have to start the entire process over again to enroll a new certificate and register it in Tachyon.
See note on Certificate permissions for more details.
Make a backup copy of your certificate by exporting the code signing certificate as a PFX (including private key) and make the private key exportable. When exporting you must specify a password, which you must protect. If you do not specify a password, then the private key will be accessible only to the user accounts, AD groups and computers which you specified.
Certificate permissions
In some cases, the private key may only be accessible to specific users and not accessible to the installer account - in this case you will need to do the first steps (as well as the steps that involve TIMS) on a developer's PC using the developer's account. You may also be required to import into the Local User store instead of the Local Computer store.
When using Microsoft Certificate Manager to request a new certificate then you must request using Local User instead of Local Computer because this is a requirement of Microsoft's code signing template.
To share the certificate you will need to export it and then provide it to each user to import into their Local User store, or into their Local Computer store, where it will be accessible to all users of the computer.
Tip
The default template for enrolling a code signing certificate does not automatically have Make private key exportable enabled. When enrolling using the Microsoft wizard you must click on the Properties button and in Certificate Properties select the Private Key tab and enable the option.
Import the certificate to the local computer store
Tip
This step ensures the signing certificate is in a Personal store that is accessible by TIMS.
Use the PFX to import the certificate into the Local Computer Personal certificate store on the 1E Server, ensure that the option to make the private key exportable is not set.
Note
If you enrolled your own certificate, then exporting a PFX and then importing back into the Local Computer store allows everyone on the Server to access the certificate and use it to sign instructions in TIMS. By not allowing others to export the private key, you prevent them sharing it with others and you can decide who to give your PFX file to.
If you were given a shared PFX and you are unable to import into the Local Computer store, then import to your Local User store. Each user that needs to use TIMS to sign instructions on the Server will also need to import the PFX into their own Local User store on the Server.
Start Certificate Manager and locate the certificate. Open the certificate and confirm you can see it "has a private key that corresponds to this certificate" (see screenshot below).
Exporting the Signing Certificate
You can export the signing certificate with or without the private key. Exporting with a private key (as a PFX) is required only when sharing the certificate with other developers on their machines. You should save the export with a password, or ensure it is permissioned.
Your code signing certificate private key is a valuable secret. If an attacker were to get a copy of the certificate and its private key, they could sign their own instruction XML files. Of course, they would still need to compromise the Tachyon server in order to upload them, and the Tachyon Explorer in order to execute them, but nonetheless, you should treat code signing certificates as protected company assets.
The public key is required by the Tachyon Server. If the certificate is not already present in the Local Computer store, then you will need to export the public key (as a CER file) and import on the Tachyon Server.
1E requires only the thumbprint, or a CER file.
Copy the certificate to the Trusted Publishers store on the 1E Server
Tip
This step is required to allow you to import instructions into Tachyon that have been signed using the certificate; if you prefer this step can wait until after the next step.
Copy the signing certificate from the Personal Store to the Trusted Publishers store.
Reset IIS so that the Consumer API can cache the new certificate.
Install TIMS onto the 1E Server
Tip
This step confirms you can see the new signing certificate in TIMS. It also means that at least this certificate can be used to sign instructions using TIMS on the server. You may already have installed TIMS.
Logon to the 1E Server as the installer account.
Install TIMS.
Start TIMS using the installer account.
Select the signing certificate (Code Signing → Select signing certificate).
View the selected signing certificate (Code Signing → View selected signing certificate).
Change to Always sign (Code Signing → Always sign).
In the Instruction Definition pane, note the default name of the instruction. This will be <YourDomainName>-NewInstruction-1.
Edit and Sign the HelloWorldTest instruction
Tip
This step confirms you can create a sign an instruction in TIMS. Later, you will import this signed instruction into Tachyon.
Download or copy the test instruction XML to a folder on the 1E Server (this instruction is not already signed).
Start TIMS using the installer account.
Open the test instruction (File → Open → select XXXX-HelloWorldTest.xml).
Click Run, to show the Message Hello World in the Results pane.
In the Instruction Definition pane, change the instruction name so that XXXX is changed to your chosen prefix.
Save the updated test instruction (File → Save As) and confirm the XML file name uses your chosen prefix.
At the top of the instruction pane, confirm you can see the 'This instruction definition was signed by <your certificate>'.
Note
If you gave your signing certificate a friendly name, you will see that here, otherwise you will see the subject name of the certificate.
Warning
If you are testing multiple prefixes or signing certificates then you must make the instruction unique and recognisable, by changing the Instruction Name and ReadablePayload.
XXXX-HelloWorldTest.xml
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<InstructionDefinition
Author="1E"
Name="XXXX-HelloWorldTest"
ReadablePayload="Get Hello World Test Message"
Description="Reply Hello World"
InstructionType="Question"
InstructionTtlMinutes="10"
ResponseTtlMinutes="10"
Version="1.0"
xmlns="http://schemas.1e.com/Tachyon/InstructionDefinition/1.0">
<Payload><![CDATA[SELECT "Hello World" AS Message;]]></Payload>
<SchemaJson><![CDATA[[
{
"Name": "Message",
"Type": "string",
"Length": 32
}
]]]></SchemaJson>
</InstructionDefinition>Import the HelloWorldTest instruction into 1E
Tip
This step confirms you can import signed instructions. More specifically, that the Tachyon Server is able to see the certificate in the Trusted Publishers store (and the updated Consumer Web.Config file has taken effect).
Using the installer account, start a browser, connect to 1E Endpoint Troubleshooting, and navigate to the Instruction Sets admin page.
Locate the XML file in the folder where you saved the instruction, and drag it onto the drop zone of the Instruction Sets admin page.
Confirm the instruction uploaded without error.
Confirm the instruction is not licensed.
Get the Thumbprint of the code signing certificate and send the Thumbprint and Prefix details to 1E
Tip
By this point we know the certificate can be used by TIMS, and will allow your own signed instructions to be imported into Tachyon; the remaining steps will update your license with your prefix and code signing thumbprint so that you can run your signed instructions. In the meantime you can carry on using TIMS to develop and test other instructions.
Get the thumbprint of your signing certificate.
Look at the properties of the code signing certificate, Details tab, and find the Thumbprint (see screenshot).
Copy this to notepad, remove the spaces, and convert to UPPERCASE.
Get your chosen prefix.
Email them to SalesOps@1e.com.
Currently, the licensing process takes around 3 days. You will receive an email notification that your license has been updated.
Warning
The application of the license will only work automatically if your Tachyon Server is connected to the Internet, so that it can re-activate its updated license directly with the 1E License server.
Confirm your 1E Server License has been updated
Tip
This step confirms the server has had its license automatically updated.
After you have received the license email notification.
Using the installer account, start a browser, connect to Tachyon Explorer, and navigate to the License Info admin page.
Note
The License Info page will auto-refresh every 10 minutes so you may have to wait for the information to update.
Check that the new license has been applied, these instructions will work if you have only registered one Prefix with 1E:
Under the Products heading expand Item 2 the Name will be TachyonExplorer.
Under Item 2 expand Instructions then expand Item 3.
Confirm that the Thumbprint and Pattern (Prefix) that you sent in the email to 1E have been added to the license.
Note
The License info page (and the LIC file it is based on) uses the term pattern to mean the same thing as prefix.
Confirm the HelloWorldTest instruction is licensed
Tip
This step confirms you can run signed instructions. More specifically, that the Tachyon Server license has been updated to include the thumbprint of your signing certificate, and your chosen prefix.
Using the installer account, start a browser, connect to 1E Endpoint Troubleshooting, and navigate to the Instruction Sets admin page.
Locate the instruction you imported earlier and confirm it is now licensed.
Optionally navigate to the 1E home page, and run the instruction. Type Hello and select the Hello World instruction; set coverage to a specific test machine.
Delete the HelloWorldTest instruction
Tip
This step avoids issues that may occur if you re-import the same instruction at a later date using the same ReadablePayload but a different prefix and signing certificate; if you did not delete then importing the same instruction with a different name will result in two instructions with the same ReadablePayload, rather than updating the instruction.
Connect to 1E Endpoint Troubleshooting and navigate to the Instruction Sets admin page.
Delete the instruction you imported earlier.