Help language development. Donate to The Perl Foundation
From the GPGME Manual:
‘GnuPG Made Easy’ (GPGME) is a C language library that allows to add support for cryptography to a program. It is designed to make access to public key crypto engines like GnuPG or GpgSM easier for applications. GPGME provides a high-level crypto API for encryption, decryption, signing, signature verification and key management. GPGME uses GnuPG and GpgSM as its backends to support OpenPGP and the Cryptographic Message Syntax (CMS).
So essentially, this is a Raku Module interfacing with a C library interfacing with GnuPG and GpgSM command line programs.
Note, this is still a work in progress, more features may or may not be forthcoming!! Patches welcome!!
use GPGME; my $gpg = GPGME.new(:armor); # ASCII armor for key export $gpg.create-key('[email protected]'); # Add key to key ring my $joes-key = $gpg.get-key('[email protected]'); # Retrieve a key put $joes-key; # Stringify key summary put my $key = $gpg.export('[email protected]'); # Export from key ring $gpg.import($key); # Import key my $cipher = $gpg.encrypt('message', '[email protected]'); my $plain = $gpg.decrypt($cipher); $gpg.signers('[email protected]'); my $signed = $gpg.sign('My message');
use GPGME; put GPGME.version; put GPGME.dirinfo('gpg-name'); GPGME.set-locale('C');
The main GPGME object holds a
context with various
settings, and can be used to perform various functions.
use GPGME; my $gpg = GPGME.new; my $gpg = GPGME.new(:armor, :homedir</tmp/dir>);
See GPGME for more information.
After performing an operation, the result of the operation can be
retrieved from the context with the C
For example, after a key generation operation, the
$gpg.create-key('[email protected]'); my $result = $gpg.result; my $fpr = $result.fpr;
This does the same thing, passing the I
my $fpr = $gpg.fpr;
Of course, for key generation, the result object is returned from
my $fpr = $gpg.create-key('[email protected]').fpr;
You can additionally retrieve the result object immediately following the appropriate operation with these methods:
$gpg.genkey-result $gpg.import-result $gpg.sign-result $gpg.encrypt-result $gpg.decrypt-result $gpg.verify-result
These are sometimes needed when an operation performs two actions (e.g. decrypt and verify).
These are only valid immediately following the appropriate operation, and all results must be used or copied prior to the next operation, when the results are no longer available.
.put for GPGME.engine-info; GPGME.engine-info('openpgp', :homedir</tmp/dir>);
See GPGME::EngineInfo for more information.
A lot of data has to be exchanged between the user and the crypto
engine, like plaintext messages, ciphertext, signatures and
information about the keys. The technical details about exchanging the
data information are completely abstracted by GPGME. The user provides
and receives the data via
GPGME::Data objects, regardless of the
communication protocol between GPGME and the crypto engine in use.
In general the API will construct the appropriate
object for you.
For input objects, you can provide one of these types:
Blob-- Actual data to use
Str-- Actual data to use
IO::Path-- Filename of file to use
IO::Handle-- File with a
native-descriptorto read from
For output objects, you can provide one of these types:
Str-- Filename of file to write to
IO::Path-- Filename to write to
IO::Handle-- File with a C
When an output object is omitted, a memory buffer will be used and returned.
GPGME::Data object is returned, you can stringify it if and
only if the data are
utf8 encoded or ascii (usually produced when
the :armor option was specified during context creation).
The object can also be treated as an
IO::Handle and read from as
An important fact to remember is that in addition to providing mechanisms to manipulate keys, GPG also serves as a Key Store or 'Key Ring'. Keys can generally be referred to by patterns and fingerprints that map to actual keys stored in the key store.
GPGME Supports two different interfaces to Key Generation --
$gpg.create-key('[email protected]'); my $key = $gpg.get-key('[email protected]'); $gpg.create-subkey($key); $gpg.adduid($key, '[email protected]'); $gpg.set-uid-flag($key, '[email protected]'); # Make new one primary $gpg.revuid($key, '[email protected]'); # Revoke a user ID
genkey takes a set of parameters, expressed either as a single
string, or a set of named parameters:
$gpg.genkey(q:to/END/) Key-Type: default Name-Email: [email protected] END
$gpg.genkey(:Name-Email<[email protected]>); # Key-Type defaults to 'default'
List keys in the key ring by specifying a list of patterns and optionally specifying the :secret option to retrieve secret keys.
$key = $gpg.get-key('[email protected]'); $key = $gpg.get-key($fpr, :secret); .put for $gpg.keylist('[email protected]', :secret); .put for $gpg.keylist(<alice harry bob>);
Individual attributes from the keys can be queried. See GPGME::Key for more information.
$gpg.delete-key($key, :secret, :force);
Key signatures are a unique concept of the OpenPGP protocol. They can be used to certify the validity of a key and are used to create the Web-of-Trust (WoT).
$gpg.signers('[email protected]'); # select signers $gpg.keysign($key); # Default sign all user IDs $gpg.keysign($key, '[email protected]'); # Specify a user ID $gpg.keysign($key, :local); # Non exportable $gpg.keysign($key, '[email protected]', expires => $DateTime);
my $gpg = GPGME.new(:armor); # Use :armor to get ASCII export put $gpg.export('[email protected]'); # Stringify and print out $gpg.export('[email protected]', :out<outputfile>); # Export to filename $gpg.export('[email protected]', out => $*OUT); # Send to a file handle
Stores the ImportResult.
$cipher = $gpg.encrypt("my message", $key); # Encrypt for a key $cipher = $gpg.encrypt("my message", '[email protected]'); # Encrypt for a pattern $cipher = $gpg.encrypt("my message", '[email protected]', :sign); # Encrypt and sign
Stores the EncryptResult.
If signed as well with the :sign option, SignResult can be examined as well.
$plain = $gpg.decrypt($cipher); $gpg.decrypt($cipher, out => 'filename'); $gpg.decrypt($cipher, out => $*OUT); $gpg.decrypt($cipher, :verify);
Stores the DecryptResult.
If the signature was verified with the :verify option, the VerifyResult is also available.
A signature can contain signatures by one or more keys. The set of keys used to create a signatures is contained in a context, and is applied to all following signing operations in this context (until the set is changed).
They can be set either at
GPGME creation with the :signers object,
or with the
.signers method later.
$gpg.signers('[email protected]'); my $signed = $gpg.sign('My message'); $gpg.sign($*IN, out => $*OUT); my $signature = $gpg.sign('My message', :detach); # Detached signature
The SignResult will be available after signing.
$message = $gpg.verify($signed); $gpg.verify('infile'.IO, :out<somefile>); put $gpg.verify($signature, $message).status; # Detached signature
The VerifyResult will be available after verification.
GPGME actions (particularly key generation with very long keys)
rely on the OS ability to generate a great deal of entropy. Things
may appear to hang on entropy starved hosts. Tools like
haveged can help the OS capture
entropy. Even doing something simple like running
if=/dev/sda of=/dev/zero in the background can help speed things up.
You must install
libgpgme which usually has the right dependencies
on GPG as well.
apt install libgpgme11
apk add gpgme
yum install gpgme
If you get locale errors on CentOS, you may need to run this:
yum install glibc-locale-source glibc-langpack-en localedef -i en_US -f UTF-8 en_US.UTF-8
This work is subject to the Artistic License 2.0.
See LICENSE for more information.