2.3.4.10 \EncryptionInfo Stream (Agile Encryption)

  • Article

The \EncryptionInfo stream (1) contains detailed information about the cryptography used to encrypt the \EncryptedPackage stream (1) (section 2.3.4.4) when agile encryption is used.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

EncryptionVersionInfo

Reserved

XmlEncryptionDescriptor (variable)

...

EncryptionVersionInfo (4 bytes): A Version structure (section 2.1.4), where Version.vMajor MUST be 0x0004 and Version.vMinor MUST be 0x0004.

Reserved (4 bytes): A value that MUST be 0x00000040.

XmlEncryptionDescriptor (variable): An XML element that MUST conform to the following XML schema namespace, as specified in [W3C-XSD]:

 <?xml version="1.0" encoding="utf-8"?>
 <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
    targetNamespace="http://schemas.microsoft.com/office/2006/encryption"
    xmlns="http://schemas.microsoft.com/office/2006/encryption"
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
   
   <xs:simpleType name="ST_SaltSize">
     <xs:restriction base="xs:unsignedInt">
       <xs:minInclusive value="1" />
       <xs:maxInclusive value="65536" />
     </xs:restriction>
   </xs:simpleType>
  
   <xs:simpleType name="ST_BlockSize">
     <xs:restriction base="xs:unsignedInt">
       <xs:minInclusive value="2" />
       <xs:maxInclusive value="4096" />
     </xs:restriction>
   </xs:simpleType>
  
   <xs:simpleType name="ST_KeyBits">
     <xs:restriction base="xs:unsignedInt">
       <xs:minInclusive value="8" />
     </xs:restriction>
   </xs:simpleType>
  
   <xs:simpleType name="ST_HashSize">
     <xs:restriction base="xs:unsignedInt">
       <xs:minInclusive value="1" />
       <xs:maxInclusive value="65536" />
     </xs:restriction>
   </xs:simpleType>
  
   <xs:simpleType name="ST_SpinCount">
     <xs:restriction base="xs:unsignedInt">
       <xs:minInclusive value="0" />
       <xs:maxInclusive value="10000000" />
     </xs:restriction>
   </xs:simpleType>
  
   <xs:simpleType name="ST_CipherAlgorithm">
     <xs:restriction base="xs:string">
       <xs:minLength value="1" />
     </xs:restriction>
   </xs:simpleType>
  
   <xs:simpleType name="ST_CipherChaining">
     <xs:restriction base="xs:string">
       <xs:minLength value="1" />
     </xs:restriction>
   </xs:simpleType>
  
   <xs:simpleType name="ST_HashAlgorithm">
     <xs:restriction base="xs:string">
       <xs:minLength value="1" />
     </xs:restriction>
   </xs:simpleType>
  
   <xs:complexType name="CT_KeyData">
     <xs:attribute name="saltSize" type="ST_SaltSize" use="required" />
     <xs:attribute name="blockSize" type="ST_BlockSize" use="required" />
     <xs:attribute name="keyBits" type="ST_KeyBits" use="required" />
     <xs:attribute name="hashSize" type="ST_HashSize" use="required" />
     <xs:attribute name="cipherAlgorithm" type="ST_CipherAlgorithm" use="required" />
     <xs:attribute name="cipherChaining" type="ST_CipherChaining" use="required" />
     <xs:attribute name="hashAlgorithm" type="ST_HashAlgorithm" use="required" />
     <xs:attribute name="saltValue" type="xs:base64Binary" use="required" />
   </xs:complexType>
  
   <xs:complexType name="CT_DataIntegrity">
     <xs:attribute name="encryptedHmacKey" type="xs:base64Binary" use="required" />
     <xs:attribute name="encryptedHmacValue" type="xs:base64Binary" use="required" />
   </xs:complexType>
  
   <xs:complexType name="CT_KeyEncryptor">
     <xs:sequence>
       <xs:any processContents="lax" />
     </xs:sequence>
     <xs:attribute name="uri" type="xs:token" />
   </xs:complexType>
  
   <xs:complexType name="CT_KeyEncryptors">
     <xs:sequence>
       <xs:element name="keyEncryptor" type="CT_KeyEncryptor" minOccurs="1" maxOccurs="unbounded" />
     </xs:sequence>
   </xs:complexType>
  
   <xs:complexType name="CT_Encryption">
     <xs:sequence>
       <xs:element name="keyData" type="CT_KeyData" minOccurs="1" maxOccurs="1" />
       <xs:element name="dataIntegrity" type="CT_DataIntegrity" minOccurs="0" maxOccurs="1" />
       <xs:element name="keyEncryptors" type="CT_KeyEncryptors" minOccurs="1" maxOccurs="1" />
     </xs:sequence>
   </xs:complexType>
  
   <xs:element name="encryption" type="CT_Encryption" />
 </xs:schema>

SaltSize: An unsigned integer that specifies the number of bytes used by a salt. It MUST be at least 1 and no greater than 65,536.

BlockSize: An unsigned integer that specifies the number of bytes used to encrypt one block of data. It MUST be at least 2, no greater than 4096, and a multiple of 2.

KeyBits: An unsigned integer that specifies the number of bits used by an encryption algorithm. It MUST be at least 8 and a multiple of 8.

HashSize: An unsigned integer that specifies the number of bytes used  by a hash value. It MUST be at least 1, no greater than 65,536, and the same number of bytes as the hash algorithm emits.

SpinCount: An unsigned integer that specifies the number of times to iterate on a hash of a password. It MUST NOT be greater than 10,000,000.

CipherAlgorithm: A string that specifies the cipher algorithm. The values in the following table are defined.

Value

Cipher algorithm

AES

MUST conform to the AES algorithm.

RC2

MUST conform to the algorithm as specified in [RFC2268].<13>

RC4

MUST NOT be used.

DES

MUST conform to the DES algorithm.<14>

DESX

MUST conform to the algorithm as specified in [DRAFT-DESX].<15>

3DES

MUST conform to the algorithm as specified in [RFC1851].<16>

3DES_112

MUST conform to the algorithm as specified in [RFC1851].<17>

Values that are not defined MAY<18> be used, and a compliant implementation is not required to support all defined values. The string MUST be at least 1 character.

CipherChaining: A string that specifies the chaining mode used by CipherAlgorithm. For more details about chaining modes, see [BCMO800-38A]. It MUST be one of the values described in the following table.

Value

Chaining mode

ChainingModeCBC

Cipher block chaining (CBC)

ChainingModeCFB

Cipher feedback chaining (CFB), with an 8-bit window

HashAlgorithm: A string specifying a hashing algorithm. The values described in the following table are defined.

Value

Hash algorithm

SHA-1

MUST conform to the algorithm as specified in [RFC4634].

SHA256

MUST conform to the algorithm as specified in [RFC4634].

SHA384

MUST conform to the algorithm as specified in [RFC4634].

SHA512

MUST conform to the algorithm as specified in [RFC4634].

MD5

MUST conform to MD5.

MD4

MUST conform to the algorithm as specified in [RFC1320].

MD2

MUST conform to the algorithm as specified in [RFC1319].

RIPEMD-128

MUST conform to the hash functions specified in [ISO/IEC 10118].

RIPEMD-160

MUST conform to the hash functions specified in [ISO/IEC 10118].

WHIRLPOOL

MUST conform to the hash functions specified in [ISO/IEC 10118].

Values that are not defined MAY<19> be used, and a compliant implementation is not required to support all defined values. The string MUST be at least 1 character. For more information, see section 4.

KeyData: A complex type that specifies the encryption used within this element. The saltValue attribute is a base64-encoded binary value that is randomly generated. The number of bytes required to decode the saltValue attribute MUST be equal to the value of the saltSize attribute.

DataIntegrity: A complex type that specifies data used to verify whether the encrypted data passes an integrity check. It MUST be generated using the method specified in section 2.3.4.14. This type is composed of the following simple types:

  • encryptedHmacKey: A base64-encoded value that specifies an encrypted key used in calculating the encryptedHmacValue.

  • encryptedHmacValue: A base64-encoded value that specifies an HMAC derived from encryptedHmacKey and the encrypted data.

KeyEncryptor: A complex type that specifies the parameters used to encrypt an intermediate key, which is used to perform the final encryption of the document. To ensure extensibility, arbitrary elements can be defined to encrypt the intermediate key. The intermediate key MUST be the same for all KeyEncryptor elements. PasswordKeyEncryptor and CertificateKeyEncryptor are defined later in this section.

KeyEncryptors: A sequence of KeyEncryptor elements. Exactly one KeyEncryptors element MUST be present, and the KeyEncryptors element MUST contain at least one KeyEncryptor.

Encryption: A complex type composed of the following elements that specify the encryption properties:

  • keyData: One KeyData element MUST be present.

  • dataIntegrity: One DataIntegrity element SHOULD<20> be present.

  • keyEncryptors: One KeyEncryptors sequence MUST be present.

The KeyEncryptor element, which MUST be used when encrypting password-protected agile encryption documents, is either a PasswordKeyEncryptor or a CertificateKeyEncryptor. Exactly one PasswordKeyEncryptor MUST be present. Zero or more CertificateKeyEncryptor elements are contained within the KeyEncryptors element. The PasswordKeyEncryptor is specified by the following schema:

 <?xml version="1.0" encoding="utf-8"?>
 <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
    targetNamespace="http://schemas.microsoft.com/office/2006/keyEncryptor/password"
    xmlns="http://schemas.microsoft.com/office/2006/keyEncryptor/password"
    xmlns:e="http://schemas.microsoft.com/office/2006/encryption"
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  
   <xs:import namespace="http://schemas.microsoft.com/office/2006/encryption" schemaLocation="encryptionInfo.xsd" />
  
   <xs:simpleType name="ST_PasswordKeyEncryptorUri">
     <xs:restriction base="xs:token">
       <xs:enumeration value="http://schemas.microsoft.com/office/2006/keyEncryptor/password" />
     </xs:restriction>
   </xs:simpleType>
  
   <xs:complexType name="CT_PasswordKeyEncryptor">
     <xs:attribute name="saltSize" type="e:ST_SaltSize" use="required" />
     <xs:attribute name="blockSize" type="e:ST_BlockSize" use="required" />
     <xs:attribute name="keyBits" type="e:ST_KeyBits" use="required" />
     <xs:attribute name="hashSize" type="e:ST_HashSize" use="required" />
     <xs:attribute name="cipherAlgorithm" type="e:ST_CipherAlgorithm" use="required" />
     <xs:attribute name="cipherChaining" type="e:ST_CipherChaining" use="required" />
     <xs:attribute name="hashAlgorithm" type="e:ST_HashAlgorithm" use="required" />
     <xs:attribute name="saltValue" type="xs:base64Binary" use="required" />
     <xs:attribute name="spinCount" type="e:ST_SpinCount" use="required" />
     <xs:attribute name="encryptedVerifierHashInput" type="xs:base64Binary" use="required" />
     <xs:attribute name="encryptedVerifierHashValue" type="xs:base64Binary" use="required" />
     <xs:attribute name="encryptedKeyValue" type="xs:base64Binary" use="required" />
   </xs:complexType>
  
   <xs:element name="encryptedKey" type="CT_PasswordKeyEncryptor" />
 </xs:schema>

saltSize: A SaltSize that specifies the size of the salt for a PasswordKeyEncryptor.

blockSize: A BlockSize that specifies the block size for a PasswordKeyEncryptor.

keyBits: A KeyBits that specifies the number of bits for a PasswordKeyEncryptor.

hashSize: A HashSize that specifies the size of the binary form of the hash for a PasswordKeyEncryptor.

cipherAlgorithm: A CipherAlgorithm that specifies the cipher algorithm for a PasswordKeyEncryptor. The cipher algorithm specified MUST be the same as the cipher algorithm specified for the Encryption.keyData element.

cipherChaining: A CipherChaining that specifies the cipher chaining mode for a PasswordKeyEncryptor.

hashAlgorithm: A HashAlgorithm that specifies the hashing algorithm for a PasswordKeyEncryptor. The hashing algorithm specified MUST be the same as the hashing algorithm specified for the Encryption.keyData element.

saltValue: A base64-encoded binary byte array that specifies the salt value for a PasswordKeyEncryptor. The number of bytes required by the decoded form of this element MUST be saltSize.

spinCount: A SpinCount that specifies the spin count for a PasswordKeyEncryptor.

encryptedVerifierHashInput: A base64-encoded value that specifies the encrypted verifier hash input for a PasswordKeyEncryptor used in password verification.

encryptedVerifierHashValue: A base64-encoded value that specifies the encrypted verifier hash value for a PasswordKeyEncryptor used in password verification.

encryptedKeyValue: A base64-encoded value that specifies the encrypted form of the intermediate key.

The CertificateKeyEncryptor is specified by the following schema:

 <?xml version="1.0" encoding="utf-8"?>
 <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
 targetNamespace="http://schemas.microsoft.com/office/2006/keyEncryptor/certificate"
 xmlns="http://schemas.microsoft.com/office/2006/keyEncryptor/certificate"
 xmlns:e="http://schemas.microsoft.com/office/2006/encryption"
 xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:import namespace="http://schemas.microsoft.com/office/2006/encryption" schemaLocation="encryptionInfo.xsd" />
   <xs:simpleType name="ST_PasswordKeyEncryptorUri">
     <xs:restriction base="xs:token">
       <xs:enumeration value="http://schemas.microsoft.com/office/2006/keyEncryptor/certificate" />
     </xs:restriction>
   </xs:simpleType>
   <xs:complexType name="CT_CertificateKeyEncryptor">
     <xs:attribute name="encryptedKeyValue" type="xs:base64Binary" use="required" />
     <xs:attribute name="X509Certificate" type="xs:base64Binary" use="required" />
     <xs:attribute name="certVerifier" type="xs:base64Binary" use="required" />
   </xs:complexType>
   <xs:element name="encryptedKey" type="CT_CertificateKeyEncryptor" />
 </xs:schema>

encryptedKeyValue: A base64-encoded value that specifies the encrypted form of the intermediate key, which is encrypted with the public key contained within the X509Certificate attribute.

 X509Certificate: A base64-encoded value that specifies a DER-encoded X.509 certificate used to encrypt the intermediate key. The certificate MUST contain only the public portion of the public-private key pair.

certVerifier: A base64-encoded value that specifies the HMAC of the binary data obtained by base64-decoding the X509Certificate attribute. The hashing algorithm used to derive the HMAC MUST be the hashing algorithm specified for the Encryption.keyData element. The secret key used to derive the HMAC MUST be the intermediate key.

If the intermediate key is reset, any CertificateKeyEncryptor elements are also reset to contain the new intermediate key, except that the certVerifier attribute MUST match the value calculated using the current intermediate key, to verify that the CertificateKeyEncryptor element actually encrypted the current intermediate key. If a CertificateKeyEncryptor element does not have a correct certVerifier attribute, it MUST be discarded.