JEDI Windows Security Code Library

From Project JEDI Wiki
Jump to navigationJump to search

The JEDI Windows Security Code Library (short JWSCL or JEDI WSCL) is a bunch of Delphi classes that brings Delphi programmers an easy access to the Windows Security programming which uses complex C style. In this way programming Windows Security in far easier because the programmer must not fight with complicated C function calls and its memory managment.

var Token : TJwSecurityToken;
begin
  Token := TJwSecurityToken.CreateTokenEffective(TOKEN_ALL_ACCESS);
  try  
    Token.ImpersonateLoggedOnUser;
  finally  
    Token.Free;
  end;
end;

JWSCL is open source and can be downloaded from Sourceforge as a package or from Subversion repository.

Features

JWSCL comes with the following features (some of them are only available in Developer Version, Release 0.9.4 or newer):

 * Windows Token management (TJwSecurityToken)
    * Impersonation
    * Supports LogonUser, LsaLogonUser
    * Lots more
 * Full support of Security ID (SID) (TJwSecurityID, TJwSecurityIDList)
    * Also well known security IDs like Everyone (JwsclKnownSid.pas) are stored as simple to use variables.
 * Full support of Access Control Lists (also CALLBACK_ACE and OBJECT_ACE)
    * DACL, SACL
 * Full support of Security Descriptor (SECURITY_DESCRIPTOR) (TJwSecurityDescriptor)
    * DACL, SACL, Owner, Group
    * Implements a simple to use Security Descriptor (TJwSimpleDescriptor)
    * Security Rights Mapping; Maps Generic Rights to specific ones (JwsclMapping.pas)
       * Conversion of Security Rights (DWORD) to Human Readable names (JwFormatAccessRights)
 * Privileges (TJwPrivilege, TJwPrivilegeSet, JwsclPrivileges.pas)
 * Windowstation and Desktops (TJwSecurityWindowStation, TJwSecurityDesktop)
 * Local Security Authority Logon Sessions (TJwLsaLogonSession)
 * Security of Windows objects; files, registry, handles (TJwSecureFileObject, TJwSecureFileObject, TJwSecureGeneralObject)
    * Support of Access Checking (AccessCheck)
    * Supports Inheritance (by default only files and registry)
 * Support of MS AuthZ API; Client Side Access Checks for custom Resources (JwsclAuthCtx.pas)
 * Credentials GUI API (TJwCredentialsPrompt)
 * MS Encryption and Protection API (TJwEncryptionApi,  TJwEncryptMemory, TJwRandomDataGenerator)
 * Windows Version Detection on remote or local client (TJwFileVersion, TJwServerInfo, TJwWindowsVersion)
 * Security Descriptor GUI (TJwSecurityDescriptorDialog)
 * Terminal Sessions (TJwTerminalServer)
   * Server Management
   * Sessions Management
   * Processes Management
   * Vista Elevation (JwShellExecute, JwElevateProcess, JwsclElevation.pas)
     * Supports SuRun (English version) (JwElevateProcess, JwCheckSuRunStatus)
 * Vista Integrity Level (Built in)
 * Firewall Administration (TJwsclFirewall)
 * Builtin basic Sma rtpointer Support (TJwAutoLock)
 * Job Object support (TJwJobObject) even with several sessions (TJwJobObjectSessionList)
 * Process Handling that encapsulates support for different Windows Versions and bugs in API

(functions JwCreateProcessAsAdminUser, JwCreateProcessInSession, JwGetProcessSessionID, JwGetTokenFromProcess, JwProcessIdToSessionId)

 * Support Memory Mapped Objects (TJwFileStreamEx, TJwIPCStream, TJwVirtualStream)
 * Extended Thread Support lile naming threads and WaitWithTimeOut (TJwThread)
 * Hashing Support (TJwHash) 
   * For JWSCL classes (JwObjectHash)
   * For files (JwCreateFileHash, JwCompareFileHash, JwDataHash, JwIntegerHash) in combination with fast Memory Mapping.
 * DCOM support for Client and Server (currently only developer branch); CoInitializeSecurity (TJwComProcessSecurity), 

Authentication, Impersonation, Proxy Security Blanket (TJwComClientSecurity, TJwComServerSecurity), Access Control (TJwServerAccessControl), DCOM Configuration (TJwComRegistrySecurity) of Global Configs and Class Security.

 * Easy to use WinAPI (Msg)WaitForMultipleObjects functions (JwMsgWaitForMultipleObjects, JwMsgWaitForMultipleObjects)
 * Multi Language Support of Resource Files (LoadLocalizedString)
 * Ansi- & Unicode due to own Delphi compatible String type TJwString (JwsclAnsiUniCode.pas)
 * Mapping of Windows Constants to Delphi enumeration (TJwEnumMap)
 * All errors are reported by exceptions using a derived class from EJwsclSecurityException. (JwsclExceptions.pas)
 * Supports Bugreports with Eurekalog (JwsclEurekaLogUtils.pas)
 * JWSCL is based on OOP

Subversion

JWSCL is available as a Subversion repository. There are several source locations because JWSCL source can be a developer or released versions.

Developers can use

https://jedi-apilib.svn.sourceforge.net/svnroot/jedi-apilib/jwscl/branches/0.9.3

where production code is available here

https://jedi-apilib.svn.sourceforge.net/svnroot/jedi-apilib/jwscl/trunk

Use a Subversion client like TortoiseSVN (for Windows). If you want to browse the source code, you can use a human friendly browser.

The JWSCL authors recommend to use Subversion to keep your source code updated. To do so, just download the code using Subversion, and you can update the source code easily without downloading packages from a website.

Documentation/Help

JWSCL comes with an extraordinary code documentation. Most of the JWSCL identifiers (classes, methods, types, functions etc.) are documented. Either you can read the documentation from the code directly or visit JWSCL Online Help. However, this page may not be up-to date like the documented code itself.

Community/Blog

* Read interesting JWSCL topics on the Blog : http://blog.delphi-jedi.net
* JWSCL on SourceForge : http://sourceforge.net/projects/jedi-apilib
  * Join the mailinglist here : http://sourceforge.net/mail/?group_id=121894 
* Join the newsgroup "API conversion" here : news://news.delphi-jedi.org/jedi.apiconversion

Bugs/Requests/Questions

Before you commit a bug, make sure you are using the latest version of the library. To do so, update your code using a Subversion client or download the latest code.

* Report a Bug on the JEDI Bug Tracker : http://issuetracker.delphi-jedi.org/
* Use the SourceForge BugTracker System here: http://sourceforge.net/tracker/?group_id=121894

Always assign the bug report/request to Dezipaitor or ChristianW. otherwise they may not be get noticed!

Of course you can also send a mail to mail(@t)delphi-jedi(d0t)org .

Units

JWSCL consists of the following units

 JwsclAcl.pas
 JwsclAuthCtx.pas
 JwsclCertificates.pas
 JwsclComSecurity.pas
 JwsclComUtils.pas
 JwsclConstants.pas
 JwsclCredentials.pas
 JwsclCryptProvider.pas
 JwsclDescriptor.pas
 JwsclDesktops.pas
 JwsclElevation.pas
 JwsclEncryption.pas
 JwsclEnumerations.pas
 JwsclExceptions.pas
 JwsclFirewall.pas
 JwsclImpersonation.pas
 JwsclKnownSid.pas
 JwsclLogging.pas
 JwsclLsa.pas
 JwsclMapping.pas
 JwsclPrivileges.pas
 JwsclProcess.pas.pas
 JwsclRegistry.pas
 JwsclResource.pas
 JwsclSecureObjects.pas
 JwsclSecurityDialogs.pas
 JwsclSid.pas
 JwsclSimpleDescriptor.pas
 JwsclStreams.pas
 JwsclStrings.pas
 JwsclTerminalServer.pas
 JwsclToken.pas
 JwsclTypes.pas
 JwsclUtils.pas
 JwsclVersion.pas
 JwsclWinStations.pas


JWSCL depends on the JEDI Windows Library. It uses the single JwaWindows.pas file. However, to improve compiling speed you should create a JwaWindows.dcu file and include it into your JWSCL project.

Exceptions

JWSCL follows a strict exception policy. Errors are propagated as Delphi exceptions instead of error return values. If an error occurs it cannot be ignored that easily. Furthermore exceptions can give more information (using text with placeholders) about a problem than a single error value.

---------------------------
Benachrichtigung über Debugger-Exception
---------------------------
Im Projekt JwsclMain.exe ist eine Exception der Klasse EJwsclOpenProcessTokenException mit der Meldung '
An Exception of type EJwsclOpenProcessTokenException was raised. 

(Data was given by programmer and can vary from actual source.)
Source method....: CreateTokenByProcess
Source class.....: TJwSecurityToken
Source file......: JwsclToken.pas
Source line......: 0
GetLastError.....: 5 ($5)
GetLastErrorMsg..: Access denied

Message : Call to OpenProcessToken failed.
' aufgetreten.
---------------------------
Anhalten   Fortsetzen   Hilfe   
---------------------------

Exceptions are defined in JwsclExceptions.pas. The root JWSCL exception is called EJwsclSecurityException (which is a descendant from SysUtils.Exception). All JWSCL Exceptions inherit its properties and methods. Instead of catching this generic exception you should check the documentation of a method for information about thrown exceptions. Be aware that the documentation does not always tell about all possible exceptions (e.g. from internal calls). If you are not sure, don't hesitate to check the implementation. JWSCL is open source.

Jwscl.inc

This include file is located in includes folder of your JWSCL installation. It provides many switches for a JWSCL compilation.

//Adds stack trace (using JCL) to JWSCL exceptions
{.$DEFINE JWSCL_DEBUG_INFO}

//Use cache mechanism for
// * TJwSecurityID.GetAccountSidString and property AccountName
{.$DEFINE JWSCL_USE_CACHES}

//Uses taskdialog when a JWSCL exception occurs in Delphi
//This needs Vista or newer and a manifest specifying Common Control Version 6 (or newer)
{.$DEFINE JWSCL_USE_TASK_EXCEPTION_DIALOGS}

// If JWSCL_LOCAL_SAFE_LOAD_LIBRARY is set
//   TJwLibraryUtilities.LoadLibProc will load libraries in a safe way.
// Furthermore the function TJwLibraryUtilities.EnterSafeLoadLibrary will be enabled.
// In this way the current directory will be set to the system directory.
{$DEFINE JWSCL_LOCAL_SAFE_LOAD_LIBRARY}

// If JWSCL_GLOBAL_SAFE_LOAD_LIBRARY is set
//  the unit initialization JwsclProcess will call TJwLibraryUtilities.SecureDLLSearchPath;
// and secure all calls to LoadLibrary and CreateProcess
//  I.e. the current directory and the process directory will be searched last for exe, dll, sys and
//    such after system dirs. The current folder of process will be set to the system directory.
//
// JWSCL_LOCAL_SAFE_LOAD_LIBRARY makes define JWSCL_LOCAL_SAFE_LOAD_LIBRARY unnecessary.
//
// You can call TJwLibraryUtilities.SecureDLLSearchPath; manually which should be done as early as possible
//   and in favour of this definition.
{.$DEFINE JWSCL_GLOBAL_SAFE_LOAD_LIBRARY}

Nice to know

 * By setting JWSCL_DEBUG_INFO compiler switch, JWSCL exception will have a stack trace.
 * By setting JWSCL_USE_TASK_EXCEPTION_DIALOGS compiler switch, JWSCL exceptions are shown as Windows Vista/7 Taskdialogs. The binary must also have a manifest included.

Setup of JWSCL

You can read a complete manual how to setup JWSCL here.

Excerpt from this page:

The JWSCL does only need a minor setup. You need to create a binary unit file (DCU-file) for the JEDI API Headers as described here.

You must setup JEDI API first before you can start with JWSCL! Otherwise if you set Delphi source path to include JwaWindows.pas you'll get an error like:

Incompatible types: JwaWindows.XXX and JwaWinNT.XXX

JWSCL works with JwaWindows from the JEDI API. However this only works with some compiler directives defined in the packages in the package folder of JEDI API. Use these packages to compile and create a JwaWindows.dcu file. ERROR: Adding the source path of JWA (folder Win32API) to your project options and then use JwaWindows and JWSCL does not work!

1. Adapt this source path to include some necessary files for JWSCL:

"path to JEDI API"\"version"\COM e.g. C:\Projects\jwapi\2.3\COM

2. Make sure that you have added the path of JwaWindows.dcu to your project or general library path. After this step you can also add the source path to the JWSCL source folder (\source) to the project or general library path so all projects can easily use JWA and JWSCL.

3. Eventually you can start using JWA and JWSCL in the simplest way: Just add the units to your uses clause.

4. Consider to update your JEDI files using Subversion (with a Subversion client like TortoiseSVN). With TortoiseSVN you can just right click on the JEDI JWSCL folder and hit "SVN Update" (not Checkout or Import!). The code is then updated.



Comments

--ChristianWimmer 18:06, 12 November 2010 (UTC) If you have questions, found a bug or similar on this page, don't hesitate to contact me: mail(@t)delphi-jedi(d0t)org

--ChristianWimmer 18:06, 12 November 2010 (UTC) First creation of this page.