@node openpgp
@section OpenPGP signature verification

The @code{(industria openpgp)} library provides procedures for
reading OpenPGP keyrings and verifying signatures. OpenPGP signatures
can be created with e.g.@: GNU Private Guard (GnuPG) and are often
used to verify the integrity of software releases.

Version 4 keys and version 3/4 signatures are supported. The
implemented public key algorithms are RSA and DSA, and it verifies
signatures made using the message digest algorithms MD5, SHA-1,
SHA-224, SHA-256, SHA-384 and SHA-512 (all the standard algorithms
except RIPE-MD160).

An OpenPGP key is actually a list of OpenPGP packets with a certain
structure: first is the primary key (e.g. an RSA or DSA key), next
possibly a revocation, then a number of user IDs, attributes,
signatures and also subkeys (which are just like primary keys, except
marked as subkeys). See RFC 4880 section 11 for the exact composition.
This library represents keyrings as hashtables indexed by key ID and
where the entries are lists of packets in the order they appeared in
the keyring file.

Please note that this library assumes the program that wrote the
keyring did due diligence when importing keys, and made sure that
e.g.@: subkey binding signatures are verified, and that the order of
packets is correct.

@deffn Procedure port-ascii-armored? port
Returns false if the data at the beginning of @var{port} doesn't look
like a valid binary OpenPGP packet. The port must be a binary input
port. The port position is not changed.
@end deffn

@deffn Procedure get-openpgp-packet port
Reads an OpenPGP packet from @var{port}, which must be a binary input
port. An error is raised if the packet type is unimplemented.
@end deffn

@deffn Procedure get-openpgp-keyring p
Reads a keyring from the binary input port @var{p}. Returns a
hashtable where all primary keys and subkeys are indexed by their key
ID (an integer). The values in the hashtable are lists that contain
all OpenPGP packets associated with each key. No effort at all is made
to verify that keys have valid signatures.

Warning: this can take a while if the keyring is very big.
@end deffn

@deffn Procedure get-openpgp-keyring/keyid p keyid
Searches the binary input port @var{p} for the public key with the
given @var{keyid}. Returns a hashtable similar to
@code{get-openpgp-keyring}, except it will only contain the primary
and subkeys associated with the @var{keyid}.

The @var{keyid} can be either a 64 or 32 bit exact integer.

Warning: this is faster than get-openpgp-keyring, but is still rather
slow with big keyrings. The speed depends on the SHA-1 implementation.
@end deffn

@deffn Procedure get-openpgp-detached-signature/ascii p
Reads a detached OpenPGP signature from the textual input port
@var{p}. Returns either an OpenPGP signature object or the end of file
object.

These signatures can be created with e.g.@: @code{gpg -a --detach-sign filename}.
@end deffn

@deffn Procedure verify-openpgp-signature sig keyring p
Verifies the signature data in @var{sig}. The @var{keyring} hashtable
is used to find the public key of the signature issuer. The signed
data is read from the binary input port @var{p}.

This procedure returns two values. These are the possible
combinations:
@itemize
@item
@t{good-signature }@emph{key-data} -- The signature matches
the data. The @emph{key-data} contains the public key list that was
used to verify the signature.
@item
@t{bad-signature }@emph{key-data} -- The signature does not
match the data. The @emph{key-data} is the same as above.
@item
@t{missing-key }@emph{key-id} -- The issuer public key for the
signature was not found in the keyring. The @emph{key-id} is the
64-bit key ID of the issuer.
@end itemize
@end deffn

@deffn Procedure openpgp-signature? obj
True if @var{obj} is an OpenPGP signature object. Such objects are
read with @code{get-openpgp-detached-signature/ascii} and are also
contained in keyring entries.
@end deffn

@deffn Procedure openpgp-signature-issuer sig
The 64-bit key ID of the OpenPGP public key that issued the
signature @var{sig}.
@end deffn

@deffn Procedure openpgp-signature-public-key-algorithm sig
Returns the name of the public key algorithm used to create the
signature @var{sig}. This is currently the symbol @code{dsa} or
@emph{rsa}.
@end deffn

@deffn Procedure openpgp-signature-hash-algorithm sig
The name of the message digest algorithm used to create the
signature @var{sig}. This is currently one of @code{md5},
@code{sha-1}, @code{ripe-md160} (unsupported), @code{sha-224},
@code{sha-256}, @code{sha-384} or @code{sha-512}.
@end deffn

@deffn Procedure openpgp-signature-creation-time sig
An SRFI-19 date object representing the time at which the signature
@var{sig} was created.
@end deffn

@deffn Procedure openpgp-signature-expiration-time sig
An SRFI-19 date object representing the time at which the signature
@var{sig} expires. Returns @code{#f} if there's no expiration time.
@end deffn

@deffn Procedure openpgp-user-id? obj
True if @var{obj} is an OpenPGP user id.
@end deffn

@deffn Procedure openpgp-user-id-value user-id
The string value of the @var{user-id}. This is often the name of the
person who owns the key.
@end deffn

@deffn Procedure openpgp-user-attribute? obj
True if @var{obj} is an OpenPGP user attribute. Attributes are used to
encode JPEG images. There's currently no way to access the image.
@end deffn

@deffn Procedure openpgp-public-key? obj
True if @var{obj} is an OpenPGP primary key or subkey.
@end deffn

@deffn Procedure openpgp-public-key-subkey? key
True if @var{obj} is a subkey.
@end deffn

@deffn Procedure openpgp-public-key-value key
The DSA or RSA public key contained in the OpenPGP public @var{key}.
The value returned has the same type as the @code{(crypto weinholt
dsa)} or @code{(crypto weinholt rsa)}.
@end deffn

@deffn Procedure openpgp-public-key-fingerprint key
The fingerprint of the OpenPGP public @var{key} as a bytevector. This
is an SHA-1 digest based on the public key values.
@end deffn

@deffn Procedure openpgp-format-fingerprint bv
Formats the bytevector @var{bv}, which was presumably created by
@code{openpgp-public-key-fingerprint}, as a string in the format
preferred for PGP public key fingerprints.
@end deffn

@deffn Procedure openpgp-public-key-id key
The 64-bit key ID of the OpenPGP public @var{key}.
@end deffn
