Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

SafeNet Authentication Service Authentication API for Microsoft .NET

Agent key file and additional deployment

search

Please Note:

Agent key file and additional deployment

Agent key file

The SAS API uses an encrypted key file to secure communication with the server. The key file is loaded and registered with the agent, and a matching key is registered with the authentication server.

A sample key file (default.bsidkey) is installed for evaluation purposes. This file is publicly distributed and should be used for evaluation purposes only. We strongly recommend that you generate your own key file for your production environment. To use an encrypted key file, load a key file and register its certificate as detailed below.

Loading key file

  1. Open the SAS COMMS tab and download the agent key file from the Authentication Agent Settings section.

  2. Copy the downloaded file to the following path:

    [INSTALLDIR]\KeyFile\

    Where [INSTALLDIR] is the installation directory of the API.

    Note

    We strongly recommend placing the file in a system-protected folder accessible only to accounts with the required privileges.

    The default location is in the Program Files folder, which is not read protected. This means that the location must be changed to a protected location that cannot be read by non-administrative accounts.

Registering key file certificate

  1. Open the Registry Editor, and expand the registry to the following path:

    My Computer > HKEY_LOCAL_MACHINE > SOFTWARE > Thales > BSIDAPI

    Note

    If a custom registry key location passes the connection information to the BSIDAPI constructor, expand the registry to the custom registry key instead, and update its EncryptionKeyFile information.

  2. Edit the EncryptionKeyFile value so that it contains the fully qualified path to the agent key file that was loaded in Loading key file, and save the changes.

Logging

If unexpected behavior occurs, view the log messages. The SAS API logs error messages to the Windows Event Viewer's Application log. The source appears as BSIDAPI.

API example

Either of the following two approaches can be used to consume the BSIDAPI SDK. Both the apiTestClient and APITestClientDotNetCore directories include an example of how to perform the following tasks:

1. DLL based approach

In this approach, a reference to the BSIDAPI.dll is added along with its dependent DLLs, which are installed using the PowerShell script (Profile.ps1) provided in the agent package.

  1. Add a reference to the BSIDAPI.dll.

  2. Install the dependent DLLs. Perform the following steps to execute the PowerShell script file:

    a. Navigate to the agent package. Copy the Profile.ps1 script file from the Scripts folder.

    b. Place the script file at the following path:

    C:\Users\{Username}\Documents\WindowsPowerShell\

    c. Open the Visual Studio IDE and navigate to Tools > NuGet Package Manager > Package Manager Console.

    d. In the Package Manager Console window, type Install-Packages, and then press Enter.

  3. Use the BSIDAPI class to define connection information.

  4. Call the Authenticate and CheckServerStatus methods.

2. NuGet package approach

In this approach, a reference to the NuGet package (BSIDAPI.1.1.0.nupkg) is added. Perform the following steps:

  1. Navigate to the agent package. Copy the BSIDAPI.1.1.0.nupkg file.

  2. Place the file locally on your machine.

  3. Open the Visual Studio IDE and navigate to Tools > NuGet Package Manager > Package Sources. Add the file as a package source and then click OK.

  4. Use the BSIDAPI class to define connection information.

  5. Call the Authenticate and CheckServerStatus methods.

Deploying on additional computers

To deploy the completed application on an additional computer, perform the following steps:

  1. Export the BSIDAPI registry key from the following path (of the system running the completed application) and import it on the target computer:

    My Computer > HKEY_LOCAL_MACHINE > SOFTWARE > Thales

    Note

    If a custom registry key location passes the connection information to the BSIDAPI constructor, export the custom registry key instead.

  2. Deploy and install an agent key file. For more information, see Agent key file.

    Note

    If the application is deployed to a different directory path than the source machine, update the EncryptionKeyFile registry value to match the actual key file location on the target machine.

  3. Ensure the following DLLs are present alongside BSIDAPI.dll in the application directory:

    • CryptoCOM.dll
    • AgentEncryptor.dll
    • BouncyCastle.Cryptography.dll (AES non-FIPS)
    • bc-fips-1.0.2.dll (AES FIPS)

  4. For BSIDAPI.dll to run correctly, ensure the following:

    • .NET Framework 4.6.2 (or later) / .NET 8 (or later) is installed.

    • AgentEncryptor.dll is COM registered. Run the following command as Administrator from the directory where AgentEncryptor.dll is present:

      C:\Windows\Microsoft.NET\Framework64\v4.0.30319\RegAsm.exe AgentEncryptor.dll /codebase

      Note

      This command may display a warning about the /codebase option. This is expected and can be safely ignored. Registration is successful if the command completes without errors.

On this page