From 581cff8473fa1f99043a16f7f52e5afdf0ca6146 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Fri, 15 Oct 2021 13:09:48 +0000 Subject: [PATCH] doc: regenerate groff and html man pages --- doc/age-keygen.1 | 88 ++++++++++++ doc/age-keygen.1.html | 141 ++++++++++++++++++ doc/age.1 | 296 ++++++++++++++++++++++++++++++++++++++ doc/age.1.html | 328 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 853 insertions(+) create mode 100644 doc/age-keygen.1 create mode 100644 doc/age-keygen.1.html create mode 100644 doc/age.1 create mode 100644 doc/age.1.html diff --git a/doc/age-keygen.1 b/doc/age-keygen.1 new file mode 100644 index 0000000..4f1d66e --- /dev/null +++ b/doc/age-keygen.1 @@ -0,0 +1,88 @@ +.\" generated with Ronn/v0.7.3 +.\" http://github.com/rtomayko/ronn/tree/0.7.3 +. +.TH "AGE\-KEYGEN" "1" "October 2021" "" "" +. +.SH "NAME" +\fBage\-keygen\fR \- generate age(1) key pairs +. +.SH "SYNOPSIS" +\fBage\-keygen\fR [\fB\-o\fR \fIOUTPUT\fR] +. +.br +\fBage\-keygen\fR \fB\-y\fR [\fB\-o\fR \fIOUTPUT\fR] [\fIINPUT\fR] +. +.br +. +.SH "DESCRIPTION" +\fBage\-keygen\fR generates a new native age(1) key pair, and outputs the identity to standard output or to the \fIOUTPUT\fR file\. The output includes the public key and the current time as comments\. +. +.P +If the output is not going to a terminal, \fBage\-keygen\fR prints the public key to standard error\. +. +.SH "OPTIONS" +. +.TP +\fB\-o\fR, \fB\-\-output\fR=\fIOUTPUT\fR +Write the identity to \fIOUTPUT\fR instead of standard output\. +. +.IP +If \fIOUTPUT\fR already exists, it is not overwritten\. +. +.TP +\fB\-y\fR +Read an identity file from \fIINPUT\fR or from standard input and output the corresponding recipient(s), one per line, with no comments\. +. +.TP +\fB\-\-version\fR +Print the version and exit\. +. +.SH "EXAMPLES" +Generate a new identity: +. +.IP "" 4 +. +.nf + +$ age\-keygen +# created: 2021\-01\-02T15:30:45+01:00 +# public key: age1lvyvwawkr0mcnnnncaghunadrqkmuf9e6507x9y920xxpp866cnql7dp2z +AGE\-SECRET\-KEY\-1N9JEPW6DWJ0ZQUDX63F5A03GX8QUW7PXDE39N8UYF82VZ9PC8UFS3M7XA9 +. +.fi +. +.IP "" 0 +. +.P +Write a new identity to \fBkey\.txt\fR: +. +.IP "" 4 +. +.nf + +$ age\-keygen \-o key\.txt +Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p +. +.fi +. +.IP "" 0 +. +.P +Convert an identity to a recipient: +. +.IP "" 4 +. +.nf + +$ age\-keygen \-y key\.txt +age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p +. +.fi +. +.IP "" 0 +. +.SH "SEE ALSO" +age(1) +. +.SH "AUTHORS" +Filippo Valsorda \fIage@filippo\.io\fR diff --git a/doc/age-keygen.1.html b/doc/age-keygen.1.html new file mode 100644 index 0000000..73e77ec --- /dev/null +++ b/doc/age-keygen.1.html @@ -0,0 +1,141 @@ + + + + + + age-keygen(1) - generate age(1) key pairs + + + + +
+ + + +
    +
  1. age-keygen(1)
    2. +
  2. +
  3. age-keygen(1)
    4. +
+ +

NAME

+

+ age-keygen - generate age(1) key pairs +

+ +

SYNOPSIS

+ +

age-keygen [-o OUTPUT]
+age-keygen -y [-o OUTPUT] [INPUT]

+ +

DESCRIPTION

+ +

age-keygen generates a new native age(1) key pair, and outputs the identity to +standard output or to the OUTPUT file. The output includes the public key and +the current time as comments.

+ +

If the output is not going to a terminal, age-keygen prints the public key to +standard error.

+ +

OPTIONS

+ +
+
-o, --output=OUTPUT

Write the identity to OUTPUT instead of standard output.

+ +

If OUTPUT already exists, it is not overwritten.

+
-y

Read an identity file from INPUT or from standard input and output the + corresponding recipient(s), one per line, with no comments.

+
--version

Print the version and exit.

+
+ + +

EXAMPLES

+ +

Generate a new identity:

+ +
$ age-keygen
+# created: 2021-01-02T15:30:45+01:00
+# public key: age1lvyvwawkr0mcnnnncaghunadrqkmuf9e6507x9y920xxpp866cnql7dp2z
+AGE-SECRET-KEY-1N9JEPW6DWJ0ZQUDX63F5A03GX8QUW7PXDE39N8UYF82VZ9PC8UFS3M7XA9
+
+ +

Write a new identity to key.txt:

+ +
$ age-keygen -o key.txt
+Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+
+ +

Convert an identity to a recipient:

+ +
$ age-keygen -y key.txt
+age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+
+ +

SEE ALSO

+ +

age(1)

+ +

AUTHORS

+ +

Filippo Valsorda age@filippo.io

+ + +
    +
  1. +
  2. October 2021
    3. +
  3. age-keygen(1)
    4. +
+ +
+ + diff --git a/doc/age.1 b/doc/age.1 new file mode 100644 index 0000000..a321ff9 --- /dev/null +++ b/doc/age.1 @@ -0,0 +1,296 @@ +.\" generated with Ronn/v0.7.3 +.\" http://github.com/rtomayko/ronn/tree/0.7.3 +. +.TH "AGE" "1" "October 2021" "" "" +. +.SH "NAME" +\fBage\fR \- simple, modern, and secure file encryption +. +.SH "SYNOPSIS" +\fBage\fR [\fB\-\-encrypt\fR] (\fB\-r\fR \fIRECIPIENT\fR | \fB\-R\fR \fIPATH\fR)\.\.\. [\fB\-\-armor\fR] [\fB\-o\fR \fIOUTPUT\fR] [\fIINPUT\fR] +. +.br +\fBage\fR [\fB\-\-encrypt\fR] \fB\-\-passphrase\fR [\fB\-\-armor\fR] [\fB\-o\fR \fIOUTPUT\fR] [\fIINPUT\fR] +. +.br +\fBage\fR \fB\-\-decrypt\fR [\fB\-i\fR \fIPATH\fR]\.\.\. [\fB\-o\fR \fIOUTPUT\fR] [\fIINPUT\fR] +. +.br +. +.SH "DESCRIPTION" +\fBage\fR encrypts or decrypts \fIINPUT\fR to \fIOUTPUT\fR\. The \fIINPUT\fR argument is optional and defaults to standard input\. Only a single \fIINPUT\fR file may be specified\. If \fB\-o\fR is not specified, \fIOUTPUT\fR defaults to standard output\. +. +.P +If \fB\-\-passphrase\fR is specified, the file is encrypted with a passphrase requested interactively\. Otherwise, it\'s encrypted to one or more \fIRECIPIENTS\fR specified with \fB\-r\fR/\fB\-\-recipient\fR or \fB\-R\fR/\fB\-\-recipients\-file\fR\. Every recipient can decrypt the file\. +. +.P +In \fB\-\-decrypt\fR mode, passphrase\-encrypted files are detected automatically and the passphrase is requested interactively\. Otherwise, one or more \fIIDENTITIES\fR specified with \fB\-i\fR/\fB\-\-identity\fR are used to decrypt the file\. +. +.P +\fBage\fR encrypted files are binary and not malleable, with around 200 bytes of overhead per recipient, plus 16 bytes every 64KiB of plaintext\. +. +.SH "OPTIONS" +. +.TP +\fB\-o\fR, \fB\-\-output\fR=\fIOUTPUT\fR +Write encrypted or decrypted file to \fIOUTPUT\fR instead of standard output\. If \fIOUTPUT\fR already exists it will be overwritten\. +. +.IP +If encrypting without \fB\-\-armor\fR, \fBage\fR will refuse to output binary to a TTY\. This can be forced by specifying \fB\-\fR as \fIOUTPUT\fR\. +. +.TP +\fB\-\-version\fR +Print the version and exit\. +. +.SS "Encryption options" +. +.TP +\fB\-e\fR, \fB\-\-encrypt\fR +Encrypt \fIINPUT\fR to \fIOUTPUT\fR\. This is the default\. +. +.TP +\fB\-r\fR, \fB\-\-recipient\fR=\fIRECIPIENT\fR +Encrypt to the explicitly specified \fIRECIPIENT\fR\. See the \fIRECIPIENTS AND IDENTITIES\fR section for possible recipient formats\. +. +.IP +This option can be repeated and combined with \fB\-R\fR/\fB\-\-recipients\-file\fR, and the file can be decrypted by all provided recipients independently\. +. +.TP +\fB\-R\fR, \fB\-\-recipients\-file\fR=\fIPATH\fR +Encrypt to the \fIRECIPIENTS\fR listed in the file at \fIPATH\fR, one per line\. Empty lines and lines starting with \fB#\fR are ignored as comments\. +. +.IP +If \fIPATH\fR is \fB\-\fR, the recipients are read from standard input\. In this case, the \fIINPUT\fR argument must be specified\. +. +.IP +This option can be repeated and combined with \fB\-r\fR/\fB\-\-recipient\fR, and the file can be decrypted by all provided recipients independently\. +. +.TP +\fB\-p\fR, \fB\-\-passphrase\fR +Encrypt with a passphrase, requested interactively from the terminal\. \fBage\fR will offer to auto\-generate a secure passphrase\. +. +.IP +This option can\'t be used with \fB\-r\fR/\fB\-\-recipient\fR or \fB\-R\fR/\fB\-\-recipients\-file\fR\. +. +.TP +\fB\-a\fR, \fB\-\-armor\fR +Encrypt to an ASCII\-only "armored" encoding\. +. +.IP +\fBage\fR armor is a strict version of PEM with type \fBAGE ENCRYPTED FILE\fR, canonical "strict" Base64, no headers, and no support for leading and trailing extra data\. +. +.IP +Decryption transparently detects and decodes ASCII armoring\. +. +.SS "Decryption options" +. +.TP +\fB\-d\fR, \fB\-\-decrypt\fR +Decrypt \fIINPUT\fR to \fIOUTPUT\fR\. +. +.IP +If \fIINPUT\fR is passphrase encrypted, it will be automatically detected and the passphrase will be requested interactively\. Otherwise, the \fIIDENTITIES\fR specified with \fB\-i\fR/\fB\-\-identity\fR are used\. +. +.IP +ASCII armoring is transparently detected and decoded\. +. +.TP +\fB\-i\fR, \fB\-\-identity\fR=\fIPATH\fR +Decrypt using the \fIIDENTITIES\fR at \fIPATH\fR\. +. +.IP +\fIPATH\fR may be one of the following: +. +.IP +a\. A file listing \fIIDENTITIES\fR one per line\. Empty lines and lines starting with "\fB#\fR" are ignored as comments\. +. +.IP +b\. An SSH private key file, in PKCS#1, PKCS#8, or OpenSSH format\. If the private key is password\-protected, the password is requested interactively only if the SSH identity matches the file\. See the \fISSH keys\fR section for more information, including supported key types\. +. +.IP +c\. "\fB\-\fR", causing one of the options above to be read from standard input\. In this case, the \fIINPUT\fR argument must be specified\. +. +.IP +This option can be repeated\. Identities are tried in the order in which are provided, and the first one matching one of the file\'s recipients is used\. Unused identities are ignored\. +. +.IP +If \fB\-e\fR/\fB\-\-encrypt\fR is explicitly specified (to avoid confusion), \fB\-i\fR/\fB\-\-identity\fR may also be used to encrypt to the \fBRECIPIENTS\fR corresponding to the \fBIDENTITIES\fR listed at \fIPATH\fR\. This allows using an identity file as a symmetric key, if desired\. +. +.SH "RECIPIENTS AND IDENTITIES" +\fBRECIPIENTS\fR are public values, like a public key, that a file can be encrypted to\. \fBIDENTITIES\fR are private values, like a private key, that allow decrypting a file encrypted to the corresponding \fBRECIPIENT\fR\. +. +.SS "Native X25519 keys" +Native \fBage\fR key pairs are generated with age\-keygen(1), and provide small encodings and strong encryption based on X25519\. They are the recommended recipient type for most applications\. +. +.P +A \fBRECIPIENT\fR encoding begins with \fBage1\fR and looks like the following: +. +.IP "" 4 +. +.nf + +age1gde3ncmahlqd9gg50tanl99r960llztrhfapnmx853s4tjum03uqfssgdh +. +.fi +. +.IP "" 0 +. +.P +An \fBIDENTITY\fR encoding begins with \fBAGE\-SECRET\-KEY\-1\fR and looks like the following: +. +.IP "" 4 +. +.nf + +AGE\-SECRET\-KEY\-1KTYK6RVLN5TAPE7VF6FQQSKZ9HWWCDSKUGXXNUQDWZ7XXT5YK5LSF3UTKQ +. +.fi +. +.IP "" 0 +. +.P +An encrypted file can\'t be linked to the native recipient it\'s encrypted to without access to the corresponding identity\. +. +.SS "SSH keys" +As a convenience feature, \fBage\fR also supports encrypting to RSA or Ed25519 ssh(1) keys\. RSA keys must be at least 2048 bits\. This feature employs more complex cryptography, and should only be used when a native key is not available for the recipient\. Note that SSH keys might not be protected long\-term by the recipient, since they are revokable when used only for authentication\. +. +.P +A \fBRECIPIENT\fR encoding is an SSH public key in \fBauthorized_keys\fR format (see the \fBAUTHORIZED_KEYS FILE FORMAT\fR section of sshd(8)), starting with \fBssh\-rsa\fR or \fBssh\-ed25519\fR, like the following: +. +.IP "" 4 +. +.nf + +ssh\-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDULTit0KUehbi[\.\.\.]GU4BtElAbzh8= +ssh\-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH9pO5pz22JZEas[\.\.\.]l1uZc31FGYMXa +. +.fi +. +.IP "" 0 +. +.P +The comment at the end of the line, if present, is ignored\. +. +.P +In recipient files passed to \fB\-R\fR/\fB\-\-recipients\-file\fR, unsupported but valid SSH public keys are ignored with a warning, to facilitate using \fBauthorized_keys\fR or GitHub \fB\.keys\fR files\. (See \fIEXAMPLES\fR\.) +. +.P +An \fBIDENTITY\fR is an SSH private key \fIfile\fR passed individually to \fB\-i\fR/\fB\-\-identity\fR\. Note that keys held on hardware tokens such as YubiKeys or accessed via ssh\-agent(1) are not supported\. +. +.P +An encrypted file \fIcan\fR be linked to the SSH public key it was encrypted to\. This is so that \fBage\fR can identify the correct SSH private key before requesting its password, if any\. +. +.SH "EXIT STATUS" +\fBage\fR will exit 0 if and only if encryption or decryption are successful for the full length of the input\. +. +.P +If an error occurs during decryption, partial output might still be generated, but only if it was possible to securely authenticate it\. No unauthenticathed output is ever released\. +. +.SH "BACKWARDS COMPATIBILITY" +Files encrypted with a stable version (not alpha, beta, or release candidate) of \fBage\fR, or with any v1\.0\.0 beta or release candidate, will decrypt with any later version of the tool\. +. +.P +If decrypting older files poses a security risk, doing so might cause an error by default\. In this case, a flag will be provided to force the operation\. +. +.SH "EXAMPLES" +Generate a new identity, encrypt data, and decrypt: +. +.IP "" 4 +. +.nf + +$ age\-keygen \-o key\.txt +Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p + +$ tar cvz ~/data | age \-r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data\.tar\.gz\.age + +$ age \-d \-o data\.tar\.gz \-i key\.txt data\.tar\.gz\.age +. +.fi +. +.IP "" 0 +. +.P +Encrypt \fBexample\.jpg\fR to multiple recipients and output to \fBexample\.jpg\.age\fR: +. +.IP "" 4 +. +.nf + +$ age \-o example\.jpg\.age \-r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p \e + \-r age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg example\.jpg +. +.fi +. +.IP "" 0 +. +.P +Encrypt to a list of recipients: +. +.IP "" 4 +. +.nf + +$ cat > recipients\.txt +# Alice +age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p +# Bob +age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg + +$ age \-R recipients\.txt example\.jpg > example\.jpg\.age +. +.fi +. +.IP "" 0 +. +.P +Encrypt and decrypt a file using a passphrase: +. +.IP "" 4 +. +.nf + +$ age \-p secrets\.txt > secrets\.txt\.age +Enter passphrase (leave empty to autogenerate a secure one): +Using the autogenerated passphrase "release\-response\-step\-brand\-wrap\-ankle\-pair\-unusual\-sword\-train"\. + +$ age \-d secrets\.txt\.age > secrets\.txt +Enter passphrase: +. +.fi +. +.IP "" 0 +. +.P +Encrypt and decrypt with an SSH public key: +. +.IP "" 4 +. +.nf + +$ age \-R ~/\.ssh/id_ed25519\.pub example\.jpg > example\.jpg\.age + +$ age \-d \-i ~/\.ssh/id_ed25519 example\.jpg\.age > example\.jpg +. +.fi +. +.IP "" 0 +. +.P +Encrypt to the SSH keys of a GitHub user: +. +.IP "" 4 +. +.nf + +$ curl https://github\.com/benjojo\.keys | age \-R \- example\.jpg > example\.jpg\.age +. +.fi +. +.IP "" 0 +. +.SH "SEE ALSO" +age\-keygen(1) +. +.SH "AUTHORS" +Filippo Valsorda \fIage@filippo\.io\fR diff --git a/doc/age.1.html b/doc/age.1.html new file mode 100644 index 0000000..6d44912 --- /dev/null +++ b/doc/age.1.html @@ -0,0 +1,328 @@ + + + + + + age(1) - simple, modern, and secure file encryption + + + + +
+ + + +
    +
  1. age(1)
    2. +
  2. +
  3. age(1)
    4. +
+ +

NAME

+

+ age - simple, modern, and secure file encryption +

+ +

SYNOPSIS

+ +

age [--encrypt] (-r RECIPIENT | -R PATH)... [--armor] [-o OUTPUT] [INPUT]
+age [--encrypt] --passphrase [--armor] [-o OUTPUT] [INPUT]
+age --decrypt [-i PATH]... [-o OUTPUT] [INPUT]

+ +

DESCRIPTION

+ +

age encrypts or decrypts INPUT to OUTPUT. The INPUT argument is +optional and defaults to standard input. Only a single INPUT file may be +specified. If -o is not specified, OUTPUT defaults to standard output.

+ +

If --passphrase is specified, the file is encrypted with a passphrase +requested interactively. Otherwise, it's encrypted to one or more +RECIPIENTS specified with -r/--recipient or +-R/--recipients-file. Every recipient can decrypt the file.

+ +

In --decrypt mode, passphrase-encrypted files are detected automatically and +the passphrase is requested interactively. Otherwise, one or more +IDENTITIES specified with -i/--identity are +used to decrypt the file.

+ +

age encrypted files are binary and not malleable, with around 200 bytes of +overhead per recipient, plus 16 bytes every 64KiB of plaintext.

+ +

OPTIONS

+ +
+
-o, --output=OUTPUT

Write encrypted or decrypted file to OUTPUT instead of standard output. + If OUTPUT already exists it will be overwritten.

+ +

If encrypting without --armor, age will refuse to output binary to a + TTY. This can be forced by specifying - as OUTPUT.

+
--version

Print the version and exit.

+
+ + +

Encryption options

+ +
+
-e, --encrypt

Encrypt INPUT to OUTPUT. This is the default.

+
-r, --recipient=RECIPIENT

Encrypt to the explicitly specified RECIPIENT. See the + RECIPIENTS AND IDENTITIES section for possible recipient formats.

+ +

This option can be repeated and combined with -R/--recipients-file, + and the file can be decrypted by all provided recipients independently.

+
-R, --recipients-file=PATH

Encrypt to the RECIPIENTS listed in the + file at PATH, one per line. Empty lines and lines starting with # + are ignored as comments.

+ +

If PATH is -, the recipients are read from standard input. In + this case, the INPUT argument must be specified.

+ +

This option can be repeated and combined with -r/--recipient, + and the file can be decrypted by all provided recipients independently.

+
-p, --passphrase

Encrypt with a passphrase, requested interactively from the terminal. + age will offer to auto-generate a secure passphrase.

+ +

This option can't be used with -r/--recipient or + -R/--recipients-file.

+
-a, --armor

Encrypt to an ASCII-only "armored" encoding.

+ +

age armor is a strict version of PEM with type AGE ENCRYPTED FILE, + canonical "strict" Base64, no headers, and no support for leading and + trailing extra data.

+ +

Decryption transparently detects and decodes ASCII armoring.

+
+ + +

Decryption options

+ +
+
-d, --decrypt

Decrypt INPUT to OUTPUT.

+ +

If INPUT is passphrase encrypted, it will be automatically detected + and the passphrase will be requested interactively. Otherwise, the + IDENTITIES specified with -i/--identity + are used.

+ +

ASCII armoring is transparently detected and decoded.

+
-i, --identity=PATH

Decrypt using the IDENTITIES at PATH.

+ +

PATH may be one of the following:

+ +

a. A file listing IDENTITIES one per line. + Empty lines and lines starting with "#" are ignored as comments.

+ +

b. An SSH private key file, in PKCS#1, PKCS#8, or OpenSSH format. + If the private key is password-protected, the password is requested + interactively only if the SSH identity matches the file. See the + SSH keys section for more information, including supported key types.

+ +

c. "-", causing one of the options above to be read from standard input. + In this case, the INPUT argument must be specified.

+ +

This option can be repeated. Identities are tried in the order in which + are provided, and the first one matching one of the file's recipients is + used. Unused identities are ignored.

+ +

If -e/--encrypt is explicitly specified (to avoid confusion), + -i/--identity may also be used to encrypt to the RECIPIENTS + corresponding to the IDENTITIES listed at PATH. This allows using an + identity file as a symmetric key, if desired.

+
+ + +

RECIPIENTS AND IDENTITIES

+ +

RECIPIENTS are public values, like a public key, that a file can be encrypted +to. IDENTITIES are private values, like a private key, that allow decrypting +a file encrypted to the corresponding RECIPIENT.

+ +

Native X25519 keys

+ +

Native age key pairs are generated with age-keygen(1), and provide small +encodings and strong encryption based on X25519. They are the recommended +recipient type for most applications.

+ +

A RECIPIENT encoding begins with age1 and looks like the following:

+ +
age1gde3ncmahlqd9gg50tanl99r960llztrhfapnmx853s4tjum03uqfssgdh
+
+ +

An IDENTITY encoding begins with AGE-SECRET-KEY-1 and looks like the +following:

+ +
AGE-SECRET-KEY-1KTYK6RVLN5TAPE7VF6FQQSKZ9HWWCDSKUGXXNUQDWZ7XXT5YK5LSF3UTKQ
+
+ +

An encrypted file can't be linked to the native recipient it's encrypted to +without access to the corresponding identity.

+ +

SSH keys

+ +

As a convenience feature, age also supports encrypting to RSA or Ed25519 +ssh(1) keys. RSA keys must be at least 2048 bits. This feature employs more +complex cryptography, and should only be used when a native key is not available +for the recipient. Note that SSH keys might not be protected long-term by the +recipient, since they are revokable when used only for authentication.

+ +

A RECIPIENT encoding is an SSH public key in authorized_keys format +(see the AUTHORIZED_KEYS FILE FORMAT section of sshd(8)), starting with +ssh-rsa or ssh-ed25519, like the following:

+ +
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDULTit0KUehbi[...]GU4BtElAbzh8=
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH9pO5pz22JZEas[...]l1uZc31FGYMXa
+
+ +

The comment at the end of the line, if present, is ignored.

+ +

In recipient files passed to -R/--recipients-file, unsupported but valid +SSH public keys are ignored with a warning, to facilitate using +authorized_keys or GitHub .keys files. (See EXAMPLES.)

+ +

An IDENTITY is an SSH private key file passed individually to +-i/--identity. Note that keys held on hardware tokens such as YubiKeys +or accessed via ssh-agent(1) are not supported.

+ +

An encrypted file can be linked to the SSH public key it was encrypted to. +This is so that age can identify the correct SSH private key before +requesting its password, if any.

+ +

EXIT STATUS

+ +

age will exit 0 if and only if encryption or decryption are successful for the +full length of the input.

+ +

If an error occurs during decryption, partial output might still be generated, +but only if it was possible to securely authenticate it. No unauthenticathed +output is ever released.

+ +

BACKWARDS COMPATIBILITY

+ +

Files encrypted with a stable version (not alpha, beta, or release candidate) of +age, or with any v1.0.0 beta or release candidate, will decrypt with any later +version of the tool.

+ +

If decrypting older files poses a security risk, doing so might cause an error +by default. In this case, a flag will be provided to force the operation.

+ +

EXAMPLES

+ +

Generate a new identity, encrypt data, and decrypt:

+ +
$ age-keygen -o key.txt
+Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+
+$ tar cvz ~/data | age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data.tar.gz.age
+
+$ age -d -o data.tar.gz -i key.txt data.tar.gz.age
+
+ +

Encrypt example.jpg to multiple recipients and output to example.jpg.age:

+ +
$ age -o example.jpg.age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p \
+    -r age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg example.jpg
+
+ +

Encrypt to a list of recipients:

+ +
$ cat > recipients.txt
+# Alice
+age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+# Bob
+age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg
+
+$ age -R recipients.txt example.jpg > example.jpg.age
+
+ +

Encrypt and decrypt a file using a passphrase:

+ +
$ age -p secrets.txt > secrets.txt.age
+Enter passphrase (leave empty to autogenerate a secure one):
+Using the autogenerated passphrase "release-response-step-brand-wrap-ankle-pair-unusual-sword-train".
+
+$ age -d secrets.txt.age > secrets.txt
+Enter passphrase:
+
+ +

Encrypt and decrypt with an SSH public key:

+ +
$ age -R ~/.ssh/id_ed25519.pub example.jpg > example.jpg.age
+
+$ age -d -i ~/.ssh/id_ed25519 example.jpg.age > example.jpg
+
+ +

Encrypt to the SSH keys of a GitHub user:

+ +
$ curl https://github.com/benjojo.keys | age -R - example.jpg > example.jpg.age
+
+ +

SEE ALSO

+ +

age-keygen(1)

+ +

AUTHORS

+ +

Filippo Valsorda age@filippo.io

+ + +
    +
  1. +
  2. October 2021
    3. +
  3. age(1)
    4. +
+ +
+ +