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