SERIALIZER: add functions for serialization to file
authorRichard Levitte <levitte@openssl.org>
Mon, 18 Nov 2019 00:32:22 +0000 (01:32 +0100)
committerRichard Levitte <levitte@openssl.org>
Fri, 29 Nov 2019 19:55:16 +0000 (20:55 +0100)
These functions are added:

- OSSL_SERIALIZER_to_bio()
- OSSL_SERIALIZER_to_fp() (unless 'no-stdio')

OSSL_SERIALIZER_to_bio() and OSSL_SERIALIZER_to_fp() work as wrapper
functions, and call an internal "do_output" function with the given
serializer context and a BIO to output the serialized result to.

The internal "do_output" function must have intimate knowledge of the
object being output.  This will defined independently with context
creators for specific OpenSSL types.

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10394)

crypto/serializer/build.info
crypto/serializer/serializer_lib.c [new file with mode: 0644]
crypto/serializer/serializer_local.h
doc/man3/OSSL_SERIALIZER.pod
doc/man3/OSSL_SERIALIZER_to_bio.pod [new file with mode: 0644]
include/openssl/serializer.h
util/libcrypto.num

index 7d69df9..1a35152 100644 (file)
@@ -1 +1 @@
-SOURCE[../../libcrypto]=serializer_meth.c
+SOURCE[../../libcrypto]=serializer_meth.c serializer_lib.c
diff --git a/crypto/serializer/serializer_lib.c b/crypto/serializer/serializer_lib.c
new file mode 100644 (file)
index 0000000..932ef1e
--- /dev/null
@@ -0,0 +1,43 @@
+/*
+ * Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+ *
+ * Licensed under the Apache License 2.0 (the "License").  You may not use
+ * this file except in compliance with the License.  You can obtain a copy
+ * in the file LICENSE in the source distribution or at
+ * https://www.openssl.org/source/license.html
+ */
+
+#include <openssl/bio.h>
+#include <openssl/serializer.h>
+#include "serializer_local.h"
+
+int OSSL_SERIALIZER_to_bio(OSSL_SERIALIZER_CTX *ctx, BIO *out)
+{
+    return ctx->do_output(ctx, out);
+}
+
+#ifndef OPENSSL_NO_STDIO
+static BIO *bio_from_file(FILE *fp)
+{
+    BIO *b;
+
+    if ((b = BIO_new(BIO_s_file())) == NULL) {
+        ERR_raise(ERR_LIB_OSSL_SERIALIZER, ERR_R_BUF_LIB);
+        return NULL;
+    }
+    BIO_set_fp(b, fp, BIO_NOCLOSE);
+    return b;
+}
+
+int OSSL_SERIALIZER_to_fp(OSSL_SERIALIZER_CTX *ctx, FILE *fp)
+{
+    BIO *b = bio_from_file(fp);
+    int ret = 0;
+
+    if (b != NULL)
+        ret = OSSL_SERIALIZER_to_bio(ctx, b);
+
+    BIO_free(b);
+    return ret;
+}
+#endif
index 979ba83..dd0eb85 100644 (file)
@@ -31,4 +31,11 @@ struct ossl_serializer_st {
 struct ossl_serializer_ctx_st {
     OSSL_SERIALIZER *ser;
     void *serctx;
+
+    /*
+     * |object| is the libcrypto object to handle.
+     * |do_output| must have intimate knowledge of this object.
+     */
+    const void *object;
+    int (*do_output)(OSSL_SERIALIZER_CTX *ctx, BIO *out);
 };
index 3476773..bf6ef34 100644 (file)
@@ -110,7 +110,8 @@ OSSL_SERIALIZER_number() returns an integer.
 
 =head1 SEE ALSO
 
-L<provider(7)>, L<OSSL_SERIALIZER_CTX(3)>, L<OPENSSL_CTX(3)>
+L<provider(7)>, L<OSSL_SERIALIZER_CTX(3)>, L<OSSL_SERIALIZER_to_bio(3)>,
+L<OPENSSL_CTX(3)>
 
 =head1 HISTORY
 
diff --git a/doc/man3/OSSL_SERIALIZER_to_bio.pod b/doc/man3/OSSL_SERIALIZER_to_bio.pod
new file mode 100644 (file)
index 0000000..3ed68a1
--- /dev/null
@@ -0,0 +1,59 @@
+=pod
+
+=head1 NAME
+
+OSSL_SERIALIZER_to_bio,
+OSSL_SERIALIZER_to_fp
+- Serializer file output routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/serializer.h>
+
+ int OSSL_SERIALIZER_to_bio(OSSL_SERIALIZER_CTX *ctx, BIO *out);
+ int OSSL_SERIALIZER_to_fp(OSSL_SERIALIZER_CTX *ctx, FILE *fp);
+
+Feature availability macros:
+
+=over 4
+
+=item OSSL_SERIALIZER_to_fp() is only available when B<OPENSSL_NO_STDIO>
+is undefined.
+
+=back
+
+=head1 DESCRIPTION
+
+OSSL_SERIALIZER_to_bio() runs the serialization process for the
+context I<ctx>, with the output going to the B<BIO> I<out>.  The
+application is required to set up the B<BIO> properly, for example to
+have it in text or binary mode if that's appropriate.
+
+=for comment Know your serializer!
+
+OSSL_SERIALIZER_to_fp() does the same thing as OSSL_SERIALIZER_to_bio(),
+except that the output is going to the B<FILE> I<fp>.
+
+=head1 RETURN VALUES
+
+OSSL_SERIALIZER_to_bio() and OSSL_SERIALIZER_to_fp() return 1 on
+success, or 0 on failure.
+
+=head1 SEE ALSO
+
+L<provider(7)>, L<OSSL_SERIALIZER_CTX(3)>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
index 79f8abe..78b57d2 100644 (file)
@@ -53,6 +53,12 @@ int OSSL_SERIALIZER_CTX_set_params(OSSL_SERIALIZER_CTX *ctx,
                                    const OSSL_PARAM params[]);
 void OSSL_SERIALIZER_CTX_free(OSSL_SERIALIZER_CTX *ctx);
 
+/* Utilities to output the object to serialize */
+int OSSL_SERIALIZER_to_bio(OSSL_SERIALIZER_CTX *ctx, BIO *out);
+#ifndef OPENSSL_NO_STDIO
+int OSSL_SERIALIZER_to_fp(OSSL_SERIALIZER_CTX *ctx, FILE *fp);
+#endif
+
 # ifdef __cplusplus
 }
 # endif
index 5f24657..cc94d58 100644 (file)
@@ -4892,3 +4892,5 @@ OSSL_SERIALIZER_CTX_get_serializer      ? 3_0_0   EXIST::FUNCTION:
 OSSL_SERIALIZER_CTX_set_params          ?      3_0_0   EXIST::FUNCTION:
 OSSL_SERIALIZER_CTX_free                ?      3_0_0   EXIST::FUNCTION:
 OSSL_SERIALIZER_properties              ?      3_0_0   EXIST::FUNCTION:
+OSSL_SERIALIZER_to_bio                  ?      3_0_0   EXIST::FUNCTION:
+OSSL_SERIALIZER_to_fp                   ?      3_0_0   EXIST::FUNCTION:STDIO