crypto/store/README

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