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:

• Project
• Subject
• Session
• Acquisition
• 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.

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
2. Select file as input to gear
3. 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.