HSDC_Sdk.h

For the source code of this file, see HSDC_Sdk.h source.

Typedefs

typedef void(HSDCAPI * HSDC_LOG_PROCESSOR_CALLBACK) (DWORD cookie, const char *jstr)

The format of the callback function for processing log events. Callback is triggered with its registration cookie and the JSON payload containing the logs.

typedef void(HSDCAPI * HSDC_SHADOW_PROCESSOR_CALLBACK) (DWORD cookie, const char *jstr, const wchar_t *filename)

Definition of the function signature for a shadow processor callback. The callback parameter is the subscription cookie, the JSON payload with shadow file information, and the shadow filename that can be used in HSDCExtractShadowStream to extract the stream.

typedef HSDCError(HSDCAPI * HSDC_SHADOW_STREAM_CALLBACK) (unsigned long long offset, const unsigned char *buffer, unsigned int length, void *parameters)

Definition of the required callback function signature for use with the /ref HSDCExtractShadowStream function.

typedef void(HSDCAPI * HSDC_NOTIFICATION_PROCESSOR_CALLBACK) (DWORD cookie, DWORD sessionId, const char *jstr)

Callback parameter is the subscription cookie, the session in which the event occurs (0 for service session), and the JSON payload containing one event.

Enumerations

enum HSDCVersion : WORD { HSDCVersionUnknown = 0, HSDCVersion_1_0 = 0x0100 }

enum HSDCHealth : DWORD { HSDCHealthUnknown = 0, HSDCHealthNotInstalled, HSDCHealthNotRunning, HSDCHealthOk }

enum HSDCHardening : DWORD { HSDCHardeningUnknown = 0, HSDCHardeningOff, HSDCHardeningRelaxed, HSDCHardeningOn }

enum HSDCConnectivityStatus : DWORD { HSDCStatusUnknown = 0, HSDCStatusOffline, HSDCStatusOnline }

enum HSDCCertificateTypes : DWORD { HSDCCertificateMachine = 0, HSDCCertificateUser }

The object to which a certificate is applied.

enum HSDCCertificateStores : DWORD { HSDCCertificateStoresLocal = 0, HSDCCertificateStoresAll }

The type of store to query for certificates.

enum HSDCCertificateAccesses : DWORD { HSDCCertificateAccessPublic = 0, HSDCCertificateAccessPrivate }

Certificate Access Types.

enum HSDCInventoryStatus : DWORD { HSDCInventoryStatusAll = 0, HSDCInventoryStatusOnline }

enum HSDCAccessCheckDepth : DWORD { HSDCAccessCheckDepthRights = 0, HSDCAccessCheckDepthRightsAndActions, HSDCAccessCheckDepthFull }

enum HSDCPolicyFormat : DWORD { HSDCPolicyFormatOffline = 0, HSDCPolicyFormatCch, HSDCPolicyFormatSkr }

These are the possible values for formatting of dumped policies.

Functions

HSDCError HSDCAPI HSDCStartup (WORD version, const char *jstr, const char *license)

The API must be initialized once per process. When the process does not need the API anymore, it can release resources by calling the HSDCCleanup function. Multiple sequences of startup and cleanup can be done in the process lifetime.

HSDCError HSDCAPI HSDCCleanup ()

This call cleans up resources (but not the dictionary strings) allocated during HSDCStartup and other API calls. No other calls should be made after this call, other than HSDCStartup. Any memory allocated by the API as returned parameters during previous call is released, and any registered callbacks are also unregistered.

HSDCError HSDCAPI HSDCGetVersion (WORD *pVersion)

Returns the API version.

HSDCError HSDCAPI HSDCFreeObject (void *pObj)

Frees memory allocated by the API that has been returned. The API tracks all memory allocations and releases forgotten allocations on HSDCCleanup. The caller is encouraged to process output parameters as soon as possible or make a copy then free output parameters as quickly as possible to avoid memory leaks.

HSDCError HSDCAPI HSDCGetConfiguration (char **pJstr)

Returns the JSON configuration of the API layer.

HSDCError HSDCAPI HSDCSetConfiguration (const char *jstr)

Sets the JSON configuration of the API layer.

HSDCError HSDCAPI HSDCSetLogging (const char *logSetup)

Updates the log settings of the HSDC Agent components.

HSDCError HSDCAPI HSDCGetLogging (char **logSettingsOut)

Returns all of the values for known HSDC components. Only found components and values that have registry entries are included. Entries not being found is not considered an error.

HSDCError HSDCAPI HSDCGetStringById (unsigned long id, wchar_t **pStr)

Gets a string from the dictionary identified by its id. The language is matched using the user LCID, then the system LCID, then it falls back to English.

HSDCError HSDCAPI HSDCGetStrings (char **pJstr)

Gets all strings from the dictionary. The language is matched using the user LCID, then the system LCID, then it falls back to English.

HSDCError HSDCAPI HSDCGetHealth (DWORD *pHealth, DWORD *pHardening, char **pJstr)

Provides an aggregated health status of the agent installation.

HSDCError HSDCAPI HSDCRelaxHardening (const char *jstr, const unsigned char *signature, unsigned int signatureLength)

Relaxes hardening using a digitally signed JSON payload.

HSDCError HSDCAPI HSDCRelaxHardeningWithTicket (const wchar_t *filename)

Relaxes hardening using a digitally signed ticket. This format is a binary structure generated by the Device Control server, this approach should not be used in an agent integration. An alternative is to copy the file in the Ticket folder specified during installation steps, but this will be asynchronous and will lack the feedback.

HSDCError HSDCAPI HSDCGetConnectivityStatus (DWORD *pStatus, char **pJstr)

Gets the current connectivity status. The meaning depends on the option 60 ( oiOnlineAsWired) mode.

HSDCError HSDCAPI HSDCSetConnectivityStatus (DWORD status)

Sets the current connectivity status. This function has a meaning only when the option 60 ( oiOnlineAsWired) is set to manual.

HSDCError HSDCAPI HSDCGatherDiagnosticInfo (const wchar_t *const outputPath=nullptr)

Gathers a set of diagnostic information related to the agent's environment, policies, and status. It adds these items into an EsDiag folder within that path.

HSDCError HSDCAPI HSDCGetSecurityIdentities (char **pJstr)

Lists the current SIDs tied to the current token, this includes the current user account and all the groups they belong to. If the token has some restriction owing to UAC, then it is flagged too.

HSDCError HSDCAPI HSDCGetCertificates (DWORD type, DWORD store, DWORD access, const wchar_t *identity, char **pJstr)

Gathers the list of digital certificates from the local store or from all stores (Local and AD) with public access or with full access (including private key) matching one of the selected criteria.

HSDCError HSDCAPI HSDCRequestCertificate (DWORD type, const char *jstr, char **pJstr)

Requests a new certificate from the default Certification Authority.

HSDCError HSDCAPI HSDCGetInventory (DWORD status, char **pJstr)

Obtains a JSON representation of devices attached (or previously attached) to the agent machine.

HSDCError HSDCAPI HSDCHashOpticalDisk (const wchar_t *path, char **pJstr)

Computes an optical disk hash that can be used to identify it and then set a policy tied to this specific optical disk.

HSDCError HSDCAPI HSDCAccessCheckIsSystem (const wchar_t *path, BOOLEAN *pSystem)

Returns if the volume is controlled by Device Control. Volumes located on the physical hard drive containing the system volume are not controlled.

HSDCError HSDCAPI HSDCAccessCheckVolume (const wchar_t *path, const char *jstr, DWORD level, char **pJstr)

Computes effective accesses for a specific volume/drive letter. The full level of details requires Administrator privilege. Details can be controlled to provide different levels of access or also provide available actions that can be performed on the volume, such as encrypt/decrypt/recover access/and so on. Full level of details additionally provides information related to shadowing, file filtering, copy limit, and the device class/model/instance.

HSDCError HSDCAPI HSDCAccessCheck (const wchar_t *device, const char *jstr, char **pJstr)

Similar but more generic than the HSDCAccessCheckVolume call, this allows checks on devices without a drive letter (such as printers, portable devices, and so on), and it also allows simulation of hypothetical case (for example, would the user have write access after encrypting this USB stick). The output is a subset of the previous call since it contains only the rights part.

HSDCError HSDCAPI HSDCRegisterLogProcessor (DWORD *pCookie, HSDC_LOG_PROCESSOR_CALLBACK cb)

Registers a callback to get logs by batch. The callback parameter is the subscription cookie and the JSON payload containing one to many log events.

HSDCError HSDCAPI HSDCUnregisterLogProcessor (DWORD cookie)

Unregisters a callback using the cookie returned at registration.

HSDCError HSDCAPI HSDCRegisterShadowProcessor (DWORD *pCookie, HSDC_SHADOW_PROCESSOR_CALLBACK cb)

Registers a callback to get shadow files by batch.

HSDCError HSDCAPI HSDCUnregisterShadowProcessor (DWORD cookie)

Unregisters a callback using the cookie returned at registration.

HSDCError HSDCAPI HSDCExtractShadowStream (const wchar_t *filename, char **pJstr, HSDC_SHADOW_STREAM_CALLBACK cb, void *parameters)

Extracts the content of a Device Control shadow file.

HSDCError HSDCAPI HSDCFetchLogs (BOOLEAN dismount, DWORD retry)

Triggers log and shadow processing and flush.

HSDCError HSDCAPI HSDCRegisterNotificationProcessor (DWORD *pCookie, DWORD sessionId, const char *jstr, HSDC_NOTIFICATION_PROCESSOR_CALLBACK cb)

Registers a callback to get notification.

HSDCError HSDCAPI HSDCUnregisterNotificationProcessor (DWORD cookie)

Unregisters a callback using the cookie returned at registration.

HSDCError HSDCAPI HSDCPolicyImport (const char *jstr, const unsigned char *signature, unsigned int signatureLength)

Imports policies in the JSON format described in Policies. The payload must be signed and is checked with the sx - public.key present in the sxdata folder.

HSDCError HSDCAPI HSDCPolicyImportFile (const wchar_t *filename)

Imports policies in binary format. This is the native/legacy format of offline policies produced by the IDAC export tool.

HSDCError HSDCAPI HSDCPolicyRefresh ()

Triggers a refresh setting. This makes sense only when SComC retrieves itis policies from a Device Control server.

HSDCError HSDCAPI HSDCPolicyGetOption (DWORD id, wchar_t **value)

Retrieves the current option value for one of a set of policy related options.

HSDCError HSDCAPI HSDCTempOfflinePolicyRequest (const char *jstr, char **pJstr)

Given a set of requested permissions and the duration of the policy to be applied, creates a request key that can be used for a temporary offline policy request.

HSDCError HSDCAPI HSDCTempOfflinePolicyAnswer (const char *jstr)

Applies a temporary offline policy with the given passphrase answer.

HSDCError HSDCAPI HSDCDumpPolicies (DWORD format, const wchar_t *path, char **pJstr)

Produces a textual representation of the current agent policies.

const wchar_t *const HSDCAPI HSDCErrorGetName (HSDCError error)

Gets a pointer to a const wchar_t c-string based on the input error enum. Used to fetch an error name without switches.

HSDCError HSDCAPI HSDCEncryptedVolumeGetStatus (const wchar_t *path, char **pJstr)

Retrieves information, including the encrypted volume identifier, of an encrypted volume.

HSDCError HSDCAPI HSDCEncryptedVolumeEncrypt (const wchar_t *path, const char *jstr)

Starts a volume encryption. This is an asynchronous operation, and feedback is delivered through the callback registered with HSDCRegisterNotificationProcessor.

HSDCError HSDCAPI HSDCEncryptedVolumeUpgrade (const wchar_t *path, const char *jstr)

Starts an encrypted volume upgrade. This is an asynchronous operation, and feedback is delivered through the callback registered with HSDCRegisterNotificationProcessor.

HSDCError HSDCAPI HSDCEncryptedVolumeChangePassword (const wchar_t *path, const char *jstr)

Changes the password of an encrypted volume.

HSDCError HSDCAPI HSDCEncryptedVolumeDecrypt (const wchar_t *path, const char *jstr)

Decrypts a volume previous encrypted by Device Control.

HSDCError HSDCAPI HSDCEncryptedVolumeImport (const wchar_t *path, const char *jstr)

Unlocks an encrypted volume.

HSDCError HSDCAPI HSDCEncryptedVolumeExport (const wchar_t *path, const char *jstr, const wchar_t *folder)

Exports encrypted volume access into either the metadata area of the volume or a password protected file.

HSDCError HSDCAPI HSDCPasswordRecoveryRequest (const wchar_t *path, char **pJstr)

Builds the initial request after extracting encrypted volume information from a path/drive letter.

HSDCError HSDCAPI HSDCPasswordRecoveryAnswer (const wchar_t *path, const char *jstr)

Recovers access to encrypted medium.

HSDCError HSDCAPI HSDCOpticalRecorderGetLetters (char **pJstr)

Obtains the drive letters of the drives that support recording.

HSDCError HSDCAPI HSDCOpticalRecorderGetDriveInformation (const wchar_t *path, char **pJstr)

Retrieves information related to an optical recorder including its capabilities. This function doesn't provide information related to inserted optical disks.

HSDCError HSDCAPI HSDCOpticalRecorderGetDiskInformation (const wchar_t *path, char **pJstr)

Retrieves information related to the inserted optical disk.

HSDCError HSDCAPI HSDCOpticalRecorderBurn (const wchar_t *path, const char *jstr)

Burns an encrypted optical disk. This is an asynchronous call, notifications are provided by the callback registered previously with HSDCRegisterOpticalRecorderNotification.

HSDCError HSDCAPI HSDCOpticalRecorderErase (const wchar_t *path, const char *jstr)

Erases a rewritable optical disk. This is an asynchronous call, notifications are provided by the callback registered previously with HSDCRegisterOpticalRecorderNotification.

HSDCError HSDCAPI HSDCOpticalRecorderCancel (const wchar_t *path)

Cancels a write operation in progress previously initiated by HSDCOpticalRecorderBurn or HSDCOpticalRecorderErase.

HSDCError HSDCAPI HSDCIsBitLockerCapable (char **pJstr)

Checks if BitLocker Full Disk Encryption on system disk can be enabled.

HSDCError HSDCAPI HSDCEnableBitLocker (const wchar_t *pin, const char *unused)

Enables BitLocker Full Disk Encryption on a system disk if the option has been set by an administrator and if conditions are met (TPM, ...). On failure, an ERROR message is emitted by IDAC Agent Service (SComC) and centralized for Admin to take action.

HSDCError HSDCAPI HSDCCryptoHashBuffer (const wchar_t *algorithm, const unsigned char *buffer, unsigned int bufferLength, unsigned char *hash, unsigned int *hashLength)

Computes a buffer hash. While hash algorithms have known length (respectively 20, 32, 48 and 64), the caller can pass a null pointer for hash in order to get the hash length programmatically.

HSDCError HSDCAPI HSDCCryptoHashFile (const wchar_t *algorithm, const wchar_t *path, unsigned char *hash, unsigned int *hashLength)

Same as HSDCCryptoHashBuffer, but the input is a filename from which the buffer is read.

HSDCError HSDCAPI HSDCCryptoGenerateKeyPair (const wchar_t *algorithm, unsigned char *privateKey, unsigned int *privateKeyLength, unsigned char *publicKey, unsigned int *publicKeyLength)

Generates a new asymmetric key pair. Obtains the required buffer lengths by passing the algorithm and pointers to zero.

HSDCError HSDCAPI HSDCCryptoSignBuffer (const wchar_t *algorithm, const unsigned char *buffer, unsigned int bufferLength, const unsigned char *privateKey, unsigned int privateKeyLength, unsigned char *signature, unsigned int *signatureLength)

Computes a digital signature of a buffer using an asymmetric key pair.

HSDCError HSDCAPI HSDCCryptoSignFile (const wchar_t *algorithm, const wchar_t *path, const unsigned char *privateKey, unsigned int privateKeyLength, unsigned char *signature, unsigned int *signatureLength)

Same as HSDCCryptoSignBuffer but the input is a filename from which the buffer is read.

HSDCError HSDCAPI HSDCCryptoCheckBufferSignature (const wchar_t *algorithm, const unsigned char *buffer, unsigned int bufferLength, const unsigned char *publicKey, unsigned int publicKeyLength, const unsigned char *signature, unsigned int signatureLength)

Validates whether the given signature was generated using the private equivalent of the given public key for the given buffer.

HSDCError HSDCAPI HSDCCryptoCheckFileSignature (const wchar_t *algorithm, const wchar_t *path, const unsigned char *publicKey, unsigned int publicKeyLength, const unsigned char *signature, unsigned int signatureLength)

Same as HSDCCryptoCheckBufferSignature but the input is a filename from which the buffer is read.

HSDCError HSDCAPI HSDCCryptoEncryptBuffer (const wchar_t *algorithm, const unsigned char *plain, unsigned int plainLength, const unsigned char *publicKey, unsigned int publicKeyLength, unsigned char *cipher, unsigned int *cipherLength)

Asymmetric encryption of buffer (used with RSA for symmetric key exchange).

HSDCError HSDCAPI HSDCCryptoDecryptBuffer (const wchar_t *algorithm, const unsigned char *cipher, unsigned int cipherLength, const unsigned char *privateKey, unsigned int privateKeyLength, unsigned char *plain, unsigned int *plainLength)

Asymmetric decryption of buffer (used with RSA for symmetric key exchange).

HSDCError HSDCAPI HSDCCryptoSymEncryptBuffer (const wchar_t *algorithm, const unsigned char *plain, unsigned int plainLength, const unsigned char *symKey, unsigned int symKeyLength, const unsigned char *iV, unsigned int iVLength, unsigned char *cipher, unsigned int *cipherLength)

Symmetric encryption of buffer with AES-256, supported modes are ECB, CTR and CBC.

HSDCError HSDCAPI HSDCCryptoSymDecryptBuffer (const wchar_t *algorithm, const unsigned char *cipher, unsigned int cipherLength, const unsigned char *symKey, unsigned int symKeyLength, const unsigned char *iV, unsigned int iVLength, unsigned char *plain, unsigned int *plainLength)

Symmetric decryption of buffer with AES-256, supported modes are ECB, CTR and CBC.

HSDCError HSDCAPI HSDCCryptoBase32Encode (const unsigned char *raw, unsigned int rawLength, unsigned char *encoded, unsigned int *encodedLength)

Base 32 encoding for temporary offline policies and password recovery.

HSDCError HSDCAPI HSDCCryptoBase32Decode (const unsigned char *encoded, unsigned int encodedLength, unsigned char *raw, unsigned int *rawLength)

Base 32 decoding for temporary offline policies and password recovery.