Unix/Linux Go Back    


NetBSD 6.1.5 - man page for netpgp (netbsd section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


NETPGP(1)			   BSD General Commands Manual				NETPGP(1)

NAME
     netpgp -- signing, verification, encryption, and decryption utility

SYNOPSIS
     netpgp --encrypt [--output=filename] [options] file ...
     netpgp --decrypt [--output=filename] [--pass-fd=fd] [--num-tries=attempts] [options] file
	    ...

     netpgp --sign [--armor] [--detach] [--hash=algorithm] [--output=filename] [--pass-fd=fd]
	    [--from=sig-valid-from] [--num-tries=attempts] [--duration=sig-valid-duration]
	    [options] file ...
     netpgp --verify [options] file ...
     netpgp --cat [--output=filename] [options] file ...
     netpgp --clearsign [--output=filename] [--pass-fd=fd] [options] file ...
     netpgp --list-packets [--pass-fd=fd] file ...
     netpgp --version
     netpgp [-Vdesv] [-olong-option=value] file ...

	    where the long options for all commands are:

	    [--cipher=ciphername]
	    [--coredumps]
	    [--homedir=home-directory]
	    [--keyring=keyring]
	    [--results=filename]
	    [--ssh-keys]
	    [--userid=userid]
	    [--verbose]

DESCRIPTION
     The netpgp command can digitally sign files and verify that the signatures attached to files
     were signed by a given user identifier.  netpgp can also encrypt files using the public or
     private keys of users and, in the same manner, decrypt files which were encrypted.

     For signing and encryption, a unique identity is needed.  This identity is made up of a pri-
     vate and public key.  The public key part is made available and known to everyone.  The pri-
     vate key is kept secret, and known only to the user who created the identity.  The secret
     key is protected with a passphrase.

     In rough terms, a digital signature is a digest of a file's contents, encrypted with the
     user's private key.  Since together, the private and public keys identify the user uniquely,
     the signature can be used to identify the exact version of the file, and any changes made to
     the file will mean that the signature no longer matches.

     As a corollary, the file can be transformed using a user's public key, into text such that
     the contents can only be viewed by someone with the corresponding private key.  This is
     called encryption.

     To manipulate keys themselves, a separate utility is provided, called netpgpkeys(1).

     Keyrings are collections of public keys belonging to other users.	By using other means of
     identification, it is possible to establish the bona fides of other users.  Once trust has
     been established, the public key of the other user will be signed.  The other user's public
     key can be added to our keyring.  The other user will add our public key to their keyring.

     Keys can be listed, exported (i.e. made available to others), and imported (i.e. users who
     have signed our public key).

     The --list-packets command can be used for debugging purposes.

     The following commands are used to sign and verify signatures:

     --cat	   The signature of the signed file named on the command line is verified against
		   the contents of the file itself.  If the two match, then the original contents
		   are sent to standard out.  If the signature does not match, no output is gen-
		   erated.

     --clearsign   The signature of the file named on the command line is calculated in the same
		   manner as the --sign command, but the text is added to the file such that the
		   text itself is not in binary format, but can be read by mere mortals.

     --sign	   The private key is used to digitally sign the files named on the command line.
		   The file and its attached signature are created with a ``.gpg'' extension to
		   the original file name.  The user will be prompted for their pass phrase using
		   getpass(3).

     --verify	   For each of the files named on the command line, the signature of the file is
		   verified, checking the contents against the user's public signature.

     The following commands can be used to encrypt and decrypt files:

     --decrypt	   Decrypt the file using the user's private key.  The pass phrase will be
		   optained by prompting the user to type it in, using getpass(3).

     --encrypt	   Use the user's public key to encrypt the files named on the command line.

     --list-packets
		   List all the ``packets'' in an encrypted or signed file.  Internally, netpgp
		   splits an encrypted or signed file into separate packets, and this option is
		   used to give a verbose representation of these packets on standard output.

     --version	   Print the version information from the libnetpgp(3) library.

     In addition to one of the preceding commands, a number of qualifiers or options may be
     given.

     --armour, -armor
		   This option, however it is spelled, wraps the signature as an ASCII-encoded
		   piece of text, for ease of use.

     --cipher ciphername
		   can be used to specify the symmetric encryption algorithm (or cipher) which is
		   used when encrypting data.  To decrypt this data, the same cipher will be
		   needed, so care should be taken at encryption time to make sure that the per-
		   son who decrypts the data has access to the cipher used.  The default cipher
		   algorithm is the ``CAST5'' algorithm.

     --detached    When signing a file, place the resulting signature in a separate file from the
		   one being signed.

     --hash-alg hash-algorithm
		   can be used to specify the hash algorithm (sometimes called a digest algo-
		   rithm) which is used with RSA keys when signing text.  The default hash algo-
		   rithm is the ``SHA256'' algorithm.  At the present time, ``SHA1'' may also be
		   used, although it is recommended that SHA256 be used, due to recent advances
		   in generating collisions for the SHA1 hashing algorithm.

     --homedir home-directory
		   Keyrings are normally located, for historical reasons, within the user's home
		   directory in a subdirectory called ``.gnupg'' and this option specifies an
		   alternative location in which to find that sub-directory.

     --keyring keyring
		   This option specifies an alternative keyring to be used.  All keyring opera-
		   tions will be relative to this alternative keyring.

     --output	   specifies a filename to which verified output from a signed file may be redi-
		   rected.  The default is to send the verified output to stdout, and this may
		   also be specified using the ``-'' value.

     --results filename
		   specifies a filename to which the results of the operation should be sent.
		   The default is to send the results to stderr.

     --ssh-keys    specifies that the public and private keys should be taken from the ssh(1)
		   host key files, usually found in /etc/ssh/ssh_host_rsa_key and
		   /etc/ssh/ssh_host_rsa_key.pub for the private and public host keys.

     --userid userid
		   This option specifies the user identity to be used for all operations.  This
		   identity can either be in the form of the full name, or as an email address.
		   Care should be exercised with these ways of specifying the user identity,
		   since the netpgp utility has no way of verifying that an email address is
		   valid, or that a key belongs to a certain individual.  The trust for a signed
		   key is given by the other signers of that key.  The 16 hexadecimal digit user
		   identity should be used when specifying user identities - email addresses and
		   names are provided as aliases.

     --pass-fd=fd  This option is intended for the use of external programs which may like to use
		   the libnetpgp(3) library through the netpgp interface, but have their own ways
		   of retrieving and caching the passphrase for the secret key.  In this case,
		   the netpgp utility will read a line of text from the file descriptor passed to
		   it in the command line argument, rather than using its own methods of retriev-
		   ing the passphrase from the user.

     --num-tries=attempts
		   This option sets the maximum number of attempts to get the correct passphrase
		   from the user.  A value of unlimited means that there is no maximum number of
		   attempts, and the utility will loop endlessly until the correct passphrase has
		   been entered, or the utility is terminated.

     --from=signature-valid-from
		   This option allows the signer to specify a time as the starting point for
		   validity of the signature.  In this way it is possible to prevent files from
		   being verified until a specific point in time.  The time can be specified
		   either in YYYY-MM-DD format, or as the number of seconds since the epoch.

     --duration=signature-valid-to
		   This option allows the signer to specify a time as the end point for validity
		   of the signature.  In this way it is possible to prevent files from being ver-
		   ified after a specific point in time.  The time can be specified either in
		   YYYY-MM-DD format, or as the number of seconds.

     --verbose	   This option can be used to view information during the process of the netpgp
		   requests.

     --coredumps   in normal processing, if an error occurs, the contents of memory are saved to
		   disk, and can be read using tools to analyse behaviour.  Unfortuinately this
		   can disclose information to people viewing the core dump, such as secret keys,
		   and passphrases protecting those keys.  In normal operation, netpgp will turn
		   off the ability to save core dumps on persistent storage, but selecting this
		   option will allow core dumps to be written to disk.	This option should be
		   used wisely, and any core dumps should be deleted in a secure manner when no
		   longer needed.

PASS PHRASES
     At the present time, the pass phrase cannot be changed by netpgpkeys(1) once it has been
     chosen, and will be used for the life of the key, so a wise choice is advised.  The pass
     phrase should not be an easily guessable word or phrase, or related to information that can
     be gained through ``social engineering'' using search engines, or other public information
     retrieval methods.

     getpass(3) will be used to obtain the pass phrase from the user if it is needed, such as
     during signing or encryption, or key generation, so that any secret information cannot be
     viewed by other users using the ps(1) or top(1) commands, or by looking over the shoulder at
     the screen.

     Since the public and private key pair can be used to verify a person's identity, and since
     identity theft can have far-reaching consequences, users are strongly encouraged to enter
     their pass phrases only when prompted by the application.

SIGNING AND VERIFICATION
     Signing and verification of a file is best viewed using the following example:

     % netpgp --sign --userid=agc@netbsd.org a
     pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
     Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
     uid	      Alistair Crooks <agc@netbsd.org>
     uid	      Alistair Crooks <agc@pkgsrc.org>
     uid	      Alistair Crooks <agc@alistaircrooks.com>
     uid	      Alistair Crooks <alistair@hockley-crooks.com>
     netpgp passphrase:
     % netpgp --verify a.gpg
     Good signature for a.gpg made Thu Jan 29 03:06:00 2009
     using RSA (Encrypt or Sign) key 1B68DCFCC0596823
     pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
     Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
     uid	      Alistair Crooks <alistair@hockley-crooks.com>
     uid	      Alistair Crooks <agc@pkgsrc.org>
     uid	      Alistair Crooks <agc@netbsd.org>
     uid	      Alistair Crooks <agc@alistaircrooks.com>
     %

     In the example above, a signature is made on a single file called ``a'' using a user iden-
     tity corresponding to ``agc@netbsd.org'' The key located for the user identity is displayed,
     and the user is prompted to type in their passphrase.  The resulting file, called ``a.gpg''
     is placed in the same directory.  The second part of the example shows a verification of the
     signed file taking place.	The time and user identity of the signatory is displayed, fol-
     lowed by a fuller description of the public key of the signatory.	In both cases, the exit
     value from the utility was a successful one.

     If a detached signature of a file called ``a'' is requested, the signature would be placed
     in a file called ``a.sig''.

     To encrypt a file, the user's public key is used.	Subsequent decryption of the file
     requires that the secret key is known.  When decrypting, the key is displayed, and the
     passphrase protecting the secret key must be typed in to access the data in the encrypted
     file.

     % netpgp --encrypt --userid=c0596823 a
     % netpgp --decrypt a.gpg
     pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
     Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
     uid	      Alistair Crooks <agc@netbsd.org>
     uid	      Alistair Crooks <agc@pkgsrc.org>
     uid	      Alistair Crooks <agc@alistaircrooks.com>
     uid	      Alistair Crooks <alistair@hockley-crooks.com>
     netpgp passphrase:
     %

     If no file name is provided, the data will be read from standard input, and displayed on
     standard output:

     % netpgp --encrypt < a | netpgp --decrypt > b
     netpgp: default key set to "C0596823"
     netpgp: default key set to "C0596823"
     pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
     Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
     uid	      Alistair Crooks <agc@netbsd.org>
     uid	      Alistair Crooks <agc@pkgsrc.org>
     uid	      Alistair Crooks <agc@alistaircrooks.com>
     uid	      Alistair Crooks <alistair@hockley-crooks.com>
     netpgp passphrase:
     %

     This simple (and contrived) example shows that netpgp commands can be used together in a
     pipeline to produce the desired effect.

     % netpgp --sign < a | netpgp --cat > b
     netpgp: default key set to "C0596823"
     netpgp: default key set to "C0596823"
     pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
     Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
     uid	      Alistair Crooks <agc@netbsd.org>
     uid	      Alistair Crooks <agc@pkgsrc.org>
     uid	      Alistair Crooks <agc@alistaircrooks.com>
     uid	      Alistair Crooks <alistair@hockley-crooks.com>
     netpgp passphrase:
     Good signature for <stdin> made Mon Dec 21 18:25:02 2009
     using RSA (Encrypt or Sign) key 1b68dcfcc0596823
     pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
     Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
     uid	      Alistair Crooks <alistair@hockley-crooks.com>
     uid	      Alistair Crooks <agc@pkgsrc.org>
     uid	      Alistair Crooks <agc@netbsd.org>
     uid	      Alistair Crooks <agc@alistaircrooks.com>
     uid	      Alistair Crooks (Yahoo!) <agcrooks@yahoo-inc.com>
     %

     For operations like signing and encrypting a file at the same time, the best way is to make
     use of pipelines:

     % netpgp --sign < example | netpgp --encrypt --userid=c0596823 > example.gpg
     netpgp: default key set to "C0596823"
     pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
     Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
     uid	      Alistair Crooks <alistair@hockley-crooks.com>
     uid	      Alistair Crooks <agc@pkgsrc.org>
     uid	      Alistair Crooks <agc@netbsd.org>
     uid	      Alistair Crooks <agc@alistaircrooks.com>
     uid	      Alistair Crooks (Yahoo!) <agcrooks@yahoo-inc.com>
     netpgp passphrase:
     % netpgp --decrypt < example.gpg | netpgp --cat
     netpgp: default key set to "C0596823"
     netpgp: default key set to "C0596823"
     pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
     Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
     uid	      Alistair Crooks <alistair@hockley-crooks.com>
     uid	      Alistair Crooks <agc@pkgsrc.org>
     uid	      Alistair Crooks <agc@netbsd.org>
     uid	      Alistair Crooks <agc@alistaircrooks.com>
     uid	      Alistair Crooks (Yahoo!) <agcrooks@yahoo-inc.com>
     netpgp passphrase:
     Good signature for <stdin> made Mon Feb 22 07:21:19 2010
     using RSA (Encrypt or Sign) key 1b68dcfcc0596823
     pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
     Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
     uid	      Alistair Crooks <alistair@hockley-crooks.com>
     uid	      Alistair Crooks <agc@pkgsrc.org>
     uid	      Alistair Crooks <agc@netbsd.org>
     uid	      Alistair Crooks <agc@alistaircrooks.com>
     uid	      Alistair Crooks (Yahoo!) <agcrooks@yahoo-inc.com>
     ...contents of original file...
     %

EXIT STATUS
     The netpgp utility will return 0 for success, 1 if the file's signature does not match what
     was expected, or 2 if any other error occurs.

SEE ALSO
     netpgpkeys(1), ssh(1), getpass(3), libnetpgp(3), ssl(3), zlib(3)

STANDARDS
     The netpgp utility is designed to conform to IETF RFC 4880.

HISTORY
     The netpgp command first appeared in NetBSD 6.0.

AUTHORS
     Ben Laurie, Rachel Willmer, and overhauled and rewritten by Alistair Crooks
     <agc@NetBSD.org>.	This manual page was also written by Alistair Crooks.

BSD					November 28, 2010				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 09:43 PM.