db/shisa.h

   1 /* shisa.h --- Header file for concurrent write-safe user information database.
   2  * Copyright (C) 2003, 2004  Simon Josefsson
   3  *
   4  * This file is part of Shishi.
   5  *
   6  * Shishi 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 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * Shishi 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 Shishi; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
  19  *
  20  */
  21
  22 #ifndef SHISA_H
  23 #define SHISA_H
  24
  25 #include <stddef.h>             /* size_t */
  26 #include <time.h>               /* time_t */
  27 #include <shishi-int.h>         /* int32_t, uint32_t */
  28
  29 /* Error codes */
  30 enum Shisa_rc
  31 {
  32   SHISA_OK = 0,
  33   /* init.c */
  34   SHISA_INIT_ERROR = 1,
  35   /* cfg.c */
  36   SHISA_CFG_NO_FILE = 2,
  37   SHISA_CFG_IO_ERROR = 3,
  38   SHISA_CFG_SYNTAX_ERROR = 4,
  39   /* db.c: file.c */
  40   SHISA_OPEN_ERROR = 5,
  41   SHISA_ENUMERATE_REALM_ERROR = 6,
  42   SHISA_ENUMERATE_PRINCIPAL_ERROR = 7,
  43   SHISA_ENUMERATE_KEY_ERROR = 23,
  44   SHISA_NO_REALM = 8,
  45   SHISA_NO_PRINCIPAL = 9,
  46   SHISA_NO_KEY = 10,
  47   SHISA_FIND_ERROR = 11,
  48   SHISA_ADD_REALM_EXISTS = 12,
  49   SHISA_ADD_REALM_ERROR = 13,
  50   SHISA_REMOVE_REALM_NONEMPTY = 14,
  51   SHISA_REMOVE_REALM_ERROR = 15,
  52   SHISA_ADD_PRINCIPAL_EXISTS = 16,
  53   SHISA_ADD_PRINCIPAL_ERROR = 17,
  54   SHISA_REMOVE_PRINCIPAL_NONEMPTY = 18,
  55   SHISA_REMOVE_PRINCIPAL_ERROR = 19,
  56   SHISA_ADD_KEY_ERROR = 20,
  57   SHISA_REMOVE_KEY_ERROR = 21,
  58   SHISA_MULTIPLE_KEY_MATCH = 22
  59 };
  60 typedef enum Shisa_rc Shisa_rc;
  61
  62 typedef struct Shisa Shisa;
  63
  64 struct Shisa_principal
  65 {
  66   int isdisabled;
  67   uint32_t kvno;
  68   time_t notusedbefore;
  69   time_t lastinitialtgt;        /* time of last initial request for a TGT */
  70   time_t lastinitialrequest;    /* time of last initial request */
  71   time_t lasttgt;               /* time of issue for the newest TGT used */
  72   time_t lastrenewal;           /* time of the last renewal */
  73   time_t passwordexpire;        /* time when the password will expire */
  74   time_t accountexpire;         /* time when the account will expire. */
  75 };
  76 typedef struct Shisa_principal Shisa_principal;
  77
  78 struct Shisa_key
  79 {
  80   uint32_t kvno;
  81   int32_t etype;
  82   int priority;
  83   char *key;
  84   size_t keylen;
  85   char *salt;
  86   size_t saltlen;
  87   char *str2keyparam;
  88   size_t str2keyparamlen;
  89   char *password;
  90 };
  91 typedef struct Shisa_key Shisa_key;
  92
  93 /* init.c */
  94 extern Shisa *shisa (void);
  95 extern void shisa_done (Shisa * dbh);
  96 extern int shisa_init (Shisa ** dbh);
  97 extern int shisa_init_with_paths (Shisa ** dbh, const char *file);
  98
  99 /* cfg.c */
 100 extern int shisa_cfg (Shisa * dbh, char *option);
 101 extern int shisa_cfg_db (Shisa * dbh, const char *value);
 102 extern int shisa_cfg_from_file (Shisa * dbh, const char *cfg);
 103 extern const char *shisa_cfg_default_systemfile (Shisa * dbh);
 104
 105 /* error.c */
 106 extern const char *shisa_strerror (int err);
 107 extern void shisa_info (Shisa * dbh, const char *format, ...);
 108
 109 /* core.c */
 110 extern void shisa_key_free (Shisa * dbh, Shisa_key * key);
 111 extern void shisa_keys_free (Shisa * dbh, Shisa_key ** keys, size_t nkeys);
 112
 113 /************************************************************** Enumerators. */
 114
 115 /* Return a list of all realm names in backend, as zero-terminated
 116    UTF-8 strings.  The caller must deallocate the strings. */
 117 extern int shisa_enumerate_realms (Shisa * dbh,
 118                                    char ***realms, size_t * nrealms);
 119
 120 /* Return a list of all principals in realm in backend, as
 121    zero-terminated UTF-8 strings.  The caller must deallocate the
 122    strings. */
 123 extern int shisa_enumerate_principals (Shisa * dbh,
 124                                        const char *realm,
 125                                        char ***principals,
 126                                        size_t * nprincipals);
 127
 128 /**************************************** Functions operating on principals. */
 129
 130 /* Return information about specified PRINCIPAL@REALM.  Can also be
 131    used check existence of principal entry, with a NULL PH. */
 132 extern int shisa_principal_find (Shisa * dbh,
 133                                  const char *realm,
 134                                  const char *principal, Shisa_principal * ph);
 135
 136 /* Add new PRINCIPAL@REALM with specified information and key.  If
 137    PRINCIPAL is NULL, then add realm REALM. */
 138 extern int shisa_principal_add (Shisa * dbh,
 139                                 const char *realm,
 140                                 const char *principal,
 141                                 const Shisa_principal * ph,
 142                                 const Shisa_key * key);
 143
 144 /* Modify information for specified PRINCIPAL@REALM.  */
 145 extern int shisa_principal_update (Shisa * dbh,
 146                                    const char *realm,
 147                                    const char *principal,
 148                                    const Shisa_principal * ph);
 149
 150 /* Remove PRINCIPAL@REALM, or REALM if PRINCIPAL is NULL.  Realms must
 151    be empty for them to be successfully removed.  */
 152 extern int shisa_principal_remove (Shisa * dbh,
 153                                    const char *realm, const char *principal);
 154
 155 /********************************************** Functions operating on keys. */
 156
 157 /* Get all keys matching HINT for specified PRINCIPAL@REALM.  The
 158    caller must deallocate the returned keys.  If HINT is NULL, then
 159    all keys are returned. */
 160 extern int shisa_keys_find (Shisa * dbh,
 161                             const char *realm,
 162                             const char *principal,
 163                             const Shisa_key * hint,
 164                             Shisa_key *** keys, size_t * nkeys);
 165
 166 /* Add key for PRINCIPAL@REALM. */
 167 extern int shisa_key_add (Shisa * dbh,
 168                           const char *realm,
 169                           const char *principal, const Shisa_key * key);
 170
 171 /* Update a key for PRINCIPAL@REALM.  The OLDKEY must uniquely
 172    determine the key to update, i.e., shishi_keys_find using OLDKEY as
 173    HINT must return exactly 1 key.  */
 174 extern int shisa_key_update (Shisa * dbh,
 175                              const char *realm,
 176                              const char *principal,
 177                              const Shisa_key * oldkey,
 178                              const Shisa_key * newkey);
 179
 180 /* Remove a key for PRINCIPAL@REALM.  The KEY must uniquely determine
 181    the key to remove, i.e., shishi_keys_find using KEY as HINT must
 182    return exactly 1 key.  */
 183 extern int shisa_key_remove (Shisa * dbh,
 184                              const char *realm,
 185                              const char *principal, const Shisa_key * key);
 186
 187 #endif /* SHISA_H */