Update landing-page/content/common for 1.1.0 (#181)
diff --git a/landing-page/content/common/gcm-stream-spec.md b/landing-page/content/common/gcm-stream-spec.md
new file mode 100644
index 0000000..36e07ad
--- /dev/null
+++ b/landing-page/content/common/gcm-stream-spec.md
@@ -0,0 +1,88 @@
+---
+title: "AES GCM Stream Spec"
+url: gcm-stream-spec
+toc: true
+disableSidebar: true
+---
+<!--
+ - Licensed to the Apache Software Foundation (ASF) under one or more
+ - contributor license agreements. See the NOTICE file distributed with
+ - this work for additional information regarding copyright ownership.
+ - The ASF licenses this file to You under the Apache License, Version 2.0
+ - (the "License"); you may not use this file except in compliance with
+ - the License. You may obtain a copy of the License at
+ -
+ - http://www.apache.org/licenses/LICENSE-2.0
+ -
+ - Unless required by applicable law or agreed to in writing, software
+ - distributed under the License is distributed on an "AS IS" BASIS,
+ - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ - See the License for the specific language governing permissions and
+ - limitations under the License.
+ -->
+
+# AES GCM Stream file format extension
+
+## Background and Motivation
+
+Iceberg supports a number of data file formats. Two of these formats (Parquet and ORC) have built-in encryption capabilities, that allow to protect sensitive information in the data files. However, besides the data files, Iceberg tables also have metadata files, that keep sensitive information too (e.g., min/max values in manifest files, or bloom filter bitsets in puffin files). Metadata file formats (AVRO, JSON, Puffin) don't have encryption support.
+
+Moreover, with the exception of Parquet, no Iceberg data or metadata file format supports integrity verification, required for end-to-end tamper proofing of Iceberg tables.
+
+This document specifies details of a simple file format extension that adds encryption and tamper-proofing to any existing file format.
+
+## Goals
+
+* Metadata encryption: enable encryption of manifests, manifest lists, snapshots and stats.
+* Avro data encryption: enable encryption of data files in tables that use the Avro format.
+* Support read splitting: enable seekable decrypting streams that can be used with splittable formats like Avro.
+* Tamper proofing of Iceberg data and metadata files.
+
+## Overview
+
+The output stream, produced by a metadata or data writer, is split into equal-size blocks (plus last block that can be shorter). Each block is enciphered (encrypted/signed) with a given encryption key, and stored in a file in the AES GCM Stream format. Upon reading, the stored cipherblocks are verified for integrity; then decrypted and passed to metadata or data readers.
+
+## Encryption algorithm
+
+AES GCM Stream uses the standard AEG GCM cipher, and supports all AES key sizes: 128, 192 and 256 bits.
+
+AES GCM is an authenticated encryption. Besides data confidentiality (encryption), it supports two levels of integrity verification (authentication): of the data (default), and of the data combined with an optional AAD (“additional authenticated data”). An AAD is a free text to be authenticated, together with the data. The structure of AES GCM Stream AADs is described below.
+
+AES GCM requires a unique vector to be provided for each encrypted block. In this document, the unique input to GCM encryption is called nonce (“number used once”). AES GCM Stream encryption uses the RBG-based (random bit generator) nonce construction as defined in the section 8.2.2 of the NIST SP 800-38D document. For each encrypted block, AES GCM Stream generates a unique nonce with a length of 12 bytes (96 bits).
+
+## Format specification
+
+### File structure
+
+The AES GCM Stream files have the following structure
+
+```
+Magic BlockLength CipherBlock₁ CipherBlock₂ ... CipherBlockₙ
+```
+
+where
+
+- `Magic` is four bytes 0x41, 0x47, 0x53, 0x31 ("AGS1", short for: AES GCM Stream, version 1)
+- `BlockLength` is four bytes (little endian) integer keeping the length of the equal-size split blocks before encryption. The length is specified in bytes.
+- `CipherBlockᵢ` is the i-th enciphered block in the file, with the structure defined below.
+
+### Cipher Block structure
+
+Cipher blocks have the following structure
+
+| nonce | ciphertext | tag |
+|-------|------------|-----|
+
+where
+
+- `nonce` is the AES GCM nonce, with a length of 12 bytes.
+- `ciphertext` is the encrypted block. Its length is identical to the length of the block before encryption ("plaintext"). The length of all plaintext blocks, except the last, is `BlockLength` bytes. The last block has a non-zero length <= `BlockLength`.
+- `tag` is the AES GCM tag, with a length of 16 bytes.
+
+AES GCM Stream encrypts all blocks by the GCM cipher, without padding. The AES GCM cipher must be implemented by a cryptographic provider according to the NIST SP 800-38D specification. In AES GCM Stream, an input to the GCM cipher is an AES encryption key, a nonce, a plaintext and an AAD (described below). The output is a ciphertext with the length equal to that of plaintext, and a 16-byte authentication tag used to verify the ciphertext and AAD integrity.
+
+### Additional Authenticated Data
+
+The AES GCM cipher protects against byte replacement inside a ciphertext block - but, without an AAD, it can't prevent replacement of one ciphertext block with another (encrypted with the same key). AES GCM Stream leverages AADs to protect against swapping ciphertext blocks inside a file or between files. AES GCM Stream can also protect against swapping full files - for example, replacement of a metadata file with an old version. AADs are built to reflects the identity of a file and of the blocks inside the file.
+
+AES GCM Stream constructs a block AAD from two components: an AAD prefix - a string provided by Iceberg for the file (with the file ID), and an AAD suffix - the block sequence number in the file, as an int in a 4-byte little-endian form. The block AAD is a direct concatenation of the prefix and suffix parts.
diff --git a/landing-page/content/common/spec.md b/landing-page/content/common/spec.md
index 96b335f..56abfc6 100644
--- a/landing-page/content/common/spec.md
+++ b/landing-page/content/common/spec.md
@@ -411,12 +411,13 @@
The schema of a manifest file is a struct called `manifest_entry` with the following fields:
-| v1 | v2 | Field id, name | Type | Description |
-| ---------- | ---------- |--------------------------|-----------------------------------------------------------|----------------------------------------------------------------------------------------------|
-| _required_ | _required_ | **`0 status`** | `int` with meaning: `0: EXISTING` `1: ADDED` `2: DELETED` | Used to track additions and deletions. Deletes are informational only and not used in scans. |
-| _required_ | _optional_ | **`1 snapshot_id`** | `long` | Snapshot id where the file was added, or deleted if status is 2. Inherited when null. |
-| | _optional_ | **`3 sequence_number`** | `long` | Data sequence number of the file. Inherited when null. |
-| _required_ | _required_ | **`2 data_file`** | `data_file` `struct` (see below) | File path, partition tuple, metrics, ... |
+| v1 | v2 | Field id, name | Type | Description |
+| ---------- | ---------- |-------------------------------|-----------------------------------------------------------|-------------|
+| _required_ | _required_ | **`0 status`** | `int` with meaning: `0: EXISTING` `1: ADDED` `2: DELETED` | Used to track additions and deletions. Deletes are informational only and not used in scans. |
+| _required_ | _optional_ | **`1 snapshot_id`** | `long` | Snapshot id where the file was added, or deleted if status is 2. Inherited when null. |
+| | _optional_ | **`3 sequence_number`** | `long` | Data sequence number of the file. Inherited when null and status is 1 (added). |
+| | _optional_ | **`4 file_sequence_number`** | `long` | File sequence number indicating when the file was added. Inherited when null and status is 1 (added). |
+| _required_ | _required_ | **`2 data_file`** | `data_file` `struct` (see below) | File path, partition tuple, metrics, ... |
`data_file` is a struct with the following fields:
@@ -463,8 +464,10 @@
When a file is replaced or deleted from the dataset, its manifest entry fields store the snapshot ID in which the file was deleted and status 2 (deleted). The file may be deleted from the file system when the snapshot in which it was deleted is garbage collected, assuming that older snapshots have also been garbage collected [1].
-Iceberg v2 adds a sequence number to the entry and makes the snapshot id optional. Both fields, `sequence_number` and `snapshot_id`, are inherited from manifest metadata when `null`. That is, if the field is `null` for an entry, then the entry must inherit its value from the manifest file's metadata, stored in the manifest list [2].
-The `sequence_number` field represents the data sequence number and must never change after a file is added to the dataset.
+Iceberg v2 adds data and file sequence numbers to the entry and makes the snapshot ID optional. Values for these fields are inherited from manifest metadata when `null`. That is, if the field is `null` for an entry, then the entry must inherit its value from the manifest file's metadata, stored in the manifest list.
+The `sequence_number` field represents the data sequence number and must never change after a file is added to the dataset. The data sequence number represents a relative age of the file content and should be used for planning which delete files apply to a data file.
+The `file_sequence_number` field represents the sequence number of the snapshot that added the file and must also remain unchanged upon assigning at commit. The file sequence number can't be used for pruning delete files as the data within the file may have an older data sequence number.
+The data and file sequence numbers are inherited only if the entry status is 1 (added). If the entry status is 0 (existing) or 2 (deleted), the entry must include both sequence numbers explicitly.
Notes:
@@ -475,10 +478,10 @@
Manifests track the sequence number when a data or delete file was added to the table.
-When adding a new file, its sequence number is set to `null` because the snapshot's sequence number is not assigned until the snapshot is successfully committed. When reading, sequence numbers are inherited by replacing `null` with the manifest's sequence number from the manifest list.
-It is also possible to add a new file that logically belongs to an older sequence number. In that case, the sequence number must be provided explicitly and not inherited.
+When adding a new file, its data and file sequence numbers are set to `null` because the snapshot's sequence number is not assigned until the snapshot is successfully committed. When reading, sequence numbers are inherited by replacing `null` with the manifest's sequence number from the manifest list.
+It is also possible to add a new file with data that logically belongs to an older sequence number. In that case, the data sequence number must be provided explicitly and not inherited. However, the file sequence number must be always assigned when the snapshot is successfully committed.
-When writing an existing file to a new manifest or marking an existing file as deleted, the sequence number must be non-null and set to the original data sequence number of the file that was either inherited or provided at the commit time.
+When writing an existing file to a new manifest or marking an existing file as deleted, the data and file sequence numbers must be non-null and set to the original values that were either inherited or provided at the commit time.
Inheriting sequence numbers through the metadata tree allows writing a new manifest without a known sequence number, so that a manifest can be written once and reused in commit retries. To change a sequence number for a retry, only the manifest list must be rewritten.
@@ -537,7 +540,7 @@
| _required_ | _required_ | **`502 partition_spec_id`** | `int` | ID of a partition spec used to write the manifest; must be listed in table metadata `partition-specs` |
| | _required_ | **`517 content`** | `int` with meaning: `0: data`, `1: deletes` | The type of files tracked by the manifest, either data or delete files; 0 for all v1 manifests |
| | _required_ | **`515 sequence_number`** | `long` | The sequence number when the manifest was added to the table; use 0 when reading v1 manifest lists |
-| | _required_ | **`516 min_sequence_number`** | `long` | The minimum sequence number of all live data or delete files in the manifest; use 0 when reading v1 manifest lists |
+| | _required_ | **`516 min_sequence_number`** | `long` | The minimum data sequence number of all live data or delete files in the manifest; use 0 when reading v1 manifest lists |
| _required_ | _required_ | **`503 added_snapshot_id`** | `long` | ID of the snapshot where the manifest file was added |
| _optional_ | _required_ | **`504 added_files_count`** | `int` | Number of entries in the manifest that have status `ADDED` (1), when `null` this is assumed to be non-zero |
| _optional_ | _required_ | **`505 existing_files_count`** | `int` | Number of entries in the manifest that have status `EXISTING` (0), when `null` this is assumed to be non-zero |
@@ -584,16 +587,16 @@
Delete files that match the query filter must be applied to data files at read time, limited by the scope of the delete file using the following rules.
* A _position_ delete file must be applied to a data file when all of the following are true:
- - The data file's sequence number is _less than or equal to_ the delete file's sequence number
+ - The data file's data sequence number is _less than or equal to_ the delete file's data sequence number
- The data file's partition (both spec and partition values) is equal to the delete file's partition
* An _equality_ delete file must be applied to a data file when all of the following are true:
- - The data file's sequence number is _strictly less than_ the delete's sequence number
+ - The data file's data sequence number is _strictly less than_ the delete's data sequence number
- The data file's partition (both spec and partition values) is equal to the delete file's partition _or_ the delete file's partition spec is unpartitioned
In general, deletes are applied only to data files that are older and in the same partition, except for two special cases:
* Equality delete files stored with an unpartitioned spec are applied as global deletes. Otherwise, delete files do not apply to files in other partitions.
-* Position delete files must be applied to data files from the same commit, when the data and delete file sequence numbers are equal. This allows deleting rows that were added in the same commit.
+* Position delete files must be applied to data files from the same commit, when the data and delete file data sequence numbers are equal. This allows deleting rows that were added in the same commit.
Notes:
@@ -980,8 +983,8 @@
| Primitive type | Hash specification | Test value |
|--------------------|-------------------------------------------|--------------------------------------------|
| **`boolean`** | `false: hashInt(0)`, `true: hashInt(1)` | `true` ￫ `1392991556` |
-| **`float`** | `hashDouble(double(v))` [4] | `1.0F` ￫ `-142385009` |
-| **`double`** | `hashLong(doubleToLongBits(v))` | `1.0D` ￫ `-142385009` |
+| **`float`** | `hashLong(doubleToLongBits(double(v))` [4]| `1.0F` ￫ `-142385009`, `0.0F` ￫ `1669671676`, `-0.0F` ￫ `1669671676` |
+| **`double`** | `hashLong(doubleToLongBits(v))` [4]| `1.0D` ￫ `-142385009`, `0.0D` ￫ `1669671676`, `-0.0D` ￫ `1669671676` |
Notes:
@@ -990,8 +993,7 @@
Hash results are not dependent on decimal scale, which is part of the type, not the data value.
3. UUIDs are encoded using big endian. The test UUID for the example above is: `f79c3e09-677c-4bbd-a479-3f349cb785e7`. This UUID encoded as a byte array is:
`F7 9C 3E 09 67 7C 4B BD A4 79 3F 34 9C B7 85 E7`
-4. Float hash values are the result of hashing the float cast to double to ensure that schema evolution does not change hash values if float types are promoted.
-
+4. `doubleToLongBits` must give the IEEE 754 compliant bit representation of the double value. All `NaN` bit patterns must be canonicalized to `0x7ff8000000000000L`. Negative zero (`-0.0`) must be canonicalized to positive zero (`0.0`). Float hash values are the result of hashing the float cast to double to ensure that schema evolution does not change hash values if float types are promoted.
## Appendix C: JSON serialization
@@ -1196,6 +1198,7 @@
* Manifest list field `min-sequence-number` should not be written
* Manifest list field `content` must be 0 (data) or omitted
* Manifest entry field `sequence_number` should not be written
+* Manifest entry field `file_sequence_number` should not be written
* Data file field `content` must be 0 (data) or omitted
Reading v1 metadata for v2:
@@ -1206,6 +1209,7 @@
* Manifest list field `min-sequence-number` must default to 0
* Manifest list field `content` must default to 0 (data)
* Manifest entry field `sequence_number` must default to 0
+* Manifest entry field `file_sequence_number` must default to 0
* Data file field `content` must default to 0 (data)
Writing v2 metadata:
@@ -1244,6 +1248,7 @@
* Manifest `manifest_entry`:
* `snapshot_id` is now optional to support inheritance
* `sequence_number` was added and is optional, to support inheritance
+ * `file_sequence_number` was added and is optional, to support inheritance
* Manifest `data_file`:
* `content` was added and is required; 0=data, 1=position deletes, 2=equality deletes; default to 0 when reading v1 manifests
* `equality_ids` was added, to be used for equality deletes only
diff --git a/landing-page/content/common/view-spec.md b/landing-page/content/common/view-spec.md
index 1066239..c2ae5c0 100644
--- a/landing-page/content/common/view-spec.md
+++ b/landing-page/content/common/view-spec.md
@@ -32,9 +32,6 @@
## Goals
* A common metadata format for view metadata, similar to how Iceberg supports a common table format for tables.
-* The view metadata format specification
- * Includes storage format as well as APIs to write/read the metadata.
- * Supports versioning of views to track how a view evolved over time.
## Overview
@@ -61,10 +58,10 @@
| Required/Optional | Field Name | Description |
|-------------------|------------|-------------|
| Required | format-version | An integer version number for the view format. Currently, this must be 1. Implementations must throw an exception if the view's version is higher than the supported version. |
-| Required | location | The view's base location. This is used to determine where to store manifest files and view metadata files. |
+| Required | location | The view's base location. This is used to determine where to store view metadata files. |
| Required | current-version-id | Current version of the view. Set to ‘1’ when the view is first created. |
| Optional | properties | A string to string map of view properties. This is used for metadata such as "comment" and for settings that affect view maintenance. This is not intended to be used for arbitrary metadata. |
-| Required | versions | An array of structs describing the last known versions of the view. Controlled by the table property: “version.history.num-entries”. See section [Versions](#versions). |
+| Required | versions | An array of structs describing the known versions of the view. The number of versions to retain is controlled by the table property: “version.history.num-entries”. See section [Versions](#versions). |
| Required | version-log | A list of timestamp and version ID pairs that encodes changes to the current version for the view. Each time the current-version-id is changed, a new entry should be added with the last-updated-ms and the new current-version-id. |
| Optional | schemas | A list of schemas, the same as the ‘schemas’ field from Iceberg table spec. |
| Optional | current-schema-id | ID of the current schema of the view |
@@ -102,7 +99,6 @@
Each representation is stored as an object with only one common field "type".
The rest of the fields are interpreted based on the type.
-There is only one type of representation defined in the spec.
##### Original View Definition in SQL
