diff options
author | Richard Levitte <levitte@openssl.org> | 2019-02-18 09:40:07 +0100 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2019-02-18 10:58:57 +0100 |
commit | 0a79572a29683bdbfd4490377ae0e0b19c060836 (patch) | |
tree | 38d69cf62673bbcedc3c089b9ef5450385478815 | |
parent | 4c3941c2eb22c44398bccb50dbd019530bb01c7d (diff) |
Property: naming and manual clarifiations
- 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)
-rw-r--r-- | crypto/property/property.c | 43 | ||||
-rw-r--r-- | doc/internal/man3/OSSL_METHOD_STORE.pod | 68 |
2 files changed, 61 insertions, 50 deletions
diff --git a/crypto/property/property.c b/crypto/property/property.c index 1f914cf500..dea0dfd66d 100644 --- a/crypto/property/property.c +++ b/crypto/property/property.c @@ -26,15 +26,15 @@ 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); diff --git a/doc/internal/man3/OSSL_METHOD_STORE.pod b/doc/internal/man3/OSSL_METHOD_STORE.pod index 36d26bca43..47f4194d1c 100644 --- a/doc/internal/man3/OSSL_METHOD_STORE.pod +++ b/doc/internal/man3/OSSL_METHOD_STORE.pod @@ -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 |