Metadata-Version: 2.4
Name: eif-sdk
Version: 0.1.0
Summary: Reference implementation of the Evidence Integrity Framework (EIF) image provenance format
License-Expression: Apache-2.0
Project-URL: Homepage, https://eif-format.org
Project-URL: Specification, https://github.com/eif-format/specification
Project-URL: Source, https://github.com/eif-format/eif-sdk
Project-URL: Issues, https://github.com/eif-format/eif-sdk/issues
Keywords: provenance,authenticity,forensics,image,cryptography,c2pa
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Legal Industry
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: cryptography>=41.0
Requires-Dist: Pillow>=10.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff==0.14.4; extra == "dev"
Dynamic: license-file

# EIF SDK

**Reference implementation of the Evidence Integrity Framework — an open file format that binds a photograph to cryptographic proof of how it was captured.**

[![CI](https://github.com/eif-format/eif-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/eif-format/eif-sdk/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/eif-format/eif-sdk/blob/main/LICENSE)
[![Spec](https://img.shields.io/badge/spec-v1.0-informational)](https://github.com/eif-format/specification)

---

## The problem

A claims adjuster receives a photograph of a damaged bumper. A lender receives a photograph of equipment they are financing. A court receives a photograph of a scene. In each case a decision worth money follows from pixels, and in 2026 pixels can be fabricated by anyone with a phone in under two minutes.

The instinctive response is detection: build a classifier that spots fakes. We tried that first and published the result. Across 150+ images and four physics-based forensic probes, the best classifier we could build reached 74% accuracy under leave-one-out cross-validation. That is not a number you can deny a claim with, and it gets worse every time a generative model improves. Detection is a race against an adversary who is improving faster than the defence.

EIF takes the other route. Rather than asking "is this image fake?", it makes it possible to ask "can this image prove where it came from?" — a question with a cryptographic answer instead of a statistical one.

## What EIF does

An `.eif` file contains five blocks:

| Block | Purpose |
|---|---|
| **Capture Attestation Block** | When, what device, what software, what location, and against what server-issued challenge |
| **Structural Integrity Layer** | A Merkle tree over a grid of image tiles |
| **Cryptographic Seal** | One ECDSA P-256 signature binding the CAB, the tree root, and the image data together |
| **Provenance Chain** | Append-only, hash-linked record of every hand the file passed through |
| **Image Data** | The pixels |

Three properties follow from that structure.

**The proof cannot be stripped.** It is not metadata sitting beside the image; it is the container. Remove it and you no longer have an EIF file — you have an ordinary image with no claim to make.

**Tampering is localised, not just detected.** Because the signature covers a per-tile Merkle tree rather than a single whole-image hash, a verifier can recompute the tree and report exactly which tiles changed. "This file is invalid" is not useful to a claims handler. "Tiles 34, 35, 44 and 45 changed — the region around the left headlight" is.

**Verification works offline.** Four of the five verification levels complete with no network access, no trust service, and no vendor. Evidence has to be checkable in a courtroom, in an adjuster's car, and in ten years' time, none of which guarantee a working connection to somebody's server.

## Install

```bash
pip install eif-sdk
```

From source:

```bash
git clone https://github.com/eif-format/eif-sdk.git
cd eif-sdk
pip install -e ".[dev]"
pytest
```

## Use it in sixty seconds

```bash
eif keygen --out signing-key.pem
eif capture damage.png --key signing-key.pem --challenge "srv-nonce-7f3a"
eif verify damage.eif --key signing-key.pub.pem
```

Then prove the localisation claim to yourself:

```bash
eif tamper-test damage.eif --x 300 --y 200 --width 80 --height 60
```

```
Verification result: NOT VALID
  L1  Format           pass
  L2  Cryptographic    FAIL
      - seal signature does not verify over this CAB, structural integrity layer and image data
      - recomputed tile tree does not match the sealed root
  L3  Temporal         pass
  L4  Provenance       pass
  L5  Device           not evaluated

  Tamper localisation: 4 of 80 tiles altered
      tile    34  (col 4, row 3)  pixels [256,192]-[320,256]
      tile    35  (col 5, row 3)  pixels [320,192]-[384,256]
      tile    44  (col 4, row 4)  pixels [256,256]-[320,320]
      tile    45  (col 5, row 4)  pixels [320,256]-[384,320]
```

## Use it from Python

```python
from eif import CaptureAttestation, Device, EIFFile, KeyPair, Location, imaging

keypair = KeyPair.generate()

attestation = CaptureAttestation(
    device=Device(
        make="Acme", model="Field-1", os="Android 15",
        app_id="com.example.claims", app_version="2.3.0",
    ),
    location=Location(latitude="12.9716", longitude="77.5946", accuracy_m=8),
    challenge="srv-nonce-7f3a",        # issued by your server, seconds before capture
    session_id="claim-2026-0041",
)

sealed = EIFFile.capture(imaging.encode_png("damage.jpg"), attestation, keypair)
sealed.save("damage.eif")
```

Verifying, with the signing key pinned:

```python
report = EIFFile.load("damage.eif").verify(expected_public_key=keypair.public_key)

if not report["valid"]:
    for tile in report["L2_cryptographic"]["altered_tiles"]:
        print(f"altered region: {tile['bounds']}")
```

## The verification protocol

| Level | Question | Network |
|---|---|---|
| **L1 Format** | Is this a well-formed EIF file? | offline |
| **L2 Cryptographic** | Does the seal verify over this CAB, tree and image? If not, which tiles changed? | offline |
| **L3 Temporal** | Are the timestamps internally coherent and plausible? | offline |
| **L4 Provenance** | Is the chain of custody unbroken? | offline |
| **L5 Device** | Is the signing key attested to real hardware? | online |

Verification never raises on an invalid file; it returns a structured report. Each level is reported independently because the levels fail for different reasons and a relying party needs to make different decisions about each.

## The challenge, and the attack it addresses

Provenance systems that only record "a real camera took this photograph" are defeated by an attack that costs nothing: generate a fake image, display it on a screen, photograph the screen with a genuine camera. The capture is real, the signature is honest, and the content is fabricated.

EIF's answer is the `challenge` field. Your server issues a nonce immediately before capture; the capture pipeline binds it into the Capture Attestation Block before signing. An image produced any other way cannot carry a fresh, unused, server-recognised nonce for a session you opened. This does not make recapture impossible — nothing in software does — but it moves the attack from "free and instant" to "requires real-time control of a device inside your session," which is a different economic proposition for a fraudster.

Captures with no challenge are permitted and are honestly weaker. Treat them as a lower assurance tier.

## Where this fits alongside C2PA and JPEG Trust

EIF is not a competitor to [C2PA Content Credentials](https://c2pa.org) or [JPEG Trust (ISO/IEC 21617)](https://jpeg.org/jpegtrust/), and positioning it as one would be dishonest. Those efforts have the ecosystem — camera manufacturers, platforms, an ISO process — and they solve the problem they set out to solve: recording and travelling with a content history across a general-purpose media supply chain.

EIF addresses a narrower case those systems do not target: **high-assurance evidence capture**, where the relying party controls the capture pipeline, the stakes justify a stricter model, and two specific requirements apply that general provenance does not meet — knowing *where* in the frame an image changed, and binding a capture to a session the relying party opened.

An EIF file can carry a C2PA manifest as an annotation, and an EIF verifier can treat a valid Content Credential as one input among several. Interoperability notes are in the [specification repository](https://github.com/eif-format/specification/blob/main/spec/Interop.md).

## Honest limitations

Read these before you build anything on this.

- **v1.0 handles losslessly-decodable images only (PNG).** JPEG decoding is not bit-exact across libraries, so tile hashes computed at capture would not reliably recompute on a verifier's machine. Rather than ship a structural integrity layer that produces false tamper reports, lossy profiles are deferred. This is the largest practical limitation and the first thing v1.1 must address.
- **A signature proves who signed, not that the content is true.** EIF can tell you an image was sealed by a specific key at a specific time and has not changed since. It cannot tell you the adjuster photographed the right car.
- **Software keys are only as good as the device.** The security of the whole scheme rests on the private key. This SDK generates software keys, which are appropriate for development. Production capture should sign inside a TEE, Secure Enclave, or StrongBox-backed keystore, and L5 exists to let a verifier check that.
- **The provenance chain records what was recorded.** It detects alteration of the sequence. It cannot detect a handler who simply never appended an entry.
- **No mobile SDK yet.** Android and iOS are the platforms this format actually needs. They are not built.
- **The specification is v1.0 and has not been through independent security review.** If you find a flaw, please tell us — see [SECURITY.md](https://github.com/eif-format/eif-sdk/blob/main/SECURITY.md).

## Repositories

| Repository | Contents |
|---|---|
| [`specification`](https://github.com/eif-format/specification) | The format specification, JSON schemas, and shared test vectors |
| [`eif-sdk`](https://github.com/eif-format/eif-sdk) | This reference implementation |
| [`research`](https://github.com/eif-format/research) | Papers, datasets and methodology |

## Contributing

Independent implementations in other languages are the single most valuable contribution. A format with one implementation is a product; a format with several is a standard. See [CONTRIBUTING.md](https://github.com/eif-format/eif-sdk/blob/main/CONTRIBUTING.md).

## Licence

Apache License 2.0. See [LICENSE](https://github.com/eif-format/eif-sdk/blob/main/LICENSE) and [NOTICE](https://github.com/eif-format/eif-sdk/blob/main/NOTICE).

The Apache 2.0 licence includes an express patent grant covering this implementation. Patent applications relating to the format have been filed in India; the licence grant applies to the contributed code as described in Section 3 of the licence.
