OSX/libsecurity_mds/README

   1 MDS RELEASE NOTES
   2
   3 This implementation of MDS is based on the idea that there
   4 is no separate module installation process. Instead, MDS
   5 interacts with modules as follows:
   6
   7 -       Each module bundle contains a resource which is simply
   8         an MDS database containing the records specific to that
   9         module.
  10
  11 -       Placing a module bundle into the designated path makes
  12         that module eligible to be registered with MDS.
  13
  14 -       Clients which utilize MDS will, when initializing MDS and
  15         then periodically thereafter, scan the module path and
  16         dynamically update the MDS database entries to reflect
  17         added, removed, or changed modules.
  18
  19 The scanning of the module path is done implicitly within
  20 MDS API functions.
  21
  22 DETECTING CHANGED MODULES
  23
  24 MDS uses the following algorithm to detect added, removed,
  25 or changed modules:
  26
  27 1.      stat() the directory in which modules are located. If
  28         its modification time is no later than the last time
  29         a scan was performed, stop.
  30
  31 2.      Read the contents of the module directory with readdir().
  32         Build a list of the directory contents, including the
  33         modification time of each bundle as returned by stat().
  34
  35 3.      Remove all MDS records for modules which are no longer
  36         present, or which have changed since the last scan.
  37
  38 4.      Insert MDS records for modules which are now present but
  39         not represented in the database, including those whose
  40         records were deleted in step 3.
  41
  42 This strategy has several implications:
  43
  44 -       Changing the contents of a module bundle will not change
  45         the module directory's modification time, and so will not
  46         trigger an update of the database. To cause an update when
  47         modifying a module, that module must be removed from the
  48         directory and then its new version must be placed into the
  49         directory.
  50
  51 -       No single process which is a client of MDS will attempt a
  52         rescan more often than once per 10 seconds. This means that
  53         it might take up to 10 seconds for MDS to sync after a
  54         change occurs.
  55
  56 -       Since any MDS client process can initiate a rescan, but no
  57         two processes should be updating the database at the same
  58         time, we use a lock file in /var/db to ensure only one
  59         process is scanning at any one time.
  60
  61 DEVIATIONS FROM THE SPEC
  62
  63 In addition to those differences noted above, this MDS
  64 implementation deviates from the specification in the following
  65 ways:
  66
  67 MDS_Initialize()
  68
  69         As part of initiating a client's connection to MDS, this
  70         function creates the MDS databases (if needed) and rescans
  71         the module path.
  72
  73 MDS_Install()
  74
  75         This call is specified to create the MDS databases. Since it
  76         can only be called with an MDS_HANDLE obtained from a prior
  77         call to MDS_Initialize(), which already creates the databases
  78         implicitly, MDS_Install() does nothing and silently returns
  79         success in this implementation.
  80
  81 MDS_Uninstall()
  82
  83         This call is specified to delete the MDS databases. In this
  84         implementation, it does nothing and throws the error
  85         CSSM_ERRCODE_FUNCTION_NOT_IMPLEMENTED.