doc/internal/man3/OSSL_METHOD_STORE.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ossl_method_store_new, ossl_method_store_free, ossl_method_store_init,
   6 ossl_method_store_cleanup, ossl_method_store_add, ossl_method_store_remove,
   7 ossl_method_store_fetch, ossl_method_store_set_global_properties,
   8 ossl_method_store_cache_get and ossl_method_store_cache_set
   9 - implementation method store and query
  10
  11 =head1 SYNOPSIS
  12
  13  #include "internal/property.h"
  14
  15  typedef struct ossl_method_store_st OSSL_METHOD_STORE;
  16
  17  OSSL_METHOD_STORE *ossl_method_store_new(void);
  18  void ossl_method_store_free(OSSL_METHOD_STORE *store);
  19  int ossl_method_store_init(void);
  20  void ossl_method_store_cleanup(void);
  21  int ossl_method_store_add(OSSL_METHOD_STORE *store,
  22                            int nid, const char *properties,
  23                            void *implementation,
  24                            void (*implementation_destruct)(void *));
  25  int ossl_method_store_remove(OSSL_METHOD_STORE *store,
  26                               int nid, const void *implementation);
  27  int ossl_method_store_fetch(OSSL_METHOD_STORE *store,
  28                              int nid, const char *properties,
  29                              void **result);
  30  int ossl_method_store_set_global_properties(OSSL_METHOD_STORE *store,
  31                                             const char *prop_query);
  32  int ossl_method_store_cache_get(OSSL_METHOD_STORE *store, int nid,
  33                                  const char *prop_query, void **result);
  34  int ossl_method_store_cache_set(OSSL_METHOD_STORE *store, int nid,
  35                                  const char *prop_query, void *result);
  36
  37 =head1 DESCRIPTION
  38
  39 OSSL_METHOD_STORE stores implementations of algorithms that can be queried using
  40 properties and a NID.
  41
  42 ossl_method_store_init() initialises the implementation method store subsystem.
  43
  44 ossl_method_store_cleanup() cleans up and shuts down the implementation method
  45 store subsystem
  46
  47 ossl_method_store_new() create a new empty implementation method store.
  48
  49 ossl_method_store_free() frees resources allocated to B<store>.
  50
  51 ossl_method_store_add() adds the B<implementation> to the B<store> as an
  52 instance of the algorithm indicated by B<nid> and the property definition
  53 <properties>.
  54 The optional B<implementation_destruct> function is called when
  55 B<implementation> is being released from B<store>.
  56
  57 ossl_method_store_remove() remove the B<implementation> of algorithm B<nid>
  58 from the B<store>.
  59
  60 ossl_method_store_fetch() query B<store> for an implementation of algorithm
  61 B<nid> that matches the property query B<prop_query>.
  62 The result, if any, is returned in B<result>.
  63
  64 ossl_method_store_set_global_properties() sets implementation method B<store>
  65 wide query properties to B<prop_query>.
  66 All subsequent fetches will need to meet both these global query properties
  67 and the ones passed to the fetch function.
  68
  69 ossl_method_store_cache_get() queries the cache associated with the B<store>
  70 for an implementation of algorithm B<nid> that matches the property query
  71 B<prop_query>.
  72 The result, if any, is returned in B<result>.
  73
  74 ossl_method_store_cache_set() sets a cache entry for algorithm B<nid> with the
  75 property query B<prop_query> in the B<store>.
  76 Future cache gets will return the specified <result>.
  77
  78 =head1 RETURN VALUES
  79
  80 ossl_method_store_new() a new method store object or B<NULL> on failure.
  81
  82 ossl_method_store_free(), ossl_method_store_add(),
  83 ossl_method_store_remove(), ossl_method_store_fetch(),
  84 ossl_method_store_set_global_properties(), ossl_method_store_cache_get()
  85 and ossl_method_store_cache_set() return B<1> on success and B<0> on error.
  86
  87 ossl_method_store_free() and ossl_method_store_cleanup() do not return values.
  88
  89 =head1 HISTORY
  90
  91 This functionality was added to OpenSSL 3.0.0.
  92
  93 =head1 COPYRIGHT
  94
  95 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
  96 Copyright (c) 2019, Oracle and/or its affiliates.  All rights reserved.
  97
  98 Licensed under the Apache License 2.0 (the "License").  You may not use this
  99 file except in compliance with the License.  You can obtain a copy in the file
 100 LICENSE in the source distribution or at
 101 L<https://www.openssl.org/source/license.html>.
 102
 103 =cut