wbrawner/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Property: naming and manual clarifiations

Browse source 
- 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)
This commit is contained in:
Richard Levitte 2019-02-18 09:40:07 +01:00
parent 4c3941c2eb
commit 0a79572a29
2 changed files with 61 additions and 50 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

43
crypto/property/property.c
View file

@ -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);

68
doc/internal/man3/OSSL_METHOD_STORE.pod
View 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