DbDefence Database Encryption API

There are two DLLs in the API folder of the DbDefence installation.

dbencrypt.dll is used for 32-bit applications
dbencrypt64.dll is used for 64-bit applications.

You can use API from C#, C++ or any other language.

For further reference, see the code examples in the included API folder. C#/C++ examples are available.

The API encryption process consists of one primary function:

int Encrypt (TCallbackFunc * func, int argc, wchar_t * argv[]);

TCallbackFunc * func is the pointer to the function to be called on events during encryption: info, error and success messages.

This can be defined as:

void WINAPI ShowMessage (const wchar_t * msg, int code);

Info messages - msg - comes with error code 0. Possible error codes:

0 - Success.
-777 - Encryption finished.
113 - Missing ALTER ANY DATABASE permission to take a database Offline and Online. Not enough privileges.
116 - Can't create symmetric key in the database. Usually means password complexity error.
117 - Can't locate and open key file.
122 - Masking is not available on this platform/SQL Server version.
141 - Can't query database. This often happens if you try to encrypt an already encrypted database.
144 - Can't decrypt database. This may be a wrong password.
145 - There are active connections in the database. Use option -F to kill.
147 - DbDefence is not running on the instance.
149 - Attach error.
150 - Detach error.
152 - Can't create symmetric key in the database.
160 - No EXECUTE permissions on master.dbo.dbd_listdb
180 - Can't load/validate FIPS 140-2 module.
181 - Incomplete parameters.
182 - Cannot operate on the mirrored database.
183 - Cannot operate on the database in AlwaysOn Availability Group.
184 - File I/O error.
185 - Error while importing encryption keys.
186 - PKCS#11 related error.
187 - PKCS#11 related error.
188 - Failed to apply masking.
189 - There were errors validating data masking settings.
190 - Database is already encrypted with TDE.
191 - License error. exec master..dbd_reg_info failed.
201 - Password complexity error. Complexity settings depend on OS.
-25 - Invalid parameter.
-24 - Can't find specified certificate (server side).
-23 - Can't find specified certificate (client side).
-22 - Malformed SHA1 thumbprint.
-21 - Error messages from SQL Server.
-20 - Can't connect to server.
-19 - DbDefence not installed or not started.
-18 - Database is already encrypted.
-17 - No password specified.
-16 - Can't use database.
-15 - Can't create DbDefence tables in the database or tables are created is errors.
-14 - Unexpected error.
-13 - Can't detach database.
-12 - Can't open database files for RW access.
-11 - Can't attach database after encryption.
-10 - File with exceptions specified but it's not accessible.
-4 - Can't access all files of the database.
-3 - Database is too big for this license.
-2 - Unknown command line option.

If the API encryption is done successfully, the API call func wll be code -777 and return 0. In the case of an error, it returns one of the error codes used in the callback.

The parameter argc is the number of parameters in the next parameter, argv. It is the same as the traditional parameters of the function used in C/C++ programming.

The parameters used in the encryption API process are the same as the parameters used in the command line encryption tool.

C# example:


using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;
using System.Text;


namespace csharpdlltest
{
    
    unsafe class Program
    {
        public delegate void Callback([MarshalAs(UnmanagedType.LPWStr)]String msg, int code);

        // Please pay attention to the platform!
        const string _dllLocation = "L:\\work\\dbencrypt.dll";
//      const string _dllLocation = "L:\\work\\dbencrypt64.dll";

        [DllImport(_dllLocation, CharSet=CharSet.Unicode)]
        public static extern int Encrypt (Delegate Func,int a, String  [] s);

        static void MyCallback(String msg, int code)
        {
            System.Console.WriteLine("Output from DLL: {0} {1}",msg,code);
        }

        static void Main(string[] args)
        {
               
            // you must run the program locally on the target server
// if you can't login with trust connection, add -U and -P parameters for sql user and sql password
String [] param={"MyProc","-S",".\\sql2005","-p","CoolPassword111","-d","mydatabase"}; Callback cb = new Callback (MyCallback); int res = Encrypt(cb,param.Length, param); if (res == 0) { //well done! } return; } } }


VB.NET Example:

-----------------------------------------------------------------------------
Imports System
Imports System.Runtime.InteropServices

Public Delegate Sub CallBack(<MarshalAs(UnmanagedType.LPWStr)> str As String, code As Integer)

Module Module1
Public Declare Sub Encrypt Lib "dbencrypt.dll" (cb As CallBack, num As Integer, <MarshalAs(UnmanagedType.LPArray, ArraySubType:=UnmanagedType.LPWStr)> params() As String)
Public Declare Sub Encrypt64 Lib "dbencrypt64.dll" Alias "Encrypt" (cb As CallBack, num As Integer, <MarshalAs(UnmanagedType.LPArray, ArraySubType:=UnmanagedType.LPWStr)> params() As
String)
Public Sub CallFromDbDefence(<MarshalAs(UnmanagedType.LPWStr)> str As String, code As Integer)

Console.Write("message " + str + ", code " + code.ToString())
End Sub

Sub Main()

Dim param() As String = {"AnyProcessName", "-S", ".\sql201264", "-p", "CoolPassword111", "-d", "mydatabase"}
If IntPtr.Size = 8 Then
' call 64 bit dll
Encrypt64(AddressOf CallFromDbDefence, param.Length, param)
Else
' call 32 bit dll
Encrypt(AddressOf CallFromDbDefence, param.Length, param)
End If
End Sub
End Module
-----------------------------------------------------------------------------