From 0a79572a29683bdbfd4490377ae0e0b19c060836 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Mon, 18 Feb 2019 09:40:07 +0100 Subject: [PATCH 1/1] 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 (Merged from https://github.com/openssl/openssl/pull/8265) --- crypto/property/property.c | 43 ++++++++-------- 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 also holds an internal query cache, which is accessed +separately (see L 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. -ossl_method_store_add() adds the B to the B as an -instance of the algorithm indicated by B and the property definition -. -The optional B function is called when -B is being released from B. +ossl_method_store_add() adds the B to the B as an instance of an +algorithm indicated by B and the property definition B. +The optional B function is called when B is being +released from B. -ossl_method_store_remove() remove the B of algorithm B -from the B. +ossl_method_store_remove() removes the B identified by B from the +B. -ossl_method_store_fetch() query B for an implementation of algorithm -B that matches the property query B. -The result, if any, is returned in B. +ossl_method_store_fetch() queries B for an method identified by B +that matches the property query B. +The result, if any, is returned in B. -ossl_method_store_set_global_properties() sets implementation method B -wide query properties to B. +ossl_method_store_set_global_properties() sets method B wide query +properties to B. 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 -for an implementation of algorithm B that matches the property query +for an method identified by B that matches the property query B. -The result, if any, is returned in B. +The result, if any, is returned in B. -ossl_method_store_cache_set() sets a cache entry for algorithm B with the +ossl_method_store_cache_set() sets a cache entry identified by B with the property query B in the B. -Future cache gets will return the specified . +Future cache gets will return the specified B. =head1 RETURN VALUES -- 2.34.1