# FastGlacier archive metadata format

This document describes the native `ArchiveDescription` values written by FastGlacier to Amazon S3 Glacier vault archives. It is intended for data migration and recovery when the original filename and related information must be reconstructed outside FastGlacier.

The archive ID and archive description are separate values. Keep the archive ID associated with its description until the data has been restored and verified. The description does not contain the archive data or an encryption password.

## Native format v4

FastGlacier 2.6.1 and later write compact XML in this form:

```xml
<m>
  <v>4</v>
  <p>base64-encoded-path</p>
  <lm>utc-last-modified</lm>
  <ce>compressed:encrypted:md5:size</ce>
</m>
```

The actual value is normally serialized on one line. Whitespace in the example is only for readability.

| Element | Meaning |
| --- | --- |
| `m` | Root element. |
| `v` | Metadata format version. The current native value is `4`. |
| `p` | Full FastGlacier path encoded as Base64 of its UTF-8 bytes. |
| `lm` | Original file modification time in UTC, formatted as `yyyyMMddTHHmmssZ`. |
| `ce` | Optional compression/encryption information. FastGlacier omits this element when the payload is neither compressed nor encrypted. |

The optional `ce` value contains four colon-separated fields:

```text
compressed_flag:encrypted_flag:original_md5:original_size
```

- `compressed_flag` is `1` when compression was requested and `0` otherwise.
- `encrypted_flag` is `1` when encryption was requested and `0` otherwise.
- `original_md5` is the 32-character lowercase hexadecimal MD5 hash of the original file bytes.
- `original_size` is the decimal size of the original file in bytes.

Example:

```xml
<m><v>4</v><p>Z2xhY2llci1kZy5wZGY=</p><lm>20120821T170824Z</lm><ce>1:1:4340ebcf79712dc5e3ef7d50bab98ba5:54687</ce></m>
```

The decoded path in this example is `glacier-dg.pdf`.

## Restoring the payload

1. Read the archive's `ArchiveDescription` from the Glacier inventory or another record that preserves it.
2. Parse the XML and Base64-decode `p`, then decode the resulting bytes as UTF-8.
3. Treat the decoded value as an untrusted relative path. Reject rooted paths and `..` traversal before writing any file.
4. If `ce` is absent, the retrieved archive payload is the original file data.
5. If either `ce` flag is `1`, the payload is a ZIP container created by FastGlacier. It contains one entry named with the original file's base name. FastGlacier uses Deflate compression, UTF-8 ZIP entry names, and Zip64 when required.
6. If `encrypted_flag` is `1`, the ZIP entry uses WinZip AES-256 encryption. The original password is required and is not stored in the archive metadata.
7. After extraction, verify the original file against `original_md5` and `original_size` when those values are present.
8. Restore the modification time from `lm` if required.

Do not discard the downloaded archive until the decoded file has passed the available size and checksum checks.

## Legacy native formats

FastGlacier can also read its earlier native formats.

### Version 3

Used from FastGlacier 2.5.1. It is the same compact XML structure, but `ce` has no original-size field:

```xml
<m><v>3</v><p>Z2xhY2llci1kZy5wZGY=</p><lm>20120821T170824Z</lm><ce>1:1:4340ebcf79712dc5e3ef7d50bab98ba5</ce></m>
```

The fields are `compressed_flag:encrypted_flag:original_md5`.

### Version 2

Used from FastGlacier 1.3.9. It stores only the encoded path and modification time:

```xml
<m><v>2</v><p>Z2xhY2llci1kZy5wZGY=</p><lm>20120821T170824Z</lm></m>
```

### Version 1

Used by the earliest FastGlacier releases. There is no explicit version element:

```xml
<ArchiveMetadata>
  <Path>Z2xhY2llci1kZy5wZGY=</Path>
  <LastModified>Wed, 19 Sep 2012 11:11:11 +0000</LastModified>
</ArchiveMetadata>
```

`Path` is Base64-encoded UTF-8. `LastModified` was normally written as an RFC-822-style date and time.

## Compatibility notes

- FastGlacier always writes version 4, but its reader accepts native versions 1 through 4.
- Native metadata starts with XML. FastGlacier also recognizes several third-party archive-description formats and otherwise treats plain text as a path; those formats are outside the scope of this document.
- If the description is empty or cannot provide a usable path, retain the Glacier archive ID as the fallback filename so that the archive remains identifiable.
- A compression or encryption password cannot be reconstructed from the metadata. If it has been lost, Netsdk Software FZE cannot decrypt the payload.

This reference reflects the FastGlacier 4.1.5 metadata reader and writer behavior.