crypto/store/README

   1 The STORE type
   2 ==============
   3
   4 A STORE, as defined in this code section, is really a rather simple
   5 thing which stores objects and per-object associations to a number
   6 of attributes.  What attributes are supported entirely depends on
   7 the particular implementation of a STORE.  It has some support for
   8 generation of certain objects (for example, keys and CRLs).
   9
  10
  11 Supported object types
  12 ----------------------
  13
  14 For now, the objects that are supported are the following:
  15
  16 X.509 certificate
  17 X.509 CRL
  18 private key
  19 public key
  20 number
  21 arbitrary (application) data
  22
  23 The intention is that a STORE should be able to store everything
  24 needed by an application that wants a cert/key store, as well as
  25 the data a CA might need to store (this includes the serial number
  26 counter, which explains the support for numbers).
  27
  28
  29 Supported attribute types
  30 -------------------------
  31
  32 For now, the following attributes are supported:
  33
  34 Friendly Name           - the value is a normal C string
  35 Key ID                  - the value is a 160 bit SHA1 hash
  36 Issuer Key ID           - the value is a 160 bit SHA1 hash
  37 Subject Key ID          - the value is a 160 bit SHA1 hash
  38 Issuer/Serial Hash      - the value is a 160 bit SHA1 hash
  39 Issuer                  - the value is a X509_NAME
  40 Serial                  - the value is a BIGNUM
  41 Subject                 - the value is a X509_NAME
  42 Certificate Hash        - the value is a 160 bit SHA1 hash
  43 Email                   - the value is a normal C string
  44 Filename                - the value is a normal C string
  45
  46 It is expected that these attributes should be enough to support
  47 the need from most, if not all, current applications.  Applications
  48 that need to do certificate verification would typically use Subject
  49 Key ID, Issuer/Serial Hash or Subject to look up issuer certificates.
  50 S/MIME applications would typically use Email to look up recipient
  51 and signer certificates.
  52
  53 There's added support for combined sets of attributes to search for,
  54 with the special OR attribute.
  55
  56
  57 Supported basic functionality
  58 -----------------------------
  59
  60 The functions that are supported through the STORE type are these:
  61
  62 generate_object         - for example to generate keys and CRLs
  63 get_object              - to look up one object
  64                           NOTE: this function is really rather
  65                           redundant and probably of lesser usage
  66                           than the list functions
  67 store_object            - store an object and the attributes
  68                           associated with it
  69 modify_object           - modify the attributes associated with
  70                           a specific object
  71 revoke_object           - revoke an object
  72                           NOTE: this only marks an object as
  73                           invalid, it doesn't remove the object
  74                           from the database
  75 delete_object           - remove an object from the database
  76 list_object             - list objects associated with a given
  77                           set of attributes
  78                           NOTE: this is really four functions:
  79                           list_start, list_next, list_end and
  80                           list_endp
  81 update_store            - update the internal data of the store
  82 lock_store              - lock the store
  83 unlock_store            - unlock the store
  84
  85 The list functions need some extra explanation: list_start is
  86 used to set up a lookup.  That's where the attributes to use in
  87 the search are set up.  It returns a search context.  list_next
  88 returns the next object searched for.  list_end closes the search.
  89 list_endp is used to check if we have reached the end.
  90
  91 A few words on the store functions as well: update_store is
  92 typically used by a CA application to update the internal
  93 structure of a database.  This may for example involve automatic
  94 removal of expired certificates.  lock_store and unlock_store
  95 are used for locking a store to allow exclusive writes.