Class: OoxmlEncryption

Inherits:
Object
  • Object
show all
Defined in:
lib/ooxml_encryption/ooxml_encryption.rb,
lib/ooxml_encryption/version.rb

Overview

Ported from github.com/dtjohnson/xlsx-populate.

Implements OOXML whole-file encryption and decryption.

For low-level file format details, see: docs.microsoft.com/en-us/openspecs/office_file_formats/ms-offcrypto.

Constant Summary collapse

VERSION =

Gem version. If this changes, be sure to re-run “bundle install” or “bundle update”.

'0.3.0'
DATE =

Date for VERSION. If this changes, be sure to re-run “bundle install” or “bundle update”.

'2024-10-22'
ENCRYPTION_INFO_PREFIX =

First 4 bytes are the version number, second 4 bytes are reserved.

[0x04, 0x00, 0x04, 0x00, 0x40, 0x00, 0x00, 0x00].pack('C*')
PACKAGE_ENCRYPTION_CHUNK_SIZE = 
4096
PACKAGE_OFFSET =

First 8 bytes are the size of the stream.

8
BLOCK_KEYS =

Block keys used for encryption.

OpenStruct.new({
  dataIntegrity: OpenStruct.new({
    hmacKey:   [0x5f, 0xb2, 0xad, 0x01, 0x0c, 0xb9, 0xe1, 0xf6].pack('C*'),
    hmacValue: [0xa0, 0x67, 0x7f, 0x02, 0xb2, 0x2c, 0x84, 0x33].pack('C*')
  }),
  verifierHash: OpenStruct.new({
    input: [0xfe, 0xa7, 0xd2, 0x76, 0x3b, 0x4b, 0x9e, 0x79].pack('C*'),
    value: [0xd7, 0xaa, 0x0f, 0x6d, 0x30, 0x61, 0x34, 0x4e].pack('C*')
  }),
  key: [0x14, 0x6e, 0x0b, 0xe7, 0xab, 0xac, 0xd0, 0xd6].pack('C*'),
})
RANDOM_BYTES_PROC =

This aids testing to ensure that deterministic results are generated. The performance overhead of a Proc is extremely low, especially compared to the overhead of the encryption or decryption calculations.

if ENV['RACK_ENV'] = 'test'
  -> (count) { '0' * count }
else
  -> (count) { SecureRandom.random_bytes(count) }
end
NUL =

Convenience accessor to binary-encoded NUL byte.

String.new("\x00", encoding: 'ASCII-8BIT')

Instance Method Summary collapse

Instance Method Details

#decrypt(encrypted_spreadsheet_data:, password:) ⇒ Object

Decrypt encrypted file data assumed to be the result of a prior encryption. Returns the decrypted OOXML blob. This is NOT a streaming operation as the underlying CFB file format used to store the data is not streamable itself; see the SimpleCFB gem for details.

encrypted_spreadsheet_data

Encrypted OOXML input data as an ASCII-8BIT

encoded string.
password

Password for decryption in your choice of string encoding.



308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
 
# File 'lib/ooxml_encryption/ooxml_encryption.rb', line 308

def decrypt(encrypted_spreadsheet_data:, password:)
  cfb = SimpleCfb.new
  cfb.parse!(StringIO.new(encrypted_spreadsheet_data))

  encryption_info_xml        = cfb.file_index.find { |f| f.name == 'EncryptionInfo'   }&.content
  encrypted_spreadsheet_data = cfb.file_index.find { |f| f.name == 'EncryptedPackage' }&.content

  raise 'Cannot read file - corrupted or not encrypted?' if encryption_info_xml.nil? || encrypted_spreadsheet_data.nil?

  encryption_info_xml.delete_prefix!(ENCRYPTION_INFO_PREFIX)
  encryption_info = self.parse_encryption_info(encryption_info_xml)

  # Convert the password into an encryption key
  #
  key = self.convert_password_to_key(
    password,
    encryption_info.key.hashAlgorithm,
    encryption_info.key.saltValue,
    encryption_info.key.spinCount,
    encryption_info.key.keyBits,
    BLOCK_KEYS.key
  )

  # Use the key to decrypt the package key
  #
  package_key = self.crypt(
    method:           :decrypt,
    cipher_algorithm: encryption_info.key.cipherAlgorithm,
    cipher_chaining:  encryption_info.key.cipherChaining,
    key:              key,
    iv:               encryption_info.key.saltValue,
    input:            encryption_info.key.encryptedKeyValue
  )

  # Use the package key to decrypt the package
  #
  return self.crypt_package(
    method:           :decrypt,
    cipher_algorithm: encryption_info.package.cipherAlgorithm,
    cipher_chaining:  encryption_info.package.cipherChaining,
    hash_algorithm:   encryption_info.package.hashAlgorithm,
    block_size:       encryption_info.package.blockSize,
    salt_value:       encryption_info.package.saltValue,
    key:              package_key,
    input:            encrypted_spreadsheet_data
  )
end

#encrypt(unencrypted_spreadsheet_data:, password:) ⇒ Object

Encrypt an unencrypted OOXML blob, returning the binary result. This is NOT a streaming operation as the CFB format used to store the data is not streamable itself - see the SimpleCfb gem for details.

unencrypted_spreadsheet_data

Unprotected OOXML input data as an ASCII-8BIT encoded string.

password

Password for encryption in your choice of string encoding.



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
 
# File 'lib/ooxml_encryption/ooxml_encryption.rb', line 71

def encrypt(unencrypted_spreadsheet_data:, password:)

  # Generate a random key to use to encrypt the document. Excel uses 32 bytes. We'll use the password to encrypt this key.
  # N.B. The number of bits needs to correspond to an algorithm available in crypto (e.g. aes-256-cbc).
  #
  package_key = RANDOM_BYTES_PROC.call(32)

  # Create the encryption info. We'll use this for all of the encryption operations and for building the encryption info XML entry
  encryption_info = OpenStruct.new({
    package: OpenStruct.new({ # Info on the encryption of the package.
      cipherAlgorithm: 'AES', # Cipher algorithm to use. Excel uses AES.
      cipherChaining:  'ChainingModeCBC', # Cipher chaining mode to use. Excel uses CBC.
      saltValue:       RANDOM_BYTES_PROC.call(16), # Random value to use as encryption salt. Excel uses 16 bytes.
      hashAlgorithm:   'SHA512', # Hash algorithm to use. Excel uses SHA512.
      hashSize:        64, # The size of the hash in bytes. SHA512 results in 64-byte hashes
      blockSize:       16, # 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. Excel uses 16
      keyBits:         package_key.size * 8 # The number of bits in the package key.
    }),
    key: OpenStruct.new({ # Info on the encryption of the package key.
      cipherAlgorithm: 'AES', # Cipher algorithm to use. Excel uses AES.
      cipherChaining:  'ChainingModeCBC', # Cipher chaining mode to use. Excel uses CBC.
      saltValue:       RANDOM_BYTES_PROC.call(16), # Random value to use as encryption salt. Excel uses 16 bytes.
      hashAlgorithm:   'SHA512', # Hash algorithm to use. Excel uses SHA512.
      hashSize:        64, # The size of the hash in bytes. SHA512 results in 64-byte hashes
      blockSize:       16, # 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. Excel uses 16
      spinCount:       100000, # The number of times to iterate on a hash of a password. It MUST NOT be greater than 10,000,000. Excel uses 100,000.
      keyBits:         256 # The length of the key to generate from the password. Must be a multiple of 8. Excel uses 256.
    })
  })

  # =========================================================================
  # PACKAGE ENCRYPTION
  # =========================================================================

  # Encrypt package using the package key
  #
  encrypted_package = self.crypt_package(
    method:           :encrypt,
    cipher_algorithm: encryption_info.package.cipherAlgorithm,
    cipher_chaining:  encryption_info.package.cipherChaining,
    hash_algorithm:   encryption_info.package.hashAlgorithm,
    block_size:       encryption_info.package.blockSize,
    salt_value:       encryption_info.package.saltValue,
    key:              package_key,
    input:            unencrypted_spreadsheet_data
  )

  # =========================================================================
  # KEY ENCRYPTION
  # =========================================================================

  # Convert the password to an encryption key
  #
  key = self.convert_password_to_key(
    password,
    encryption_info.key.hashAlgorithm,
    encryption_info.key.saltValue,
    encryption_info.key.spinCount,
    encryption_info.key.keyBits,
    BLOCK_KEYS.key
  )

  # Encrypt the package key
  #
  encryption_info.key.encryptedKeyValue = self.crypt(
    method:           :encrypt,
    cipher_algorithm: encryption_info.key.cipherAlgorithm,
    cipher_chaining:  encryption_info.key.cipherChaining,
    key:              key,
    iv:               encryption_info.key.saltValue,
    input:            package_key
  )

  # =========================================================================
  # VERIFIER HASH
  # =========================================================================

  # Create a random byte array for hashing
  #
  verifier_hash_input = RANDOM_BYTES_PROC.call(16)

  # Create an encryption key from the password for the input
  #
  verifier_hash_input_key = self.convert_password_to_key(
    password,
    encryption_info.key.hashAlgorithm,
    encryption_info.key.saltValue,
    encryption_info.key.spinCount,
    encryption_info.key.keyBits,
    BLOCK_KEYS.verifierHash.input
  )

  # Use the key to encrypt the verifier input
  #
  encryption_info.key.encryptedVerifierHashInput = self.crypt(
    method:           :encrypt,
    cipher_algorithm: encryption_info.key.cipherAlgorithm,
    cipher_chaining:  encryption_info.key.cipherChaining,
    key:              verifier_hash_input_key,
    iv:               encryption_info.key.saltValue,
    input:            verifier_hash_input
  )

  # Create a hash of the input
  #
  verifier_hash_value = self.hash(
    encryption_info.key.hashAlgorithm,
    verifier_hash_input
  )

  # Create an encryption key from the password for the hash
  #
  verifier_hash_value_key = self.convert_password_to_key(
    password,
    encryption_info.key.hashAlgorithm,
    encryption_info.key.saltValue,
    encryption_info.key.spinCount,
    encryption_info.key.keyBits,
    BLOCK_KEYS.verifierHash.value
  )

  # Use the key to encrypt the hash value
  #
  encryption_info.key.encryptedVerifierHashValue = self.crypt(
    method:           :encrypt,
    cipher_algorithm: encryption_info.key.cipherAlgorithm,
    cipher_chaining:  encryption_info.key.cipherChaining,
    key:              verifier_hash_value_key,
    iv:               encryption_info.key.saltValue,
    input:            verifier_hash_value
  )

  # =========================================================================
  # DATA INTEGRITY
  # =========================================================================

  # Create the data integrity fields used by clients for integrity checks.
  #
  # First generate a random array of bytes to use in HMAC. The documentation
  # says that we should use the same length as the key salt, but Excel seems
  # to use 64.
  #
  hmac_key = RANDOM_BYTES_PROC.call(64)

  # Then create an initialization vector using the package encryption info
  # and the appropriate block key.
  #
  hmac_key_iv = self.create_iv(
    encryption_info.package.hashAlgorithm,
    encryption_info.package.saltValue,
    encryption_info.package.blockSize,
    BLOCK_KEYS.dataIntegrity.hmacKey
  )

  # Use the package key and the IV to encrypt the HMAC key
  #
  encrypted_hmac_key = self.crypt(
    method:           :encrypt,
    cipher_algorithm: encryption_info.package.cipherAlgorithm,
    cipher_chaining:  encryption_info.package.cipherChaining,
    key:              package_key,
    iv:               hmac_key_iv,
    input:            hmac_key
  )

  # Create the HMAC
  #
  hmac_value = self.hmac(
    encryption_info.package.hashAlgorithm,
    hmac_key,
    encrypted_package
  )

  # Generate an initialization vector for encrypting the resulting HMAC value
  #
  hmac_value_iv = self.create_iv(
    encryption_info.package.hashAlgorithm,
    encryption_info.package.saltValue,
    encryption_info.package.blockSize,
    BLOCK_KEYS.dataIntegrity.hmacValue
  )

  # Encrypt that value
  #
  encrypted_hmac_value = self.crypt(
    method:           :encrypt,
    cipher_algorithm: encryption_info.package.cipherAlgorithm,
    cipher_chaining:  encryption_info.package.cipherChaining,
    key:              package_key,
    iv:               hmac_value_iv,
    input:            hmac_value
  )

  # Add the encrypted key and value into the encryption info
  #
  encryption_info.dataIntegrity = OpenStruct.new({
    encryptedHmacKey:   encrypted_hmac_key,
    encryptedHmacValue: encrypted_hmac_value
  })

  # =========================================================================
  # OUTPUT
  # =========================================================================

  # Build the encryption info XML string
  #
  encryption_info = self.build_encryption_info(encryption_info)

  # Create a new CFB file
  #
  cfb = SimpleCfb.new

  # Add the encryption info and encrypted package
  #
  cfb.add('EncryptionInfo',   encryption_info  )
  cfb.add('EncryptedPackage', encrypted_package)

  # Compile and return the CFB file data
  #
  return cfb.write()
end