Updating OTS repo from https://github.com/khaledhosny/ots.git

third_party/ots/docs/DesignDoc.md

Index: third_party/ots/docs/DesignDoc.md
diff --git a/third_party/ots/docs/DesignDoc.md b/third_party/ots/docs/DesignDoc.md
new file mode 100644
index 0000000000000000000000000000000000000000..ffcc03522f86949eb0ec16ed2c0caf46e99fbe4f
--- /dev/null
+++ b/third_party/ots/docs/DesignDoc.md
@@ -0,0 +1,136 @@
+What's OTS?
+===========
+
+Sanitiser for OpenType (OTS) is a small library which parses OpenType files
+(usually from `@font-face`) and attempts to validate and sanitise them. This
+library is primarily intended to be used with Chromium. We hope this reduces
+the attack surface of the system font libraries.
+
+What the sanitiser does is as follows:
+
+1. Parses an original font. If the parsing fails, OTS rejects the original
+   font.
+2. Validates the parsed data structure. If the validation fails, it rejects the
+   original font as well.
+3. Creates a new font on memory by serializing the data structure, and we call
+   this "transcoding".
+
+By transcoding fonts in this way, it is ensured that:
+
+1. All information in an original font that OTS doesn't know or can't parse is
+   dropped from the transcoded font.
+2. All information in the transcoded font is valid (standard compliant).
+   Particularly 'length' and 'offset' values, that are often used as attack
+   vectors, are ensured to be correct.
+
+Supported OpenType tables
+=========================
+
+| Name   | Mandatory table?            | Supported by OTS? | Note   |
+|--------|-----------------------------|-------------------|--------|
+| `sfnt` | Yes                         | Yes               | Overlapped tables are not allowed; it is treated as a fatal parser error.|
+| `maxp` | Yes                         | Yes               |        |
+| `head` | Yes                         | Yes               |        |
+| `hhea` | Yes                         | Yes               |        |
+| `hmtx` | Yes                         | Yes               |        |
+| `name` | Yes                         | Yes               |        |
+| `OS/2` | Yes                         | Yes               |        |
+| `post` | Yes                         | Yes               |        |
+| `cmap` | Yes                         | Partialy          | see below |
+| `glyf` | Yes, for TrueType fonts     | Yes               | TrueType bytecode is supported, but OTS does **not** validate it.|
+| `loca` | Yes, when glyf table exists | Yes               |        |
+| `CFF ` | Yes, for OpenType fonts     | Yes               | OpenType bytecode is also supported, and OTS **does** validate it.|
+| `cvt ` | No                          | Yes               | Though this table is not mandatory, OTS can't drop the table from a transcoded font since it might be referred from other hinting-related tables. Errors on this table should be treated as fatal.|
+| `fpgm` | No                          | Yes               | Ditto. |
+| `prep` | No                          | Yes               | Ditto. |
+| `VDMX` | No                          | Yes               | This table is important for calculating the correct line spacing, at least on Chromium Windows and Chromium Linux.|
+| `hdmx` | No                          | Yes               |        |
+| `gasp` | No                          | Yes               |        |
+| `VORG` | No                          | Yes               |        |
+| `LTSH` | No                          | Yes               |        |
+| `kern` | No                          | Yes               |        |
+| `GDEF` | No                          | Yes               |        |
+| `GSUB` | No                          | Yes               |        |
+| `GPOS` | No                          | Yes               |        |
+| `morx` | No                          | No                |        |
+| `jstf` | No                          | No                |        |
+| `vmtx` | No                          | Yes               |        |
+| `vhea` | No                          | Yes               |        |
+| `EBDT` | No                          | No                | We don't support embedded bitmap strikes.|
+| `EBLC` | No                          | No                | Ditto. |
+| `EBSC` | No                          | No                | Ditto. |
+| `bdat` | No                          | No                | Ditto. |
+| `bhed` | No                          | No                | Ditto. |
+| `bloc` | No                          | No                | Ditto. |
+| `DSIG` | No                          | No                |        |
+| All other tables | -                 | No                |        |
+
+Please note that OTS library does not parse "unsupported" tables. These
+unsupported tables never appear in a transcoded font.
+
+Supported cmap formats
+----------------------
+
+The following 9 formats are supported:
+
+* "MS Unicode" (platform 3 encoding 1 format 4)
+    * BMP
+* "MS UCS-4" (platform 3 encoding 10 format 12)
+* "MS UCS-4 fallback" (platform 3 encoding 10 format 13)
+* "MS Symbol" (platform 3 encoding 0 format 4)
+* "Mac Roman" (platform 1 encoding 0 format 0)
+    * 1-0-0 format is supported while 1-0-6 is not.
+* "Unicode default" format (platform 0 encoding 0 format 4)
+    * treated as 3-1-4 format
+* "Unicode 1.1" format (platform 0 encoding 1 format 4)
+    * ditto
+* "Unicode 2.0+" format (platform 0 encoding 3 format 4)
+* "Unicode UCS-4" format (platform 0 encoding 4 format 12)
+    * treated as 3-10-12 format
+* Unicode Variation Sequences (platform 0 encoding 5 format 14)
+
+All other types of subtables are not supported and do not appear in transcoded fonts.
+
+Validation strategies
+=====================
+
+With regards to 8 mandatory tables, glyph-related tables (`glyf`, `loca` and `CFF`),
+and hinting-related tables (`cvt`, `prep`, and `fpgm`):
+
+* If OTS finds table-length, table-offset, or table-alignment errors, in other
+  words it cannot continue parsing, OTS treats the error as fatal.
+* If OTS finds simple value error which could be automatically fixed (e.g.,
+  font weight is greater than 900 - that's undefined), and if the error is
+  considered common among non-malicious fonts, OTS rewrites the value and
+  continues transcoding.
+* If OTS finds a value error which is hard to fix (e.g., values which should be
+  sorted are left unsorted), OTS treats the error as fatal.
+
+With regards to optional tables (`VORG`, `gasp`, `hdmx`, `LTSH`, and `VDMX`):
+
+* If OTS finds table-length, table-offset, or table-alignment errors, OTS
+  treats the error as fatal.
+* If OTS finds other errors, it simply drops the table from a transcoded font.
+
+Files
+=====
+
+* include/opentype-sanitiser.h
+    * Declaration for the public API, `ots::Process()`.
+    * Definition of the `OTSStream` interface, a write-only memory stream.
+* include/ots-memory-stream.h
+    * Definition of the `MemoryStream` class which implements the `OTSStream`
+      interface above.
+* src/ots.h
+    * Debug macros.
+    * Definition of a `Buffer` class which is a read-only memory stream.
+* src/ots.cc
+    * Definition of the `ots::Process()` function.
+    * `sfnt` table parser.
+* test/\*.cc
+    * test tools. see test/README for details.
+
+Known issues
+============
+
+Please check the [issues](https://github.com/khaledhosny/ots/issues) page.