JASS(1)			NetBSD General Commands Manual		       JASS(1)

NAME
     jass -- just another secret sharer

SYNOPSIS
     jass [-Vdehlv] [-f file] [-g group] [-k key] [-p passin] [-u user]

DESCRIPTION
     The jass tool allows you to share a secret with other people through the
     use of SSH keypairs.  It accepts input on stdin and generates ciphertext
     on stdout, encrypted for the given key or user.

OPTIONS
     The following options are supported by jass:

     -V		 Print version number and exit.

     -e		 Perform encryption.  This is the default.

     -d		 Perform decryption.

     -f file	 Encrypt/decrypt this file.  If not specified, jass will read
		 data from stdin.

     -g group	 Encrypt for all members of this group.

     -h		 Print a short help message and exit.

     -k key	 Encrypt or decrypt the input using the key(s) found in key.

     -l		 List recipients of the encrypted input.

     -p passin	 Specify the method to retrieve the passphrase for the private
		 key.  See PASS PHRASE ARGUMENTS for details.  Defaults to
		 interactively prompt on the controlling tty.

     -u user	 Encrypt the input for this user, attempting to find suitable
		 public SSH keys on the local system or from LDAP or the
		 enabled URLs.

     -v		 Be verbose.  Can be specified multiple times.

DETAILS
     It is not uncommon for people within a given organization to have a need
     to share secrets with one another.	 jass lets you do this through the use
     of SSH RSA keys, as those are frequently already well distributed and
     trusted.

     Since asymmetric encryption is only suitable for inputs smaller than the
     keysize, jass will extract the public RSA key from an SSH formatted key,
     generate a 256 bit session key, and then encrypt the session key using
     the public RSA key.  The data itself is encrypted using AES-256-CBC mode
     with said session key.

     As an alternative to providing a public key, a recipient may also be
     specified via the -g and -u flags.	 If -g was specified, jass will expand
     the given group to individual users.  This expansion will include local
     and LDAP groups (if LDAP is enabled) as well as GitHub teams (see Section
     GITHUB SERVICE).

     For each user, jass will first look for that user's ~/.ssh/autho-
     rized_keys file, then the file /etc/ssh/authorized_keys/<user>.

     If neither of these is readable, and LDAP is configured as a default, it
     will look for the field designated by the LDAPFIELD environment variable
     for the given username in LDAP.

     Alternatively, jass may look on a 'KeyKeeper' server or on an internal or
     public GitHub service for the public key associated with the user.

     Eventually, jass will attempt to encrypt the data for each of the public
     keys found.

     The output from jass consists of several uuencode(1)ed files.  The first
     is the encrypted message, followed by a SHA-256 HMAC.  The following
     files are the session key encrypted for each of the public keys, followed
     by version information.  jass will properly extract, decode and use the
     session suitable key when the -d flag is specified.

     When decrypting, if no key is specified via the -k flag, then jass will
     try ~/.ssh/id_rsa.

     If the message has been tampered with and does not match the HMAC, then
     jass will abort prior to decryption of the input.

     Since earlier versions of jass did not support the use of an HMAC, it is
     possible that input generated by an older version of jass is missing the
     HMAC.  In that case, jass will print a warning and exit.  If the user
     wants to proceed and decrypt the data without the use of an HMAC, then
     they may set the JASS_NO_HMAC environment variable.

PASS PHRASE ARGUMENTS
     jass allows you to specify the passphrase for your private key via one of
     the following methods.  Please note that doing so carries certain risks,
     and you should carefully evaluate what may be the best option for you.

     pass:password   The actual password is password.  Since the password is
		     visible to utilities such as ps(1) this form should only
		     be used where security is not important.

     env:var	     Obtain the password from the environment variable var.
		     Since the environment of other processes may be visible
		     via e.g.  ps(1), this option should be used with caution.

     file:pathname   The first line of pathname is the password.  pathname
		     need not refer to a regular file: it could for example
		     refer to a device or named pipe.  Note that standard Unix
		     file access controls should be used to protect this file.

GITHUB SERVICE
     jass can look for public SSH keys on a GitHub service.  The URL to use
     for this can be set via the GITHUB_URL environment variable.

     If this variable is set, jass will retrieve keys for users from GitHub as
     well as expand groups specified via -g as GitHub teams in the format
     "org/team" or "numeric-team-id".

     If you use an internal GitHub instance that requires authentication, then
     jass can make use of the GITHUB_API_TOKEN environment variable.  If set,
     jass will use it to set the Basic HTTP Authentication header 'Authoriza-
     tion' using the current user's username.

     When parsing GitHub data, jass will assume that the result will be JSON
     data in the format of:

	    [
	     {
	       "id": 12345,
	       "key": "ssh-rsa AAAAB3NzaC1...",
	     },
	     ...
	    ]

EXAMPLES
     To generate a secret message encrypted with the file 'bobs_pubkey' and
     store it in the file 'secret':

	   echo "The ostrich has left the savannah." | \
		   jass -e -k bobs_pubkey > secret

     To send a secret message to 'jschauma':

	   echo "The lion sleeps." | jass -u jschauma |	 \
		   mail -s "Nothing to see here" jschauma

     To decrypt a secret message generated by jass using the private ssh key
     found in 'my_privkey':

	   jass -d -k my_privkey < secret

     To encrypt the file service.yml for the user 'jschauma':

	   jass -u jschauma -f service.yml >service.yml.enc

     To encrypt data for multiple recipients:

	   jass -u user1 -u user2 -u user3 <data

     To encrypt data using the internal GitHub instance with Basic HTTP Auth:

	   export GITHUB_URL="https://git.example.com/api/v3"
	   export GITHUB_API_TOKEN="abcdef0123456789abcdef0123456789abcdef01"
	   jass -u user1 <data

ENVIRONMENT
     When attempting to query LDAP for public keys, jass will require the
     variables LDAPFIELD and LDAPSEARCH to be set.  You can either edit the
     script and set them in there, or export them in your environment.

     The following are example values.

     GITHUB_URL		https://api.github.com/

     GITHUB_API_TOKEN	abcdef0123456789abcdef0123456789abcdef01

     JASS_NO_HMAC	feeling_lucky

     LDAPFIELD		SSHPubkey

     LDAPSEARCH		ldapsearch -LLLxh ldap.yourdomain.com -b dc=exam-
			ple,dc=com

     In order to retrieve public SSH keys from your internal GitHub instance,
     you could invoke jass as follows:

	   $ export GITHUB_URL="https://git.your.internal.site/api/v3"
	   $ jass -u jdoe <data

SEE ALSO
     enc(1), openssl(1), rsautl(1), ssh-keygen(1)

BUGS
     jass will only allow RSA keys.

     jass assumes the public SSH key to be in OpenSSH's default format; if the
     public key is in another format, it will fail.

     jass will not accept private SSH keys in PEM format when decrypting.

HISTORY
     jass was originally written by Jan Schaumann <jschauma@netmeister.org> in
     April 2013.

NetBSD 8.0			March 04, 2020			    NetBSD 8.0