updated olefile to v0.42

Philippe Lagadec
1 parent 4c98aa7a
Showing 14 changed files with 201 additions and 114 deletions
oletools/thirdparty/olefile/LICENSE.txt
oletools/thirdparty/olefile/README.html
oletools/thirdparty/olefile/README.rst
oletools/thirdparty/olefile/__init__.py
oletools/thirdparty/olefile/doc/API.html
oletools/thirdparty/olefile/doc/API.md
oletools/thirdparty/olefile/doc/Home.html
oletools/thirdparty/olefile/doc/Home.md
oletools/thirdparty/olefile/doc/Install.html
oletools/thirdparty/olefile/doc/Install.md
oletools/thirdparty/olefile/doc/License.html
oletools/thirdparty/olefile/doc/License.md
oletools/thirdparty/olefile/olefile.html
oletools/thirdparty/olefile/olefile.py
 LICENSE for the olefile package:
-olefile (formerly OleFileIO_PL) is copyright (c) 2005-2014 Philippe Lagadec
+olefile (formerly OleFileIO_PL) is copyright (c) 2005-2015 Philippe Lagadec
 (http://www.decalage.info)
 All rights reserved.
@@ -8,25 +8,21 @@
 </head>
 <body>
 <h1 id="olefile-formerly-olefileio_pl">olefile (formerly OleFileIO_PL)</h1>
-<p><a href="http://www.decalage.info/python/olefileio">olefile</a> is a Python package to parse, read and write [Microsoft OLE2 files (also called Structured Storage, Compound File Binary Format or Compound Document File Format)] (http://en.wikipedia.org/wiki/Compound_File_Binary_Format), such as Microsoft Office 97-2003 documents, Image Composer and FlashPix files, Outlook messages, StickyNotes, several Microscopy file formats, McAfee antivirus quarantine files, etc.</p>
+<p><a href="http://www.decalage.info/olefile">olefile</a> is a Python package to parse, read and write <a href="http://en.wikipedia.org/wiki/Compound_File_Binary_Format">Microsoft OLE2 files</a> (also called Structured Storage, Compound File Binary Format or Compound Document File Format), such as Microsoft Office 97-2003 documents, vbaProject.bin in MS Office 2007+ files, Image Composer and FlashPix files, Outlook messages, StickyNotes, several Microscopy file formats, McAfee antivirus quarantine files, etc.</p>
 <p><strong>Quick links:</strong> <a href="http://www.decalage.info/olefile">Home page</a> - <a href="https://bitbucket.org/decalage/olefileio_pl/wiki/Install">Download/Install</a> - <a href="https://bitbucket.org/decalage/olefileio_pl/wiki">Documentation</a> - <a href="https://bitbucket.org/decalage/olefileio_pl/issues?status=new&amp;status=open">Report Issues/Suggestions/Questions</a> - <a href="http://decalage.info/contact">Contact the author</a> - <a href="https://bitbucket.org/decalage/olefileio_pl">Repository</a> - <a href="https://twitter.com/decalage2">Updates on Twitter</a></p>
-<p>olefile is based on the OleFileIO module from <a href="http://www.pythonware.com/products/pil/index.htm">PIL</a>, the excellent Python Imaging Library, created and maintained by Fredrik Lundh. The olefile API is still compatible with PIL, but since 2005 I have improved the internal implementation significantly, with new features, bugfixes and a more robust design. From 2005 to 2014 the project was called OleFileIO_PL, and in 2014 I changed its name to olefile to celebrate its 9 years and its new write features.</p>
-<p>As far as I know, this module is the most complete and robust Python implementation to read MS OLE2 files, portable on several operating systems. (please tell me if you know other similar Python modules)</p>
-<p>Since 2014 olefile/OleFileIO_PL has been integrated into <a href="http://python-imaging.github.io/">Pillow</a>, the friendly fork of PIL. olefile will continue to be improved as a separate project, and new versions will be merged into Pillow regularly.</p>
-<p>olefile can be used as an independent module or with PIL/Pillow.</p>
-<p>olefile is mostly meant for developers. If you are looking for tools to analyze OLE files or to extract data (especially for security purposes such as malware analysis and forensics), then please also check my [python-oletools] (http://www.decalage.info/python/oletools), which are built upon olefile and provide a higher-level interface.</p>
 <h2 id="news">News</h2>
 <p>Follow all updates and news on Twitter: <a href="https://twitter.com/decalage2"><code class="url">https://twitter.com/decalage2</code></a></p>
 <ul>
-<li><strong>2014-11-25 v0.41</strong>: OleFileIO.open and isOleFile now support OLE files stored in byte strings, fixed installer for python 3, added support for Jython (Niko Ehrenfeuchter)</li>
+<li><strong>2015-01-25 v0.42</strong>: improved handling of special characters in stream/storage names on Python 2.x (using UTF-8 instead of Latin-1), fixed bug in listdir with empty storages.</li>
+<li>2014-11-25 v0.41: OleFileIO.open and isOleFile now support OLE files stored in byte strings, fixed installer for python 3, added support for Jython (Niko Ehrenfeuchter)</li>
 <li>2014-10-01 v0.40: renamed OleFileIO_PL to olefile, added initial write support for streams &gt;4K, updated doc and license, improved the setup script.</li>
 <li>2014-07-27 v0.31: fixed support for large files with 4K sectors, thanks to Niko Ehrenfeuchter, Martijn Berger and Dave Jones. Added test scripts from Pillow (by hugovk). Fixed setup for Python 3 (Martin Panter)</li>
 <li>2014-02-04 v0.30: now compatible with Python 3.x, thanks to Martin Panter who did most of the hard work.</li>
 <li>2013-07-24 v0.26: added methods to parse stream/storage timestamps, improved listdir to include storages, fixed parsing of direntry timestamps</li>
-<li>2013-05-27 v0.25: improved metadata extraction, properties parsing and exception handling, fixed [issue #12] (https://bitbucket.org/decalage/olefileio_pl/issue/12/error-when-converting-timestamps-in-ole)</li>
+<li>2013-05-27 v0.25: improved metadata extraction, properties parsing and exception handling, fixed <a href="https://bitbucket.org/decalage/olefileio_pl/issue/12/error-when-converting-timestamps-in-ole">issue #12</a></li>
 <li>2013-05-07 v0.24: new features to extract metadata (get_metadata method and OleMetadata class), improved getproperties to convert timestamps to Python datetime</li>
 <li>2012-10-09: published <a href="http://www.decalage.info/python/oletools">python-oletools</a>, a package of analysis tools based on OleFileIO_PL</li>
-<li>2012-09-11 v0.23: added support for file-like objects, fixed [issue #8] (https://bitbucket.org/decalage/olefileio_pl/issue/8/bug-with-file-object)</li>
+<li>2012-09-11 v0.23: added support for file-like objects, fixed <a href="https://bitbucket.org/decalage/olefileio_pl/issue/8/bug-with-file-object">issue #8</a></li>
 <li>2012-02-17 v0.22: fixed issues #7 (bug in getproperties) and #2 (added close method)</li>
 <li>2011-10-20: code hosted on bitbucket to ease contributions and bug tracking</li>
 <li>2010-01-24 v0.21: fixed support for big-endian CPUs, such as PowerPC Macs.</li>
@@ -35,7 +31,9 @@
 <li>see changelog in source code for more info.</li>
 </ul>
 <h2 id="downloadinstall">Download/Install</h2>
-<p>If you have pip or setuptools installed, you may simply run &quot;<strong>pip install olefile</strong>&quot; or &quot;<strong>easy_install olefile</strong>&quot;. Otherwise, see https://bitbucket.org/decalage/olefileio_pl/wiki/Install</p>
+<p>If you have pip or setuptools installed (pip is included in Python 2.7.9+), you may simply run <strong>pip install olefile</strong> or <strong>easy_install olefile</strong> for the first installation.</p>
+<p>To update olefile, run <strong>pip install -U olefile</strong>.</p>
+<p>Otherwise, see https://bitbucket.org/decalage/olefileio_pl/wiki/Install</p>
 <h2 id="features">Features</h2>
 <ul>
 <li>Parse, read and write any OLE file such as Microsoft Office 97-2003 legacy document formats (Word .doc, Excel .xls, PowerPoint .ppt, Visio .vsd, Project .mpp), Image Composer and FlashPix files, Outlook messages, StickyNotes, Zeiss AxioVision ZVI files, Olympus FluoView OIB files, etc</li>
@@ -44,6 +42,12 @@
 <li>Parse and read property streams, containing metadata of the file</li>
 <li>Portable, pure Python module, no dependency</li>
 </ul>
+<p>olefile can be used as an independent package or with PIL/Pillow.</p>
+<p>olefile is mostly meant for developers. If you are looking for tools to analyze OLE files or to extract data (especially for security purposes such as malware analysis and forensics), then please also check my <a href="http://www.decalage.info/python/oletools">python-oletools</a>, which are built upon olefile and provide a higher-level interface.</p>
+<h2 id="history">History</h2>
+<p>olefile is based on the OleFileIO module from <a href="http://www.pythonware.com/products/pil/index.htm">PIL</a>, the excellent Python Imaging Library, created and maintained by Fredrik Lundh. The olefile API is still compatible with PIL, but since 2005 I have improved the internal implementation significantly, with new features, bugfixes and a more robust design. From 2005 to 2014 the project was called OleFileIO_PL, and in 2014 I changed its name to olefile to celebrate its 9 years and its new write features.</p>
+<p>As far as I know, olefile is the most complete and robust Python implementation to read MS OLE2 files, portable on several operating systems. (please tell me if you know other similar Python modules)</p>
+<p>Since 2014 olefile/OleFileIO_PL has been integrated into <a href="http://python-imaging.github.io/">Pillow</a>, the friendly fork of PIL. olefile will continue to be improved as a separate project, and new versions will be merged into Pillow regularly.</p>
 <h2 id="main-improvements-over-the-original-version-of-olefileio-in-pil">Main improvements over the original version of OleFileIO in PIL:</h2>
 <ul>
 <li>Compatible with Python 3.x and 2.6+</li>
@@ -60,12 +64,12 @@
 <li>Write features</li>
 </ul>
 <h2 id="documentation">Documentation</h2>
-<p>Please see the <a href="https://bitbucket.org/decalage/olefileio_pl/wiki">online documentation</a> for more information, especially the <a href="https://bitbucket.org/decalage/olefileio_pl/wiki/OLE_Overview">OLE overview</a> and the [API page] (https://bitbucket.org/decalage/olefileio_pl/wiki/API) which describe how to use olefile in Python applications. A copy of the same documentation is also provided in the doc subfolder of the olefile package.</p>
+<p>Please see the <a href="https://bitbucket.org/decalage/olefileio_pl/wiki">online documentation</a> for more information, especially the <a href="https://bitbucket.org/decalage/olefileio_pl/wiki/OLE_Overview">OLE overview</a> and the <a href="https://bitbucket.org/decalage/olefileio_pl/wiki/API">API page</a> which describe how to use olefile in Python applications. A copy of the same documentation is also provided in the doc subfolder of the olefile package.</p>
 <h2 id="real-life-examples">Real-life examples</h2>
-<p>A real-life example: [using OleFileIO_PL for malware analysis and forensics] (http://blog.gregback.net/2011/03/using-remnux-for-forensic-puzzle-6/).</p>
+<p>A real-life example: <a href="http://blog.gregback.net/2011/03/using-remnux-for-forensic-puzzle-6/">using OleFileIO_PL for malware analysis and forensics</a>.</p>
 <p>See also <a href="https://computer-forensics.sans.org/community/papers/gcfa/grow-forensic-tools-taxonomy-python-libraries-helpful-forensic-analysis_6879">this paper</a> about python tools for forensics, which features olefile.</p>
 <h2 id="license">License</h2>
-<p>olefile (formerly OleFileIO_PL) is copyright (c) 2005-2014 Philippe Lagadec (<a href="http://www.decalage.info">http://www.decalage.info</a>)</p>
+<p>olefile (formerly OleFileIO_PL) is copyright (c) 2005-2015 Philippe Lagadec (<a href="http://www.decalage.info">http://www.decalage.info</a>)</p>
 <p>All rights reserved.</p>
 <p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p>
 <ul>
 olefile (formerly OleFileIO\_PL)
 ================================
-`olefile <http://www.decalage.info/python/olefileio>`_ is a Python
-package to parse, read and write [Microsoft OLE2 files (also called
-Structured Storage, Compound File Binary Format or Compound Document
-File Format)]
-(http://en.wikipedia.org/wiki/Compound\_File\_Binary\_Format), such as
-Microsoft Office 97-2003 documents, Image Composer and FlashPix files,
-Outlook messages, StickyNotes, several Microscopy file formats, McAfee
-antivirus quarantine files, etc.
+`olefile <http://www.decalage.info/olefile>`_ is a Python package to
+parse, read and write `Microsoft OLE2
+files <http://en.wikipedia.org/wiki/Compound_File_Binary_Format>`_ (also
+called Structured Storage, Compound File Binary Format or Compound
+Document File Format), such as Microsoft Office 97-2003 documents,
+vbaProject.bin in MS Office 2007+ files, Image Composer and FlashPix
+files, Outlook messages, StickyNotes, several Microscopy file formats,
+McAfee antivirus quarantine files, etc.
 **Quick links:** `Home page <http://www.decalage.info/olefile>`_ -
 `Download/Install <https://bitbucket.org/decalage/olefileio_pl/wiki/Install>`_
@@ -19,40 +19,17 @@ Issues/Suggestions/Questions &lt;https://bitbucket.org/decalage/olefileio_pl/issues
 `Repository <https://bitbucket.org/decalage/olefileio_pl>`_ - `Updates
 on Twitter <https://twitter.com/decalage2>`_
-olefile is based on the OleFileIO module from
-`PIL <http://www.pythonware.com/products/pil/index.htm>`_, the excellent
-Python Imaging Library, created and maintained by Fredrik Lundh. The
-olefile API is still compatible with PIL, but since 2005 I have improved
-the internal implementation significantly, with new features, bugfixes
-and a more robust design. From 2005 to 2014 the project was called
-OleFileIO\_PL, and in 2014 I changed its name to olefile to celebrate
-its 9 years and its new write features.
-
-As far as I know, this module is the most complete and robust Python
-implementation to read MS OLE2 files, portable on several operating
-systems. (please tell me if you know other similar Python modules)
-
-Since 2014 olefile/OleFileIO\_PL has been integrated into
-`Pillow <http://python-imaging.github.io/>`_, the friendly fork of PIL.
-olefile will continue to be improved as a separate project, and new
-versions will be merged into Pillow regularly.
-
-olefile can be used as an independent module or with PIL/Pillow.
-
-olefile is mostly meant for developers. If you are looking for tools to
-analyze OLE files or to extract data (especially for security purposes
-such as malware analysis and forensics), then please also check my
-[python-oletools] (http://www.decalage.info/python/oletools), which are
-built upon olefile and provide a higher-level interface.
-
 News
 ----
 Follow all updates and news on Twitter: https://twitter.com/decalage2
--  **2014-11-25 v0.41**: OleFileIO.open and isOleFile now support OLE
-   files stored in byte strings, fixed installer for python 3, added
-   support for Jython (Niko Ehrenfeuchter)
+-  **2015-01-25 v0.42**: improved handling of special characters in
+   stream/storage names on Python 2.x (using UTF-8 instead of Latin-1),
+   fixed bug in listdir with empty storages.
+-  2014-11-25 v0.41: OleFileIO.open and isOleFile now support OLE files
+   stored in byte strings, fixed installer for python 3, added support
+   for Jython (Niko Ehrenfeuchter)
 -  2014-10-01 v0.40: renamed OleFileIO\_PL to olefile, added initial
    write support for streams >4K, updated doc and license, improved the
    setup script.
@@ -66,17 +43,16 @@ Follow all updates and news on Twitter: https://twitter.com/decalage2
    improved listdir to include storages, fixed parsing of direntry
    timestamps
 -  2013-05-27 v0.25: improved metadata extraction, properties parsing
-   and exception handling, fixed [issue #12]
-   (https://bitbucket.org/decalage/olefileio\_pl/issue/12/error-when-converting-timestamps-in-ole)
+   and exception handling, fixed `issue
+   #12 <https://bitbucket.org/decalage/olefileio_pl/issue/12/error-when-converting-timestamps-in-ole>`_
 -  2013-05-07 v0.24: new features to extract metadata (get\_metadata
    method and OleMetadata class), improved getproperties to convert
    timestamps to Python datetime
 -  2012-10-09: published
    `python-oletools <http://www.decalage.info/python/oletools>`_, a
    package of analysis tools based on OleFileIO\_PL
--  2012-09-11 v0.23: added support for file-like objects, fixed [issue
-   #8]
-   (https://bitbucket.org/decalage/olefileio\_pl/issue/8/bug-with-file-object)
+-  2012-09-11 v0.23: added support for file-like objects, fixed `issue
+   #8 <https://bitbucket.org/decalage/olefileio_pl/issue/8/bug-with-file-object>`_
 -  2012-02-17 v0.22: fixed issues #7 (bug in getproperties) and #2
    (added close method)
 -  2011-10-20: code hosted on bitbucket to ease contributions and bug
@@ -92,9 +68,13 @@ Follow all updates and news on Twitter: https://twitter.com/decalage2
 Download/Install
 ----------------
-If you have pip or setuptools installed, you may simply run "**pip
-install olefile**\ " or "**easy\_install olefile**\ ". Otherwise, see
-https://bitbucket.org/decalage/olefileio\_pl/wiki/Install
+If you have pip or setuptools installed (pip is included in Python
+2.7.9+), you may simply run **pip install olefile** or **easy\_install
+olefile** for the first installation.
+
+To update olefile, run **pip install -U olefile**.
+
+Otherwise, see https://bitbucket.org/decalage/olefileio\_pl/wiki/Install
 Features
 --------
@@ -109,6 +89,35 @@ Features
 -  Parse and read property streams, containing metadata of the file
 -  Portable, pure Python module, no dependency
+olefile can be used as an independent package or with PIL/Pillow.
+
+olefile is mostly meant for developers. If you are looking for tools to
+analyze OLE files or to extract data (especially for security purposes
+such as malware analysis and forensics), then please also check my
+`python-oletools <http://www.decalage.info/python/oletools>`_, which are
+built upon olefile and provide a higher-level interface.
+
+History
+-------
+
+olefile is based on the OleFileIO module from
+`PIL <http://www.pythonware.com/products/pil/index.htm>`_, the excellent
+Python Imaging Library, created and maintained by Fredrik Lundh. The
+olefile API is still compatible with PIL, but since 2005 I have improved
+the internal implementation significantly, with new features, bugfixes
+and a more robust design. From 2005 to 2014 the project was called
+OleFileIO\_PL, and in 2014 I changed its name to olefile to celebrate
+its 9 years and its new write features.
+
+As far as I know, olefile is the most complete and robust Python
+implementation to read MS OLE2 files, portable on several operating
+systems. (please tell me if you know other similar Python modules)
+
+Since 2014 olefile/OleFileIO\_PL has been integrated into
+`Pillow <http://python-imaging.github.io/>`_, the friendly fork of PIL.
+olefile will continue to be improved as a separate project, and new
+versions will be merged into Pillow regularly.
+
 Main improvements over the original version of OleFileIO in PIL:
 ----------------------------------------------------------------
@@ -134,18 +143,17 @@ Please see the `online
 documentation <https://bitbucket.org/decalage/olefileio_pl/wiki>`_ for
 more information, especially the `OLE
 overview <https://bitbucket.org/decalage/olefileio_pl/wiki/OLE_Overview>`_
-and the [API page]
-(https://bitbucket.org/decalage/olefileio\_pl/wiki/API) which describe
-how to use olefile in Python applications. A copy of the same
+and the `API
+page <https://bitbucket.org/decalage/olefileio_pl/wiki/API>`_ which
+describe how to use olefile in Python applications. A copy of the same
 documentation is also provided in the doc subfolder of the olefile
 package.
 Real-life examples
 ------------------
-A real-life example: [using OleFileIO\_PL for malware analysis and
-forensics]
-(http://blog.gregback.net/2011/03/using-remnux-for-forensic-puzzle-6/).
+A real-life example: `using OleFileIO\_PL for malware analysis and
+forensics <http://blog.gregback.net/2011/03/using-remnux-for-forensic-puzzle-6/>`_.
 See also `this
 paper <https://computer-forensics.sans.org/community/papers/gcfa/grow-forensic-tools-taxonomy-python-libraries-helpful-forensic-analysis_6879>`_
@@ -154,7 +162,7 @@ about python tools for forensics, which features olefile.
 License
 -------
-olefile (formerly OleFileIO\_PL) is copyright (c) 2005-2014 Philippe
+olefile (formerly OleFileIO\_PL) is copyright (c) 2005-2015 Philippe
 Lagadec (`http://www.decalage.info <http://www.decalage.info>`_)
 All rights reserved.
@@ -10,7 +10,7 @@ This version is compatible with Python 2.6+ and 3.x
 Project website: http://www.decalage.info/olefile
-olefile is copyright (c) 2005-2014 Philippe Lagadec (http://www.decalage.info)
+olefile is copyright (c) 2005-2015 Philippe Lagadec (http://www.decalage.info)
 olefile is based on the OleFileIO module from the PIL library v1.1.6
 See: http://www.pythonware.com/products/pil/index.htm
@@ -56,16 +56,22 @@ else:
 <pre><code>ole = olefile.OleFileIO(&#39;test.doc&#39;, write_mode=True)</code></pre>
 <p>(new in v0.40)</p>
 <p>The code for write features is new and it has not been thoroughly tested yet. See <a href="https://bitbucket.org/decalage/olefileio_pl/issue/6/improve-olefileio_pl-to-write-ole-files">issue #6</a> for the roadmap and the implementation status. If you encounter any issue, please send me your <a href="http://www.decalage.info/en/contact">feedback</a> or <a href="https://bitbucket.org/decalage/olefileio_pl/issues?status=new&amp;status=open">report issues</a>.</p>
-<h2 id="syntax-for-stream-and-storage-path">Syntax for stream and storage path</h2>
+<h2 id="syntax-for-stream-and-storage-paths">Syntax for stream and storage paths</h2>
 <p>Two different syntaxes are allowed for methods that need or return the path of streams and storages:</p>
 <ol style="list-style-type: decimal">
 <li><p>Either a <strong>list of strings</strong> including all the storages from the root up to the stream/storage name. For example a stream called &quot;WordDocument&quot; at the root will have ['WordDocument'] as full path. A stream called &quot;ThisDocument&quot; located in the storage &quot;Macros/VBA&quot; will be ['Macros', 'VBA', 'ThisDocument']. This is the original syntax from PIL. While hard to read and not very convenient, this syntax works in all cases.</p></li>
-<li><p>Or a <strong>single string with slashes</strong> to separate storage and stream names (similar to the Unix path syntax). The previous examples would be 'WordDocument' and 'Macros/VBA/ThisDocument'. This syntax is easier, but may fail if a stream or storage name contains a slash. (new in v0.15)</p></li>
+<li><p>Or a <strong>single string with slashes</strong> to separate storage and stream names (similar to the Unix path syntax). The previous examples would be 'WordDocument' and 'Macros/VBA/ThisDocument'. This syntax is easier, but may fail if a stream or storage name contains a slash (which is normally not allowed, according to the Microsoft specifications [MS-CFB]). (new in v0.15)</p></li>
 </ol>
 <p>Both are case-insensitive.</p>
 <p>Switching between the two is easy:</p>
 <pre><code>slash_path = &#39;/&#39;.join(list_path)
 list_path  = slash_path.split(&#39;/&#39;)</code></pre>
+<p><strong>Encoding</strong>:</p>
+<ul>
+<li>Stream and Storage names are stored in Unicode format in OLE files, which means they may contain special characters (e.g. Greek, Cyrillic, Japanese, etc) that applications must support to avoid exceptions.</li>
+<li><strong>On Python 2.x</strong>, all stream and storage paths are handled by olefile in bytes strings, using the <strong>UTF-8 encoding</strong> by default. If you need to use Unicode instead, add the option <strong>path_encoding=None</strong> when creating the OleFileIO object. This is new in v0.42. Olefile was using the Latin-1 encoding until v0.41, therefore special characters were not supported.<br /></li>
+<li><strong>On Python 3.x</strong>, all stream and storage paths are handled by olefile in unicode strings, without encoding.</li>
+</ul>
 <h2 id="get-the-list-of-streams">Get the list of streams</h2>
 <p>listdir() returns a list of all the streams contained in the OLE file, including those stored in storages. Each stream is listed itself as a list, as described above.</p>
 <pre><code>print(ole.listdir())</code></pre>
@@ -112,13 +112,18 @@ Before using the write features, the OLE file must be opened in read/write mode:
 The code for write features is new and it has not been thoroughly tested yet. See [issue #6](https://bitbucket.org/decalage/olefileio_pl/issue/6/improve-olefileio_pl-to-write-ole-files) for the roadmap and the implementation status. If you encounter any issue, please send me your [feedback](http://www.decalage.info/en/contact) or [report issues](https://bitbucket.org/decalage/olefileio_pl/issues?status=new&status=open).
-## Syntax for stream and storage path
+## Syntax for stream and storage paths
 Two different syntaxes are allowed for methods that need or return the path of streams and storages:
-1) Either a **list of strings** including all the storages from the root up to the stream/storage name. For example a stream called "WordDocument" at the root will have ['WordDocument'] as full path. A stream called "ThisDocument" located in the storage "Macros/VBA" will be ['Macros', 'VBA', 'ThisDocument']. This is the original syntax from PIL. While hard to read and not very convenient, this syntax works in all cases.
+1) Either a **list of strings** including all the storages from the root up to the stream/storage name. For example a 
+stream called "WordDocument" at the root will have ['WordDocument'] as full path. A stream called "ThisDocument" 
+located in the storage "Macros/VBA" will be ['Macros', 'VBA', 'ThisDocument']. This is the original syntax from PIL. 
+While hard to read and not very convenient, this syntax works in all cases.
-2) Or a **single string with slashes** to separate storage and stream names (similar to the Unix path syntax). The previous examples would be 'WordDocument' and 'Macros/VBA/ThisDocument'. This syntax is easier, but may fail if a stream or storage name contains a slash. (new in v0.15)
+2) Or a **single string with slashes** to separate storage and stream names (similar to the Unix path syntax). 
+The previous examples would be 'WordDocument' and 'Macros/VBA/ThisDocument'. This syntax is easier, but may fail if a 
+stream or storage name contains a slash (which is normally not allowed, according to the Microsoft specifications [MS-CFB]). (new in v0.15)
 Both are case-insensitive.
@@ -128,10 +133,20 @@ Switching between the two is easy:
     slash_path = '/'.join(list_path)
     list_path  = slash_path.split('/')
+**Encoding**: 
+
+- Stream and Storage names are stored in Unicode format in OLE files, which means they may contain special characters
+    (e.g. Greek, Cyrillic, Japanese, etc) that applications must support to avoid exceptions.
+- **On Python 2.x**, all stream and storage paths are handled by olefile in bytes strings, using the **UTF-8 encoding**
+    by default. If you need to use Unicode instead, add the option **path_encoding=None** when creating the OleFileIO 
+    object. This is new in v0.42. Olefile was using the Latin-1 encoding until v0.41, therefore special characters were 
+    not supported.  
+- **On Python 3.x**, all stream and storage paths are handled by olefile in unicode strings, without encoding.
 ## Get the list of streams
-listdir() returns a list of all the streams contained in the OLE file, including those stored in storages. Each stream is listed itself as a list, as described above. 
+listdir() returns a list of all the streams contained in the OLE file, including those stored in storages. 
+Each stream is listed itself as a list, as described above. 
 	:::python
     print(ole.listdir())
@@ -7,16 +7,18 @@
   <title></title>
 </head>
 <body>
-<h1 id="olefile-v0.41-documentation">olefile v0.41 documentation</h1>
+<h1 id="olefile-v0.42-documentation">olefile v0.42 documentation</h1>
 <p>This is the home page of the documentation for olefile. The latest version can be found <a href="https://bitbucket.org/decalage/olefileio_pl/wiki">online</a>, otherwise a copy is provided in the doc subfolder of the package.</p>
-<p><a href="http://www.decalage.info/olefile">olefile</a> is a Python package to parse, read and write <a href="http://en.wikipedia.org/wiki/Compound_File_Binary_Format">Microsoft OLE2 files (also called Structured Storage, Compound File Binary Format or Compound Document File Format)</a>, such as Microsoft Office 97-2003 documents, Image Composer and FlashPix files, Outlook messages, StickyNotes, several Microscopy file formats, McAfee antivirus quarantine files, etc.</p>
+<p><a href="http://www.decalage.info/olefile">olefile</a> is a Python package to parse, read and write <a href="http://en.wikipedia.org/wiki/Compound_File_Binary_Format">Microsoft OLE2 files</a> (also called Structured Storage, Compound File Binary Format or Compound Document File Format), such as Microsoft Office 97-2003 documents, Image Composer and FlashPix files, Outlook messages, StickyNotes, several Microscopy file formats, McAfee antivirus quarantine files, etc.</p>
 <p><strong>Quick links:</strong> <a href="http://www.decalage.info/olefile">Home page</a> - <a href="https://bitbucket.org/decalage/olefileio_pl/wiki/Install">Download/Install</a> - <a href="https://bitbucket.org/decalage/olefileio_pl/wiki">Documentation</a> - <a href="https://bitbucket.org/decalage/olefileio_pl/issues?status=new&amp;status=open">Report Issues/Suggestions/Questions</a> - <a href="http://decalage.info/contact">Contact the author</a> - <a href="https://bitbucket.org/decalage/olefileio_pl">Repository</a> - <a href="https://twitter.com/decalage2">Updates on Twitter</a></p>
-<h2 id="history">History</h2>
-<p>olefile is based on the OleFileIO module from <a href="http://www.pythonware.com/products/pil/index.htm">PIL</a>, the excellent Python Imaging Library, created and maintained by Fredrik Lundh. The olefile API is still compatible with PIL, but since 2005 I have improved the internal implementation significantly, with new features, bugfixes and a more robust design. From 2005 to 2014 the project was called OleFileIO_PL, and in 2014 I changed its name to olefile to celebrate its 9 years and its new write features.</p>
-<p>As far as I know, this module is the most complete and robust Python implementation to read MS OLE2 files, portable on several operating systems. (please tell me if you know other similar Python modules)</p>
-<p>Since 2014 olefile/OleFileIO_PL has been integrated into <a href="http://python-imaging.github.io/">Pillow</a>, the friendly fork of PIL. olefile will continue to be improved as a separate project, and new versions will be merged into Pillow regularly.</p>
-<p>olefile can be used as an independent module or with PIL/Pillow.</p>
-<p>olefile is mostly meant for developers. If you are looking for tools to analyze OLE files or to extract data (especially for security purposes such as malware analysis and forensics), then please also check my <a href="http://www.decalage.info/python/oletools">python-oletools</a>, which are built upon olefile and provide a higher-level interface.</p>
+<h2 id="documentation-pages">Documentation pages</h2>
+<ul>
+<li><a href="License.html">License</a></li>
+<li><a href="Install.html">Install</a></li>
+<li><a href="Contribute.html">Contribute</a>, Suggest Improvements or Report Issues</li>
+<li><a href="OLE_Overview.html">OLE_Overview</a></li>
+<li><a href="API.html">API</a> and Usage</li>
+</ul>
 <h2 id="features">Features</h2>
 <ul>
 <li>Parse, read and write any OLE file such as Microsoft Office 97-2003 legacy document formats (Word .doc, Excel .xls, PowerPoint .ppt, Visio .vsd, Project .mpp), Image Composer and FlashPix files, Outlook messages, StickyNotes, Zeiss AxioVision ZVI files, Olympus FluoView OIB files, etc</li>
@@ -25,6 +27,12 @@
 <li>Parse and read property streams, containing metadata of the file</li>
 <li>Portable, pure Python module, no dependency</li>
 </ul>
+<p>olefile can be used as an independent module or with PIL/Pillow.</p>
+<p>olefile is mostly meant for developers. If you are looking for tools to analyze OLE files or to extract data (especially for security purposes such as malware analysis and forensics), then please also check my <a href="http://www.decalage.info/python/oletools">python-oletools</a>, which are built upon olefile and provide a higher-level interface.</p>
+<h2 id="history">History</h2>
+<p>olefile is based on the OleFileIO module from <a href="http://www.pythonware.com/products/pil/index.htm">PIL</a>, the excellent Python Imaging Library, created and maintained by Fredrik Lundh. The olefile API is still compatible with PIL, but since 2005 I have improved the internal implementation significantly, with new features, bugfixes and a more robust design. From 2005 to 2014 the project was called OleFileIO_PL, and in 2014 I changed its name to olefile to celebrate its 9 years and its new write features.</p>
+<p>As far as I know, this module is the most complete and robust Python implementation to read MS OLE2 files, portable on several operating systems. (please tell me if you know other similar Python modules)</p>
+<p>Since 2014 olefile/OleFileIO_PL has been integrated into <a href="http://python-imaging.github.io/">Pillow</a>, the friendly fork of PIL. olefile will continue to be improved as a separate project, and new versions will be merged into Pillow regularly.</p>
 <h2 id="main-improvements-over-the-original-version-of-olefileio-in-pil">Main improvements over the original version of OleFileIO in PIL:</h2>
 <ul>
 <li>Compatible with Python 3.x and 2.6+</li>
-olefile v0.41 documentation
+olefile v0.42 documentation
 ===========================
-This is the home page of the documentation for olefile. The latest version can be found [online](https://bitbucket.org/decalage/olefileio_pl/wiki), otherwise a copy is provided in the doc subfolder of the package.
+This is the home page of the documentation for olefile. The latest version can be found 
+[online](https://bitbucket.org/decalage/olefileio_pl/wiki), otherwise a copy is provided in the doc subfolder of the package.
-[olefile](http://www.decalage.info/olefile) is a Python package to parse, read and write [Microsoft OLE2 files (also called Structured Storage, Compound File Binary Format or Compound Document File Format)](http://en.wikipedia.org/wiki/Compound_File_Binary_Format), such as Microsoft Office 97-2003 documents, Image Composer and FlashPix files, Outlook messages, StickyNotes, several Microscopy file formats, McAfee antivirus quarantine files, etc.
+[olefile](http://www.decalage.info/olefile) is a Python package to parse, read and write 
+[Microsoft OLE2 files](http://en.wikipedia.org/wiki/Compound_File_Binary_Format)
+(also called Structured Storage, Compound File Binary Format or Compound Document File Format), such as Microsoft 
+Office 97-2003 documents, Image Composer and FlashPix files, Outlook messages, StickyNotes, several Microscopy file 
+formats, McAfee antivirus quarantine files, etc.
-**Quick links:** [Home page](http://www.decalage.info/olefile) - [Download/Install](https://bitbucket.org/decalage/olefileio_pl/wiki/Install) - [Documentation](https://bitbucket.org/decalage/olefileio_pl/wiki) - [Report Issues/Suggestions/Questions](https://bitbucket.org/decalage/olefileio_pl/issues?status=new&status=open) - [Contact the author](http://decalage.info/contact) - [Repository](https://bitbucket.org/decalage/olefileio_pl) - [Updates on Twitter](https://twitter.com/decalage2)
+**Quick links:** 
+[Home page](http://www.decalage.info/olefile) - 
+[Download/Install](https://bitbucket.org/decalage/olefileio_pl/wiki/Install) - 
+[Documentation](https://bitbucket.org/decalage/olefileio_pl/wiki) - 
+[Report Issues/Suggestions/Questions](https://bitbucket.org/decalage/olefileio_pl/issues?status=new&status=open) - 
+[Contact the author](http://decalage.info/contact) - 
+[Repository](https://bitbucket.org/decalage/olefileio_pl) - 
+[Updates on Twitter](https://twitter.com/decalage2)
-History
--------
-
-olefile is based on the OleFileIO module from [PIL](http://www.pythonware.com/products/pil/index.htm), the excellent Python Imaging Library, created and maintained by Fredrik Lundh. The olefile API is still compatible with PIL, but since 2005 I have improved the internal implementation significantly, with new features, bugfixes and a more robust design. From 2005 to 2014 the project was called OleFileIO_PL, and in 2014 I changed its name to olefile to celebrate its 9 years and its new write features. 
-
-As far as I know, this module is the most complete and robust Python implementation to read MS OLE2 files, portable on several operating systems. (please tell me if you know other similar Python modules)
-
-Since 2014 olefile/OleFileIO_PL has been integrated into [Pillow](http://python-imaging.github.io/), the friendly fork of PIL. olefile will continue to be improved as a separate project, and new versions will be merged into Pillow regularly.
+Documentation pages
+-------------------
-olefile can be used as an independent module or with PIL/Pillow. 
+- [[License]]
+- [[Install]]
+- [[Contribute]], Suggest Improvements or Report Issues
+- [[OLE_Overview]]
+- [[API]] and Usage
-olefile is mostly meant for developers. If you are looking for tools to analyze OLE files or to extract data (especially for security purposes such as malware analysis and forensics), then please also check my [python-oletools](http://www.decalage.info/python/oletools), which are built upon olefile and provide a higher-level interface.
 Features
 --------
-- Parse, read and write any OLE file such as Microsoft Office 97-2003 legacy document formats (Word .doc, Excel .xls, PowerPoint .ppt, Visio .vsd, Project .mpp), Image Composer and FlashPix files, Outlook messages, StickyNotes, Zeiss AxioVision ZVI files, Olympus FluoView OIB files, etc
+- Parse, read and write any OLE file such as Microsoft Office 97-2003 legacy document formats (Word .doc, Excel .xls, 
+    PowerPoint .ppt, Visio .vsd, Project .mpp), Image Composer and FlashPix files, Outlook messages, StickyNotes, Zeiss 
+    AxioVision ZVI files, Olympus FluoView OIB files, etc
 - List all the streams and storages contained in an OLE file
 - Open streams as files
 - Parse and read property streams, containing metadata of the file
 - Portable, pure Python module, no dependency
+olefile can be used as an independent module or with PIL/Pillow. 
+
+olefile is mostly meant for developers. If you are looking for tools to analyze OLE files or to extract data 
+(especially for security purposes such as malware analysis and forensics), then please also check my 
+[python-oletools](http://www.decalage.info/python/oletools), which are built upon olefile and provide a higher-level 
+interface.
+
+
+History
+-------
+
+olefile is based on the OleFileIO module from [PIL](http://www.pythonware.com/products/pil/index.htm), the excellent 
+Python Imaging Library, created and maintained by Fredrik Lundh. The olefile API is still compatible with PIL, but 
+since 2005 I have improved the internal implementation significantly, with new features, bugfixes and a more robust 
+design. From 2005 to 2014 the project was called OleFileIO_PL, and in 2014 I changed its name to olefile to celebrate 
+its 9 years and its new write features. 
+
+As far as I know, this module is the most complete and robust Python implementation to read MS OLE2 files, portable on 
+several operating systems. (please tell me if you know other similar Python modules)
+
+Since 2014 olefile/OleFileIO_PL has been integrated into [Pillow](http://python-imaging.github.io/), the friendly fork 
+of PIL. olefile will continue to be improved as a separate project, and new versions will be merged into Pillow regularly.
 Main improvements over the original version of OleFileIO in PIL:
 ----------------------------------------------------------------
@@ -12,8 +12,9 @@
 <p>olefile requires Python 2.6, 2.7 or 3.x.</p>
 <p>For Python 2.5 and older, olefile falls back to an older version (based on OleFileIO_PL 0.26) which might not contain all the enhancements implemented in olefile.</p>
 <h2 id="download-and-install">Download and Install</h2>
-<p>To use olefile with other Python applications or your own scripts, the simplest solution is to run &quot;<strong>pip install olefile</strong>&quot; or &quot;<strong>easy_install olefile</strong>&quot; to download and install the package in one go.</p>
-<p>Otherwise you may download/extract the <a href="https://bitbucket.org/decalage/olefileio_pl/downloads">zip archive</a> in a temporary directory and run &quot;<strong>python setup.py install</strong>&quot;.</p>
+<p>To use olefile with other Python applications or your own scripts, the simplest solution is to run <strong>pip install olefile</strong> or <strong>easy_install olefile</strong>, to download and install the package in one go. Pip is part of the standard Python distribution since v2.7.9.</p>
+<p>To update olefile if a previous version is already installed, run <strong>pip install -U olefile</strong>.</p>
+<p>Otherwise you may download/extract the <a href="https://bitbucket.org/decalage/olefileio_pl/downloads">zip archive</a> in a temporary directory and run <strong>python setup.py install</strong>.</p>
 <p>On Windows you may simply double-click on <strong>install.bat</strong>.</p>
 <hr />
 <h2 id="olefile-documentation">olefile documentation</h2>
@@ -6,15 +6,21 @@ Pre-requisites
 olefile requires Python 2.6, 2.7 or 3.x. 
-For Python 2.5 and older, olefile falls back to an older version (based on OleFileIO_PL 0.26) which might not contain all the enhancements implemented in olefile. 
+For Python 2.5 and older, olefile falls back to an older version (based on OleFileIO_PL 0.26) which might not contain 
+all the enhancements implemented in olefile. 
 Download and Install
 --------------------
-To use olefile with other Python applications or your own scripts, the simplest solution is to run "**pip install olefile**" or "**easy_install olefile**" to download and install the package in one go. 
+To use olefile with other Python applications or your own scripts, the simplest solution is to run **pip install olefile** 
+or **easy_install olefile**, to download and install the package in one go. Pip is part of the standard Python 
+distribution since v2.7.9.
-Otherwise you may download/extract the [zip archive](https://bitbucket.org/decalage/olefileio_pl/downloads) in a temporary directory and run "**python setup.py install**". 
+To update olefile if a previous version is already installed, run **pip install -U olefile**.
+
+Otherwise you may download/extract the [zip archive](https://bitbucket.org/decalage/olefileio_pl/downloads) in a 
+temporary directory and run **python setup.py install**. 
 On Windows you may simply double-click on **install.bat**.
@@ -8,7 +8,7 @@
 </head>
 <body>
 <h1 id="license-for-olefile">License for olefile</h1>
-<p>olefile (formerly OleFileIO_PL) is copyright (c) 2005-2014 Philippe Lagadec (<a href="http://www.decalage.info">http://www.decalage.info</a>)</p>
+<p>olefile (formerly OleFileIO_PL) is copyright (c) 2005-2015 Philippe Lagadec (<a href="http://www.decalage.info">http://www.decalage.info</a>)</p>
 <p>All rights reserved.</p>
 <p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p>
 <ul>
 License for olefile
 ===================
-olefile (formerly OleFileIO_PL) is copyright (c) 2005-2014 Philippe Lagadec ([http://www.decalage.info](http://www.decalage.info))
+olefile (formerly OleFileIO_PL) is copyright (c) 2005-2015 Philippe Lagadec ([http://www.decalage.info](http://www.decalage.info))
 All rights reserved.
 #!/usr/bin/env python
-# olefile (formerly OleFileIO_PL) version 0.42 2015-01-24
+# olefile (formerly OleFileIO_PL) version 0.42 2015-01-25
 #
 # Module to read/write Microsoft OLE2 files (also called Structured Storage or
 # Microsoft Compound Document File Format), such as Microsoft Office 97-2003
@@ -29,8 +29,8 @@ from __future__ import print_function   # This version of olefile requires Pytho
 __author__  = "Philippe Lagadec"
-__date__    = "2015-01-24"
-__version__ = '0.42'
+__date__    = "2015-01-25"
+__version__ = '0.42.1'
 #--- LICENSE ------------------------------------------------------------------