common/audit.h

   1 /* audit.h - Definitions for the audit subsystem
   2  *      Copyright (C) 2007 Free Software Foundation, Inc.
   3  *
   4  * This file is part of GnuPG.
   5  *
   6  * GnuPG is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * GnuPG is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #ifndef GNUPG_COMMON_AUDIT_H
  21 #define GNUPG_COMMON_AUDIT_H
  22
  23 #include <ksba.h>
  24
  25 #include "estream.h"
  26
  27 struct audit_ctx_s;
  28 typedef struct audit_ctx_s *audit_ctx_t;
  29
  30 /* Constants for the audit type.  */
  31 typedef enum
  32   {
  33     AUDIT_TYPE_NONE  = 0,  /* No type set.  */
  34     AUDIT_TYPE_ENCRYPT,    /* Data encryption.  */
  35     AUDIT_TYPE_SIGN,       /* Signature creation.  */
  36     AUDIT_TYPE_DECRYPT,    /* Data decryption.  */
  37     AUDIT_TYPE_VERIFY      /* Signature verification.  */
  38   }
  39 audit_type_t;
  40
  41 /* The events we support.  */
  42 typedef enum
  43   {
  44     AUDIT_NULL_EVENT = 0,
  45     /* No such event.  Its value shall be 0 and no other values shall
  46        be assigned to the other enum symbols.  This is required so
  47        that the exaudit.awk script comes up with correct values
  48        without running cc.  */
  49
  50     AUDIT_SETUP_READY,
  51     /* All preparations done so that the actual processing can start
  52        now.  This indicates that all parameters are okay and we can
  53        start to process the actual data.  */
  54
  55     AUDIT_AGENT_READY,   /* err */
  56     /* Indicates whether the gpg-agent is available.  For some
  57        operations the agent is not required and thus no such event
  58        will be logged.  */
  59
  60     AUDIT_DIRMNGR_READY,   /* err */
  61     /* Indicates whether the Dirmngr is available.  For some
  62        operations the Dirmngr is not required and thus no such event
  63        will be logged.  */
  64
  65     AUDIT_GOT_DATA,
  66     /* Data to be processed has been seen.  */
  67
  68     AUDIT_DETACHED_SIGNATURE,
  69     /* The signature is a detached one. */
  70
  71     AUDIT_CERT_ONLY_SIG,
  72     /* A certifciate only signature has been detected.  */
  73
  74     AUDIT_DATA_HASH_ALGO,  /* int */
  75     /* The hash algo given as argument is used for this signature.
  76        This event will be repeated for all hash algorithms used with
  77        the data.  */
  78
  79     AUDIT_BAD_DATA_HASH_ALGO,  /* string */
  80     /* The hash algo as specified by the signature can't be used.
  81        STRING is the description of this algorithm which usually is an
  82        OID string.  STRING may be NULL. */
  83
  84     AUDIT_DATA_HASHING,    /* ok_err */
  85     /* Logs the result of the data hashing. */
  86
  87     AUDIT_READ_ERROR,     /* ok_err */
  88     /* A generic read error occurred.  */
  89
  90     AUDIT_WRITE_ERROR,     /* ok_err */
  91     /* A generic write error occurred.  */
  92
  93     AUDIT_USAGE_ERROR,
  94     /* The program was used in an inappropriate way; For example by
  95        passing a data object while the signature does not expect one
  96        or vice versa.  */
  97
  98     AUDIT_SAVE_CERT,       /* cert, ok_err */
  99     /* Save the certificate received in a message. */
 100
 101     AUDIT_NEW_SIG,         /* int */
 102     /* Start the verification of a new signature for the last data
 103        object.  The argument is the signature number as used
 104        internally by the program.  */
 105
 106     AUDIT_SIG_NAME,        /* string */
 107     /* The name of a signer.  This is the name or other identification
 108        data as known from the signature and not the name from the
 109        certificate used for verification.  An example for STRING when
 110        using CMS is: "#1234/CN=Prostetnic Vogon Jeltz".  */
 111
 112     AUDIT_SIG_STATUS,     /* string */
 113     /* The signature status of the current signer.  This is the last
 114        audit information for one signature.  STRING gives the status:
 115
 116          "error"       - there was a problem checking this or any signature.
 117          "unsupported" - the signature type is not supported.
 118          "no-cert"     - The certificate of the signer was not found (the
 119                          S/N+issuer of the signer is already in the log).
 120          "bad"         - bad signature
 121          "good"        - good signature
 122     */
 123
 124     AUDIT_VALIDATE_CHAIN,
 125     /* Start the validation of a certificate chain. */
 126
 127     AUDIT_CHAIN_BEGIN,
 128     AUDIT_CHAIN_CERT,    /* cert */
 129     AUDIT_CHAIN_ROOTCERT,/* cert */
 130     AUDIT_CHAIN_END,
 131     /* These 4 events are used to log the certificates making up a
 132        certificate chain.  ROOTCERT is used for the trustanchor and
 133        CERT for all other certificates.  */
 134
 135     AUDIT_CHAIN_STATUS,  /* err */
 136     /* Tells the final status of the chain validation.  */
 137
 138     AUDIT_ROOT_TRUSTED,  /* cert, err */
 139     /* Tells whether the root certificate is trusted.  This event is
 140        emmited durcing chain validation.  */
 141
 142     AUDIT_GOT_RECIPIENTS,  /* int */
 143     /* Records the number of recipients to be used for encryption.
 144        This includes the recipients set by --encrypt-to but records 0
 145        if no real recipient has been given.  */
 146
 147     AUDIT_SESSION_KEY,     /* string */
 148     /* Mark the creation or availibility of the session key.  The
 149        parameter is the algorithm ID.  */
 150
 151     AUDIT_ENCRYPTED_TO,   /* cert, err */
 152     /* Records the certificate used for encryption and whether the
 153        session key could be encrypted to it (err==0).  */
 154
 155     AUDIT_ENCRYPTION_DONE,
 156     /* Encryption succeeded.  */
 157
 158
 159
 160
 161     AUDIT_LAST_EVENT  /* Marker for parsing this list.  */
 162   }
 163 audit_event_t;
 164
 165
 166 audit_ctx_t audit_new (void);
 167 void audit_release (audit_ctx_t ctx);
 168 void audit_set_type (audit_ctx_t ctx, audit_type_t type);
 169 void audit_log (audit_ctx_t ctx, audit_event_t event);
 170 void audit_log_ok (audit_ctx_t ctx, audit_event_t event, gpg_error_t err);
 171 void audit_log_i (audit_ctx_t ctx, audit_event_t event, int value);
 172 void audit_log_s (audit_ctx_t ctx, audit_event_t event, const char *value);
 173 void audit_log_cert (audit_ctx_t ctx, audit_event_t event,
 174                      ksba_cert_t cert, gpg_error_t err);
 175
 176 void audit_print_result (audit_ctx_t ctx, estream_t stream, int use_html);
 177
 178
 179
 180 #endif /*GNUPG_COMMON_AUDIT_H*/