libqaeda

Unnamed repository; edit this file 'description' to name the repository.
Info | Log | Files | Refs | README | LICENSE

README.md (3986B)

      1 # libqaeda
      2 
      3 The aim of this library is to enable bi-lateral countersigning of chains of promises and statements.
      4 
      5 There are many use-cases to imagine, among which:
      6 
      7 * Authenticity and proof-of-ownership of certificates.
      8 * Credit tracking between individuals
      9 
     10 See bottom of document for development related information.
     11 
     12 
     13 ## Design 
     14 
     15 
     16 ### Certificate
     17 
     18 The highest level construct in the library is the certificate `LQCert`.
     19 
     20 It consists of two messages, a request and a response.
     21 
     22 The request message is authored  and signed first then transmitted to the responder.
     23 
     24 The responder authors its own message, and signed its message together with the signature of the request.
     25 
     26 The certificate may optionally be linked to a previous `LQCert`. In this case both the request and response signature are also made over the linked certificate.
     27 
     28 
     29 #### Certificate domain
     30 
     31 An arbirary domain byte string can be defined for each certificate.
     32 
     33 This is intended for use at the application level, to decide whether a certificate is relevant, and how to process it.
     34 
     35 The domain is also part of the request and response signatures.
     36 
     37 
     38 ### Message
     39 
     40 Both the request and response message use the same data structure, the `LQMsg`.
     41 
     42 The message contents are stores as a digest of the message itself.
     43 
     44 This digest is serialized together with the nanosecond timestamp when the message was created, and the public key that will sign the message. The serialized message is then added to the certificate.
     45 
     46 
     47 ### Resolving content
     48 
     49 `libqaeda` defines a key-value store interface, that is embedded into message creation, certificate creation and public key stores.
     50 
     51 On message creation, the message contents will be `put` into the store keyed by its digest. This store can be a network store, a local disk, a database, memory - any backend possible to implement.
     52 
     53 Once the message is recovered, the same store can be used to `get` the content by the same key.
     54 
     55 
     56 ### Trust handling
     57 
     58 One function of a store is to keep a dictionary of public keys and their trust data.
     59 
     60 This is used by the application data to decide whether or not a signature belongs to a public key that is known, and how and for what the public key can be trusted.
     61 
     62 The trust module allows for a range of behaviors, from only checking whether a public key exists, to trust ratios calculated by matching application defined trust flags.
     63 
     64 
     65 ### Cryptography.
     66 
     67 Crypto is defined as an interface.
     68 
     69 The aim is to allow for any public-key crypto backend to be implemented. 
     70 
     71 Key handling is abstracted by two data structures, `LQPrivKey` and `LQPubKey`. The `LQPubKey` structure may or may not contain the `LQPrivKey`.
     72 
     73 Signatures are encapsulated by `LQSig`. This structure must contain the public key, unless the signature implementation allows for keys being recovered from signatures.
     74 
     75 
     76 ### IO handling
     77 
     78 Similarly as with the cryptography component, the component for memory handling and io operations only defines an interface.
     79 
     80 The aim is to grant greater control to the application author to implement handling for environments like phones, webassembly and so on.
     81 
     82 
     83 ## Development status
     84 
     85 **This software is strictly alpha and not safe in any way.**
     86 
     87 * File content store currently has hardcoded unix/linux file operation functions.
     88 * Memory and IO currently only implements standard library.
     89 * Currently only contains dummy crypto backend.
     90 * Not threads audited.
     91 * All private keys are currently unencrypted.
     92 * There are probably memory leaks.
     93 
     94 
     95 ### Dependencies
     96 
     97 * `libasn1`
     98 * `libcheck` (tests)
     99 
    100 
    101 ### Example code
    102 
    103 Please refer to the `src/test` directory. There are no other examples.
    104 
    105 
    106 ## License
    107 
    108 The `libqaeda` library is provided under the Affero Gnu Public License 3.0 (`AGPL3`) license.
    109 
    110 All documentation is provided under the Creative Commons Attribution Share-alike International 4.0 license (`CC-BY-SA-4.0`).
    111 
    112 This repository contains other code sources that may be subject under other licenses. Please see `src/aux` for more details.