Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GnuPG(3)	      User Contributed Perl Documentation	      GnuPG(3)

NAME
       GnuPG - Perl module interface to	the GNU	Privacy	Guard (v1.x.x series)

SYNOPSIS
	   use GnuPG qw( :algo );

	   my $gpg = new GnuPG();

	   $gpg->encrypt(  plaintext	=> "file.txt",	  output	=> "file.gpg",
		   armor    => 1,	  sign	  => 1,
		   passphrase  => $secret );

	   $gpg->decrypt( ciphertext	=> "file.gpg",	  output	=> "file.txt" );

	   $gpg->clearsign( plaintext => "file.txt", output => "file.txt.asc",
		    passphrase => $secret,   armor => 1,
		   );

	   $gpg->verify( signature => "file.txt.asc", file => "file.txt" );

	   $gpg->gen_key( name => "Joe Blow",	     comment =>	"My GnuPG key",
		  passphrase =>	$secret,
		   );

DESCRIPTION
       GnuPG is	a perl interface to the	GNU Privacy Guard. It uses the shared
       memory coprocess	interface that gpg provides for	its wrappers. It tries
       its best	to map the interactive interface of the	gpg to a more
       programmatic model.

API OVERVIEW
       The API is accessed through methods on a	GnuPG object which is a
       wrapper around the gpg program.	All methods takes their	argument using
       named parameters, and errors are	returned by throwing an	exception
       (using croak).  If you wan't to catch errors you	will have to use eval.

       When handed in a	file handle for	input or output	parameters on many of
       the functions, the API attempts to tie that handle to STDIN and STDOUT.
       In certain persistent environments (particularly	a web environment),
       this will not work. This	problem	can be avoided by passing in file
       names to	all relevant parameters	rather than a Perl file	handle.

       There is	also a tied file handle	interface which	you may	find more
       convenient for encryption and decryption. See GnuPG::Tie(3) for
       details.

CONSTRUCTOR
   new ( [params] )
       You create a new	GnuPG wrapper object by	invoking its new method.  (How
       original	!).  The module	will try to finds the gpg program in your path
       and will	croak if it can't find it. Here	are the	parameters that	it
       accepts :

       gnupg_path
	   Path	to the gpg program.

       options
	   Path	to the options file for	gpg. If	not specified, it will use the
	   default one (usually	~/.gnupg/options).

       homedir
	   Path	to the gpg home	directory. This	is the directory that contains
	   the default options file, the public	and private key	rings as well
	   as the trust	database.

       trace
	   If this variable is set to true, gpg	debugging output will be sent
	   to stderr.

	   Example: my $gpg = new GnuPG();

METHODS
   gen_key( [params] )
       This methods is used to create a	new gpg	key pair. The methods croaks
       if there	is an error. It	is a good idea to press	random keys on the
       keyboard	while running this methods because it consumes a lot of
       entropy from the	computer. Here are the parameters it accepts :

       algo
	   This	is the algorithm use to	create the key.	Can be DSA_ELGAMAL,
	   DSA,	RSA_RSA	or RSA.	 It defaults to	DSA_ELGAMAL. To	import those
	   constant in your name space,	use the	:algo tag.

       size
	   The size of the public key. Defaults	to 1024. Cannot	be less	than
	   768 bits, and keys longer than 2048 are also	discouraged. (You *DO*
	   know	that your monitor may be leaking sensitive information ;-).

       valid
	   How long the	key is valid. Defaults to 0 or never expire.

       name
	   This	is the only mandatory argument.	This is	the name that will
	   used	to construct the user id.

       email
	   Optional email portion of the user id.

       comment
	   Optional comment portion of the user	id.

       passphrase
	   The passphrase that will be used to encrypt the private key.
	   Optional but	strongly recommended.

	   Example: $gpg->gen_key( algo	=> DSA_ELGAMAL,	size =>	1024,
		       name => "My name" );

   import_keys(	[params] )
       Import keys into	the GnuPG private or public keyring. The method	croaks
       if it encounters	an error. It returns the number	of keys	imported.
       Parameters :

       keys
	   Only	parameter and mandatory. It can	either be a filename or	a
	   reference to	an array containing a list of files that will be
	   imported.

	   Example: $gpg->import_keys( keys => [ qw( key.pub key.sec ) ] );

   export_keys(	[params] )
       Exports keys from the GnuPG keyrings. The method	croaks if it
       encounters an error. Parameters :

       keys
	   Optional argument that restricts the	keys that will be exported.
	   Can either be a user	id or a	reference to an	array of userid	that
	   specifies the keys to be exported. If left unspecified, all keys
	   will	be exported.

       secret
	   If this argument is to true,	the secret keys	rather than the	public
	   ones	will be	exported.

       all If this argument is set to true, all	keys (even those that aren't
	   OpenPGP compliant) will be exported.

       output
	   This	argument specifies where the keys will be exported. Can	be
	   either a file name or a reference to	a file handle. If not
	   specified, the keys will be exported	to stdout.

       armor
	   Set this parameter to true, if you want the exported	keys to	be
	   ASCII armored.

	   Example: $gpg->export_keys( armor =>	1, output => "keyring.pub" );

   encrypt( [params] )
       This method is used to encrypt a	message, either	using assymetric or
       symmetric cryptography. The methods croaks if an	error is encountered.
       Parameters:

       plaintext
	   This	argument specifies what	to encrypt. It can be either a
	   filename or a reference to a	file handle. If	left unspecified,
	   STDIN will be encrypted.

       output
	   This	optional argument specifies where the ciphertext will be
	   output.  It can be either a file name or a reference	to a file
	   handle. If left unspecified,	the ciphertext will be sent to STDOUT.

       armor
	   If this parameter is	set to true, the ciphertext will be ASCII
	   armored.

       symmetric
	   If this parameter is	set to true, symmetric cryptography will be
	   used	to encrypt the message.	You will need to provide a passphrase
	   parameter.

       recipient
	   If not using	symmetric cryptography,	you will have to provide this
	   parameter. It should	contains the userid of the intended recipient
	   of the message. It will be used to look up the key to use to
	   encrypt the message.	The parameter can also take an array ref, if
	   you want to encrypt the message for a group of recipients.

       sign
	   If this parameter is	set to true, the message will also be signed.
	   You will probably have to use the passphrase	parameter to unlock
	   the private key used	to sign	message. This option is	incompatible
	   with	the symmetric one.

       local-user
	   This	parameter is used to specified the private key that will be
	   used	to sign	the message. If	left unspecified, the default user
	   will	be used. This option only makes	sense when using the sign
	   option.

       passphrase
	   This	parameter contains either the secret passphrase	for the
	   symmetric algorithm or the passphrase that should be	used to
	   decrypt the private key.

	   Example: $gpg->encrypt( plaintext =>	file.txt, output => "file.gpg",
		       sign => 1, passphrase =>	$secret
		       );

   sign( [params] )
       This method is used create a signature for a file or stream of data.
       This method croaks on errors. Parameters	:

       plaintext
	   This	argument specifies what	 to sign. It can be either a filename
	   or a	reference to a file handle. If left unspecified, the data read
	   on STDIN will be signed.

       output
	   This	optional argument specifies where the signature	will be
	   output.  It can be either a file name or a reference	to a file
	   handle. If left unspecified,	the signature will be sent to STDOUT.

       armor
	   If this parameter is	set to true, the signature will	be ASCII
	   armored.

       passphrase
	   This	parameter contains the secret that should be used to decrypt
	   the private key.

       local-user
	   This	parameter is used to specified the private key that will be
	   used	to make	the signature .	If left	unspecified, the default user
	   will	be used.

       detach-sign
	   If set to true, a digest of the data	will be	signed rather than the
	   whole file.

	   Example: $gpg->sign(	plaintext => "file.txt", output	=> "file.txt.asc",
		    armor => 1,
		    );

   clearsign( [params] )
       This methods clearsign a	message. The output will contains the original
       message with a signature	appended. It takes the same parameters as the
       sign method.

   verify( [params] )
       This method verifies a signature	against	the signed message. The
       methods croaks if the signature is invalid or an	error is encountered.
       If the signature	is valid, it returns an	hash with the signature
       parameters. Here	are the	method's parameters :

       signature
	   If the message and the signature are	in the same file (i.e. a
	   clearsigned message), this parameter	can be either a	file name or a
	   reference to	a file handle. If the signature	doesn't	follows	the
	   message, than it must be the	name of	the file that contains the
	   signature.

       file
	   This	is a file name or a reference to an array of file names	that
	   contains the	signed data.

       When the	signature is valid, here are the elements of the hash that is
       returned	by the method :

       sigid
	   The signature id. This can be used to protect against replay
	   attack.

       date
	   The data at which the signature has been made.

       timestamp
	   The epoch timestamp of the signature.

       keyid
	   The key id used to make the signature.

       user
	   The userid of the signer.

       fingerprint
	   The fingerprint of the signature.

       trust
	   The trust value of the public key of	the signer. Those are values
	   that	can be imported	in your	namespace with the :trust tag. They
	   are (TRUST_UNDEFINED, TRUST_NEVER, TRUST_MARGINAL, TRUST_FULLY,
	   TRUST_ULTIMATE).

	   Example : my	$sig = $gpg->verify( signature => "file.txt.asc",
			     file => "file.txt"	);

   decrypt( [params] )
       This method decrypts an encrypted message. It croaks, if	there is an
       error while decrypting the message. If the message was signed, this
       method also verifies the	signature. If decryption is sucessful, the
       method either returns the valid signature parameters if present,	or
       true. Method parameters :

       ciphertext
	   This	optional parameter contains either the name of the file
	   containing the ciphertext or	a reference to a file handle
	   containing the ciphertext. If not present, STDIN will be decrypted.

       output
	   This	optional parameter determines where the	plaintext will be
	   stored.  It can be either a file name or a reference	to a file
	   handle.  If left unspecified, the plaintext will be sent to STDOUT.

       symmetric
	   This	should be set to true, if the message is encrypted using
	   symmetric cryptography.

       passphrase
	   The passphrase that should be used to decrypt the message (in the
	   case	of a message encrypted using a symmetric cipher) or the	secret
	   that	will unlock the	private	key that should	be used	to decrypt the
	   message.

	   Example: $gpg->decrypt( ciphertext => "file.gpg", output => "file.txt"
		       passphrase => $secret );

BUGS AND LIMITATIONS
       This module doesn't work	(yet) with the v2 branch of GnuPG.

AUTHOR
       Francis J. Lacoste <francis.lacoste@Contre.COM>

COPYRIGHT
       Copyright (c) 1999,2000 iNsu Innovations. Inc.  Copyright (c) 2001
       Francis J. Lacoste

       This program is free software; you can redistribute it and/or modify it
       under the terms of the GNU General Public License as published by the
       Free Software Foundation; either	version	2 of the License, or (at your
       option) any later version.

SEE ALSO
       GnuPG::Tie

       Alternative module: GnuPG::Interface

       gpg(1)

perl v5.24.1			  2012-04-15			      GnuPG(3)

NAME | SYNOPSIS | DESCRIPTION | API OVERVIEW | CONSTRUCTOR | METHODS | BUGS AND LIMITATIONS | AUTHOR | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=GnuPG&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help