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 <https://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 struct audit_ctx_s;
  26 typedef struct audit_ctx_s *audit_ctx_t;
  27
  28 /* Constants for the audit type.  */
  29 typedef enum
  30   {
  31     AUDIT_TYPE_NONE  = 0,  /* No type set.  */
  32     AUDIT_TYPE_ENCRYPT,    /* Data encryption.  */
  33     AUDIT_TYPE_SIGN,       /* Signature creation.  */
  34     AUDIT_TYPE_DECRYPT,    /* Data decryption.  */
  35     AUDIT_TYPE_VERIFY      /* Signature verification.  */
  36   }
  37 audit_type_t;
  38
  39 /* The events we support.  */
  40 typedef enum
  41   {
  42     AUDIT_NULL_EVENT = 0,
  43     /* No such event.  Its value shall be 0 and no other values shall
  44        be assigned to the other enum symbols.  This is required so
  45        that the exaudit.awk script comes up with correct values
  46        without running cc.  */
  47
  48     AUDIT_SETUP_READY,
  49     /* All preparations done so that the actual processing can start
  50        now.  This indicates that all parameters are okay and we can
  51        start to process the actual data.  */
  52
  53     AUDIT_AGENT_READY,   /* err */
  54     /* Indicates whether the gpg-agent is available.  For some
  55        operations the agent is not required and thus no such event
  56        will be logged.  */
  57
  58     AUDIT_DIRMNGR_READY,   /* err */
  59     /* Indicates whether the Dirmngr is available.  For some
  60        operations the Dirmngr is not required and thus no such event
  61        will be logged.  */
  62
  63     AUDIT_GPG_READY,   /* err */
  64     /* Indicates whether the Gpg engine is available. */
  65
  66     AUDIT_GPGSM_READY, /* err */
  67     /* Indicates whether the Gpgsm engine is available. */
  68
  69     AUDIT_G13_READY, /* err */
  70     /* Indicates whether the G13 engine is available. */
  71
  72     AUDIT_GOT_DATA,
  73     /* Data to be processed has been seen.  */
  74
  75     AUDIT_DETACHED_SIGNATURE,
  76     /* The signature is a detached one. */
  77
  78     AUDIT_CERT_ONLY_SIG,
  79     /* A certifciate only signature has been detected.  */
  80
  81     AUDIT_DATA_HASH_ALGO,  /* int */
  82     /* The hash algo given as argument is used for the data.  This
  83        event will be repeated for all hash algorithms used with the
  84        data.  */
  85
  86     AUDIT_ATTR_HASH_ALGO,  /* int */
  87     /* The hash algo given as argument is used to hash the message
  88        digest and other signed attributes of this signature. */
  89
  90     AUDIT_DATA_CIPHER_ALGO,  /* int */
  91     /* The cipher algo given as argument is used for this data.  */
  92
  93     AUDIT_BAD_DATA_HASH_ALGO,  /* string */
  94     /* The hash algo as specified by the signature can't be used.
  95        STRING is the description of this algorithm which usually is an
  96        OID string.  STRING may be NULL. */
  97
  98     AUDIT_BAD_DATA_CIPHER_ALGO,  /* string */
  99     /* The symmetric cipher algorithm is not supported.  STRING is the
 100        description of this algorithm which usually is an OID string.
 101        STRING may be NULL. */
 102
 103     AUDIT_DATA_HASHING,    /* ok_err */
 104     /* Logs the result of the data hashing. */
 105
 106     AUDIT_READ_ERROR,     /* ok_err */
 107     /* A generic read error occurred.  */
 108
 109     AUDIT_WRITE_ERROR,     /* ok_err */
 110     /* A generic write error occurred.  */
 111
 112     AUDIT_USAGE_ERROR,
 113     /* The program was used in an inappropriate way; For example by
 114        passing a data object while the signature does not expect one
 115        or vice versa.  */
 116
 117     AUDIT_SAVE_CERT,       /* cert, ok_err */
 118     /* Save the certificate received in a message. */
 119
 120     AUDIT_NEW_SIG,         /* int */
 121     /* Start the verification of a new signature for the last data
 122        object.  The argument is the signature number as used
 123        internally by the program.  */
 124
 125     AUDIT_SIG_NAME,        /* string */
 126     /* The name of a signer.  This is the name or other identification
 127        data as known from the signature and not the name from the
 128        certificate used for verification.  An example for STRING when
 129        using CMS is: "#1234/CN=Prostetnic Vogon Jeltz".  */
 130
 131     AUDIT_SIG_STATUS,      /* string */
 132     /* The signature status of the current signer.  This is the last
 133        audit information for one signature.  STRING gives the status:
 134
 135          "error"       - there was a problem checking this or any signature.
 136          "unsupported" - the signature type is not supported.
 137          "no-cert"     - The certificate of the signer was not found (the
 138                          S/N+issuer of the signer is already in the log).
 139          "bad"         - bad signature
 140          "good"        - good signature
 141     */
 142
 143     AUDIT_NEW_RECP,        /* int */
 144     /* A new recipient has been seen during decryption.  The argument
 145        is the recipient number as used internally by the program.  */
 146
 147     AUDIT_RECP_NAME,       /* string */
 148     /* The name of a recipient.  This is the name or other identification
 149        data as known from the decryption and not the name from the
 150        certificate used for decryption.  An example for STRING when
 151        using CMS is: "#1234/CN=Prostetnic Vogon Jeltz".  */
 152
 153     AUDIT_RECP_RESULT,    /* ok_err */
 154     /* The status of the session key decryption.  This is only written
 155        for recipients tried. */
 156
 157     AUDIT_DECRYPTION_RESULT,    /* ok_err */
 158     /* The status of the entire decryption.  The decryption was
 159        successful if the error code is 0. */
 160
 161     AUDIT_VALIDATE_CHAIN,
 162     /* Start the validation of a certificate chain. */
 163
 164     AUDIT_CHAIN_BEGIN,
 165     AUDIT_CHAIN_CERT,    /* cert */
 166     AUDIT_CHAIN_ROOTCERT,/* cert */
 167     AUDIT_CHAIN_END,
 168     /* These 4 events are used to log the certificates making up a
 169        certificate chain.  ROOTCERT is used for the trustanchor and
 170        CERT for all other certificates.  */
 171
 172     AUDIT_CHAIN_STATUS,  /* err */
 173     /* Tells the final status of the chain validation.  */
 174
 175     AUDIT_ROOT_TRUSTED,  /* cert, err */
 176     /* Tells whether the root certificate is trusted.  This event is
 177        emitted during chain validation.  */
 178
 179     AUDIT_CRL_CHECK, /* err */
 180     /* Tells the status of a CRL or OCSP check.  */
 181
 182     AUDIT_GOT_RECIPIENTS,  /* int */
 183     /* Records the number of recipients to be used for encryption.
 184        This includes the recipients set by --encrypt-to but records 0
 185        if no real recipient has been given.  */
 186
 187     AUDIT_SESSION_KEY,     /* string */
 188     /* Mark the creation or availibility of the session key.  The
 189        parameter is the algorithm ID.  */
 190
 191     AUDIT_ENCRYPTED_TO,   /* cert, err */
 192     /* Records the certificate used for encryption and whether the
 193        session key could be encrypted to it (err==0).  */
 194
 195     AUDIT_ENCRYPTION_DONE,
 196     /* Encryption succeeded.  */
 197
 198     AUDIT_SIGNED_BY,   /* cert, err */
 199     /* Records the certificate used for signed and whether the signure
 200        could be created (if err==0).  */
 201
 202     AUDIT_SIGNING_DONE,
 203     /* Signing succeeded.  */
 204
 205
 206     AUDIT_LAST_EVENT  /* Marker for parsing this list.  */
 207   }
 208 audit_event_t;
 209
 210
 211 audit_ctx_t audit_new (void);
 212 void audit_release (audit_ctx_t ctx);
 213 void audit_set_type (audit_ctx_t ctx, audit_type_t type);
 214 void audit_log (audit_ctx_t ctx, audit_event_t event);
 215 void audit_log_ok (audit_ctx_t ctx, audit_event_t event, gpg_error_t err);
 216 void audit_log_i (audit_ctx_t ctx, audit_event_t event, int value);
 217 void audit_log_s (audit_ctx_t ctx, audit_event_t event, const char *value);
 218 void audit_log_cert (audit_ctx_t ctx, audit_event_t event,
 219                      ksba_cert_t cert, gpg_error_t err);
 220
 221 void audit_print_result (audit_ctx_t ctx, estream_t stream, int use_html);
 222
 223
 224
 225 #endif /*GNUPG_COMMON_AUDIT_H*/