[MS-EFSR]: Encrypting File System Remote (EFSRPC) Protocol. Intellectual Property Rights Notice for Open Specifications Documentation

Transcription

1 [MS-EFSR]: Intellectual Property Rights Notice for Open Specifications Documentation Technical Documentation. Microsoft publishes Open Specifications documentation ( this documentation ) for protocols, file formats, data portability, computer languages, and standards support. Additionally, overview documents cover inter-protocol relationships and interactions. Copyrights. This documentation is covered by Microsoft copyrights. Regardless of any other terms that are contained in the terms of use for the Microsoft website that hosts this documentation, you can make copies of it in order to develop implementations of the technologies that are described in this documentation and can distribute portions of it in your implementations that use these technologies or in your documentation as necessary to properly document the implementation. You can also distribute in your implementation, with or without modification, any schemas, IDLs, or code samples that are included in the documentation. This permission also applies to any documents that are referenced in the Open Specifications documentation. No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation. Patents. Microsoft has patents that might cover your implementations of the technologies described in the Open Specifications documentation. Neither this notice nor Microsoft's delivery of this documentation grants any licenses under those patents or any other Microsoft patents. However, a given Open Specifications document might be covered by the Microsoft Open Specifications Promise or the Microsoft Community Promise. If you would prefer a written license, or if the technologies described in this documentation are not covered by the Open Specifications Promise or Community Promise, as applicable, patent licenses are available by contacting iplg@microsoft.com. License Programs. To see all of the protocols in scope under a specific license program and the associated patents, visit the Patent Map. Trademarks. The names of companies and products contained in this documentation might be covered by trademarks or similar intellectual property rights. This notice does not grant any licenses under those rights. For a list of Microsoft trademarks, visit Fictitious Names. The example companies, organizations, products, domain names, addresses, logos, people, places, and events that are depicted in this documentation are fictitious. No association with any real company, organization, product, domain name, address, logo, person, place, or event is intended or should be inferred. Reservation of Rights. All other rights are reserved, and this notice does not grant any rights other than as specifically described above, whether by implication, estoppel, or otherwise. Tools. The Open Specifications documentation does not require the use of Microsoft programming tools or programming environments in order for you to develop an implementation. If you have access to Microsoft programming tools and environments, you are free to take advantage of them. Certain Open Specifications documents are intended for use in conjunction with publicly available standards specifications and network programming art and, as such, assume that the reader either is familiar with the aforementioned material or has immediate access to it. Support. For questions and support, please contact dochelp@microsoft.com. 1 / 92

2 Revision Summary Date Revision History Revision Class Comments 3/2/ New Version 1.0 release 4/3/ Minor Version 1.1 release 5/11/ Minor Version 1.2 release 6/1/ Editorial Changed language and formatting in the technical content. 7/3/ Minor Clarified the meaning of the technical content. 8/10/ Major Updated and revised the technical content. 9/28/ Major Converted to unified format. 10/23/ Minor Clarified the meaning of the technical content. 1/25/ Editorial Changed language and formatting in the technical content. 3/14/ Editorial Changed language and formatting in the technical content. 6/20/ Major Updated and revised the technical content. 7/25/ Editorial Changed language and formatting in the technical content. 8/29/ Editorial Changed language and formatting in the technical content. 10/24/ Editorial Changed language and formatting in the technical content. 12/5/ Major Updated and revised the technical content. 1/16/ Editorial Changed language and formatting in the technical content. 2/27/ Editorial Changed language and formatting in the technical content. 4/10/ Editorial Changed language and formatting in the technical content. 5/22/ Major Updated and revised the technical content. 7/2/ Editorial Changed language and formatting in the technical content. 8/14/ Editorial Changed language and formatting in the technical content. 9/25/ Major Updated and revised the technical content. 11/6/ Major Updated and revised the technical content. 12/18/ Major Updated and revised the technical content. 1/29/ Major Updated and revised the technical content. 3/12/ Major Updated and revised the technical content. 4/23/ Editorial Changed language and formatting in the technical content. 6/4/ Major Updated and revised the technical content. 7/16/ Major Updated and revised the technical content. 8/27/ Major Updated and revised the technical content. 2 / 92

3 Date Revision History Revision Class Comments 10/8/ Major Updated and revised the technical content. 11/19/ None 1/7/ None No changes to the meaning, language, or formatting of the technical content. No changes to the meaning, language, or formatting of the technical content. 2/11/ Major Updated and revised the technical content. 3/25/ Major Updated and revised the technical content. 5/6/ None No changes to the meaning, language, or formatting of the technical content. 6/17/ Minor Clarified the meaning of the technical content. 9/23/ Major Updated and revised the technical content. 12/16/ Major Updated and revised the technical content. 3/30/ None 7/12/ None No changes to the meaning, language, or formatting of the technical content. No changes to the meaning, language, or formatting of the technical content. 10/25/ Major Updated and revised the technical content. 1/31/ None No changes to the meaning, language, or formatting of the technical content. 8/8/ Major Updated and revised the technical content. 11/14/ None 2/13/ None 5/15/ None No changes to the meaning, language, or formatting of the technical content. No changes to the meaning, language, or formatting of the technical content. No changes to the meaning, language, or formatting of the technical content. 6/30/ Major Significantly changed the technical content. 10/16/ Major Significantly changed the technical content. 7/14/ Major Significantly changed the technical content. 6/1/ None No changes to the meaning, language, or formatting of the technical content. 9/15/ Major Significantly changed the technical content. 3 / 92

4 Table of Contents 1 Introduction Glossary References Normative References Informative References Overview Relationship to Other Protocols Prerequisites/Preconditions Applicability Statement Versioning and Capability Negotiation Vendor-Extensible Fields Standards Assignments Messages Transport Common Data Types EFSRPC Identifiers EFSRPC Metadata EFSRPC Metadata Version Key List Structure Key List Entry Public Key Information Certificate Data Encrypted FEK EFSRPC Metadata Version Protector List Structure EFSX Datum Blob Datum Descriptor Datum Protector List Entry Protector Info Datum Key Agreement Datum Fek Info Datum DPAPI-NG Datum EFSRPC Metadata Version EFSRPC Raw Data Format Marshaled Stream Stream Data Segment Data Segment Encryption Header Extended Header PEXIMPORT_CONTEXT_HANDLE EFS_EXIM_PIPE EFS_CERTIFICATE_BLOB EFS_HASH_BLOB ENCRYPTION_CERTIFICATE ENCRYPTION_CERTIFICATE_LIST ENCRYPTION_CERTIFICATE_HASH ENCRYPTION_CERTIFICATE_HASH_LIST EFS_RPC_BLOB ALG_ID EFS_KEY_INFO EFS_COMPATIBILITY_INFO EFS_ENCRYPTION_STATUS_INFO EFS_DECRYPTION_STATUS_INFO ENCRYPTED_FILE_METADATA_SIGNATURE / 92

5 ENCRYPTION_PROTECTOR ENCRYPTION_PROTECTOR_LIST Protocol Details Server Details Abstract Data Model User-Certificate Binding EFSRPC Server Control Timers Initialization Message Processing Events and Sequencing Rules Application Requests for a User-Certificate Binding EFS Certificate Enrollment Algorithm Inputs Outputs Internal Variables Processing Rules Building a List of CAs that Support a Particular Template Creating a Request EFSRPC Interface Receiving an EfsRpcOpenFileRaw Message (Opnum 0) Receiving an EfsRpcReadFileRaw Message (Opnum 1) Receiving an EfsRpcWriteFileRaw Message (Opnum 2) Receiving an EfsRpcCloseRaw Message (Opnum 3) Receiving an EfsRpcEncryptFileSrv Message (Opnum 4) Receiving an EfsRpcDecryptFileSrv Message (Opnum 5) Receiving an EfsRpcQueryUsersOnFile Message (Opnum 6) Receiving an EfsRpcQueryRecoveryAgents Message (Opnum 7) Receiving an EfsRpcRemoveUsersFromFile Message (Opnum 8) Receiving an EfsRpcAddUsersToFile Message (Opnum 9) Receiving an EfsRpcNotSupported Message (Opnum 11) Receiving an EfsRpcFileKeyInfo Message (Opnum 12) Receiving an EfsRpcDuplicateEncryptionInfoFile Message (Opnum 13) Receiving an EfsRpcAddUsersToFileEx Message (Opnum 15) Receiving an EfsRpcFileKeyInfoEx Message (Opnum 16) Receiving an EfsRpcGetEncryptedFileMetadata Message (Opnum 18) Receiving an EfsRpcSetEncryptedFileMetadata Message (Opnum 19) Receiving an EfsRpcFlushEfsCache Message (Opnum 20) Receiving an EfsRpcEncryptFileExSrv Message (Opnum 21) Receiving an EfsRpcQueryProtectors (Opnum 22) Timer Events Other Local Events Protocol Examples Security Security Considerations for Implementers Index of Security Parameters Appendix A: Full IDL Appendix B: Product Behavior Change Tracking Index 91 5 / 92

6 1 Introduction The is used for performing maintenance and management operations on encrypted data that is stored remotely and accessed over a network. It is used in Windows to manage files that reside on remote file servers and are encrypted using the Encrypting File System (EFS). Sections 1.5, 1.8, 1.9, 2, and 3 of this specification are normative. All other sections and examples in this specification are informative. 1.1 Glossary This document uses the following terms: access control list (ACL): A list of access control entries (ACEs) that collectively describe the security rules for authorizing access to some resource; for example, an object or set of objects. Active Directory: A general-purpose network directory service. Active Directory also refers to the Windows implementation of a directory service. Active Directory stores information about a variety of objects in the network. User accounts, computer accounts, groups, and all related credential information used by the Windows implementation of Kerberos are stored in Active Directory. Active Directory is either deployed as Active Directory Domain Services (AD DS) or Active Directory Lightweight Directory Services (AD LDS). [MS-ADTS] describes both forms. For more information, see [MS-AUTHSOD] section , Lightweight Directory Access Protocol (LDAP) versions 2 and 3, Kerberos, and DNS. Advanced Encryption Standard (AES): A block cipher that supersedes the Data Encryption Standard (DES). AES can be used to protect electronic data. The AES algorithm can be used to encrypt (encipher) and decrypt (decipher) information. Encryption converts data to an unintelligible form called ciphertext; decrypting the ciphertext converts the data back into its original form, called plaintext. AES is used in symmetric-key cryptography, meaning that the same key is used for the encryption and decryption operations. It is also a block cipher, meaning that it operates on fixed-size blocks of plaintext and ciphertext, and requires the size of the plaintext as well as the ciphertext to be an exact multiple of this block size. AES is also known as the Rijndael symmetric encryption algorithm [FIPS197]. binary large object (BLOB): A collection of binary data stored as a single entity in a database. binding: The string representation of the protocol sequence, NetworkAddress, and optionally the endpoint. Also referred to as "string binding". For more information, see [C706] section "String Bindings". certificate: A certificate is a collection of attributes and extensions that can be stored persistently. The set of attributes in a certificate can vary depending on the intended usage of the certificate. A certificate securely binds a public key to the entity that holds the corresponding private key. A certificate is commonly used for authentication and secure exchange of information on open networks, such as the Internet, extranets, and intranets. Certificates are digitally signed by the issuing certification authority (CA) and can be issued for a user, a computer, or a service. The most widely accepted format for certificates is defined by the ITU-T X.509 version 3 international standards. For more information about attributes and extensions, see [RFC3280] and [X509] sections 7 and 8. certificate template: A list of attributes that define a blueprint for creating an X.509 certificate. It is often referred to in non-microsoft documentation as a "certificate profile". A certificate template is used to define the content and purpose of a digital certificate, including issuance requirements (certificate policies), implemented X.509 extensions such as application policies, key usage, or extended key usage as specified in [X509], and enrollment permissions. Enrollment permissions define the rules by which a certification authority (CA) will issue or 6 / 92

7 deny certificate requests. In Windows environments, certificate templates are stored as objects in the Active Directory and used by Microsoft enterprise CAs. certification authority (CA): A third party that issues public key certificates. Certificates serve to bind public keys to a user identity. Each user and certification authority (CA) can decide whether to trust another user or CA for a specific purpose, and whether this trust should be transitive. For more information, see [RFC3280]. Data Decryption Field (DDF): The portion of the EFSRPC Metadata that contains information that enables authorized users to decrypt the file. data recovery agent (DRA): A logical entity corresponding to an asymmetric key pair, which is configured as part of Encrypting File System (EFS) administrative policy by an administrator. Whenever an EFS file is created or modified, it is also automatically configured to give authorized access to all DRAs in effect at that time. data recovery field (DRF): The portion of the EFSRPC Metadata that contains information that enables authorized DRAs to decrypt the file. decryption: In cryptography, the process of transforming encrypted information to its original clear text form. domain: A set of users and computers sharing a common namespace and management infrastructure. At least one computer member of the set must act as a domain controller (DC) and host a member list that identifies all members of the domain, as well as optionally hosting the Active Directory service. The domain controller provides authentication of members, creating a unit of trust for its members. Each domain has an identifier that is shared among its members. For more information, see [MS-AUTHSOD] section and [MS-ADTS]. domain controller (DC): The service, running on a server, that implements Active Directory, or the server hosting this service. The service hosts the data store for objects and interoperates with other DCs to ensure that a local change to an object replicates correctly across all DCs. When Active Directory is operating as Active Directory Domain Services (AD DS), the DC contains full NC replicas of the configuration naming context (config NC), schema naming context (schema NC), and one of the domain NCs in its forest. If the AD DS DC is a global catalog server (GC server), it contains partial NC replicas of the remaining domain NCs in its forest. For more information, see [MS-AUTHSOD] section and [MS-ADTS]. When Active Directory is operating as Active Directory Lightweight Directory Services (AD LDS), several AD LDS DCs can run on one server. When Active Directory is operating as AD DS, only one AD DS DC can run on one server. However, several AD LDS DCs can coexist with one AD DS DC on one server. The AD LDS DC contains full NC replicas of the config NC and the schema NC in its forest. The domain controller is the server side of Authentication Protocol Domain Support [MS-APDS]. EFSRPC Metadata: The additional data stored with an encrypted file to enable authorized users to access the data in the file. The format of this metadata is implementation-dependent. The EFSRPC Metadata general requirements are specified in detail in section and the Windows format is specified in associated endnotes in Appendix B of this specification. EFSRPC Raw Data Format: The data format used by the EFSRPC raw methods to marshal the contents and metadata of an encrypted file into a single-bit stream. It is specified in section Encrypting File System (EFS): The name for the encryption capability of the NTFS file system. When a file is encrypted using EFS, a symmetric key known as the file encryption key (FEK) is generated and the contents of the file are encrypted with the FEK. For each user or data recovery agent (DRA) that is authorized to access the file, a copy of the FEK is encrypted with that user's or DRA's public key and is stored in the file's metadata. For more information about EFS, see [MSFT-EFS]. 7 / 92

8 encryption: In cryptography, the process of obscuring information to make it unreadable without special knowledge. endpoint: A network-specific address of a remote procedure call (RPC) server process for remote procedure calls. The actual name and type of the endpoint depends on the RPC protocol sequence that is being used. For example, for RPC over TCP (RPC Protocol Sequence ncacn_ip_tcp), an endpoint might be TCP port For RPC over Server Message Block (RPC Protocol Sequence ncacn_np), an endpoint might be the name of a named pipe. For more information, see [C706]. file: A unit of data in the file system. An encrypted file consists of encrypted data along with the metadata required for a user to decrypt the file. The file and its metadata are protected using public key cryptography such that an authorized user's private key is required to decrypt the file. File Encryption Key (FEK): The symmetric key that is used to encrypt the data in an EFSprotected file. The FEK is further encrypted and stored in the file metadata such that only authorized users can access it. file system: A system that enables applications to store and retrieve files on storage devices. Files are placed in a hierarchical structure. The file system specifies naming conventions for files and the format for specifying the path to a file in the tree structure. Each file system consists of one or more drivers and DLLs that define the data formats and features of the file system. File systems can exist on the following storage devices: diskettes, hard disks, jukeboxes, removable optical disks, and tape backup units. flags: A set of values used to configure or report options or settings. folder: A container for files and other folders. A folder may be encrypted. The semantics of encrypting a folder are implementation-dependent. In the Windows implementation, encrypting a folder does not directly cause any data to be encrypted. Encrypting a folder in Windows has the following consequences of EFSRPC Metadata is created and stored with the folder and an NTFS attribute is set on the folder to signify that it is encrypted. NTFS checks this attribute when any new files or folders are created in the folder. NTFS will automatically encrypt any files or folders created within a folder that has this attribute set. fully qualified domain name (FQDN): An unambiguous domain name that gives an absolute location in the Domain Name System's (DNS) hierarchy tree, as defined in [RFC1035] section 3.1 and [RFC2181] section 11. globally unique identifier (GUID): A term used interchangeably with universally unique identifier (UUID) in Microsoft protocol technical documents (TDs). Interchanging the usage of these terms does not imply or require a specific algorithm or mechanism to generate the value. Specifically, the use of this term does not imply or require that the algorithms described in [RFC4122] or [C706] must be used for generating the GUID. See also universally unique identifier (UUID). Kerberos constrained delegation: A form of authentication delegation in which Kerberos can be used to impersonate users that send requests for certain services, as opposed to all services. key: In cryptography, a generic term used to refer to cryptographic data that is used to initialize a cryptographic algorithm. Keys are also sometimes referred to as keying material. Lightweight Directory Access Protocol (LDAP): The primary access protocol for Active Directory. Lightweight Directory Access Protocol (LDAP) is an industry-standard protocol, established by the Internet Engineering Task Force (IETF), which allows users to query and update information in a directory service (DS), as described in [MS-ADTS]. The Lightweight Directory Access Protocol can be either version 2 [RFC1777] or version 3 [RFC3377]. 8 / 92

9 named pipe: A named, one-way, or duplex pipe for communication between a pipe server and one or more pipe clients. New Technology File System (NTFS): The native file system of Windows 2000 operating system, Windows XP operating system, Windows Vista operating system, Windows 7 operating system, and Windows 8 operating system. Within this document, this term is occasionally used to refer to the operating system subsystem that implements NTFS support. For more information, see [MSFT-NTFS]. NT file system (NTFS): A proprietary Microsoft file system. For more information, see [MSFT- NTFS]. opnum: An operation number or numeric identifier that is used to identify a specific remote procedure call (RPC) method or a method in an interface. For more information, see [C706] section or [MS-RPCE]. plaintext: In cryptography, ordinary readable text before it is encrypted into ciphertext, or after it has been decrypted. private key: One of a pair of keys used in public-key cryptography. The private key is kept secret and is used to decrypt data that has been encrypted with the corresponding public key. For an introduction to this concept, see [CRYPTO] section 1.8 and [IEEE1363] section 3.1. public key: One of a pair of keys used in public-key cryptography. The public key is distributed freely and published as part of a digital certificate. For an introduction to this concept, see [CRYPTO] section 1.8 and [IEEE1363] section 3.1. remote procedure call (RPC): A context-dependent term commonly overloaded with three meanings. Note that much of the industry literature concerning RPC technologies uses this term interchangeably for any of the three meanings. Following are the three definitions: (*) The runtime environment providing remote procedure call facilities. The preferred usage for this meaning is "RPC runtime". (*) The pattern of request and response message exchange between two parties (typically, a client and a server). The preferred usage for this meaning is "RPC exchange". (*) A single message from an exchange as defined in the previous definition. The preferred usage for this term is "RPC message". For more information about RPC, see [C706]. Rivest-Shamir-Adleman (RSA): A system for public key cryptography. RSA is specified in [PKCS1] and [RFC3447]. RPC protocol sequence: A character string that represents a valid combination of a remote procedure call (RPC) protocol, a network layer protocol, and a transport layer protocol, as described in [C706] and [MS-RPCE]. RPC transport: The underlying network services used by the remote procedure call (RPC) runtime for communications between network nodes. For more information, see [C706] section 2. security context: An abstract data structure that contains authorization information for a particular security principal in the form of a Token/Authorization Context (see [MS-DTYP] section 2.5.2). A server uses the authorization information in a security context to check access to requested resources. A security context also contains a key identifier that associates mutually established cryptographic keys, along with other information needed to perform secure communication with another security principal. security identifier (SID): An identifier for security principals that is used to identify an account or a group. Conceptually, the SID is composed of an account authority portion (typically a domain) and a smaller integer representing an identity relative to the account authority, termed the relative identifier (RID). The SID format is specified in [MS-DTYP] section 2.4.2; a string representation of SIDs is specified in [MS-DTYP] section and [MS-AZOD] section / 92

10 security provider: A pluggable security module that is specified by the protocol layer above the remote procedure call (RPC) layer, and will cause the RPC layer to use this module to secure messages in a communication session with the server. The security provider is sometimes referred to as an authentication service. For more information, see [C706] and [MS-RPCE]. Security Support Provider Interface (SSPI): A Windows-specific API implementation that provides the means for connected applications to call one of several security providers to establish authenticated connections and to exchange data securely over those connections. This is the Windows equivalent of Generic Security Services (GSS)-API, and the two families of APIs are on-the-wire compatible. server: A computer on which the remote procedure call (RPC) server is executing. Server Message Block (SMB): A protocol that is used to request file and print services from server systems over a network. The SMB protocol extends the CIFS protocol with additional security, file, and disk management support. For more information, see [CIFS] and [MS-SMB]. sparse file: A file containing large sections of data composed only of zeros. This file is marked as a sparse file in the file system, which saves disk space by only allocating as many ranges on disk as are required to completely reconstruct the non-zero data. When an attempt is made to read in the nonallocated portions of the file (also known as holes), the file system automatically returns zeros to the caller. stream: A sequence of bytes written to a file on the target file system. Every file stored on a volume that uses the file system contains at least one stream, which is normally used to store the primary contents of the file. Additional streams within the file can be used to store file attributes, application parameters, or other information specific to that file. Every file has a default data stream, which is unnamed by default. That data stream, and any other data stream associated with a file, can optionally be named. UncPath: The location of a file in a network of computers, as specified in Universal Naming Convention (UNC) syntax. Unicode: A character encoding standard developed by the Unicode Consortium that represents almost all of the written languages of the world. The Unicode standard [UNICODE5.0.0/2007] provides three forms (UTF-8, UTF-16, and UTF-32) and seven schemes (UTF-8, UTF-16, UTF-16 BE, UTF-16 LE, UTF-32, UTF-32 LE, and UTF-32 BE). universally unique identifier (UUID): A 128-bit value. UUIDs can be used for multiple purposes, from tagging objects with an extremely short lifetime, to reliably identifying very persistent objects in cross-process communication such as client and server interfaces, manager entry-point vectors, and RPC objects. UUIDs are highly likely to be unique. UUIDs are also known as globally unique identifiers (GUIDs) and these terms are used interchangeably in the Microsoft protocol technical documents (TDs). Interchanging the usage of these terms does not imply or require a specific algorithm or mechanism to generate the UUID. Specifically, the use of this term does not imply or require that the algorithms described in [RFC4122] or [C706] must be used for generating the UUID. valid data length (VDL): In NTFS, there are two important concepts of file length: the end-offile (EOF) marker and the valid data length (VDL). The EOF indicates the actual length of the file. The VDL identifies the length of valid data on disk. Any reads between VDL and EOF automatically return zeros. well-known endpoint: A preassigned, network-specific, stable address for a particular client/server instance. For more information, see [C706]. X.509: An ITU-T standard for public key infrastructure subsequently adapted by the IETF, as specified in [RFC3280]. 10 / 92

11 MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as defined in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or SHOULD NOT. 1.2 References Links to a document in the Microsoft Open Specifications library point to the correct section in the most recently published version of the referenced document. However, because individual documents in the library are not updated at the same time, the section numbers in the documents may not match. You can confirm the correct section numbering by checking the Errata Normative References We conduct frequent surveys of the normative references to assure their continued availability. If you have any issue with finding a normative reference, please contact dochelp@microsoft.com. We will assist you in finding the relevant information. [C706] The Open Group, "DCE 1.1: Remote Procedure Call", C706, August 1997, [MS-ADTS] Microsoft Corporation, "Active Directory Technical Specification". [MS-CRTD] Microsoft Corporation, "Certificate Templates Structure". [MS-DTYP] Microsoft Corporation, "Windows Data Types". [MS-ERREF] Microsoft Corporation, "Windows Error Codes". [MS-RMPR] Microsoft Corporation, "Rights Management Services (RMS): Client-to-Server Protocol". [MS-RPCE] Microsoft Corporation, "Remote Procedure Call Protocol Extensions". [MS-SMB2] Microsoft Corporation, "Server Message Block (SMB) Protocol Versions 2 and 3". [MS-SMB] Microsoft Corporation, "Server Message Block (SMB) Protocol". [MS-WCCE] Microsoft Corporation, "Windows Client Certificate Enrollment Protocol". [RFC1035] Mockapetris, P., "Domain Names - Implementation and Specification", STD 13, RFC 1035, November 1987, [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997, [RFC2251] Wahl, M., Howes, T., and Kille, S., "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997, [RFC3394] Schaad, J., Housley, R., "Advanced Encryption Standard (AES) Key Wrap Algorithm", RFC 3394, September 2002, [RFC5280] Cooper, D., Santesson, S., Farrell, S., et al., "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, May 2008, Informative References [FIPS180-4] FIPS PUBS, "Secure Hash Standards (SHS)", March 2012, 11 / 92

12 [MS-ADOD] Microsoft Corporation, "Active Directory Protocols Overview". [MS-SFU] Microsoft Corporation, "Kerberos Protocol Extensions: Service for User and Constrained Delegation Protocol". [MS-WDV] Microsoft Corporation, "Web Distributed Authoring and Versioning (WebDAV) Protocol: Client Extensions". [MSDN-CRYPTO] Microsoft Corporation, "Cryptography Reference", [MSFT-EFS] Microsoft Corporation, "The Encrypting File System", [MSFT-NTFS] Microsoft Corporation, "NTFS Technical Reference", March 2003, [MSFT-XPUEFS] Microsoft Corporation, "Windows XP Professional Resource Kit: Using Encrypting File System", November 2005, [TDEA] National Institute of Standards and Technology, "Recommendation for the Triple Data Encryption Algorithm (TDEA) Block Cipher", Special Publication , May 2004, [X509] ITU-T, "Information Technology - Open Systems Interconnection - The Directory: Public-Key and Attribute Certificate Frameworks", Recommendation X.509, August 2005, [X690] ITU-T, "Information Technology - ASN.1 Encoding Rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)", Recommendation X.690, July 2002, Overview The Encrypting File System Remote Protocol (hereafter referred to as EFSRPC) is a Remote Procedure Call (RPC) interface that is used to manage data objects stored in an encrypted form. The objective of encrypting data in this fashion is to enforce access control policies and to provide confidentiality from unauthorized users. EFSRPC is implemented in Windows to provide remote management for files encrypted by the Encrypting File System (EFS). EFS is the ability of the New Technology File System (NTFS) file system to encrypt files on disk in a manner that is transparent to the user. For more information on EFS, see [MSFT-EFS]. For more information about NTFS, see [MSFT-NTFS]. EFSRPC does not address how data is encrypted, how the encrypted data is stored, or how it is accessed for routine operations such as reading, writing, creating, and deleting. All these actions are specific to the server implementation. On Windows, NTFS provides the storage mechanism (the file is the unit of storage) and the Server Message Block (SMB) Protocol provides remote access to such files. For more information about SMB, see [MS-SMB] and [MS-SMB2]. EFSRPC models the underlying data encryption architecture using two basic constructs: A set of data objects, each of which is encrypted independently and can be managed independently. A set of access control subjects, each of which is represented by a key pair generated by a public key cryptographic algorithm. The public key of this key pair is embedded in a certificate and can be widely distributed in that form. The corresponding private key is held solely by the user or 12 / 92

13 users who represent that subject. Thus, a given access control subject can correspond to one or more users, and a given user can possess the private keys for zero or more access control subjects. Access control subjects are further divided into two types: Unprivileged user subjects, which are used for routine data access by ordinary users of the system. For convenience, this specification refers to such subjects as user certificate. Data Recovery Agents (DRAs), which are controlled by system administrators. The storage system ensures that all active DRAs for the system are automatically authorized to access all encrypted objects on the system. If an unprivileged user loses the private key, an administrator can use a DRA's private key to recover the contents of encrypted objects. EFSRPC also assumes that each encrypted object is associated with some security-related metadata, which contains information required for authorized users and DRAs to access the plaintext of the object. This specification refers to this security-related metadata as the EFSRPC Metadata. EFSRPC does not specify how data is encrypted, stored, or accessed. It is possible to build a compliant EFSRPC implementation that uses a mechanism, such as access control lists (ACLs), instead of encryption to control access to data objects. For the purposes of this specification, the term encrypted is used to indicate that a data object and its metadata can be successfully manipulated through the EFSRPC methods, with the exception of the EfsRpcEncryptFileSrv method, which converts data objects from an unencrypted state to an encrypted state. Within the preceding model, EFSRPC provides various categories of management routines. The syntax of the individual methods and rules for how these methods are processed on the server are specified in section The categories of management routines that EFSRPC provides are as follows: Requesting the server to convert objects from encrypted state to unencrypted state and vice versa. EfsRpcEncryptFileSrv (section ) EfsRpcDecryptFileSrv (section ) Creating, querying, and manipulating the EFSRPC Metadata. Clients use the following methods to query and change which user certificates can be used to decrypt an encrypted object. The set of user certificates with access to an object needs to be changed when the set of users with access to the object changes or when a user with access to the object changes the user certificate. The following methods can also be used to copy the access rights from one object to another; the EfsRpcDuplicateEncryptionInfoFile method is particularly well-suited for this purpose. Methods: EfsRpcQueryUsersOnFile (section ) EfsRpcQueryRecoveryAgents (section ) EfsRpcRemoveUsersFromFile (section ) EfsRpcAddUsersToFile (section ) EfsRpcFileKeyInfo (section ) EfsRpcDuplicateEncryptionInfoFile (section ) EfsRpcAddUsersToFileEx (section ) EfsRpcFileKeyInfoEx (section ) EfsRpcGetEncryptedFileMetadata (section ) EfsRpcSetEncryptedFileMetadata (section ) 13 / 92

14 Performing backup of encrypted objects in ciphertext form along with their EFSRPC Metadata, and restoring encrypted objects from such backups. Depending on the implementation of these methods, the backups that are created can expose the implementation-specific EFSRPC Metadata format to the client. The Windows implementation of these methods exposes the Windows EFSRPC Metadata format; however, Windows applications do not manipulate this information. The following methods are suitable for secure content archival or transferring encrypted data securely between servers of the same implementation because they do not require decrypting the data. Methods: EfsRpcOpenFileRaw (section ) EfsRpcReadFileRaw (section ) EfsRpcWriteFileRaw (section ) EfsRpcCloseRaw (section ) Controlling the server's encryption subsystem. Methods: EfsRpcFlushEfsCache (section ) Most of the EFSRPC routines are stateless and can be called in any order. When one of these routines is called, the message exchange is as follows. Figure 1: Message exchange for stateless routines There are two routines in EFSRPC that are an exception to the stateless nature of the protocol. Several methods, collectively known as the EFSRPC raw methods, are an exception and need to be called in a specific order. This includes the EfsRpcOpenFileRaw, EfsRpcReadFileRaw, EfsRpcWriteFileRaw, and EfsRpcCloseRaw methods. The following two sequences are permissible. 14 / 92

15 Figure 2: Message sequence for opening a file 15 / 92

16 Figure 3: Message sequence for importing a file 1.4 Relationship to Other Protocols The Encrypting File System Remote Protocol is built on the Microsoft Remote Procedure Call (RPC) interface (as specified in [C706] and [MS-RPCE]). EFSRPC uses the Server Message Block (SMB) Protocol [MS-SMB] [MS-SMB2] as its RPC transport. Specifically, it uses named pipes over SMB (that is, RPC protocol sequence ncacn_np) as its transport mechanism. Either version 1 or version 2 of SMB can be used. The client has to connect to the server over SMB and negotiate a version of SMB before it can access the named pipe that is the RPC endpoint on the server. Windows also supports the storage of encrypted files via WebDAV [MS-WDV]. However, this feature does not use EFSRPC. This feature does not alter the WebDAV Protocol. Windows clients store encrypted files on WebDAV servers in the EFSRPC Raw Data Format, but the Windows WebDAV client performs all encryption and decryption operations locally. It also performs the local operations necessary to transform the file to and from the EFSRPC Raw Data Format during upload and download respectively. For more information, see [MSFT-XPUEFS]. This specification provides an interface (see section ) for applications to request a user certificate. This interface uses methods outlined in [MS-WCCE] to enroll for a certificate and key. 16 / 92

17 Figure 4: Protocol relationships 1.5 Prerequisites/Preconditions To use EFSRPC with a remote server, the client is required to possess valid credentials recognized by the server and be able to pass authentication and authorization checks for access to the encrypted data on the server. If secure operation is desired, the server is required to register an appropriate server principal name/authentication service pair that supports a protection level that provides packet integrity. Additionally, the client needs to be configured to associate the appropriate server principal name and authentication, and authorization and protection level with its binding, when connecting to the server.<1> The User-Certificate Binding interface described in section stores user keys protected to the user credentials and requires that the EFSRPC server be joined to the domain and configured for Kerberos delegation.<2> Alternatively, the server can be configured for Kerberos constrained delegation (as specified in [MS-SFU]) for only the services used for user key storage. 1.6 Applicability Statement This protocol is appropriate for remotely managing encrypted data objects on a server. It is used by Windows clients to manage EFSRPC-protected files on remote file servers using either version 1 or version 2 of the SMB Protocol. It does not specify any particular data protection mechanism. 1.7 Versioning and Capability Negotiation This document covers versioning issues in the following areas. Supported Transports: This protocol uses RPC for communication. It uses named pipes as the transport mechanism, as specified in section / 92

18 Protocol Versions: The RPC runtime negotiates the version of the EFSRPC interface, as specified in [C706]. The only supported version of this protocol is 1.0, as specified in section Security and Authentication Methods: EFSRPC does not specify any methods for authenticating access to the objects it operates on. The underlying data encryption and storage system can implement any authentication mechanism. In Windows, such authentication is provided by SMB, as specified in [MS-SMB] and [MS-SMB2]. An EFSRPC server can register a server principal name/authentication service pair to enable secure RPC communications, and a client can choose to associate this security service with its binding when connecting to the server, as specified in section 3. Capability Negotiation: Implicit negotiation of RPC security mechanisms can be performed through the security-related APIs specified in [C706] Chapter 13. The security mechanisms negotiated by Windows clients and servers are as specified in section Vendor-Extensible Fields EFSRPC does not include any vendor-extensible fields. This protocol uses Win32 error codes. These values are taken from the Windows error number space as specified in [MS-ERREF] section 2.2. Vendors SHOULD reuse those values with their indicated meaning. Using any other value runs the risk of a collision in the future. 1.9 Standards Assignments Parameter RPC Well-Known Endpoint RPC Interface UUID RPC Well-Known Endpoint RPC Interface UUID Value \pipe\lsarpc {c681d488-d850-11d0-8c52-00c04fd90f7e} \pipe\efsrpc {df1941c5-fe89-4e79-bf acf44d} 18 / 92

19 2 Messages 2.1 Transport The client and server MUST communicate over RPC, using named pipes over the Server Message Block (SMB) Protocol. The SMB version, capabilities, and authentication used for this connection are negotiated between the client and server when the connection is established, as specified in [MS-SMB] and [MS-SMB2]. EFSRPC messages to remote servers SHOULD be sent using the well-known endpoint \pipe\efsrpc. Remote servers MAY respond to EFSRPC messages sent using the well-known endpoint \pipe\lsarpc. When connecting to \pipe\efsrpc, the server interface is identified by UUID [df1941c5-fe89-4e79- bf acf44d], version 1.0. When connecting to \pipe\lsarpc, the server interface is identified by UUID [c681d488-d850-11d0-8c52-00c04fd90f7e], version 1.0.<3> The EFSRPC client MUST use explicit binding to create the RPC binding handle used to connect to the server, unless otherwise specified in section A server SHOULD<4> register one or more server principal name/authentication service pairs that provide a protection level that includes packet integrity. A client SHOULD attempt to associate suitable security information with its binding for the EFSRPC methods. For EfsRpcOpenFileRaw, clients SHOULD set the security options explicitly as noted in section 3. For all other EFSRPC methods, clients SHOULD use default values for the binding security information as specified in [MS-RPCE] section Common Data Types This section specifies the syntax of EFSRPC data types. In addition to the RPC base types and definitions specified in [C706] and [MS-DTYP], the additional data types described in the following sections are defined in the Microsoft Interface Definition Language (MIDL) specification for this RPC interface. This protocol MUST indicate to the RPC runtime that it is to support the NDR20 transfer syntax only, as specified in [C706] Part 4. This specification uses GUID structures as specified in [MS-DTYP] section EFSRPC Identifiers An EFSRPC identifier is used to uniquely refer to an encrypted data object on a remote server. The format of the identifier used is implementation-specific. It MUST be represented as a null-terminated Unicode string in UTF-16 encoding. EFSRPC servers SHOULD use UncPaths for EFSRPC identifiers. The server MUST return an error if it is passed an identifier that violates the syntactic rules imposed by its implementation.<5> EFSRPC Metadata The EFSRPC Metadata is attached to an encrypted object and contains information required to decrypt it. The EFSRPC Metadata is used implicitly by the EFSRPC raw methods, because it forms part of the EFSRPC Raw Data Format. The structure of the EFSRPC Metadata is implementation dependent. An EFSRPC server SHOULD return an error if EFSRPC Metadata is passed to it in an unsupported format. An EFSRPC client SHOULD NOT parse the EFSRPC Metadata, and SHOULD NOT rely on it being in any particular format. The EFSRPC Metadata SHOULD be represented on the server as follows. 19 / 92

20 EFSRPC Metadata Version Length Reserved1 EFS_Version Reserved2 EFS_ID (16 bytes) EFS_Hash (16 bytes) Reserved3 (16 bytes) DDF_Offset DRF_Offset Reserved4 Data_Fields (variable) 20 / 92

21 Length (4 bytes): This field MUST contain a 32-bit unsigned integer equal to the length, in bytes, of the EFSRPC Metadata.<6> Reserved1 (4 bytes): MUST be set to zero and ignored upon receipt. EFS_Version (4 bytes): This field represents the highest EFS version supported by the implementation that created this metadata. It MUST be a 32-bit unsigned integer in little-endian format. It MUST be set to one of the following values. Value Version_1 0x Version_2 0x Version_3 0x Meaning The file encryption key (FEK) will be a DESX key, and encrypted with RSA only. The Flags field in all key list entries will be zero. The FEK will use DESX, 3DES, or AES-256. The FEK will be encrypted with RSA only. The Flags field in all key list entries will be zero. The FEK will use DESX, 3DES, or AES-256. The FEK will be encrypted with either RSA or AES A server that supports a given version number MUST also support all lower numbered versions. A server SHOULD support all versions listed.<7> Reserved2 (4 bytes): MUST be set to zero and ignored upon receipt. EFS_ID (16 bytes): A 16-byte GUID value that MUST be unique for the computer that created this metadata. EFS_Hash (16 bytes): This field SHOULD be set to zero and ignored by the server.<8> Reserved3 (16 bytes): MUST be set to zero and ignored upon receipt. DDF_Offset (4 bytes): This field MUST contain the offset, in bytes, of the data decryption field (DDF) key list from the start of the EFSRPC Metadata. It MUST be a 32-bit unsigned integer in little-endian format. The DDF key list lies completely within the Data Fields and does not overlap the data recovery field (DRF) key list (if present). DRF_Offset (4 bytes): This field MUST contain the offset, in bytes, of the DRF key list from the start of the EFSRPC Metadata. It MUST be a 32-bit unsigned integer in little-endian format. A zero value in this field indicates that the DRF key list is absent and no DRAs have been applied to the file. If present, the DRF key list MUST lie completely within Data Fields and MUST NOT overlap the DDF key list. Reserved4 (12 bytes): MUST be set to zero and ignored upon receipt. Data_Fields (variable): This field MUST contain the following two items in any order at the locations indicated by the respective Offset fields previously listed. Both items MUST conform to the key list format specified in section The DDF key list MUST NOT overlap with the DRF key list (if present). There MUST NOT be any unused areas within this field spanning more than 8 contiguous bytes. Any unused areas within this field MUST be set to zero bytes and ignored by the server DDF_key_list (variable) 21 / 92