<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Crypt4GH Format</title>
<meta name="robots" content="noindex" />
<!-- Custom HTML head -->
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="How to share human genetic data securely">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="icon" href="favicon.svg">
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item expanded "><a href="0_intro.html"><strong aria-hidden="true">1.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="1_installation.html"><strong aria-hidden="true">2.</strong> Installation</a></li><li class="chapter-item expanded "><a href="2_encryption.html"><strong aria-hidden="true">3.</strong> Encryption</a></li><li class="chapter-item expanded "><a href="3_key_format.html"><strong aria-hidden="true">4.</strong> Key Format</a></li><li class="chapter-item expanded "><a href="4_usage_and_examples.html"><strong aria-hidden="true">5.</strong> Usage & Examples</a></li><li class="chapter-item expanded "><a href="5_rust_library.html"><strong aria-hidden="true">6.</strong> Rust Library</a></li></ol> </div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Crypt4GH Format</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1 id="crypt4gh-utility"><a class="header" href="#crypt4gh-utility">Crypt4GH utility</a></h1>
<h2 id="introduction"><a class="header" href="#introduction">Introduction</a></h2>
<p>Bob wants to send a message to Alice, containing sensitive data. Bob uses <a href="https://www.ga4gh.org/news/crypt4gh-a-secure-method-for-sharing-human-genetic-data/">Crypt4GH, the Global Alliance approved secure method for sharing human genetic data</a></p>
<p>crypt4gh, a Rust tool to encrypt, decrypt or re-encrypt files, according to the <a href="http://samtools.github.io/hts-specs/crypt4gh.pdf">GA4GH encryption file format</a>. <a href="https://www.ga4gh.org/news/crypt4gh-a-secure-method-for-sharing-human-genetic-data/"><img src="https://www.ga4gh.org/wp-content/uploads/Crypt4GH_comic.png" alt="How Crypt4GH works" /></a></p>
<h2 id="basic-example"><a class="header" href="#basic-example">Basic example</a></h2>
<p>Alice and Bob generate both a pair of public/private keys.</p>
<pre><code class="language-sh">crypt4gh keygen --sk alice.sec --pk alice.pub
crypt4gh keygen --sk bob.sec --pk bob.pub
</code></pre>
<p>Bob encrypts a file for Alice:</p>
<pre><code class="language-sh">crypt4gh encrypt --sk bob.sec --recipient_pk alice.pub < file > file.c4gh
</code></pre>
<p>Alice decrypts the encrypted file:</p>
<pre><code class="language-sh">crypt4gh decrypt --sk alice.sec < file.c4gh
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><h1 id="installation"><a class="header" href="#installation">Installation</a></h1>
<h2 id="requirements"><a class="header" href="#requirements">Requirements</a></h2>
<p>You need to install Rust in order to compile the source code.</p>
<blockquote>
<p>To build from source on <strong>Windows</strong>, you should first have installed the <a href="https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019">MSVC Build Tools</a>.</p>
</blockquote>
<h3 id="linux-macos-or-another-unix-like-os"><a class="header" href="#linux-macos-or-another-unix-like-os">Linux, MacOS or another Unix-like OS</a></h3>
<p>To download Rustup and install Rust, run the following in your terminal, then follow the on-screen instructions.</p>
<pre><code class="language-sh">curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
</code></pre>
<h3 id="windows"><a class="header" href="#windows">Windows</a></h3>
<p>Download and run the following executable: <a href="https://static.rust-lang.org/rustup/dist/i686-pc-windows-gnu/rustup-init.exe">rustup-init.exe</a></p>
<h3 id="other-ways-to-install-rust"><a class="header" href="#other-ways-to-install-rust">Other ways to install Rust</a></h3>
<p>If you prefer not to use the shell script, you may directly download rustup-init for the platform of your choice <a href="https://forge.rust-lang.org/infra/other-installation-methods.html#other-ways-to-install-rustup">here</a>.</p>
<h2 id="building-from-source-recommended"><a class="header" href="#building-from-source-recommended">Building from source (recommended)</a></h2>
<p>Once installed, you can install <code>crypt4gh</code> executing the following in your terminal:</p>
<pre><code class="language-sh">cargo install crypt4gh
</code></pre>
<h2 id="standalone-binaries"><a class="header" href="#standalone-binaries">Standalone binaries</a></h2>
<p>In the <a href="https://github.com/EGA-archive/crypt4gh-rust/releases/latest">releases page</a>, You can find compiled binaries for:</p>
<ul>
<li><a href="https://github.com/EGA-archive/crypt4gh-rust/releases/latest/download/Linux.zip">Linux (x86_64-unknown-linux-gnu)</a></li>
<li><a href="https://github.com/EGA-archive/crypt4gh-rust/releases/latest/download/macOS.zip">OS X (x86_64-apple-darwin)</a></li>
<li><a href="https://github.com/EGA-archive/crypt4gh-rust/releases/latest/download/Windows.zip">Windows (x86_64-pc-windows-msvc)</a></li>
</ul>
<h2 id="issues"><a class="header" href="#issues">Issues</a></h2>
<p>If you have any issue with the installation please <a href="https://github.com/EGA-archive/crypt4gh-rust/issues/new">create an issue on Github</a>.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="encryption-algorithm---crypt4gh"><a class="header" href="#encryption-algorithm---crypt4gh">Encryption Algorithm - Crypt4GH</a></h1>
<h2 id="encryption-format"><a class="header" href="#encryption-format">Encryption Format</a></h2>
<p>A random session key (of 256 bits) is generated to seed a ChaCha20 engine, with Poly1305 authentication mode. For each segment of at most 64kB of data, a nonce is randomly generated and prepended to the segment. Using the two latters, the original file is segmented and each segment is encrypted.</p>
<p>The header is prepended to the encrypted data.</p>
<p>Informally, the header contains, the word <code>crypt4gh</code>, the format version (currently 1), the number of header packets, and the sequence of header packets.</p>
<p>A header packet is a length followed by its content. The content can be a data encryption packet or an edit list packet.</p>
<p>All packets are encrypted using a Curve25519-based encryption.</p>
<p><img src="https://crypt4gh.readthedocs.io/en/latest/_images/encryption.png" alt="Encryption process" /></p>
<h2 id="features"><a class="header" href="#features">Features</a></h2>
<p>The advantages of the format are, among others:</p>
<ul>
<li>Re-encrypting the file for another user requires only to decrypt the header and encrypt it with the user’s public key.</li>
<li>Header packets can be encrypted for multiple recipients.</li>
<li>Re-arranging the file to chunk a portion requires only to decrypt the header, re-encrypt with an edit list, and select the cipher segments surrounding the portion. The file itself is not decrypted and reencrypted.</li>
</ul>
<div style="break-before: page; page-break-before: always;"></div><h1 id="crypt4gh-key-format"><a class="header" href="#crypt4gh-key-format">Crypt4GH Key Format</a></h1>
<blockquote>
<p>This utility supports OpenSSH key-format (version 6.5 or above) if the key was generated with type ed25519 (i.e. with <code>ssh-keygen -t ed25519 ...</code>). Otherwise, this utility can generate keys in the following format:</p>
</blockquote>
<h2 id="keys"><a class="header" href="#keys">Keys</a></h2>
<p>A key is stored in the following PEM format:</p>
<pre><code class="language-text">-----BEGIN CRYPT4GH <type> KEY-----
BASE64-ENCODED DATA
-----END CRYPT4GH <type> KEY-----
</code></pre>
<p>where <code><type></code> is either PUBLIC or PRIVATE.</p>
<h3 id="public-key-data"><a class="header" href="#public-key-data">Public key data</a></h3>
<p>For a public key, the key data is the byte representation of the plaintext key material.</p>
<h3 id="private-key-data"><a class="header" href="#private-key-data">Private key data</a></h3>
<p>For a private key, we use the following encoding format.</p>
<pre><code class="language-py">byte[] MAGIC_WORD
string kdfname
string (rounds || salt) # included if kdfname is not "none"
string ciphername
string private blob # Key material encrypted or not
string comment # Optional
</code></pre>
<ol>
<li>
<p>The <strong>MAGIC_WORD</strong> is the byte-representation of the ASCII word "c4gh-v1".</p>
<blockquote>
<p>Everything <code>string</code> consists of a length n (encoded as 2 big-endian bytes) and a sequence of n bytes (i.e. the <code>string</code> "hello", is encoded as <code>\x00\x05hello</code>).</p>
</blockquote>
</li>
<li>
<p>The <strong>kdfname</strong> is the name of the Key Derivation Function. We support either <code>"scrypt"</code>, <code>"pbkdf2_hmac_sha256"</code>, <code>"bcrypt"</code>, or <code>"none"</code>. The Rust implementation uses scrypt when available, and defaults to bcrypt for generating keys.</p>
</li>
<li>
<p>The <strong>rounds</strong> is a 4 big-endian bytes representation of the number of iterations used in the KDF.</p>
</li>
<li>
<p>The <strong>ciphername</strong> describes which symmetric algorithm is used to generate the encrypted data, as follows. The only supported cipher is <code>"chacha20_poly1305"</code> (so far), or "none".</p>
<blockquote>
<p>When kdfname is none, so should the ciphername be (and vice-versa), and the (rounds || salt) string is not included. This is used when the key material is not encrypted.</p>
</blockquote>
</li>
<li>
<p>In case the key material is encrypted, the KDF is used to derive a secret from a user-supplied passphrase. A nonce is randomly generated, and used in conjunction with the secret to encrypt the private key, using Chacha20 and authenticated with Poly1305. The nonce is prepended to the <strong>encrypted data</strong>.</p>
</li>
<li>
<p>Finally, an optional <strong>comment</strong> can be used at the end of the encoded format.</p>
</li>
</ol>
<h2 id="examples"><a class="header" href="#examples">Examples</a></h2>
<h3 id="crypt4gh-key-generation"><a class="header" href="#crypt4gh-key-generation">Crypt4GH Key generation</a></h3>
<pre><code class="language-sh">crypt4gh keygen --sk user.sec --pk user.pub
</code></pre>
<h3 id="openssh-key-generation"><a class="header" href="#openssh-key-generation">OpenSSH Key generation</a></h3>
<pre><code class="language-sh">ssh-keygen -t ed25519 -f <output_filepath> -N <passphrase>
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><h1 id="usage--examples"><a class="header" href="#usage--examples">Usage & Examples</a></h1>
<p>The usual <code>--help</code> flag shows you the different options that the tool accepts.</p>
<pre><code class="language-text">$ crypt4gh --help
Utility for the cryptographic GA4GH standard, reading from stdin and outputting to stdout.
USAGE:
crypt4gh [FLAGS] [SUBCOMMAND]
FLAGS:
-h, --help Prints help information
-v, --verbose Sets the level of verbosity
-V, --version Prints version information
SUBCOMMANDS:
decrypt Decrypts the input using your secret key and the (optional) public key of the sender.
encrypt Encrypts the input using your (optional) secret key and the public key of the recipient.
help Prints this message or the help of the given subcommand(s)
keygen Utility to create Crypt4GH-formatted keys.
rearrange Rearranges the input according to the edit list packet.
reencrypt Decrypts the input using your (optional) secret key and then it reencrypts it using the
public key of the recipient.
</code></pre>
<h2 id="keygen"><a class="header" href="#keygen">Keygen</a></h2>
<pre><code class="language-text">$ crypt4gh keygen --help
crypt4gh-keygen
Utility to create Crypt4GH-formatted keys.
USAGE:
crypt4gh keygen [FLAGS] [OPTIONS]
FLAGS:
-f Overwrite the destination files
-h, --help Prints help information
--nocrypt Do not encrypt the private key. Otherwise it is encrypted in the Crypt4GH key
format (See https://crypt4gh.readthedocs.io/en/latest/keys.html)
-V, --version Prints version information
OPTIONS:
-C, --comment <comment> Key's Comment
--pk <keyfile> Curve25519-based Public key [env: C4GH_PUBLIC_KEY] [default:
~/.c4gh/key.pub]
--sk <keyfile> Curve25519-based Private key [env: C4GH_SECRET_KEY] [default:
~/.c4gh/key]
</code></pre>
<p>Generate a Crypt4GH Key for Alice and Bob.</p>
<pre><code class="language-sh">crypt4gh keygen --sk alice.sec --pk alice.pub
</code></pre>
<pre><code class="language-sh">crypt4gh keygen --sk bob.sec --pk bob.pub
</code></pre>
<h2 id="encrypt"><a class="header" href="#encrypt">Encrypt</a></h2>
<pre><code class="language-text">$ crypt4gh encrypt --help
crypt4gh-encrypt
Encrypts the input using your (optional) secret key and the public key of the recipient.
USAGE:
crypt4gh encrypt [OPTIONS] --recipient_pk <path>...
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
--range <start-end> Byte-range either as <start-end> or just <start> (Start
included, End excluded)
--recipient_pk <path>... Recipient's Curve25519-based Public key
--sk <path> Curve25519-based Private key [env: C4GH_SECRET_KEY]
</code></pre>
<p>Alice encrypts a file <code>file.txt</code> for Bob:</p>
<pre><code class="language-sh">crypt4gh encrypt --sk alice.sec --recipient_pk bob.pub < original_file.txt > encrypted_file.c4gh
</code></pre>
<h2 id="decrypt"><a class="header" href="#decrypt">Decrypt</a></h2>
<pre><code class="language-text">$ crypt4gh decrypt --help
crypt4gh-decrypt
Decrypts the input using your secret key and the (optional) public key of the sender.
USAGE:
crypt4gh decrypt [OPTIONS]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
--sender_pk <path> Peer's Curve25519-based Public key to verify provenance (akin to
signature)
--sk <path> Curve25519-based Private key. [env: C4GH_SECRET_KEY]
</code></pre>
<p>Bob decrypts an encrypted file:</p>
<pre><code class="language-sh">crypt4gh decrypt --sk bob.sec < encrypted_file.c4gh > decrypted_file.txt
</code></pre>
<p>If Bob wants to, optionally, verify that the message indeed comes from Alice, he needs to fetch Alice's public key via another trusted channel. He can then decrypt and check the provenance of the file with:</p>
<pre><code class="language-sh">crypt4gh decrypt --sk bob.sec --sender_pk alice.pub < encrypted_file.c4gh > decrypted_file.txt
</code></pre>
<h2 id="reencrypt"><a class="header" href="#reencrypt">Reencrypt</a></h2>
<pre><code class="language-text">$ crypt4gh reencrypt --help
crypt4gh-reencrypt
Decrypts the input using your (optional) secret key and then it reencrypts it using the public key
of the recipient.
USAGE:
crypt4gh reencrypt [FLAGS] [OPTIONS] --recipient_pk <path>...
FLAGS:
-h, --help Prints help information
-t, --trim Keep only header packets that you can decrypt
-V, --version Prints version information
OPTIONS:
--recipient_pk <path>... Recipient's Curve25519-based Public key
--sk <path> Curve25519-based Private key [env: C4GH_SECRET_KEY]
</code></pre>
<p>Bob reencrypts a file for alice and for himself:</p>
<pre><code class="language-sh">crypt4gh reencrypt --sk bob.sec --recipient_pk alice.pub bob.pub < encrypted_file.c4gh > reencrypted_file.c4gh
</code></pre>
<h2 id="rearrange"><a class="header" href="#rearrange">Rearrange</a></h2>
<pre><code class="language-text">$ crypt4gh rearrange --help
crypt4gh-rearrange
Rearranges the input according to the edit list packet.
USAGE:
crypt4gh rearrange [OPTIONS] --range <start-end>
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
--range <start-end> Byte-range either as <start-end> or just <start> (Start included,
End excluded)
--sk <path> Curve25519-based Private key [env: C4GH_SECRET_KEY]
</code></pre>
<p>Bob rearranges an encrypted file with the bytes from 65535 to 131074:</p>
<pre><code class="language-sh">crypt4gh rearrange --sk bob.sec --range 65535-131074 < encrypted_file.c4gh > rearranged_file.c4gh
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><h1 id="rust-library"><a class="header" href="#rust-library">Rust Library</a></h1>
<p>You can check the documentation of the Rust library on <a href="https://docs.rs/crypt4gh/latest/crypt4gh">docs.rs</a>.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
</nav>
</div>
<script type="text/javascript">
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
<script type="text/javascript">
window.addEventListener('load', function() {
window.setTimeout(window.print, 100);
});
</script>
</body>
</html>
