fw-gear-file-esign 0.1.1
file-esign is a gear for e-signing plaintext and pdf files. It uses MFA to authenticate the user and incorporates identity and timestamp into an e-signature of the file.
License: MIT
Requires Python: <4.0,>=3.11
Keywords: Flywheel, Gears

# File Esign (fw-gear-file-esign)

## Overview

### Summary

*This gear enables users to digitally sign files within the Flywheel platform using RSA
encryption and multi-factor authentication (MFA). It supports signing text files, PDFs,
and binary files by embedding signatures appropriately into the file content or
metadata. The gear ensures the integrity and authenticity of files by allowing users to
verify the signatures.*

### Cite

No citation information provided.

### License

**License:** Apache License 2.0

### Classification

**Category:** Security

**Gear Level:**

- [x] Project
- [x] Subject
- [x] Session
- [x] Acquisition
- [x] Analysis

----

[[TOC]]

----

### Inputs

- **input_file**
  - **Name**: input_file
  - **Type**: file
  - **Optional**: No
  - **Classification**: Any
  - **Description**: The file to be signed. It can be a text file, PDF, or binary
    file.
  - **Notes**: Ensure the file is correctly uploaded to the platform and accessible
    by the gear.

### Config

- **mfa_code**
  - **Name**: mfa_code
  - **Type**: string
  - **Optional**: No
  - **Description**: The multi-factor authentication (MFA) code provided by the user
    for verification.
  - **Default**: None

- **signature_purpose**
  - **Name**: signature_purpose
  - **Type**: string
  - **Optional**: No
  - **Description**: The purpose or reason for signing the file.
  - **Default**: "No reason provided"

- **debug**
  - **Name**: debug
  - **Type**: boolean
  - **Description**: Enable Debugging
  - **Default**: false

### Outputs

#### Files

*A list of output files generated by the gear:*

- **Signed File**
  - **Name**: signed_file
  - **Type**: file
  - **Optional**: No
  - **Classification**: Signed file
  - **Description**: The input file signed with the user's digital signature.
  - **Notes**: The signed file will be saved as a new file.

#### Metadata

*The gear may add or modify the following metadata:*

- For PDF files, the signature is embedded into the PDF's metadata, including the user
ID, timestamp, and signature purpose.
- For text files, the signature is embedded within the file content using zero-width
characters.
- For binary files, a signature file is included in the signed ZIP archive.

### Pre-requisites

This section contains any prerequisites.

#### Prerequisite Gear Runs

- No prerequisite gear runs required.

#### Prerequisite Files

- No prerequisite files required.

#### Prerequisite Metadata

- No specific metadata required.

## Usage

### Description

This gear enables users to digitally sign files within the Flywheel platform using RSA
encryption and multi-factor authentication (MFA). The user provides an MFA code for
authentication, and the gear retrieves the user's email address to associate the
signature with the user. The gear supports signing text files, PDFs, and binary files:

- **Text files** are signed by embedding the signature using zero-width characters
directly into the content of the file, including the signature purpose if provided.
- **PDF files** are signed by embedding the signature into the PDF's metadata,
including user ID, timestamp, and signature purpose.
- **Binary files** are signed by creating a signed ZIP archive containing the original
file and a signature file that includes the signature purpose.

The signed files can then be verified to ensure integrity and authenticity. The gear
ensures that only authenticated users can sign files, providing an additional layer of
security.

#### File Specifications

This section contains specifications on any input files that the gear may need.

##### File

*A description of the input file:*

- The input file to be signed. It can be any of the following:
  - Text files (e.g., `.txt`, `.csv`, `.md`).
  - PDF files (e.g., `.pdf`).
  - Binary files (e.g., images, executables).

*The gear will handle the signing process appropriately based on the file type.*

### Workflow

A picture and description of the workflow.

```mermaid
graph LR;
    A[Input File]:::input --> B[Upload];
    B --> C[Parent Container<br>Project, Subject, etc];
    C:::container --> D((File E-sign Gear));
    D:::gear --> E[Signed File]:::container;
    
    classDef container fill:#57d,color:#fff;
    classDef input fill:#7a9,color:#fff;
    classDef gear fill:#659,color:#fff;
```

Description of workflow

1. Upload file to container
1. Select file as input to gear
1. Geat places output in Analysis

### Configuration

> **Note**: The following configuration steps are managed by Flywheel Support.
Contact <support@flywheel.io> to ensure the gear is properly set up.

Flywheel Support will handle the following:

#### Dedicated Engine Setup

- Configure a dedicated static engine for this gear, ensuring all other gears are
blacklisted from running on this engine.

#### Key Pair Generation and Encoding

- Generate a unique public and private key pair using bin/keygen.py. The keys will
be securely stored in the Flywheel Customer Vault.
- Encode the keys using bin/encode_key.py for storage, and document the encoded keys.

#### Secrets Management

- Add the encoded keys to the instance's secrets.yaml file using SOPS encryption.

For more information on gear setup, please coordinate with the SSE team.