Property: naming and manual clarifiations
authorRichard Levitte <levitte@openssl.org>
Mon, 18 Feb 2019 08:40:07 +0000 (09:40 +0100)
committerRichard Levitte <levitte@openssl.org>
Mon, 18 Feb 2019 09:58:57 +0000 (10:58 +0100)
- Add a bit more text about that is expected of the user or
  OSSL_METHOD_STOREs.
- Clarify what a method and what a numeric identity are.
- Change all mentions of 'implementation' and 'result' to 'method'.

To clarify further: OpenSSL has used the term 'method' for structures
that mainly contains function pointers.  Those are the methods that
are expected to be stored away in OSSL_METHOD_STOREs.  In the end,
however, it's the caller's responsibility to define exactly what they
want to store, as long as its 'methods' are associated with a numeric
identity and properties.

Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/8265)

crypto/property/property.c
doc/internal/man3/OSSL_METHOD_STORE.pod

index 1f914cf..dea0dfd 100644 (file)
 
 typedef struct {
     OSSL_PROPERTY_LIST *properties;
-    void *implementation;
-    void (*implementation_destruct)(void *);
+    void *method;
+    void (*method_destruct)(void *);
 } IMPLEMENTATION;
 
 DEFINE_STACK_OF(IMPLEMENTATION)
 
 typedef struct {
     const char *query;
-    void *result;
+    void *method;
     char body[1];
 } QUERY;
 
@@ -120,8 +120,8 @@ static int query_cmp(const QUERY *a, const QUERY *b)
 static void impl_free(IMPLEMENTATION *impl)
 {
     if (impl != NULL) {
-        if (impl->implementation_destruct)
-            impl->implementation_destruct(impl->implementation);
+        if (impl->method_destruct)
+            impl->method_destruct(impl->method);
         OPENSSL_free(impl);
     }
 }
@@ -185,14 +185,13 @@ static int ossl_method_store_insert(OSSL_METHOD_STORE *store, ALGORITHM *alg)
 
 int ossl_method_store_add(OSSL_METHOD_STORE *store,
                           int nid, const char *properties,
-                          void *implementation,
-                          void (*implementation_destruct)(void *))
+                          void *method, void (*method_destruct)(void *))
 {
     ALGORITHM *alg = NULL;
     IMPLEMENTATION *impl;
     int ret = 0;
 
-    if (nid <= 0 || implementation == NULL || store == NULL)
+    if (nid <= 0 || method == NULL || store == NULL)
         return 0;
     if (properties == NULL)
         properties = "";
@@ -201,8 +200,8 @@ int ossl_method_store_add(OSSL_METHOD_STORE *store,
     impl = OPENSSL_malloc(sizeof(*impl));
     if (impl == NULL)
         return 0;
-    impl->implementation = implementation;
-    impl->implementation_destruct = implementation_destruct;
+    impl->method = method;
+    impl->method_destruct = method_destruct;
 
     /*
      * Insert into the hash table if required.
@@ -245,12 +244,12 @@ err:
 }
 
 int ossl_method_store_remove(OSSL_METHOD_STORE *store, int nid,
-                             const void *implementation)
+                             const void *method)
 {
     ALGORITHM *alg = NULL;
     int i;
 
-    if (nid <= 0 || implementation == NULL || store == NULL)
+    if (nid <= 0 || method == NULL || store == NULL)
         return 0;
 
     ossl_property_write_lock(store);
@@ -269,7 +268,7 @@ int ossl_method_store_remove(OSSL_METHOD_STORE *store, int nid,
     for (i = 0; i < sk_IMPLEMENTATION_num(alg->impls); i++) {
         IMPLEMENTATION *impl = sk_IMPLEMENTATION_value(alg->impls, i);
 
-        if (impl->implementation == implementation) {
+        if (impl->method == method) {
             sk_IMPLEMENTATION_delete(alg->impls, i);
             ossl_property_unlock(store);
             impl_free(impl);
@@ -281,7 +280,7 @@ int ossl_method_store_remove(OSSL_METHOD_STORE *store, int nid,
 }
 
 int ossl_method_store_fetch(OSSL_METHOD_STORE *store, int nid,
-                            const char *prop_query, void **result)
+                            const char *prop_query, void **method)
 {
     ALGORITHM *alg;
     IMPLEMENTATION *impl;
@@ -289,7 +288,7 @@ int ossl_method_store_fetch(OSSL_METHOD_STORE *store, int nid,
     int ret = 0;
     int j;
 
-    if (nid <= 0 || result == NULL || store == NULL)
+    if (nid <= 0 || method == NULL || store == NULL)
         return 0;
 
     /*
@@ -305,7 +304,7 @@ int ossl_method_store_fetch(OSSL_METHOD_STORE *store, int nid,
 
     if (prop_query == NULL) {
         if ((impl = sk_IMPLEMENTATION_value(alg->impls, 0)) != NULL) {
-            *result = impl->implementation;
+            *method = impl->method;
             ret = 1;
         }
         goto fin;
@@ -324,7 +323,7 @@ int ossl_method_store_fetch(OSSL_METHOD_STORE *store, int nid,
         impl = sk_IMPLEMENTATION_value(alg->impls, j);
 
         if (ossl_property_match(pq, impl->properties)) {
-            *result = impl->implementation;
+            *method = impl->method;
             ret = 1;
             goto fin;
         }
@@ -434,7 +433,7 @@ static void ossl_method_cache_flush_some(OSSL_METHOD_STORE *store)
 }
 
 int ossl_method_store_cache_get(OSSL_METHOD_STORE *store, int nid,
-                                const char *prop_query, void **result)
+                                const char *prop_query, void **method)
 {
     ALGORITHM *alg;
     QUERY elem, *r;
@@ -455,13 +454,13 @@ int ossl_method_store_cache_get(OSSL_METHOD_STORE *store, int nid,
         ossl_property_unlock(store);
         return 0;
     }
-    *result = r->result;
+    *method = r->method;
     ossl_property_unlock(store);
     return 1;
 }
 
 int ossl_method_store_cache_set(OSSL_METHOD_STORE *store, int nid,
-                                const char *prop_query, void *result)
+                                const char *prop_query, void *method)
 {
     QUERY elem, *old, *p = NULL;
     ALGORITHM *alg;
@@ -481,7 +480,7 @@ int ossl_method_store_cache_set(OSSL_METHOD_STORE *store, int nid,
         return 0;
     }
 
-    if (result == NULL) {
+    if (method == NULL) {
         elem.query = prop_query;
         lh_QUERY_delete(alg->cache, &elem);
         ossl_property_unlock(store);
@@ -490,7 +489,7 @@ int ossl_method_store_cache_set(OSSL_METHOD_STORE *store, int nid,
     p = OPENSSL_malloc(sizeof(*p) + (len = strlen(prop_query)));
     if (p != NULL) {
         p->query = p->body;
-        p->result = result;
+        p->method = method;
         memcpy((char *)p->query, prop_query, len + 1);
         if ((old = lh_QUERY_insert(alg->cache, p)) != NULL)
             OPENSSL_free(old);
index 36d26bc..47f4194 100644 (file)
@@ -20,60 +20,72 @@ ossl_method_store_cache_get and ossl_method_store_cache_set
  void ossl_method_store_cleanup(void);
  int ossl_method_store_add(OSSL_METHOD_STORE *store,
                            int nid, const char *properties,
-                           void *implementation,
-                           void (*implementation_destruct)(void *));
+                           void *method, void (*method_destruct)(void *));
  int ossl_method_store_remove(OSSL_METHOD_STORE *store,
-                              int nid, const void *implementation);
+                              int nid, const void *method);
  int ossl_method_store_fetch(OSSL_METHOD_STORE *store,
                              int nid, const char *properties,
-                             void **result);
+                             void **method);
  int ossl_method_store_set_global_properties(OSSL_METHOD_STORE *store,
                                             const char *prop_query);
  int ossl_method_store_cache_get(OSSL_METHOD_STORE *store, int nid,
-                                 const char *prop_query, void **result);
+                                 const char *prop_query, void **method);
  int ossl_method_store_cache_set(OSSL_METHOD_STORE *store, int nid,
-                                 const char *prop_query, void *result);
+                                 const char *prop_query, void *method);
 
 =head1 DESCRIPTION
 
-OSSL_METHOD_STORE stores implementations of algorithms that can be queried using
-properties and a NID.
+OSSL_METHOD_STORE stores methods that can be queried using properties and a
+numeric identity (nid).
 
-ossl_method_store_init() initialises the implementation method store subsystem.
+Methods are expected to be library internal structures.
+It's left to the caller to define the exact contents.
+
+Numeric identities are expected to be an algorithm identity for the methods.
+It's left to the caller to define exactly what an algorithm is, and to allocate
+these numeric identities accordingly.
+
+The B<OSSL_METHOD_STORE> also holds an internal query cache, which is accessed
+separately (see L</Cache Functions> below).
+
+=head2 Store Functions
+
+ossl_method_store_init() initialises the method store subsystem.
 
 ossl_method_store_cleanup() cleans up and shuts down the implementation method
-store subsystem
+store subsystem.
 
-ossl_method_store_new() create a new empty implementation method store.
+ossl_method_store_new() create a new empty method store.
 
 ossl_method_store_free() frees resources allocated to B<store>.
 
-ossl_method_store_add() adds the B<implementation> to the B<store> as an
-instance of the algorithm indicated by B<nid> and the property definition
-<properties>.
-The optional B<implementation_destruct> function is called when
-B<implementation> is being released from B<store>.
+ossl_method_store_add() adds the B<method> to the B<store> as an instance of an
+algorithm indicated by B<nid> and the property definition B<properties>.
+The optional B<method_destruct> function is called when B<method> is being
+released from B<store>.
 
-ossl_method_store_remove() remove the B<implementation> of algorithm B<nid>
-from the B<store>.
+ossl_method_store_remove() removes the B<method> identified by B<nid> from the
+B<store>.
 
-ossl_method_store_fetch() query B<store> for an implementation of algorithm
-B<nid> that matches the property query B<prop_query>.
-The result, if any, is returned in B<result>.
+ossl_method_store_fetch() queries B<store> for an method identified by B<nid>
+that matches the property query B<prop_query>.
+The result, if any, is returned in B<method>.
 
-ossl_method_store_set_global_properties() sets implementation method B<store>
-wide query properties to B<prop_query>.
+ossl_method_store_set_global_properties() sets method B<store> wide query
+properties to B<prop_query>.
 All subsequent fetches will need to meet both these global query properties
-and the ones passed to the fetch function.
+and the ones passed to the ossl_method_store_free().
+
+=head2 Cache Functions
 
 ossl_method_store_cache_get() queries the cache associated with the B<store>
-for an implementation of algorithm B<nid> that matches the property query
+for an method identified by B<nid> that matches the property query
 B<prop_query>.
-The result, if any, is returned in B<result>.
+The result, if any, is returned in B<method>.
 
-ossl_method_store_cache_set() sets a cache entry for algorithm B<nid> with the
+ossl_method_store_cache_set() sets a cache entry identified by B<nid> with the
 property query B<prop_query> in the B<store>.
-Future cache gets will return the specified <result>.
+Future cache gets will return the specified B<method>.
 
 =head1 RETURN VALUES