NAME

  Wotsap.pm - unpack, use, pack a Wotsap (PGP strong set) archive


SYNOPSIS

  use Wotsap ;
  $W -> Wotsap -> Make ( path => "/path/to/workdir" )
  $key = $W -> key ( '8b962943fc243f3c' ) ;
  $key -> id  # some unique number
  $key -> kid # 8b962943fc243f3c
  $key -> uid # the key's primary uid ; some name
  @keys = $key -> has_signed
  @keys = $key -> signed_by
  @sigs = $key -> signatures
  $sig -> src # id of the signing key
  $sig -> dst # id of the signed key
  $sig -> lvl # the sig's trust level
  $keys = $W -> keys # table keys ; a Wotsap::Tab::Keys object
  $sigs = $W -> sigs # table sigs ; a Wotsap::Tab::Sigs object
  $dbh  = $W -> dbh # the DBI database handle for workdir's wotsap.lite
  @keys = $W -> keys -> select ( where => '...', ... )
  @sigs = $W -> sigs -> select ( where => '...', ... )
  $list = $W -> xpaths ( $a, $b ) # some paths from key $a to key $b


DESCRIPTION

The Wotsap.pm module allows you to access a Wotsap archive. See http://pgp.cs.uu.nl/doc/ for a description of the Wotfile format.

A Wotsap archive is a densely packed file containing historic information about the PGP strong set. For definitions, please see the section DEFINITIONS. In short : the PGP strong set is a (maximal) set of PGP keys such that for every two keys in the set, there is a trust path from each one to the other.

Central to Wotsap.pm is the notion of a Wotsap working directory (workdir for short). A workdir is a just a directory containing stuff pertaining to one Wotsap archive.

A workdir may contain the following files :


Wotsap class methods

Make ( path => $path, [ option -> value, ... ] )

Method Make creates a workdir $path (if it doesn't exist) and/or stores option-values.

If $path exists, method Make checks that the specified options are compatible with the stuff in workdir $path.

Make recognizes these options :

version

The Wotsap version ; currently 0.2 or 0.3. The version is usually set by the import of a wotsap archive.

db_type

The workdir type ; currently import or export. The db_type is usually set by the import of a wotsap archive.

kserver

The fully qualified domain name of a PGP key-server.

prg_gpg

The path to gpg(1) ; default /usr/bin/gpg.


Wotsap instance methods

get ( $id )

Method get returns a Wotsap::Key object with the given id, or undef if no such key can be found.

key ( $key_id )

Method key returns a Wotsap::Key object with the given key_id, or undef if no such key can be found.

find_key ( $key_id )

Method find_key returns a Wotsap::Key object.

If $key_id is longer than the Wotsap's key-length, method find_key uses a proper suffix of $key_id.

If $key_id is shorter than the Wotsap's key-length, method find_key returns any key that has $key_id as a suffix of it's key_id. Note : this search is very expensive.

Method find_key returns undef if no key can be found.

xpaths ( $a, $b [, $max] )

Method xpaths searches for (atmost $max) paths from Wotsap::Key $a to Wotsap::Key $b.

The result is a list of key-lists :

  [ [ key, ... ], ... ]

where each key-list is a path from $a to $b with $a and $b omitted (the interior of a path from $a to $b).

If key $a signed key $b, the result is [[]].

If there are no paths from $a to $b, If the result is [].

If $a or $b is not defined, the result is undef.

All paths are disjunct (don't overlap).

path

The path of this Wotsap's workdir.

dbh

A database handle for this Wotsap's wotsap.lite.

keys

A Wotsap::Keys object, representing the database's keys table.

sigs

A Wotsap::Sigs object, representing the database's sigs table.

version

The wotsap-version (0.1, 0.2 or 0.3) of this Wotsap instance.

kid_len

The length (8 or 16) of key_id's in this Wotsap instance.


Wotsap::Tab

A Wotsap::Tab object represents a database table.

Wotsap::Tab is a stub for

  Wotsap::Tab::Keys
  Wotsap::Tab::Sigs

Wotsap::Tab class methods

row_pack

The result of method row_pack is 'Wotsap::Rec'.

This message should be overridden in a subclass of Wotsap::Tab. That method must return the (name of the) package used to create objects for rows of the subclass.

For instance :

  # package Wotsap::Tab::Keys ;
  sub row_pack { 'Wotsap::Key' ; }

Wotsap::Tab instance methods

name

The name of the sql-table.

base

A reference to the parent Wotsap object.

select ( [option => ..., ...] )

Select tuples from a table ; with the options you can build a query.

The result is a list of objects. The class of the objects is defined by the instance's attribute row_pack.

For instance, a select on a Wotsap::Tab::Keys object, results in a list of Wotsap::Key objects.

Option defaults are shown as => ...

cols => '*'

A comma-separated list of result columns.

from => ''

The sql from clause. Use from (and cols) if you want to do a join.

where => '', group_by => '', having => '', order_by => '', limit => ''

The usual clauses in an sql-select statement.

args => [ [] ]

Method select creates an sql-statement-handle, and then executes the select-statement once for each element ($tup) of $args with

  $sth -> execute ( @$tup ) ;

When using DBI placeholders, call select with args like :

  $W -> keys -> select ( where => "kid = ?", args => [ [$kid1], [$kid2] ] )
  $W -> sigs -> select
    ( where => "src = ? and dst = ?"
    , args =>
        [ [ $src1, $dst1 ]
        , [ $src2, $dst2 ]
        ]
    )
as_recs => 1

When set to 0, the result of the select is a list of plain hashes.

select1 ( [option => ..., ...] )

Same as select, except for this default :

  limit => 1

Method select1 returns the first record found, or undef if no record was found.

count ( [option => ..., ...] )

Same as select, except for these defaults :

  cols    => 'count(*) as _count_'
  limit   => 1
  as_recs => 0

Method count returns _count_ of the first record found.


Wotsap::Rec

A Wotsap::Rec object represents a row is a database table.

Wotsap::Rec is a stub for

  Wotsap::Key
  Wotsap::Sig

Wotsap::Rec instance methods

tabl

A reference to the parent Wotsap::Tab object.

This expression yields the parent Wotsap object of a record :

  $rec -> tabl -> base


Wotsap::Key

A Wotsap::Key object represents a key.

Wotsap::Key is a subclass of Wotsap::Rec.

Wotsap::Key instance methods

id

Some meaningless, unique number.

kid

The key's kid ; a lowercase 8- or 16-hex-digit string.

uid

The key's (primary) uid.

has_signed

Returns a list of Wotsap::Key objects ; the keys this key has signed.

signed_by

Returns a list of Wotsap::Key objects ; the keys that signed this key.

signatures

Returns a list of Wotsap::Sig objects ; the signatures on this key.


Wotsap::Sig

A Wotsap::Sig object represents a signature.

Wotsap::Sig is a subclass of Wotsap::Rec.

Wotsap::Sig instance methods

src
  The id of the signing key.
dst
  The id of the signed key.
lvl

The sig's trust level ; a number between 0 and seven. See the relevant specification for an interpretation.

In short, the last 2 bits represent the PGP check-level ; the third least-significant bit indicates that the signature was made on the key's primary uid.

  $sig -> lvl & 3 # check-level
  $sig -> lvl & 4 # sig on primary uid


DEFINITIONS


CAVEAT

This page describes how to access an imported wotsap-archive.

This page doesn't (yet) document how to create and update a wotsap archive.


SEE ALSO

wotsap(1)


AUTHOR

Wotsap © 2015 Henk P. Penning - All rights reserved ; Wotsap-0.02.08 - Sat Aug 19 15:46:06 2017

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl 5.10.0 README file.