doc/man3/OSSL_SERIALIZER_CTX_new_by_EVP_PKEY.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_SERIALIZER_CTX_new_by_EVP_PKEY,
   6 OSSL_SERIALIZER_CTX_set_cipher,
   7 OSSL_SERIALIZER_CTX_set_passphrase,
   8 OSSL_SERIALIZER_CTX_set_passphrase_cb,
   9 OSSL_SERIALIZER_CTX_set_passphrase_ui,
  10 OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ,
  11 OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ,
  12 OSSL_SERIALIZER_Parameters_TO_PEM_PQ,
  13 OSSL_SERIALIZER_PUBKEY_TO_DER_PQ,
  14 OSSL_SERIALIZER_PrivateKey_TO_DER_PQ,
  15 OSSL_SERIALIZER_Parameters_TO_DER_PQ,
  16 OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ,
  17 OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ,
  18 OSSL_SERIALIZER_Parameters_TO_TEXT_PQ
  19 - Serializer routines to serialize EVP_PKEYs
  20
  21 =head1 SYNOPSIS
  22
  23  #include <openssl/serializer.h>
  24
  25  OSSL_SERIALIZER_CTX *OSSL_SERIALIZER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey,
  26                                                           const char *propquery);
  27
  28  int OSSL_SERIALIZER_CTX_set_cipher(OSSL_SERIALIZER_CTX *ctx,
  29                                     const char *cipher_name,
  30                                     const char *propquery);
  31  int OSSL_SERIALIZER_CTX_set_passphrase(OSSL_SERIALIZER_CTX *ctx,
  32                                         const unsigned char *kstr,
  33                                         size_t klen);
  34  int OSSL_SERIALIZER_CTX_set_passphrase_cb(OSSL_SERIALIZER_CTX *ctx, int enc,
  35                                            pem_password_cb *cb, void *cbarg);
  36  int OSSL_SERIALIZER_CTX_set_passphrase_ui(OSSL_SERIALIZER_CTX *ctx,
  37                                            const UI_METHOD *ui_method,
  38                                            void *ui_data);
  39
  40  #define OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ "format=pem,type=public"
  41  #define OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ "format=pem,type=private"
  42  #define OSSL_SERIALIZER_Parameters_TO_PEM_PQ "format=pem,type=parameters"
  43
  44  #define OSSL_SERIALIZER_PUBKEY_TO_DER_PQ "format=der,type=public"
  45  #define OSSL_SERIALIZER_PrivateKey_TO_DER_PQ "format=der,type=private"
  46  #define OSSL_SERIALIZER_Parameters_TO_DER_PQ "format=der,type=parameters"
  47
  48  #define OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ "format=text,type=public"
  49  #define OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ "format=text,type=private"
  50  #define OSSL_SERIALIZER_Parameters_TO_TEXT_PQ "format=text,type=parameters"
  51
  52 =head1 DESCRIPTION
  53
  54 OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() creates a B<OSSL_SERIALIZER_CTX>
  55 with a suitable attached output routine for B<EVP_PKEY>s.  It will
  56 search for a serializer implementation that matches the algorithm of
  57 the B<EVP_PKEY> and the property query given with I<propquery>.  It
  58 will prefer to find a serializer from the same provider as the key
  59 data of the B<EVP_PKEY> itself, but failing that, it will choose the
  60 first serializer that supplies a generic serializing function.
  61
  62 If no suitable serializer was found, OSSL_SERIALIZER_CTX_new_by_EVP_PKEY()
  63 still creates a B<OSSL_SERIALIZER_CTX>, but with no associated
  64 serializer (L<OSSL_SERIALIZER_CTX_get_serializer(3)> returns NULL).
  65 This helps the caller distinguish between an error when creating
  66 the B<OSSL_SERIALIZER_CTX>, and the lack the serializer support and
  67 act accordingly.
  68
  69 OSSL_SERIALIZER_CTX_set_cipher() tells the implementation what cipher
  70 should be used to encrypt serialized keys.  The cipher is given by
  71 name I<cipher_name>.  The interpretation of that I<cipher_name> is
  72 implementation dependent.  The implementation may implement the digest
  73 directly itself or by other implementations, or it may choose to fetch
  74 it.  If the implementation supports fetching the cipher, then it may
  75 use I<propquery> as properties to be queried for when fetching.
  76 I<cipher_name> may also be NULL, which will result in unencrypted
  77 serialization.
  78
  79 OSSL_SERIALIZER_CTX_set_passphrase() gives the implementation a
  80 pass phrase to use when encrypting the serialized private key.
  81 Alternatively, a pass phrase callback may be specified with the
  82 following functions.
  83
  84 OSSL_SERIALIZER_CTX_set_passphrase_cb() and
  85 OSSL_SERIALIZER_CTX_set_passphrase_ui() sets up a callback method that
  86 the implementation can use to prompt for a pass phrase.
  87
  88 =for comment Note that the callback method is called indirectly,
  89 through an internal B<OSSL_PASSPHRASE_CALLBACK> function.
  90
  91 The macros B<OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ>,
  92 B<OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ>,
  93 B<OSSL_SERIALIZER_Parameters_TO_PEM_PQ>,
  94 B<OSSL_SERIALIZER_PUBKEY_TO_DER_PQ>,
  95 B<OSSL_SERIALIZER_PrivateKey_TO_DER_PQ>,
  96 B<OSSL_SERIALIZER_Parameters_TO_DER_PQ>,
  97 B<OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ>,
  98 B<OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ>,
  99 B<OSSL_SERIALIZER_Parameters_TO_TEXT_PQ> are convenience macros with
 100 property queries to serialize the B<EVP_PKEY> as a public key, private
 101 key or parameters to B<PEM>, to B<DER>, or to text.
 102
 103 =head1 RETURN VALUES
 104
 105 OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() returns a pointer to a
 106 B<OSSL_SERIALIZER_CTX>, or NULL if it couldn't be created.
 107
 108 OSSL_SERIALIZER_CTX_set_cipher(),
 109 OSSL_SERIALIZER_CTX_set_passphrase(),
 110 OSSL_SERIALIZER_CTX_set_passphrase_cb(), and
 111 OSSL_SERIALIZER_CTX_set_passphrase_ui() all return 1 on success, or 0
 112 on failure.
 113
 114 =head1 NOTES
 115
 116 Parts of the function and macro names are made to match already
 117 existing OpenSSL names.
 118
 119 B<EVP_PKEY> in OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() matches the type
 120 name, thus making for the naming pattern
 121 B<OSSL_SERIALIZER_CTX_new_by_I<TYPE>>() when new types are handled.
 122
 123 B<PUBKEY>, B<PrivateKey> and B<Parameters> in the macro names match
 124 the B<I<TYPE>> part of of B<PEM_write_bio_I<TYPE>> functions as well
 125 as B<i2d_I<TYPE>_bio> functions.
 126
 127 =head1 SEE ALSO
 128
 129 L<provider(7)>, L<OSSL_SERIALIZER(3)>, L<OSSL_SERIALIZER_CTX(3)>
 130
 131 =head1 HISTORY
 132
 133 The functions described here were added in OpenSSL 3.0.
 134
 135 =head1 COPYRIGHT
 136
 137 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 138
 139 Licensed under the Apache License 2.0 (the "License").  You may not use
 140 this file except in compliance with the License.  You can obtain a copy
 141 in the file LICENSE in the source distribution or at
 142 L<https://www.openssl.org/source/license.html>.
 143
 144 =cut