Update documentation following changes of various types
authorMatt Caswell <matt@openssl.org>
Thu, 7 May 2020 11:11:44 +0000 (12:11 +0100)
committerMatt Caswell <matt@openssl.org>
Sat, 16 May 2020 16:10:03 +0000 (17:10 +0100)
The previous commit changed the types of various objects passed between
the core and providers. Therefore the documentation needs to be updated
to reflect that.

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11758)

doc/man7/provider-base.pod
doc/man7/provider-serializer.pod
doc/man7/provider.pod

index a52c718..aefaa40 100644 (file)
@@ -16,15 +16,15 @@ provider-base
   */
 
  /* Functions offered by libcrypto to the providers */
- const OSSL_ITEM *core_gettable_params(const OSSL_PROVIDER *prov);
- int core_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]);
- int core_thread_start(const OSSL_PROVIDER *prov,
+ const OSSL_ITEM *core_gettable_params(const OSSL_CORE_HANDLE *handle);
+ int core_get_params(const OSSL_CORE_HANDLE *handle, OSSL_PARAM params[]);
+ int core_thread_start(const OSSL_CORE_HANDLE *handle,
                        OSSL_thread_stop_handler_fn handfn);
- OPENSSL_CTX *core_get_library_context(const OSSL_PROVIDER *prov);
- void core_new_error(const OSSL_PROVIDER *prov);
- void core_set_error_debug(const OSSL_PROVIDER *prov,
+ OPENSSL_CORE_CTX *core_get_library_context(const OSSL_CORE_HANDLE *handle);
+ void core_new_error(const OSSL_CORE_HANDLE *handle);
+ void core_set_error_debug(const OSSL_CORE_HANDLE *handle,
                            const char *file, int line, const char *func);
- void core_vset_error(const OSSL_PROVIDER *prov,
+ void core_vset_error(const OSSL_CORE_HANDLE *handle,
                       uint32_t reason, const char *fmt, va_list args);
 
  /*
@@ -52,7 +52,19 @@ provider-base
                                const char *file, int line);
  int CRYPTO_secure_allocated(const void *ptr);
  void OPENSSL_cleanse(void *ptr, size_t len);
- unsigned char *OPENSSL_hexstr2buf(const char *str, long *len);
+
+ OSSL_CORE_BIO * BIO_new_file(const char *filename, const char *mode)
+ OSSL_CORE_BIO * BIO_new_membuf(const void *buf, int len)
+ int BIO_read_ex(OSSL_CORE_BIO *bio, void *data, size_t data_len,
+                 size_t *bytes_read))
+ int BIO_write_ex(OSSL_CORE_BIO *bio, const void *data, size_t data_len,
+                  size_t *written)
+ int BIO_free(OSSL_CORE_BIO *bio))
+ int BIO_vprintf(OSSL_CORE_BIO *bio, const char *format, va_list args)
+ int BIO_vsnprintf(char *buf, size_t n, const char *fmt, va_list args)
+
+ void self_test_cb(OPENSSL_CORE_CTX *ctx, OSSL_CALLBACK **cb, void **cbarg)
+
 
  /* Functions offered by the provider to libcrypto */
  void provider_teardown(void *provctx);
@@ -76,8 +88,8 @@ function pointer from a B<OSSL_DISPATCH> element named
 B<OSSL_get_{name}>.
 For example, the "function" core_gettable_params() has these:
 
- typedef OSSL_ITEM *
-     (OSSL_core_gettable_params_fn)(const OSSL_PROVIDER *prov);
+ typedef OSSL_PARAM *
+     (OSSL_core_gettable_params_fn)(const OSSL_CORE_HANDLE *handle);
  static ossl_inline OSSL_NAME_core_gettable_params_fn
      OSSL_get_core_gettable_params(const OSSL_DISPATCH *opf);
 
@@ -114,7 +126,6 @@ provider):
  BIO_free                       OSSL_FUNC_BIO_FREE
  BIO_vprintf                    OSSL_FUNC_BIO_VPRINTF
  OPENSSL_cleanse                OSSL_FUNC_OPENSSL_CLEANSE
- OPENSSL_hexstr2buf             OSSL_FUNC_OPENSSL_HEXSTR2BUF
  OSSL_SELF_TEST_set_callback    OSSL_FUNC_SELF_TEST_CB
 
 For I<*out> (the B<OSSL_DISPATCH> array passed from the provider to
@@ -131,20 +142,20 @@ F<libcrypto>):
 core_gettable_params() returns a constant array of descriptor
 B<OSSL_PARAM>, for parameters that core_get_params() can handle.
 
-core_get_params() retrieves I<prov> parameters from the core.
+core_get_params() retrieves parameters from the core for the given I<handle>.
 See L</Core parameters> below for a description of currently known
 parameters.
 
 =for comment core_thread_start() TBA
 
-core_get_library_context() retrieves the library context in which the
-B<OSSL_PROVIDER> object I<prov> is stored.
+core_get_library_context() retrieves the library context in which the library
+object for the current provider is stored, accessible through the I<handle>.
 This may sometimes be useful if the provider wishes to store a
 reference to its context in the same library context.
 
 core_new_error(), core_set_error_debug() and core_set_error() are
 building blocks for reporting an error back to the core, with
-reference to the provider object I<prov>.
+reference to the I<handle>.
 
 =over 4
 
@@ -188,7 +199,10 @@ BIO_new_file(), BIO_new_mem_buf(), BIO_read_ex(), BIO_free(),
 BIO_vprintf(), OPENSSL_cleanse(), and OPENSSL_hexstr2buf()
 correspond exactly to the public functions with the same name.
 As a matter of fact, the pointers in the B<OSSL_DISPATCH> array are
-direct pointers to those public functions.
+direct pointers to those public functions. Note that the BIO functions take an
+B<OSSL_CORE_BIO> type rather than the standard B<BIO> type. This is to ensure
+that a provider does not mix BIOs from the core with BIOs used on the provider
+side (the two are not compatible).
 OSSL_SELF_TEST_set_callback() is used to set an optional callback that can be
 passed into a provider. This may be ignored by a provider.
 
@@ -327,7 +341,7 @@ operation C<BAR>.
 
  /* Provider context */
  struct prov_ctx_st {
-     OSSL_PROVIDER *prov;
+     OSSL_CORE_HANDLE *handle;
  }
 
  /* operation context for the algorithm FOO */
@@ -343,7 +357,7 @@ operation C<BAR>.
      if (fooctx != NULL)
          fooctx->provctx = provctx;
      else
-         c_put_error(provctx->prov, E_MALLOC, __FILE__, __LINE__);
+         c_put_error(provctx->handle, E_MALLOC, __FILE__, __LINE__);
      return fooctx;
  }
 
@@ -419,7 +433,7 @@ operation C<BAR>.
      { 0, NULL }
  };
 
- int OSSL_provider_init(const OSSL_PROVIDER *provider,
+ int OSSL_provider_init(const OSSL_CORE_HANDLE *handle,
                         const OSSL_DISPATCH *in,
                         const OSSL_DISPATCH **out,
                         void **provctx)
@@ -440,9 +454,10 @@ operation C<BAR>.
           * ALEA IACTA EST, if the core retrieves the reason table
           * regardless, that string will be displayed, otherwise not.
           */
-         c_put_error(provider, E_MALLOC, __FILE__, __LINE__);
+         c_put_error(handle, E_MALLOC, __FILE__, __LINE__);
          return 0;
      }
+     pctx->handle = handle;
      return 1;
  }
 
index dfc8031..ad3b5fd 100644 (file)
@@ -28,10 +28,10 @@ Future development will also include deserializing functions.
 
  /* Functions to serialize object data */
  int OP_serializer_serialize_data(void *ctx, const OSSL_PARAM *data,
-                                  BIO *out,
+                                  OSSL_CORE_BIO *out,
                                   OSSL_PASSPHRASE_CALLBACK *cb,
                                   void *cbarg);
- int OP_serializer_serialize_object(void *ctx, void *obj, BIO *out,
+ int OP_serializer_serialize_object(void *ctx, void *obj, OSSL_CORE_BIO *out,
                                     OSSL_PASSPHRASE_CALLBACK *cb,
                                     void *cbarg);
 
@@ -39,11 +39,11 @@ Future development will also include deserializing functions.
 
 The SERIALIZER is a generic method to serialize any set of object data
 in L<OSSL_PARAM(3)> array form, or any provider side object into
-serialized form, and write it to the given BIO.  If the caller wants
+serialized form, and write it to the given OSSL_CORE_BIO.  If the caller wants
 to get the serialized stream to memory, it should provide a
 L<BIO_s_membuf(3)>.
 
-The serializer doesn't need to know more about the B<BIO> pointer than
+The serializer doesn't need to know more about the B<OSSL_CORE_BIO> pointer than
 being able to pass it to the appropriate BIO upcalls (see
 L<provider-base(7)/Core functions>).
 
@@ -71,7 +71,7 @@ For example, the "function" OP_serializer_serialize_data() has these:
  typedef int
      (OSSL_OP_serializer_serialize_data_fn)(void *provctx,
                                             const OSSL_PARAM params[],
-                                            BIO *out);
+                                            OSSL_CORE_BIO *out);
  static ossl_inline OSSL_OP_serializer_serialize_data_fn
      OSSL_get_OP_serializer_serialize_data(const OSSL_DISPATCH *opf);
 
@@ -180,11 +180,11 @@ by OP_serializer_set_ctx_params() and OP_serializer_settable_ctx_params().
 OP_serializer_serialize_data() should take an array of B<OSSL_PARAM>,
 I<data>, and if it contains the data necessary for the object type
 that the implementation handles, it should output the object in
-serialized form to the B<BIO>.
+serialized form to the B<OSSL_CORE_BIO>.
 
 OP_serializer_serialize_object() should take a pointer to an object
 that it knows intimately, and output that object in serialized form to
-the B<BIO>.  The caller I<must> ensure that this function is called
+the B<OSSL_CORE_BIO>.  The caller I<must> ensure that this function is called
 with a pointer that the provider of this function is familiar with.
 It is not suitable to use with object pointers coming from other
 providers.
index f7f6bbe..581c33b 100644 (file)
@@ -42,16 +42,15 @@ If it's built-in, the initialization function may have any name.
 
 The initialization function must have the following signature:
 
- int NAME(const OSSL_PROVIDER *provider,
+ int NAME(const OSSL_CORE_HANDLE *handle,
           const OSSL_DISPATCH *in, const OSSL_DISPATCH **out,
           void **provctx);
 
-I<provider> is the OpenSSL library object for the provider, and works
+I<handle> is the OpenSSL library object for the provider, and works
 as a handle for everything the OpenSSL libraries need to know about
 the provider.
-For the provider itself, it may hold some interesting information,
-and is also passed to some of the functions given in the dispatch
-array I<in>.
+For the provider itself, it is passed to some of the functions given in the
+dispatch array I<in>.
 
 I<in> is a dispatch array of base functions offered by the OpenSSL
 libraries, and the available functions are further described in
@@ -288,6 +287,13 @@ Should it be needed (if other providers are loaded and offer
 implementations of the same algorithms), the property "provider=legacy" can be
 used as a search criterion for these implementations.
 
+=head2 Null provider
+
+The null provider is built in as part of the F<libcrypto> library. It contains
+no algorithms in it at all. When fetching algorithms the default provider will
+be automatically loaded if no other provider has been explicitly loaded. To
+prevent that from happening you can explicitly load the null provider.
+
 =head1 EXAMPLES
 
 =head2 Fetching