README.txt
author Damiano Boppart <damiano@pep-security.net>
Wed, 23 Aug 2017 11:06:55 +0000
branchENGINE-228
changeset 1993 efaeadf3e6f0
parent 1989 d3e5bc4a9854
permissions -rw-r--r--
Merge in default
     1 # this file is under Creative Commons License 3.0 cc-by-sa
     2 
     3 p≡p Engine
     4 ==========
     5 
     6 0. What it is
     7 -------------
     8 
     9 The p≡p engine is a Free Software library encapsulating implementations of:
    10 
    11 - Key Management
    12 
    13   Key Management in p≡p engine is based on GnuPG key chains (NetPGP on iOS).
    14   Keys are stored in an OpenPGP compatbile format and can be used for different
    15   crypto implementations.
    16 
    17 - Trust Rating
    18 
    19   p≡p engine is sporting a two phase trust rating system. In phase one there is
    20   a rating based on channel, crypto and key security named “comm_types”. In
    21   phase 2 these are mapped to user representable values which have attached
    22   colors to present them in traffic light semantics.
    23 
    24 - Abstract Crypto API
    25 
    26   The Abstract Crypto API is providing functions to encrypt and decrypt data or
    27   full messages without requiring an application programmer to understand the
    28   different formats and standards.
    29 
    30 - Message Transports
    31 
    32   p≡p engine will sport a growing list of Message Transports to support any
    33   widespread text messaging system including E-Mail, SMS, XMPP and many more.
    34 
    35 p≡p engine is written in C99. It is not meant to be used in application code
    36 directly. Instead, p≡p engine is coming together with a list of software
    37 adapters for a variety of programming languages and development environments.
    38 
    39 p≡p engine is under Gnu General Public License v3. If you want to use it under
    40 a different license, please contact mailto:council@pep.foundation.
    41 
    42 
    43 1. Dependencies
    44 ---------------
    45 
    46 p≡p engine is depending on the following FOSS libraries:
    47 
    48 * libetpan, see https://github.com/fdik/libetpan
    49        git clone https://github.com/fdik/libetpan
    50 
    51 * zlib, see http://zlib.net/
    52 
    53 * OpenSSL, see http://openssl.org/
    54 
    55 * iconv, see http://www.gnu.org/software/libiconv/
    56 
    57 * Cyrus SASL, see http://cyrusimap.org/
    58 
    59 * GnuPG via GPGME, version 1.6.0 or newer, see https://gnupg.org/
    60 
    61 * NetPGP/p≡p, see https://cacert.pep.foundation/dev/repos/netpgp-et/
    62 
    63 * Asn1c, download from https://lionet.info/soft/asn1c-0.9.27.tar.gz . Debian 8's v0.9.24 does not work. Debian 9's v0.9.27 generates non-POSIX code, that will cause issues when the engine is compiled with '-std=c99'. Thus, use v0.9.28 for best results.
    64 
    65 * yml2, which needs lxml (where to get?)
    66 
    67 2. Building p≡p engine
    68 ----------------------
    69 
    70 p≡p engine has an old style Makefile for building it.
    71 
    72 The build is configured in Makefile.conf
    73 
    74 It supports the common targets
    75 
    76 $ make all
    77 $ make install
    78 $ make clean
    79 
    80 and additionally
    81 
    82 $ make package # for building a .tar.bz2 with the source distribution
    83 
    84 On Windows, use Visual Studio.
    85 
    86 
    87 3. How to cross-build
    88 ---------------------
    89 
    90 For cross-building, BUILD_FOR is being used. I.e.:
    91 
    92 $ BUILD_FOR=yourOS make -e
    93 
    94 
    95 4. How to build the databases
    96 -----------------------------
    97 
    98 p≡p Engine uses two databases: ~/.pEp_management (on *NIX) or
    99 %LOCALAPPDATA%\pEp\management.db on Windoze respectively, and
   100 /usr/local/share/system.db on *NIX or %ALLUSERSPROFILE%\pEp\system.db
   101 respectively. The latter contains the Trustwords dbs.
   102 
   103 The managment db is being created by the first call of init() of p≡p Engine. It
   104 does not need to be created manually. system.db is being created by using the
   105 DDL in db/create_system_db.sql – the content is created by db/dic2csv.py
   106 out of hunspell's dictionary packages (or something similar) and then being
   107 imported using sqlite3's .import command. Dictionary files for different
   108 languages are part of p≡p engine source distribution.
   109 
   110 $ make db
   111 $ make -C db install
   112 
   113 You can test the Trustwords in system.db using db/trustwords.py
   114 Both Python tools have a switch --help
   115 
   116 
   117 5. How to run the tests
   118 -----------------------
   119 
   120 You have to import all the test keys into your local gpg instance:
   121 
   122 	cd test
   123 	cat 0x*.asc *_sec.asc| gpg --import
   124