Network Associates Laboratories

September 2002

Applies to:
    The Microsoft® Windows® Server 2003 Family
    Microsoft® Windows® XP Professional

Summary: Learn how to use the Encrypting File System (EFS), a transparent file encryption service provided by the Windows Server 2003 family. This article covers EFS as it exists in Windows XP Professional and the Windows Server 2003 family. We will first discuss the architecture of EFS including operation, data recovery, and the EFS components. We will follow with a description of how to use EFS, both from the shell and programmatically. Finally, we will finish with some discussion on EFS security. (23 printed pages)

Contents

Introduction
Architecture
Using EFS
Programmatic Use
Security
Contributors
References

Introduction

The Encrypting File System (EFS) is a transparent file encryption service provided by the Windows Server 2003 family. EFS provides file confidentiality but does not provide any integrity or authentication protection. EFS offers an optional data recovery capability that allows access to the files if the user keys are lost or destroyed. EFS also provides for multiple users to share access to an encrypted file using their own access credentials.

This paper covers EFS as it exists in Windows XP Professional and the Windows Server 2003 family. We will first discuss the architecture of EFS including operation, data recovery, and the EFS components. We will follow with a description of how to use EFS, both from the shell and programmatically. Finally, we will finish with some discussion on EFS security.

Architecture

Keys and Certificates

EFS uses standard x509 certificates for all access credentials. Each protected file is encrypted with a randomly generated File Encryption Key (FEK) using a symmetric encryption algorithm. EFS "wraps" the FEK by encrypting it with the public keys from one or more EFS certificates. For a user to access an encrypted file, they must have the private key that corresponds to one of the public keys used to "wrap" the FEK. Any user that has access to one of the private keys may get access to a file by first decrypting the wrapped FEK with the private key and then decrypting the file with the recovered FEK.

Operation

EFS has four main operations: opening, reading, writing, and converting files. Each of these operations is discussed in a section below. Since EFS was designed to be transparent, opening, reading, and writing encrypted files is no different than for normal files: applications still use the normal Win32 APIs. Converting files is the process of either encrypting a plaintext file or decrypting an encrypted file. Conversion requires a specific interface, discussed later.

Open

An application uses the normal Win32 API CreateFile() or OpenFile() to open encrypted files. When an encrypted file is opened, EFS unwraps the file encryption key and creates the necessary context to allow for decryption or encryption of data.

Read

An application uses the normal Win32 APIs ReadFile(), ReadFileEx(), and ReadFileScatter()to read encrypted files. When an encrypted file is read, the data is first read into memory and then EFS decrypts the data in-place. The decrypted data is then returned to the application. When an application requests for an encrypted file to be mapped into memory, the data is decrypted immediately before being mapped into memory.

Write

An application uses the normal Win32 APIs WriteFile(), WriteFileEx(), and WriteFileScatter() to write encrypted files. When an encrypted files is written, EFS encrypts the data in-place, and then the encrypted data is written to disk. When an application requests for a memory-mapped file to be unmapped, the mapped data is encrypted before it is written back to disk.

Convert

One of the overriding concerns with the design of the conversion process is that data is never lost, even when a power outage or other catastrophic failure occurs. To this end, EFS is very careful about keeping backups of unencrypted data until the entire conversion process is complete.

When EFS receives a request to convert a file, a number of steps happen:

• EFS starts by performing a number of verification checks. These checks include whether the file may be encrypted and whether there is enough disk space to encrypt the file. If the file is marked as a system file or resides in the %systemroot% directory, then the file cannot be encrypted.
• EFS then generates a file encryption key and wraps it with the current user's public key. If a recovery policy (discussed later) is defined, the FEK is also wrapped in any required recovery agent public keys.
• After the file encryption key has been generated and wrapped, the EFS metadata is created. It contains the Data Decryption Field (DDF), which is the FEK wrapped in all the public keys of users that have been given access to the file. It also contains the Data Recovery Field (DRF), which is the FEK wrapped in all recovery agent public keys. EFS also stores other information, such as the EFS version and encryption algorithm in the metadata.
• Next, EFS creates a temporary file in the current directory. Each data stream in the source file is copied to the temporary file for backup purposes. Each data stream in the original file is then truncated to a length of zero. Its length is then set back to its original size. This essentially deletes all the data in the stream. Next, EFS writes the metadata to the original file. At this point EFS has the plaintext data in a temporary file and an empty source file that is marked encrypted (because of the presence of the EFS metadata).
• EFS reads the streams from the temporary file and writes them to the original file. Due to EFS' transparent nature, the writes encrypt the data before actually writing it to disk.
• Once all of the data has been written back to the original file, EFS verifies that the file is encrypted and then deletes the temporary file. If the conversion process fails for some reason, EFS will restore the file to its original state.

Conversion to plaintext follows a similar process, in that a temporary file is created and the source file is written to it. The source file is then truncated and the data is read from the temporary file and written back to the source file in the clear.

Notes   A side effect of this process is that when the temporary file is deleted, plaintext remnants of the file may remain in unused space on the disk. The command line utility cipher.exe has a switch (/W) to wipe all of the marked free space on a partition. This operation can clear the plaintext remnants of all files that do not fit entirely within a Master File Table (MFT) record left over from encryption. The MFT record size depends on the disk cluster size but is usually 1024 bytes. The file size that fits within the MFT record depends on how much space is left in the MFT record after accounting for the file metadata. The MFT may contain other data, for example file attributes or streams. Additionally, a file may have more data than the MFT record. For more information about the MFT, see the Master File Table and MFT Zone entry in the Platform SDK Documentation in the Microsoft Developer Network.

To completely prevent the possibility of having plaintext remnants on a disk, current best practices recommend that files are never converted from plaintext source. Instead a directory should be created and marked encrypted. When a file is created in an encrypted directory, the file is immediately written to the disk encrypted, and no temporary file is created.

Obviously for a user who already has files that need encryption this doesn't work. The recommended procedure then is to convert all existing files that need protection and then use cipher.exe to wipe all free space on the partition. From then on, all files should be created in encrypted directories.

Data Recovery

EFS provides a data recovery capability. Data recovery is used to recover encrypted files in the event user keys are lost or destroyed. It also allows organizations to define and enforce a policy to access data stored on company systems. The capability is defined by a recovery policy that is automatically enabled on domain machines, and disabled on standalone machines. In a domain, the recovery policy is distributed via group policy from the active directory.

When a recovery policy is in place, all FEKs are additionally wrapped with the recovery agent public keys. These wrapped FEKs make up the Data Recovery Field (DRF) which EFS rewrites after every operation to ensure that the most current recovery policy is used.

Recovery agent private keys are very valuable. Every encrypted file in a domain has its FEK wrapped by a recovery public key. If an attacker could gain access to the corresponding recovery private key she could access any encrypted file in the domain. Protecting those keys is very important.

Recovery policy

Domain

The default recovery policy in a domain consists of the domain administrator. When the domain administrator logs on to the domain controller for the first time, an EFS recovery certificate is generated and stored in the local profile. That certificate is added to the recovery policy. Any domain administrator can then create recovery agents in the domain and generate EFS certificates for those recovery agents. Those certificates can be added to the recovery policy.

When a domain machine is booting, the group policy, including the recovery policy, is retrieved from the Active Directory. The machine then overwrites whatever recovery policy is configured with the one obtained from group policy. Periodically the machine will query the Active Directory for an updated group policy, including the recovery policy.

The recovery policy obtained from the Active Directory is cached locally on the domain-joined machine. If the machine is unable to contact the Active Directory and download updated policy, it will use the cached policy.

A domain administrator can also configure an empty recovery policy for the domain. An empty policy disables EFS for Windows 2000 clients, but not for XP or Windows Server 2003 clients. An empty recovery policy is different from not defining a policy, because an administrator must create an empty policy but not add any recovery agents to the policy. If an administrator removes the policy, then no recovery policy is defined.

Group policy objects can be created at multiple levels in an Active Directory tree. A local recovery policy can also be configured on a domain machine. It will, however, never be used as the domain recovery policy takes precedence. For more information on Group Policy propagation and precedence, refer to the Windows Server 2003 help files.

Standalone

No recovery policy initially exists on a standalone machine. Administrators on standalone machines can modify the EFS recovery policy. Recovery certificates can be created and added to the policy.

Components

For EFS to work transparently its components must exist at many layers in the operating system. These components are broken out into two groups: user-space components and kernel-space components. Figure 1, below, shows the components involved when files are accessed. The boxes with (EFS) in them contain only EFS code, while the boxes with EFS in a sub-box, contain some EFS code. Each of the components containing EFS code is discussed below.

Figure 1. Operating System Components and Relationships

User-space components

There are five components in user space that have EFS-specific code in them. They are: LSA, Feclient, Efsadu, Shell, and Winlogon. Their relationships are shown above in Figure 1. Each component is discussed further in the following sections.

Local Security Authority

The Local Security Authority (LSA) performs the majority of the user-space EFS operations. The LSA responds to requests from the kernel to create a FEK and wrap it in the proper user and recovery agent public keys. The FEK is returned to the kernel and used to encrypt a file. The LSA also performs the reverse operation of unwrapping a FEK and returning it to the kernel to decrypt a file.

During the wrapping process, the recovery policy is checked to see if the FEK should be wrapped by recovery agent public keys. During unwrapping, the recovery policy is checked again to see if additional or new recovery certificates exist such that the FEK should be rewrapped. The LSA also checks to see if the current user's EFS certificate has changed such that the FEK should be rewrapped.

The LSA exports a number of interfaces via RPC that enable communication with Feclient. The LSA also exports a number of interfaces via LPC that enable communication with Ksecdd.

To improve performance, the LSA maintains a cache of handles to private keys used for wrapping and unwrapping FEKs. These handles point to private keys that remain in the CSP and are, therefore, in a safe location.

Feclient

The Win32 APIs pass all EFS-related calls to the Feclient DLL. Feclient is then responsible for calling the EFS RPC interfaces in the LSA. The reason for this two-stage process in calling the EFS routines in LSA is that EFS supports remote storage of encrypted files on other servers running Windows Server 2003 or servers running Windows 2000. The Feclient is responsible for determining which server the file resides on and contacting the LSA on that server.

Efsadu

The Efsadu DLL provides the EFS-specific user interface. It is accessed when the Advanced sub-dialog of the Properties dialog is opened, and the Details button, next to Encrypt file, is clicked. Clicking this button opens the Encryption Details dialog discussed later.

Shell

The shell can display the filenames of encrypted files in explorer windows in a green color. The shell determines whether a file is encrypted by calling an EFS file status function.

Winlogon

Winlogon behaves differently on domain controllers and local machines. Winlogon will create a default recovery policy when a domain administrator logs on for the first time onto a domain controller. On a local machine, Winlogon calls the security configuration engine to process the EFS recovery policy obtained from group policy.

Kernel-space components

There are three components in kernel space that have EFS-specific code in them. They are: NTFS, WebDAV Redirector, and Ksecdd. Their relationships are shown above in Figure 1.

NTFS

The NTFS driver contains the majority of the EFS code in the kernel. This driver responds to file system controls (FSCTLs) from the LSA to encrypt or decrypt a file. When a file is opened, the driver passes the wrapped FEK to Ksecdd to be unwrapped by the LSA. The driver then decrypts the data when it is read from the file and encrypts the data when it is written to the file.

The EFS API in the NTFS driver also provides a set of functions for reading and writing encrypted files in a raw mode. Raw mode allows direct reading and writing of the ciphertext. This allows the Win32 file backup API to read and write the encrypted data for backup purposes while still maintaining confidentiality. This API is intended for use by backup software applications only.

The NTFS driver maintains a cache of unwrapped FEKs that it receives from the LSA to improve performance for files opened multiple times in quick succession. By default FEKs are cached for five seconds. The cache time is configurable from two to thirty seconds.

WebDAV Redirector

The WebDAV client redirector is responsible for handling encrypted files on WebDAV shares. The redirector works by retrieving the file off the server and then caching it locally while edits are performed. Once the file is closed, the redirector stores the file on the server. While the file is cached locally, the redirector calls the NTFS driver to read and write the file.

When the file is stored on the server, the client redirector performs a BackupRead() on the locally cached file and takes the data and stores it on the server. BackupRead() returns the encrypted contents of the file while the file remains encrypted on the system. When a file is retrieved from the server, the redirector performs a BackupWrite() to the cached file which takes the encrypted data and restores it to a normal, but encrypted, NTFS file.

Ksecdd

Ksecdd is a very thin component that NTFS calls to communicate with the LSA. Ksecdd is responsible for setting up the LPC communications to the LSA.

Using EFS

EFS is designed to be transparent to both users and applications. However users will have to interact with EFS directly, to perform some actions. These actions consist of converting files (encryption and decryption); adding additional users to files; and removing additional users from files. All of these actions are performed through the Advanced sub-dialog of the Properties dialog accessed by right-clicking on a file in Windows Explorer. This dialog is shown below in Figure 2.

Figure 2. Advanced sub-dialog of Properties dialog

Encryption

To encrypt a file, check the Encrypt contents to secure data checkbox in the Advanced sub-dialog and click OK. EFS then converts this file as discussed earlier.

To encrypt a directory, the same steps are followed as for a file. If the directory is empty, an encrypted flag is set in the directory header telling EFS that any file created in this directory is to be created encrypted. If the directory is non-empty, another dialog box is displayed, shown below in Figure 3, asking whether to apply the encryption to this folder only or to this folder, subfolders and files.

Figure 3. Confirm encryption dialog

If the Apply changes to this folder only option is selected, then the directory is treated as if it is empty, and the encrypted flag is set in the directory header. If, however, the Apply changes to this folder, subfolders and files option is selected, then every file in this directory, and all subdirectories, is encrypted as discussed above. The encrypted flag is then set for every subdirectory, including the current directory, in the directory headers.

Decryption

Decryption is the opposite of encryption and the process is the same as encrypting a file. To decrypt a file, uncheck the Encrypt contents to secure data checkbox in the Advanced sub-dialog and click OK. EFS then decrypts this file as discussed earlier.

To decrypt a directory, the same steps are followed as for a file. If the directory is empty, the encrypted flag is unset in the directory header. If the directory is nonempty, another dialog box is displayed, shown below in Figure 4, asking whether to apply the decryption to this folder only or to this folder, subfolders and files.

Figure 4. Confirm decryption dialog

If the Apply changes to this folder only option is selected, then the directory is treated as if it is empty, and the encrypted flag is unset in the directory header. If, however, the Apply changes to this folder, subfolders and files option is selected, then every file in this directory and all subdirectories is decrypted as discussed above. The encrypted flag is then unset for every subdirectory, including the current directory, in the directory headers.

Adding Users

Adding users to a file gives those users cryptographic access to that file. Cryptographic access means the users are able to decrypt and encrypt the file, as well as add and remove other users. Having cryptographic access, however, does not imply the users have file-system access. File-system access is controlled through NTFS file access control lists (ACLs). For a user to have full access to a protected file, the ACLs must be set to allow a user to access the file in addition to adding the user being given cryptographic access.

Clicking on the Details button in the Advanced sub-dialog brings up the Encryption Details dialog shown below in Figure 5.

Figure 5. Encryption Details dialog

Using the Add button, additional users can be added to the file. Any user that has an EFS certificate in the current user's Trusted People or Other People certificate store can be added. The active directory can also be searched for users.

Removing Users

Removing users from a file removes the users' cryptographic access to that file. The process is the same as adding users. Clicking on the Details button in the Advanced sub-dialog brings up the Encryption Details dialog shown above in Figure 5.

Using the Remove button, users can be removed from the file. Like when users are added, removing users only removes cryptographic access to the file. If the file-system ACLs are not adjusted, then the removed users still have file-system access to the file.

Recovery

Recovering a file is performed just like decrypting a file. The recovery agent must be logged onto the system where the file exists and must have access to the recovery certificate private key.

A recovery agent could also open the file and save it to a new file outside of an encrypted directory hierarchy, thereby saving the file unencrypted.

To avoid having the recovery agent import the recovery certificate private key onto a user workstation, a recovery station could be set up. Users would bring the files needing recovery to the recovery station and the recovery agent could log in to the station and recover the files.

Programmatic Use

Interfaces

EFS provides a number of public Win32 interfaces for interacting with encrypted files. These interfaces are available through the Platform SDK. They are summarized below and fully documented in the Platform SDK Documentation.

EncryptFile

Definition

BOOL WINAPI EncryptFile (
LPCWSTR   lpFilename)

Parameters

• lpFilenamePath to the file or directory to encrypt.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. For extended error information, call GetLastError().

Reference

For more information and example source code, please see the EncryptFile entry in the Microsoft Developer Network.

DecryptFile

Definition

BOOL WINAPI DecryptFile (
LPCWSTR   lpFilename,
DWORD   dwReserved)

Parameters

• lpFilenamePath to the file or directory to decrypt.
• dwReservedReserved for future use and must be zero.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. For extended error information, call GetLastError().

Reference

For more information and example source code, please see the DecryptFile entry in the Microsoft Developer Network.

AddUsersToEncryptedFile

Definition

BOOL WINAPI AddUsersToEncryptedFile (
LPCWSTR   lpFilename,
PENCRYPTION_CERTIFICATE_LIST   pUsers)

Parameters

• lpFilenamePath to the encrypted file to add users to.
• pUsersPointer to an ENCRYPTION_CERTIFICATE_LIST structure that contains a list of new user keys to be added to the file.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a system error code. For extended error information, call GetLastError().

Reference

For more information and example source code, please see the AddUsersToEncryptedFile entry in the Microsoft Developer Network.

RemoveUsersFromEncryptedFile

Definition

BOOL WINAPI RemoveUsersFromEncryptedFile (
LPCWSTR   lpFilename,
PENCRYPTION_CERTIFICATE_HASH_L

IST   pHashes)

Parameters

• lpFilenamePath to the encrypted file to remove users from.
• pHashesPointer to an ENCRYPTION_CERTIFICATE_HASH_LIST structure that contains a list of certificate hashes to be removed from the file.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a system error code. For extended error information, call GetLastError().

Reference

For more information and example source code, please see the RemoveUsersFromEncryptedFile entry in the Microsoft Developer Network.

DuplicateEncryptionInfoFile

This function copies the EFS metadata from one file or directory to another. This allows a user to copy a file without requiring access to all of the certificates that the FEK is wrapped in. This interface is especially valuable to application developers that will expect multiple user access to encrypted files. The developers can ensure that the encryption properties and wrapped FEK is maintained for all users.

Definition

DWORD WINAPI DuplicateEncryptionInfoFile (
LPCTSTR   lpSourceFilename,
LPCTSTR   lpDestinationFilename,
DWORD   dwCreationDistribution,
DWORD   dwAttributes,
LPSECURITY_ATTRIBUTES   lpSecurityAttributes)

Parameters

• lpSourceFilenamePath to the encrypted file or directory to read the EFS metadata from.
• lpDestinationFilenamePath to the file or directory to write the EFS metadata to. If source is a directory, then destination must be a directory. If source is a file, then destination must be a file.
• dwCreationDistributionThe following table lists the defined values:

• dwAttributesFile attributes of the destination file or directory. FILE_READ_ONLY and FILE_ENCRYPTED are ignored by this function.
• lpSecurityAttributesPointer to a SECURITY_ATTRIBUTES structure that specifies the security attributes of the destination file or directory, if it does not already exist. If NULL, a default security descriptor, inherited from the parent, is applied.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a system error code. For extended error information, call GetLastError().

Reference

For more information and example source code, please see the DuplicateEncryptionInfoFile entry in the Microsoft Developer Network.

QueryUsersOnEncryptedFile

This function queries and returns a list of certificate hashes for the users on an encrypted file.

DEFINTION

DWORD WINAPI QueryUsersOnEncryptedFile (
LPCWSTR   lpFilename,
PENCRYPTION_CERTIFICATE_HASH_LIST   pUsers)

Parameters

• lpFilenamePath to the encrypted file to return a list of users from.
• pUsersPointer to an ENCRYPTION_CERTIFICATE_HASH_LIST structure that receives the list of users.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a system error code. For extended error information, call GetLastError().

Reference

For more information and example source code, please see the QueryUsersOnEncryptedFile entry in the Microsoft Developer Network.

QueryRecoveryAgentsOnEncryptedFile

This function queries and returns a list of certificate hashes for the recovery agents on an encrypted file.

Definition

DWORD WINAPI QueryRecoveryAgentsOnEncryptedFile (
LPCWSTR   lpFilename,
PENCRYPTION_CERTIFICATE_HASH_LIST   pRecoveryAgents)

Parameters

• lpFilenamePath to the encrypted file to return a list of recovery agents from.
• pRecoveryAgentsPointer to an ENCRYPTION_CERTIFICATE_HASH_LIST structure that receives the list of recovery agents.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a system error code. For extended error information, call GetLastError().

Reference

For more information and example source code, please see the QueryRecoveryAgentsOnEncryptedFile entry in the Microsoft Developer Network.

FileEncryptionStatus

This function retrieves EFS status information about a file, including whether a file is encrypted or could be encrypted.

Definition

BOOL FileEncryptionStatus (
LPCTSTR   lpFilename,
LPDWORD   lpStatus)

Parameters

• lpFilenamePath to the file or directory to retrieve the status for.
• lpStatusPointer to a variable that receives that status of the file. The following table lists the possible values:

Return Values

If the function succeeds, the return value is non-zero.

If the function fails, the return value is zero. For extended error information, call GetLastError().

Reference

For more information and example source code, please see the FileEncryptionStatus entry in the Microsoft Developer Network.

SetUserFileEncryptionKey

This function configures an EFS certificate for the current user.

Definition

BOOL WINAPI SetUserFileEncryptionKey (
PENCRYPTION_CERTIFICATE   pEncryptionCertificate)

Parameters

• pEncryptionCertificatePointer to an ENCRYPTION_CERTIFICATE structure that holds the user's key.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a system error code. For extended error information, call GetLastError().

Reference

For more information and example source code, please see the SetUserFileEncryptionKey entry in the Microsoft Developer Network.

EncryptionDisable

This function enables or disables encryption for a specified directory.

Definition

BOOL WINAPI EncryptionDisable (
LPCWSTR   lpDirectoryname,
BOOL   bDisable)

Parameters

• lpDirectoryNamePath to the directory to disable or enable encryption for.
• bDisableIf TRUE, disable encryption. If FALSE, enable encryption.

Return Values

If the function succeeds, the return value is non-zero.

If the function fails, the return value is zero. For extended error information, call GetLastError().

Reference

For more information and example source code, please see the EncryptionDisable entry in the Microsoft Developer Network.

Data Structures

The EFS interfaces described above use a number of data structures. They are defined below.

EFS_CERTIFICATE_BLOB

This structure contains the actual data of a certificate

Definition

typedef struct _CERTIFICATE_BLOB {
DWORD   dwCertEncodingType;
DWORD   cbData;
PBYTE   pbData;
} EFS_CERTIFICATE_BLOB, *PEFS_CERTIFICATE_BLOB;

Members

• dwCertEncodingTypeCertificate encoding type. The following table lists the possible values:

• cbDataNumber of bytes in the pbData buffer.
• pbDataBinary certificate. The format of this certificate is specified by the dwCertEncodingType member.

Reference

For more information and example source code, please see the EFS_CERTIFICATE_BLOB entry in the Microsoft Developer Network.

ENCRYPTION_CERTIFICATE

This structure contains a certificate.

Definition

typedef struct _ENCRYPTION_CERTIFICATE {
DWORD   cbTotalLength;
SID   *pUserSid;
PEFS_CERTIFICATE_BLOB   pCertBlob;
} ENCRYPTION_CERTIFICATE, *PENCRYPTION_CERTIFICATE;

Members

• cbTotalLengthSize of structure in bytes.
• *pUserSidSID of the user who owns the certificate.
• pCertBlobPointer to an EFS_CERTIFICATE_BLOB structure.

Reference

For more information and example source code, please see the ENCRYPTION_CERTIFICATE entry in the Microsoft Developer Network.

For more information about the SID data structure, please see the SID entry in the Microsoft Developer Network.

ENCRYPTION_CERTIFICATE_LIST

This structure contains a list of certificates.

Definition

typedef struct _ENCRYPTION_CERTIFICATE_LIST {
DWORD   nUsers;
PENCRYPTION_CERTIFICATE   *pUsers;
} ENCRYPTION_CERTIFICATE_LIST, *PENCRYPTION_CERTIFICATE_LIST;

Members

• nUsersNumber of certificates in the list.
• *pUsersPointer to the first ENCRYPTION_CERTIFICATE in the list.

Reference

For more information and example source code, please see the ENCRYPTION_CERTIFICATE_LIST entry in the Microsoft Developer Network.

EFS_HASH_BLOB

This structure contains the actual data of a certificate hash.

Definition

typedef struct _EFS_HASH_BLOB {
DWORD   cbData;
PBYTE   pbData;
} EFS_HASH_BLOB, *PEFS_HASH_BLOB;

Members

• cbDataNumber of bytes in the pbData buffer.
• pbDataCertificate hash.

Reference

For more information and example source code, please see the EFS_HASH_BLOB entry in the Microsoft Developer Network.

ENCRYPTION_CERTIFICATE_HASH

This structure contains a certificate hash.

Definition

typedef struct _ENCRYPTION_CERTIFICATE_HASH {
DWORD   cbTotalLength;
SID   *pUserSid;
PEFS_HASH_BLOB   pHash;
LPWSTR   lpDisplayInformation;
} ENCRYPTION_CERTIFICATE_HASH, *PENCRYPTION_CERTIFICATE_HASH;

Members

• cbTotalLengthSize of structure in bytes.
• *pUserSidSID of the user who owns the certificate.
• pHashPointer to an EFS_HASH_BLOB structure.
• lpDisplayInformationUser displayable information for the certificate.

Reference

For more information and example source code, please see the ENCRYPTION_CERTIFICATE_HASH entry in the Microsoft Developer Network.

For more information about the SID data structure, please see the SID entry in the Microsoft Developer Network.

ENCRYPTION_CERTIFICATE_HASH_LIST

This structure contains a list of certificate hashes.

Definition

typedef struct _ENCRYPTION_CERTIFICATE_HASH_LIST {
DWORD   nUsers;
PENCRYPTION_CERTIFICATE_HASH   *pUsers;
} ENCRYPTION_CERTIFICATE_HASH_LIST, *PENCRYPTION_CERTIFICATE_HASH_LIST;

Members

• nUsersNumber of certificate hashes in the list.
• *pUsersPointer to the first ENCRYPTION_CERTIFICAT_HASH in the list.

Reference

For more information and example source code, please see the ENCRYPTION_CERTIFICATE_HASH_LIST entry in the Microsoft Developer Network.

SECURITY_ATTRIBUTES

This structure contains the security descriptor for an object.

Definition

typedef struct _SECURITY_ATTRIBUTES {
DWORD   nLength;
LPVOID   lpSecurityDescriptor;
BOOL   bInheritHandle;
} SECURITY_ATTRIBUTES, *PSECURITY_ATTRIBUTES;

Members

• nLengthSize of structure in bytes.
• lpSecurityDescriptorPointer to a security descriptor object that controls the sharing of it. If NULL, a default security descriptor, from the calling process, is assigned.
• bInheritHandleSpecifies whether the returned handle is inherited when a new process is created. If this member is TRUE, the new process inherits the handle.

Reference

For more information and example source code, please see the SECURITY_ATTRIBUTES entry in the Microsoft Developer Network.

Security

Overall, EFS makes a reasonable effort at providing file confidentiality. The EFS components are well-designed and implemented. The EFS code makes good attempts to clean up resources when finished with them and to recover from system failures while performing operations. The EFS components also reuse existing code through system APIs for key and certificate management.

It is important to note that file integrity or authentication protection are not services EFS provides.

The design of EFS has made some conscious tradeoffs between absolute security and convenience. These tradeoff decisions result in some edge-case scenarios, which we describe below. None of these edge-case scenarios are bugs; they are results of the design decisions and were known from the start. Additionally, the vast majority of EFS users will never encounter these edge-case scenarios in normal use. We discuss them here simply to make users aware that using EFS does require a heightened awareness of file handling.

• First, it is possible after certain actions for two files to share a FEK. If two files share a FEK, a user with cryptographic access to either of the files can use the FEK from the file they can access to decrypt the other file. The user must also have file-system access to the other file.

  For example, Bob creates an encrypted file. He then copies the file, using explorer or some other method that uses the Win32 CopyFile() interface, to a new file. The result is that the new file has the same FEK as the original file. If Mallory can get the FEK from either file, she can then access both files.

  A recommended way to prevent this from occurring is for a user to open the original encrypted file in an editor and perform a Save As and save the data to a new file. This creates a completely new file with a new FEK.

• Second, when a user is removed from an encrypted file, there is no absolute guarantee that cryptographic access has been fully revoked. If the newly-removed user has a backup of the original file which grants them access, they can decrypt the FEK from the backup file and access the new file. Again, the user must have file-system access to the new file.

  For example, Alice creates an encrypted file and then adds Bob to the file such that Bob can access it. After some time Alice removes Bob from the file. If Bob had saved the FEK from the file while he had access to it, or if he had a backup of the original file, he could then decrypt the new file after Alice had removed him. To accomplish this, Bob would have to write custom code to decrypt the file and have physical offline access to the file.

  No recommended procedure exists to prevent this scenario, as once a user has access to the plaintext data of a file, the user may copy the data to another medium physically separate from the original encrypted file.

• Third, EFS does not provide file integrity protection or file authentication. If a user can gain file-system access to an encrypted file, for exmple by bypassing the normal file access controls, that user can replace the original encrypted file with a different file without any notification to the file owner. Of course, this is no worse than not using EFS, and since EFS does provide confidentiality, that user will not know the contents of the original encrypted file.

  For example, Bob creates an encrypted file. Mallory, in some manner, is able to gain file-system access to the file. She cannot read the contents of the file, but she can replace the encrypted file with another file, without any notification to Bob.

  A recommended way to prevent this from occurring is to maintain tight access controls and physical controls of files in order to prevent spoofing attacks.

Contributors

The contributors of this document are Wesley Griffin, Michael Heyman, Richard Clayton, Michael St. Johns, and David Carman, members of the Cryptographic Technologies Group in Network Associates Laboratories. Network Associates Laboratories is a multi-discipline research organization with world-renowned expertise in the areas of network security, cryptographic technologies, security infrastructure components, secure execution environments, adaptive network defense, distributed systems security, and security architecture modeling.

The contributors would like to acknowledge the help of Mike Lai, David Cross, Robert Gu and Drew Cooper, all at Microsoft, for providing information on EFS. We would also like to thank Doug Bayer and Dave Thompson for contributing Microsoft resources.

References

Encrypting File System in Windows XP and Windows Server 2003, David Cross, Microsoft, August 2002.

MSDN Library, Microsoft, January 2002.

Windows NT File System Internals: A Developer's Guide, Rajeev Nagar, O'Reilly, September 1997.