[openssl] master update
Richard Levitte
levitte at openssl.org
Mon Feb 18 09:59:02 UTC 2019
The branch master has been updated
via 0a79572a29683bdbfd4490377ae0e0b19c060836 (commit)
from 4c3941c2eb22c44398bccb50dbd019530bb01c7d (commit)
- Log -----------------------------------------------------------------
commit 0a79572a29683bdbfd4490377ae0e0b19c060836
Author: Richard Levitte <levitte at openssl.org>
Date: Mon Feb 18 09:40:07 2019 +0100
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 at oracle.com>
(Merged from https://github.com/openssl/openssl/pull/8265)
-----------------------------------------------------------------------
Summary of changes:
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 1f914cf..dea0dfd 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 36d26bc..47f4194 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
More information about the openssl-commits
mailing list