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