NAME¶

OSSL_SERIALIZER_CTX_new_by_EVP_PKEY, OSSL_SERIALIZER_CTX_set_cipher, OSSL_SERIALIZER_CTX_set_passphrase, OSSL_SERIALIZER_CTX_set_passphrase_cb, OSSL_SERIALIZER_CTX_set_passphrase_ui, OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ, OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ, OSSL_SERIALIZER_Parameters_TO_PEM_PQ, OSSL_SERIALIZER_PUBKEY_TO_DER_PQ, OSSL_SERIALIZER_PrivateKey_TO_DER_PQ, OSSL_SERIALIZER_Parameters_TO_DER_PQ, OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ, OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ, OSSL_SERIALIZER_Parameters_TO_TEXT_PQ - Serializer routines to serialize EVP_PKEYs

SYNOPSIS¶

 #include <openssl/serializer.h>
 OSSL_SERIALIZER_CTX *OSSL_SERIALIZER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey,
                                                          const char *propquery);
 int OSSL_SERIALIZER_CTX_set_cipher(OSSL_SERIALIZER_CTX *ctx,
                                    const char *cipher_name,
                                    const char *propquery);
 int OSSL_SERIALIZER_CTX_set_passphrase(OSSL_SERIALIZER_CTX *ctx,
                                        const unsigned char *kstr,
                                        size_t klen);
 int OSSL_SERIALIZER_CTX_set_passphrase_cb(OSSL_SERIALIZER_CTX *ctx, int enc,
                                           pem_password_cb *cb, void *cbarg);
 int OSSL_SERIALIZER_CTX_set_passphrase_ui(OSSL_SERIALIZER_CTX *ctx,
                                           const UI_METHOD *ui_method,
                                           void *ui_data);
 #define OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ "format=pem,type=public"
 #define OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ "format=pem,type=private"
 #define OSSL_SERIALIZER_Parameters_TO_PEM_PQ "format=pem,type=parameters"
 #define OSSL_SERIALIZER_PUBKEY_TO_DER_PQ "format=der,type=public"
 #define OSSL_SERIALIZER_PrivateKey_TO_DER_PQ "format=der,type=private"
 #define OSSL_SERIALIZER_Parameters_TO_DER_PQ "format=der,type=parameters"
 #define OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ "format=text,type=public"
 #define OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ "format=text,type=private"
 #define OSSL_SERIALIZER_Parameters_TO_TEXT_PQ "format=text,type=parameters"

DESCRIPTION¶

OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() creates a OSSL_SERIALIZER_CTX with a suitable attached output routine for EVP_PKEYs. It will search for a serializer implementation that matches the algorithm of the EVP_PKEY and the property query given with propquery. It will prefer to find a serializer from the same provider as the key data of the EVP_PKEY itself, but failing that, it will choose the first serializer that supplies a generic serializing function.

If no suitable serializer was found, OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() still creates a OSSL_SERIALIZER_CTX, but with no associated serializer (OSSL_SERIALIZER_CTX_get_serializer(3) returns NULL). This helps the caller distinguish between an error when creating the OSSL_SERIALIZER_CTX, and the lack the serializer support and act accordingly.

OSSL_SERIALIZER_CTX_set_cipher() tells the implementation what cipher should be used to encrypt serialized keys. The cipher is given by name cipher_name. The interpretation of that cipher_name is implementation dependent. The implementation may implement the digest directly itself or by other implementations, or it may choose to fetch it. If the implementation supports fetching the cipher, then it may use propquery as properties to be queried for when fetching. cipher_name may also be NULL, which will result in unencrypted serialization.

OSSL_SERIALIZER_CTX_set_passphrase() gives the implementation a pass phrase to use when encrypting the serialized private key. Alternatively, a pass phrase callback may be specified with the following functions.

OSSL_SERIALIZER_CTX_set_passphrase_cb() and OSSL_SERIALIZER_CTX_set_passphrase_ui() sets up a callback method that the implementation can use to prompt for a pass phrase.

The macros OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ, OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ, OSSL_SERIALIZER_Parameters_TO_PEM_PQ, OSSL_SERIALIZER_PUBKEY_TO_DER_PQ, OSSL_SERIALIZER_PrivateKey_TO_DER_PQ, OSSL_SERIALIZER_Parameters_TO_DER_PQ, OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ, OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ, OSSL_SERIALIZER_Parameters_TO_TEXT_PQ are convenience macros with property queries to serialize the EVP_PKEY as a public key, private key or parameters to PEM, to DER, or to text.

RETURN VALUES¶

OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() returns a pointer to a OSSL_SERIALIZER_CTX, or NULL if it couldn't be created.

OSSL_SERIALIZER_CTX_set_cipher(), OSSL_SERIALIZER_CTX_set_passphrase(), OSSL_SERIALIZER_CTX_set_passphrase_cb(), and OSSL_SERIALIZER_CTX_set_passphrase_ui() all return 1 on success, or 0 on failure.

NOTES¶

Parts of the function and macro names are made to match already existing OpenSSL names.

EVP_PKEY in OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() matches the type name, thus making for the naming pattern OSSL_SERIALIZER_CTX_new_by_TYPE() when new types are handled.

PUBKEY, PrivateKey and Parameters in the macro names match the TYPE part of of PEM_write_bio_TYPE functions as well as i2d_TYPE_bio functions.

SEE ALSO¶

provider(7), OSSL_SERIALIZER(3), OSSL_SERIALIZER_CTX(3)

HISTORY¶

The functions described here were added in OpenSSL 3.0.

COPYRIGHT¶

Copyright 2019-2020 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>.