xoxa.h

Go to the documentation of this file.

/* xoxa.h.prefix ... */
/* This file is part of the Xoxa library: https://bitbucket.org/nxg/xoxa
 * Copyright 2013, 2014, Norman Gray <http://nxg.me.uk>.
 * It is distributed under the terms of the BSD 2-clause Licence;
 * see the file LICENCE for details.
 */

/* util_types.h ... */
#ifndef UTIL_TYPES_H_READ
#define UTIL_TYPES_H_READ 1

// This header contains types which are used in util.h, and which are
// also used in xml_expat.h, which util.h includes.  Separate them out
// here to avoid an import loop.

#include <stdlib.h>
#include <stdint.h>

typedef uint8_t byte;

typedef struct {
    size_t nwritten;
    size_t len;
    byte* buf;
} Buf;

#endif /* UTIL_TYPES_H_READ */
/* pgp_types.h ... */
#ifndef PGP_TYPES_H_READ
#define PGP_TYPES_H_READ 1

#include <sys/select.h>

//#include "util_types.h"

// This header contains types which are used in pgp.h, and which are
// also used in xml_expat.h, which pgp.h includes.  Separate them out
// here to avoid an import loop.

#if XOXA_PRIVATE_INTERFACE
// A channel for communicating with the subprocess.  Note that the
// Channel is a read or write channel _from the point of view of the
// parent process_ rather than the child.
//
// Creating a writing channel (non-zero argument to new_channel)
// creates a Buf within the channel; creating a reading channel does
// not, and one must be added to the channel subsequently.
typedef struct {
    int fd[2];                  // fd[0]=read end; fd[1]=write end
    Buf* buf;                   // the content to be written, or into which the pipe will be read
    ssize_t nwritten;           // negative if this channel is to be read from
} Channel;
#define CHANNEL_FOR_WRITING_P(ch) ((ch)->nwritten >= 0)
// Retrieve the FD associated with this Channel; this will be open for
// reading (respectively writing) if the Channel is a read (write) one.
#define CHANNEL_GET_FD(ch)        (CHANNEL_FOR_WRITING_P(ch) ? (ch)->fd[1] : (ch)->fd[0])
// Get the _other_ FD, which is the FD associated with the other
// end of the Channel's pipe, in the child.
#define CHANNEL_GET_CHILD_FD(ch)  (CHANNEL_FOR_WRITING_P(ch) ? (ch)->fd[0] : (ch)->fd[1])

typedef struct process_manager_s {
    int in;                     // the write end of a pipe, which goes to the subprocess stdin
    char nchan;                 // the number of extra channels (including the subprocess stdout/stderr)
    Channel** ch;               // the other channels
    pid_t child;                // the PID of the subprocess
    fd_set readable;            // a mask of the readable channels
} ProcessManager;
#endif /* XOXA_PRIVATE_INTERFACE */

typedef enum { good_sig, bad_sig, unknown } GPGResult;

typedef struct gpg_result_s {
    GPGResult status;
    union {
        struct {
            char* keyid;
            char* username;
        } goodsig;
        struct {
            char* keyid;
            char* username;
        } badsig;
    } detail;
    const char* stderr;         // content of GPG stderr, or NULL if unavailable
} SignatureDetail;


#endif /* PGP_TYPES_H_READ */
/* xml_expat.h ... */
#ifndef XML_EXPAT_H
#define XML_EXPAT_H 1

#include <stdio.h>
#include <stdint.h>
#include <setjmp.h>

#include <expat.h>

//#include "util_types.h"
//#include "pgp_types.h"

struct ParserState_s;
typedef struct ParserState_s ParserState;



typedef void (*output_callback_t)(const byte* bytes, size_t len, void* data);

typedef void (*output_callback_end_t)(ParserState*, void* data);

int xoxa_push_output_callback(ParserState* P,
                              output_callback_t cb,
                              void* data,
                              const char* label);

void xoxa_register_output_callback_finalizer(ParserState* P,
                                             output_callback_end_t cb_end);

// public interface

typedef uint8_t ParserFlags;
// the flag values are only for communication with the xoxa_parser_flags function
#define XOXA_REPORT_ALL         1<<0
// the following three occupy two bits; XOXA_CHATTER also acts as a mask for these
#define XOXA_QUIET              1<<1
#define XOXA_FEEDBACK           2<<1
#define XOXA_CHATTER            3<<1
#if XOXA_PRIVATE_INTERFACE
#define SHOWING_MESSAGES(PS_P) ((PS_P)->flags.verbosity > 0)
#define SHOWING_CHATTER(PS_P)  ((PS_P)->flags.verbosity > 1)
#endif

#define INPUT_SOURCE_STRING 0
#define INPUT_SOURCE_FILE 1
typedef struct {
    char type;                  // INPUT_SOURCE_*
    const char* basename;       // the filename, in the case of in.f
    union {
        const char* buffer;
        FILE* f;
    } in;
} InputSource;

struct callback_frame_s {
    output_callback_t f;
    output_callback_end_t f_end;
    unsigned int startdepth;
    void* data;
    const char* label;          // a printable label for this frame
    struct callback_frame_s* down;
};
typedef struct callback_frame_s callback_frame_t;
#define VALID_CALLBACK_FRAME(FRAME) ((FRAME)->f != NULL)


struct ParserState_s {
    XML_Parser parser;
    InputSource *src;
    callback_frame_t* callback;
    // element_depth is incremented at the start of any element,
    // and decremented at its end
    unsigned int element_depth;
    Buf* B;
    Buf* text;
    char text_skipping_whitespace; // values of this are private to xml_expat.c
    struct {
        unsigned int report_all    : 1;
        unsigned int verbosity     : 2; // values 0, 1, 2
#define XOXA_DIGEST_TYPE_NONE 0
#define XOXA_DIGEST_TYPE_MD 1
#define XOXA_DIGEST_TYPE_PGP 2
        // also indicates whether pgp or digest is used in union 'd' below
        unsigned int digest_type   : 2;
    } flags;
    union {
        struct {
            void* ctx;
            byte* bytes;
            unsigned int len;
        } digest;
        SignatureDetail pgp;    // if parser_flags & XOXA_DIGEST_IS_PGP_
    } d;
    // following three are filled in from a <?signature?> PI
    const char* signature_armor;
    const char* signature_xpath;
    const char* signature_algorithm;
    output_callback_t signature_callback;
    void* signature_callback_data;
    jmp_buf* error_jmp_buf;
    char* error_message;        // NULL if no error

    // The following extra_* functions are so that we can insert the
    // Xoxa handlers in between the caller and the underlying Expat
    // handlers, and so implement the Expat interface transparently.
    // Each Xoxa handler is written so that it calls the corresponding
    // extra_* handler as well.
    XML_StartElementHandler extra_StartElementHandler;
    XML_EndElementHandler extra_EndElementHandler;
    XML_CharacterDataHandler extra_CharacterDataHandler;
    XML_ProcessingInstructionHandler extra_ProcessingInstructionHandler;
    XML_StartCdataSectionHandler extra_StartCdataSectionHandler;
    XML_EndCdataSectionHandler extra_EndCdataSectionHandler;
    XML_StartNamespaceDeclHandler extra_StartNamespaceDeclHandler;
    XML_EndNamespaceDeclHandler extra_EndNamespaceDeclHandler;
    XML_XmlDeclHandler extra_XmlDeclHandler;
    XML_SkippedEntityHandler extra_SkippedEntityHandler;
    void* extra_UserData;
};

#if XOXA_PRIVATE_INTERFACE
ParserState* xoxa_make_new_parserstate_(InputSource* src,
                                        XML_Parser parser,
                                        ParserState* copy_of);

// assertions for checking the ParserState structure.
// P->src may be NULL, if we're planning to use the GetBuffer
// mechanism to read the content, rather than xoxa_parse_*.
#define PARSERSTATE_OK_TEST_(P)                 \
    ((P) != NULL                                \
     && (P)->parser != NULL                     \
     && (P)->B != NULL                          \
     && (P)->text != NULL)
#define OK_PARSERSTATE(P) do {                  \
        assert(PARSERSTATE_OK_TEST_(P));        \
    } while (0)

// Allocate and fail on any memory errors
#define MALLOC(var, Type) if ((var = (Type*)malloc(sizeof(Type))) == NULL) { \
        fatal("Can't allocate space for " # Type);                      \
    }

#endif /* XOXA_PRIVATE_INTERFACE */

ParserState* xoxa_new_parser(InputSource*);
void xoxa_parser_flags(ParserState*, ParserFlags);
void xoxa_release_parser(ParserState*);

int xoxa_parse(ParserState*);
void xoxa_signature_fd(ParserState*, int);
byte* xoxa_get_digest(ParserState*, size_t*);
SignatureDetail* xoxa_get_signature(ParserState* P);

void xoxa_null_callback(const byte* buf, size_t len, void* data);
void xoxa_default_callback(const byte* buf, size_t len, void* data);

const char* xoxa_error_message(ParserState*);

InputSource* xoxa_new_input_source_from_string(const char* xmlcontent);
InputSource* xoxa_new_input_source_from_filename(const char* filename);
InputSource* xoxa_new_input_source_from_fd(const int fd);

const char* xoxa_parser_library_ident(void);

#endif /* XML_EXPAT_H */
/* util.h ... */
#ifndef READ_UTIL_H
#define READ_UTIL_H 1

//#include "util_types.h"
//#include "xml_expat.h"


const char* xoxa_version_string(void);

#ifdef XOXA_PRIVATE_INTERFACE

#include <setjmp.h>

void fatal(const char* fmt, ...);
void warning(const char* fmt, ...);
void xoxa_set_error_message_(ParserState*, int abandon_parse_p, const char* fmt, ...);
void xoxa_abandon_parse_(ParserState*);
void xoxa_jmp_set_(ParserState*, jmp_buf*);
void xoxa_jmp_clear_(ParserState*);
int isxmlspace(const byte* p);

byte* copystring(const byte* s);

Buf* bufinit(void);
Buf* bufinit_with(const byte*);
Buf* bufprintf(Buf* B, const char* fmt, ...);
Buf* bufchar(Buf* B, byte c);
Buf* bufstrcpy(Buf* dst, const byte* src);
Buf* bufstrncpy(Buf* dst, const byte* src, const size_t len);
Buf* bufcrop(Buf* B);
byte* bufstring(Buf* B);
byte* bufstring_copy(Buf* B);
void bufreset(Buf* B);
size_t buflength(Buf*);
void buffree(Buf*);

int bufstrcmp(const byte* b1, const byte* b2);

#endif /* XOXA_PRIVATE_INTERFACE */

#endif /* READ_UTIL_H */
/* digest.h ... */
#ifndef READ_DIGEST_H
#define READ_DIGEST_H 1

//#include "xml_expat.h"

// xoxa_parse_for_digest is implemented in digest.c
// xoxa_digest_{initialize,finalize} are implemented in digest_???.c

int xoxa_parse_for_digest(ParserState* parser,
                          const char* digest_name);

int xoxa_digest_initialize(ParserState* parser,
                           const char* digest_name);

int xoxa_digest_is_initialized(ParserState* parser);

const char* xoxa_digest_library_ident(void);

#endif /* READ_DIGEST_H */
/* pgp.h ... */
#ifndef PGP_H_LOADED
#define PGP_H_LOADED 1

// The functions and structs in this header file are visible outside this module,
// but they are not part of the Xoxa public interface.

//#include "util_types.h"
//#include "pgp_types.h"
//#include "xml_expat.h"

#if XOXA_PRIVATE_INTERFACE

#define CHANNEL_WRITE 1
#define CHANNEL_READ 0
Channel* new_channel(char writing_p); // call with non-zero to create a writing channel
void channel_free(Channel*);
int channel_add_buffer(Channel* ch, Buf* b); // can only be called with a writing channel
void subprocess_free(ProcessManager* pm);
int subprocess_send(ProcessManager* pm, const char* buf, size_t buflen);
ProcessManager* new_subprocess(char** cmd, ...);
ProcessManager* pgp_verify_detached(Channel* signature, Channel* status_info);
SignatureDetail* gpg_signature_init(SignatureDetail*);
SignatureDetail* gpg_parse_status(Channel* chatter, SignatureDetail* detail);
#endif /* XOXA_PRIVATE_INTERFACE */

void gpg_signature_free(SignatureDetail*);
int xoxa_pgp_verify_initialize(ParserState* PS);
SignatureDetail* xoxa_parse_for_pgp_verify(ParserState* PS);

// Name for the algorithm
//#define PGP_ALGORITHM_NAME "http://ns.nxg.me.uk/xoxa/algo#openpgp"
#define PGP_ALGORITHM_NAME "pgp"

#endif /* PGP_H_LOADED */