Alexandre Savard | 1b09e31 | 2012-08-07 20:33:29 -0400 | [diff] [blame] | 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. |