Using the 1E PowerShell Toolkit on non-Windows platforms
Special considerations using the 1E PowerShell Toolkit Tachyon PowerShell toolkit from a non-Windows platform.
Caution
Only preliminary testing has been conducted, and only on Debian 11.5 at this stage. It is expected that other Linux distributions that allow .NET to be installed should function similarly. MacOS has not been tested yet.
Authentication using platform-neutral authentication via a JWT, and subsequent API calls appear to function correctly.
Interactive platform-neutral authentication (where the browser is automatically invoked by the toolkit) also works, but note that you cannot be ‘root’ when you do this, as Debian (and possibly other distributions) won’t allow the browser to be invoked in this situation.
About non-Windows platforms
The PowerShell toolkit will run on PowerShell 6.x onwards as well as legacy PowerShell.
The main changes that will affect the toolkit are as follows.
NTLM authentication does not function
Attempting to make a connection to a Tachyon server over SSL with NTLM authentication does not work. This is a known issue with PowerShell Core but it’s not clear if Microsoft have any plans to address it.
Linux files are case-sensitive
If you are unable to load the toolkit module with import-module, check that the two files match in case, they should be:
PSTachyonToolkit.psd1
PSTachyonToolkit.psm1
On Windows, filenames are not case-sensitive, but if the case doesn’t match exactly as shown on Linux, you cannot load the toolkit module.
Certificates
Linux does not have a certificate store that works the way it does on Windows. However, the .NET environment under Linux does emulate the Windows certificate store. It does so by storing certificates in a folder tree whose structure is not specified - you should never interact directly with the files. However, the System.Security.Cryptography.X509Certificates namespace does support certificate storage and retrieval operations that function pretty much as they would in a Windows environment.
This includes all the core cryptographic operations that are required by platform-neutral authentication.
However, PowerShell on Linux does not support the certificate store as a virtual drive (that is, prefixed with cert:). This means that you have to call the underlying .NET assemblies to interact with the certificate store. Once you have retrieved an X509Certificate, all remaining operations work the same on that certificate.
Version 1.1.32 and later of the PowerShell toolkit transparently interact with the certificate store on Linux by detecting the OS that the toolkit is running on.
Note
Version 1.1.33 and later of the PowerShell toolkit supports retrieval of certificates from the Azure Key Vault as an alternative to retrieving certificates from the local certificate store.
For more information, see Accessing Certificates from the Azure Key Vault.
Storing certificates
PowerShell on Linux does not support the new-selfsignedcertificate cmdlet (or the other certificate management cmdlets) but there is a downloadable .NET utility that can be used to import .PFX files into the .NET certificate store on Linux. For more information, see medium.com/gsoft-tech/certificates-in-net-core-on-linux-and-docker-29b3d5f09cd6.
To get this utility installed, you must install the .NET SDK on the Linux target to ensure that the required support components are available. This is separate from installing PowerShell Core, which only bundles the .NET runtime components it relies on.
Note
Certificates are usually stored in the CurrentUser\My certificate store, rather than LocalMachine\My. This is not available on Linux. Consequently, the certificates visible at any time will correspond to the Linux account under which the PowerShell toolkit is running.
Authenticating
The set-tachyonserver cmdlet will operate exactly as it does in Windows environments, but you can only connect to a Tachyon server running platform-neutral authentication. (Or probably basic authentication, either directly or via the Tachyon proxy.)
Note
NTLM authentication is not functional in the Linux environment.
Note
The proxy option to use SSL client certificates is not (yet) supported by the PowerShell toolkit, but is probably feasible if required at some point.
You can authenticate interactively, or by supplying an -AppId and -CertSubject or -CertThumbprint parameter to use a signed JWT, just as you do in the Windows environment.
You can also request a Tachyon platform token using the get-tachyonplatformtoken cmdlet. The platform token certificate must be in the cert store to do this.
Enumerating certificates
The tool mentioned earlier has a command line option to do this. Additionally, the get-tachyoncertificatethumbprint cmdlet in the PS toolkit does operate in the Linux environment. You would normally specify CurrentUser\My as the certificate store rather than LocalMachine\My when using this cmdlet.