From fe75766c9c2919f649df7b3ad209df2bc5e56dd0 Mon Sep 17 00:00:00 2001 From: Tomas Mraz Date: Thu, 11 Feb 2021 16:57:37 +0100 Subject: Rename OSSL_ENCODER_CTX_new_by_EVP_PKEY and OSSL_DECODER_CTX_new_by_EVP_PKEY Additional renames done in encoder and decoder implementation to follow the style. Fixes #13622 Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/14155) --- apps/dhparam.c | 22 +-- apps/dsa.c | 4 +- apps/ec.c | 6 +- apps/ecparam.c | 4 +- apps/rsa.c | 6 +- crypto/asn1/i2d_evp.c | 4 +- crypto/cms/cms_ec.c | 4 +- crypto/encode_decode/decoder_pkey.c | 46 +++--- crypto/encode_decode/encoder_pkey.c | 32 ++-- crypto/evp/evp_pkey.c | 6 +- crypto/evp/p_lib.c | 4 +- crypto/pem/pem_all.c | 2 +- crypto/pem/pem_local.h | 58 +++---- crypto/pem/pem_pk8.c | 4 +- crypto/pem/pem_pkey.c | 8 +- crypto/store/store_result.c | 4 +- crypto/x509/x_pubkey.c | 12 +- doc/man3/OSSL_DECODER.pod | 2 +- doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod | 144 ------------------ doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod | 138 +++++++++++++++++ doc/man3/OSSL_ENCODER.pod | 2 +- doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod | 183 ----------------------- doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod | 174 +++++++++++++++++++++ doc/man3/d2i_RSAPrivateKey.pod | 4 +- include/crypto/decoder.h | 8 +- include/openssl/decoder.h | 10 +- include/openssl/encoder.h | 10 +- providers/encoders.inc | 10 +- providers/implementations/storemgmt/file_store.c | 10 +- ssl/ssl_conf.c | 6 +- test/endecode_test.c | 20 +-- test/endecoder_legacy_test.c | 42 +++--- test/evp_extra_test.c | 4 +- test/evp_libctx_test.c | 8 +- test/evp_pkey_provided_test.c | 8 +- util/libcrypto.num | 4 +- 36 files changed, 499 insertions(+), 514 deletions(-) delete mode 100644 doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod create mode 100644 doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod delete mode 100644 doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod create mode 100644 doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod diff --git a/apps/dhparam.c b/apps/dhparam.c index 30fdfbbf6e..d3f96e61d2 100644 --- a/apps/dhparam.c +++ b/apps/dhparam.c @@ -254,14 +254,14 @@ int dhparam_main(int argc, char **argv) * We check that we got one of those key types afterwards. */ decoderctx - = OSSL_DECODER_CTX_new_by_EVP_PKEY(&tmppkey, - (informat == FORMAT_ASN1) + = OSSL_DECODER_CTX_new_for_pkey(&tmppkey, + (informat == FORMAT_ASN1) ? "DER" : "PEM", - NULL, - (informat == FORMAT_ASN1) + NULL, + (informat == FORMAT_ASN1) ? keytype : NULL, - OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS, - NULL, NULL); + OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS, + NULL, NULL); if (decoderctx != NULL && !OSSL_DECODER_from_bio(decoderctx, in) @@ -328,11 +328,11 @@ int dhparam_main(int argc, char **argv) if (!noout) { OSSL_ENCODER_CTX *ectx = - OSSL_ENCODER_CTX_new_by_EVP_PKEY(pkey, - OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS, - outformat == FORMAT_ASN1 - ? "DER" : "PEM", - NULL, NULL); + OSSL_ENCODER_CTX_new_for_pkey(pkey, + OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS, + outformat == FORMAT_ASN1 + ? "DER" : "PEM", + NULL, NULL); if (ectx == NULL || !OSSL_ENCODER_to_bio(ectx, out)) { OSSL_ENCODER_CTX_free(ectx); diff --git a/apps/dsa.c b/apps/dsa.c index c4baaf7de9..523dab80fc 100644 --- a/apps/dsa.c +++ b/apps/dsa.c @@ -260,8 +260,8 @@ int dsa_main(int argc, char **argv) } /* Perform the encoding */ - ectx = OSSL_ENCODER_CTX_new_by_EVP_PKEY(pkey, selection, output_type, - output_structure, NULL); + ectx = OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, output_type, + output_structure, NULL); if (OSSL_ENCODER_CTX_get_num_encoders(ectx) == 0) { BIO_printf(bio_err, "%s format not supported\n", output_type); goto end; diff --git a/apps/ec.c b/apps/ec.c index d89c580020..490a64122b 100644 --- a/apps/ec.c +++ b/apps/ec.c @@ -256,9 +256,9 @@ int ec_main(int argc, char **argv) assert(private); } - ectx = OSSL_ENCODER_CTX_new_by_EVP_PKEY(eckey, selection, - output_type, output_structure, - NULL); + ectx = OSSL_ENCODER_CTX_new_for_pkey(eckey, selection, + output_type, output_structure, + NULL); if (enc != NULL) { OSSL_ENCODER_CTX_set_cipher(ectx, EVP_CIPHER_name(enc), NULL); if (passout != NULL) diff --git a/apps/ecparam.c b/apps/ecparam.c index e05a3a495f..fc19ab6bf9 100644 --- a/apps/ecparam.c +++ b/apps/ecparam.c @@ -292,7 +292,7 @@ int ecparam_main(int argc, char **argv) noout = 1; if (!noout) { - ectx_params = OSSL_ENCODER_CTX_new_by_EVP_PKEY( + ectx_params = OSSL_ENCODER_CTX_new_for_pkey( params_key, OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS, outformat == FORMAT_ASN1 ? "DER" : "PEM", NULL, NULL); if (!OSSL_ENCODER_to_bio(ectx_params, out)) { @@ -317,7 +317,7 @@ int ecparam_main(int argc, char **argv) goto end; } assert(private); - ectx_key = OSSL_ENCODER_CTX_new_by_EVP_PKEY( + ectx_key = OSSL_ENCODER_CTX_new_for_pkey( key, OSSL_KEYMGMT_SELECT_ALL, outformat == FORMAT_ASN1 ? "DER" : "PEM", NULL, NULL); if (!OSSL_ENCODER_to_bio(ectx_key, out)) { diff --git a/apps/rsa.c b/apps/rsa.c index 1a75681c70..8658f58708 100644 --- a/apps/rsa.c +++ b/apps/rsa.c @@ -334,9 +334,9 @@ int rsa_main(int argc, char **argv) } /* Now, perform the encoding */ - ectx = OSSL_ENCODER_CTX_new_by_EVP_PKEY(pkey, selection, - output_type, output_structure, - NULL); + ectx = OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, + output_type, output_structure, + NULL); if (OSSL_ENCODER_CTX_get_num_encoders(ectx) == 0) { BIO_printf(bio_err, "%s format not supported\n", output_type); goto end; diff --git a/crypto/asn1/i2d_evp.c b/crypto/asn1/i2d_evp.c index 599c512901..515a81d18c 100644 --- a/crypto/asn1/i2d_evp.c +++ b/crypto/asn1/i2d_evp.c @@ -42,8 +42,8 @@ static int i2d_provided(const EVP_PKEY *a, int selection, */ size_t len = INT_MAX; - ctx = OSSL_ENCODER_CTX_new_by_EVP_PKEY(a, selection, "DER", - *output_structures, NULL); + ctx = OSSL_ENCODER_CTX_new_for_pkey(a, selection, "DER", + *output_structures, NULL); if (ctx == NULL) return -1; if (OSSL_ENCODER_to_data(ctx, pp, &len)) diff --git a/crypto/cms/cms_ec.c b/crypto/cms/cms_ec.c index 8ae912c9c3..79b96f596c 100644 --- a/crypto/cms/cms_ec.c +++ b/crypto/cms/cms_ec.c @@ -27,8 +27,8 @@ static EVP_PKEY *pkey_type2param(int ptype, const void *pval, OSSL_DECODER_CTX *ctx = NULL; int selection = OSSL_KEYMGMT_SELECT_ALL_PARAMETERS; - ctx = OSSL_DECODER_CTX_new_by_EVP_PKEY(&pkey, "DER", NULL, "EC", - selection, libctx, propq); + ctx = OSSL_DECODER_CTX_new_for_pkey(&pkey, "DER", NULL, "EC", + selection, libctx, propq); if (ctx == NULL) goto err; diff --git a/crypto/encode_decode/decoder_pkey.c b/crypto/encode_decode/decoder_pkey.c index c515cb6d44..3a97afbcb0 100644 --- a/crypto/encode_decode/decoder_pkey.c +++ b/crypto/encode_decode/decoder_pkey.c @@ -48,13 +48,13 @@ int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx, } /* - * Support for OSSL_DECODER_CTX_new_by_EVP_PKEY: + * Support for OSSL_DECODER_CTX_new_for_pkey: * The construct data, and collecting keymgmt information for it */ DEFINE_STACK_OF(EVP_KEYMGMT) -struct decoder_EVP_PKEY_data_st { +struct decoder_pkey_data_st { OSSL_LIB_CTX *libctx; char *propq; @@ -62,11 +62,11 @@ struct decoder_EVP_PKEY_data_st { void **object; /* Where the result should end up */ }; -static int decoder_construct_EVP_PKEY(OSSL_DECODER_INSTANCE *decoder_inst, - const OSSL_PARAM *params, - void *construct_data) +static int decoder_construct_pkey(OSSL_DECODER_INSTANCE *decoder_inst, + const OSSL_PARAM *params, + void *construct_data) { - struct decoder_EVP_PKEY_data_st *data = construct_data; + struct decoder_pkey_data_st *data = construct_data; OSSL_DECODER *decoder = OSSL_DECODER_INSTANCE_get_decoder(decoder_inst); void *decoderctx = OSSL_DECODER_INSTANCE_get_decoder_ctx(decoder_inst); EVP_KEYMGMT *keymgmt = NULL; @@ -159,9 +159,9 @@ static int decoder_construct_EVP_PKEY(OSSL_DECODER_INSTANCE *decoder_inst, return (*data->object != NULL); } -static void decoder_clean_EVP_PKEY_construct_arg(void *construct_data) +static void decoder_clean_pkey_construct_arg(void *construct_data) { - struct decoder_EVP_PKEY_data_st *data = construct_data; + struct decoder_pkey_data_st *data = construct_data; if (data != NULL) { OPENSSL_free(data->propq); @@ -269,12 +269,12 @@ static void collect_decoder(OSSL_DECODER *decoder, void *arg) data->error_occured = 0; /* All is good now */ } -int ossl_decoder_ctx_setup_for_EVP_PKEY(OSSL_DECODER_CTX *ctx, - EVP_PKEY **pkey, const char *keytype, - OSSL_LIB_CTX *libctx, - const char *propquery) +int ossl_decoder_ctx_setup_for_pkey(OSSL_DECODER_CTX *ctx, + EVP_PKEY **pkey, const char *keytype, + OSSL_LIB_CTX *libctx, + const char *propquery) { - struct decoder_EVP_PKEY_data_st *process_data = NULL; + struct decoder_pkey_data_st *process_data = NULL; STACK_OF(EVP_KEYMGMT) *keymgmts = NULL; STACK_OF(OPENSSL_CSTRING) *names = NULL; int ok = 0; @@ -327,10 +327,10 @@ int ossl_decoder_ctx_setup_for_EVP_PKEY(OSSL_DECODER_CTX *ctx, } if (OSSL_DECODER_CTX_get_num_decoders(ctx) != 0) { - if (!OSSL_DECODER_CTX_set_construct(ctx, decoder_construct_EVP_PKEY) + if (!OSSL_DECODER_CTX_set_construct(ctx, decoder_construct_pkey) || !OSSL_DECODER_CTX_set_construct_data(ctx, process_data) || !OSSL_DECODER_CTX_set_cleanup(ctx, - decoder_clean_EVP_PKEY_construct_arg)) + decoder_clean_pkey_construct_arg)) goto err; process_data = NULL; /* Avoid it being freed */ @@ -338,16 +338,16 @@ int ossl_decoder_ctx_setup_for_EVP_PKEY(OSSL_DECODER_CTX *ctx, ok = 1; err: - decoder_clean_EVP_PKEY_construct_arg(process_data); + decoder_clean_pkey_construct_arg(process_data); return ok; } OSSL_DECODER_CTX * -OSSL_DECODER_CTX_new_by_EVP_PKEY(EVP_PKEY **pkey, - const char *input_type, - const char *input_structure, - const char *keytype, int selection, - OSSL_LIB_CTX *libctx, const char *propquery) +OSSL_DECODER_CTX_new_for_pkey(EVP_PKEY **pkey, + const char *input_type, + const char *input_structure, + const char *keytype, int selection, + OSSL_LIB_CTX *libctx, const char *propquery) { OSSL_DECODER_CTX *ctx = NULL; @@ -367,8 +367,8 @@ OSSL_DECODER_CTX_new_by_EVP_PKEY(EVP_PKEY **pkey, if (OSSL_DECODER_CTX_set_input_type(ctx, input_type) && OSSL_DECODER_CTX_set_input_structure(ctx, input_structure) && OSSL_DECODER_CTX_set_selection(ctx, selection) - && ossl_decoder_ctx_setup_for_EVP_PKEY(ctx, pkey, keytype, - libctx, propquery) + && ossl_decoder_ctx_setup_for_pkey(ctx, pkey, keytype, + libctx, propquery) && OSSL_DECODER_CTX_add_extra(ctx, libctx, propquery)) { OSSL_TRACE_BEGIN(DECODER) { BIO_printf(trc_out, "(ctx %p) Got %d decoders\n", diff --git a/crypto/encode_decode/encoder_pkey.c b/crypto/encode_decode/encoder_pkey.c index e8e1c77b5f..9604ae56bd 100644 --- a/crypto/encode_decode/encoder_pkey.c +++ b/crypto/encode_decode/encoder_pkey.c @@ -67,7 +67,7 @@ int OSSL_ENCODER_CTX_set_passphrase_cb(OSSL_ENCODER_CTX *ctx, } /* - * Support for OSSL_ENCODER_CTX_new_by_TYPE: + * Support for OSSL_ENCODER_CTX_new_for_type: * finding a suitable encoder */ @@ -162,7 +162,7 @@ static int encoder_import_cb(const OSSL_PARAM params[], void *arg) } static const void * -encoder_construct_EVP_PKEY(OSSL_ENCODER_INSTANCE *encoder_inst, void *arg) +encoder_construct_pkey(OSSL_ENCODER_INSTANCE *encoder_inst, void *arg) { struct construct_data_st *data = arg; @@ -188,7 +188,7 @@ encoder_construct_EVP_PKEY(OSSL_ENCODER_INSTANCE *encoder_inst, void *arg) return data->obj; } -static void encoder_destruct_EVP_PKEY(void *arg) +static void encoder_destruct_pkey(void *arg) { struct construct_data_st *data = arg; @@ -202,15 +202,15 @@ static void encoder_destruct_EVP_PKEY(void *arg) } /* - * OSSL_ENCODER_CTX_new_by_EVP_PKEY() returns a ctx with no encoder if + * OSSL_ENCODER_CTX_new_for_pkey() returns a ctx with no encoder if * it couldn't find a suitable encoder. This allows a caller to detect if * a suitable encoder was found, with OSSL_ENCODER_CTX_get_num_encoder(), * and to use fallback methods if the result is NULL. */ -static int ossl_encoder_ctx_setup_for_EVP_PKEY(OSSL_ENCODER_CTX *ctx, - const EVP_PKEY *pkey, - int selection, - const char *propquery) +static int ossl_encoder_ctx_setup_for_pkey(OSSL_ENCODER_CTX *ctx, + const EVP_PKEY *pkey, + int selection, + const char *propquery) { struct construct_data_st *data = NULL; OSSL_LIB_CTX *libctx = NULL; @@ -262,9 +262,9 @@ static int ossl_encoder_ctx_setup_for_EVP_PKEY(OSSL_ENCODER_CTX *ctx, } if (OSSL_ENCODER_CTX_get_num_encoders(ctx) != 0) { - if (!OSSL_ENCODER_CTX_set_construct(ctx, encoder_construct_EVP_PKEY) + if (!OSSL_ENCODER_CTX_set_construct(ctx, encoder_construct_pkey) || !OSSL_ENCODER_CTX_set_construct_data(ctx, data) - || !OSSL_ENCODER_CTX_set_cleanup(ctx, encoder_destruct_EVP_PKEY)) + || !OSSL_ENCODER_CTX_set_cleanup(ctx, encoder_destruct_pkey)) goto err; data->pk = pkey; @@ -282,11 +282,11 @@ static int ossl_encoder_ctx_setup_for_EVP_PKEY(OSSL_ENCODER_CTX *ctx, return ok; } -OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey, - int selection, - const char *output_type, - const char *output_struct, - const char *propquery) +OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new_for_pkey(const EVP_PKEY *pkey, + int selection, + const char *output_type, + const char *output_struct, + const char *propquery) { OSSL_ENCODER_CTX *ctx = NULL; OSSL_LIB_CTX *libctx = NULL; @@ -325,7 +325,7 @@ OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey, && (output_struct == NULL || OSSL_ENCODER_CTX_set_output_structure(ctx, output_struct)) && OSSL_ENCODER_CTX_set_selection(ctx, selection) - && ossl_encoder_ctx_setup_for_EVP_PKEY(ctx, pkey, selection, propquery) + && ossl_encoder_ctx_setup_for_pkey(ctx, pkey, selection, propquery) && OSSL_ENCODER_CTX_add_extra(ctx, libctx, propquery)) { OSSL_TRACE_BEGIN(ENCODER) { BIO_printf(trc_out, "(ctx %p) Got %d encoders\n", diff --git a/crypto/evp/evp_pkey.c b/crypto/evp/evp_pkey.c index dd20a52e7a..87091cf16b 100644 --- a/crypto/evp/evp_pkey.c +++ b/crypto/evp/evp_pkey.c @@ -85,9 +85,9 @@ PKCS8_PRIV_KEY_INFO *EVP_PKEY2PKCS8(const EVP_PKEY *pkey) size_t derlen = 0; const unsigned char *pp; - if ((ctx = OSSL_ENCODER_CTX_new_by_EVP_PKEY(pkey, selection, - "DER", "pkcs8", - NULL)) == NULL + if ((ctx = OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, + "DER", "pkcs8", + NULL)) == NULL || !OSSL_ENCODER_to_data(ctx, &der, &derlen)) goto error; diff --git a/crypto/evp/p_lib.c b/crypto/evp/p_lib.c index 8cf65d6a34..e655adde05 100644 --- a/crypto/evp/p_lib.c +++ b/crypto/evp/p_lib.c @@ -1093,8 +1093,8 @@ static int print_pkey(const EVP_PKEY *pkey, BIO *out, int indent, if (!print_set_indent(&out, &pop_f_prefix, &saved_indent, indent)) return 0; - ctx = OSSL_ENCODER_CTX_new_by_EVP_PKEY(pkey, selection, "TEXT", NULL, - propquery); + ctx = OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, "TEXT", NULL, + propquery); if (OSSL_ENCODER_CTX_get_num_encoders(ctx) != 0) ret = OSSL_ENCODER_to_bio(ctx, out); OSSL_ENCODER_CTX_free(ctx); diff --git a/crypto/pem/pem_all.c b/crypto/pem/pem_all.c index 8766395051..222af64397 100644 --- a/crypto/pem/pem_all.c +++ b/crypto/pem/pem_all.c @@ -223,4 +223,4 @@ DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u) # endif #endif -IMPLEMENT_PEM_provided_write(PUBKEY, EVP_PKEY, PEM_STRING_PUBLIC, PUBKEY) +IMPLEMENT_PEM_provided_write(PUBKEY, EVP_PKEY, pkey, PEM_STRING_PUBLIC, PUBKEY) diff --git a/crypto/pem/pem_local.h b/crypto/pem/pem_local.h index 3f54644e89..732825c03c 100644 --- a/crypto/pem/pem_local.h +++ b/crypto/pem/pem_local.h @@ -47,7 +47,7 @@ # define IMPLEMENT_PEM_provided_write_body_vars(type, asn1, pq) \ int ret = 0; \ OSSL_ENCODER_CTX *ctx = \ - OSSL_ENCODER_CTX_new_by_##type(x, PEM_SELECTION_##asn1, \ + OSSL_ENCODER_CTX_new_for_##type(x, PEM_SELECTION_##asn1, \ "PEM", PEM_STRUCTURE_##asn1, \ (pq)); \ \ @@ -98,16 +98,16 @@ return PEM_ASN1_##writename##((i2d_of_void *)i2d_##asn1, str, out, \ x, enc, kstr, klen, cb, u) -# define IMPLEMENT_PEM_provided_write_to(name, type, str, asn1, \ +# define IMPLEMENT_PEM_provided_write_to(name, TYPE, type, str, asn1, \ OUTTYPE, outtype, writename) \ - PEM_write_fnsig(name, type, OUTTYPE, writename) \ + PEM_write_fnsig(name, TYPE, OUTTYPE, writename) \ { \ IMPLEMENT_PEM_provided_write_body_vars(type, asn1, NULL); \ IMPLEMENT_PEM_provided_write_body_main(type, outtype); \ IMPLEMENT_PEM_provided_write_body_fallback(str, asn1, \ writename); \ } \ - PEM_write_ex_fnsig(name, type, OUTTYPE, writename) \ + PEM_write_ex_fnsig(name, TYPE, OUTTYPE, writename) \ { \ IMPLEMENT_PEM_provided_write_body_vars(type, asn1, propq); \ IMPLEMENT_PEM_provided_write_body_main(type, outtype); \ @@ -116,9 +116,9 @@ } -# define IMPLEMENT_PEM_provided_write_cb_to(name, type, str, asn1, \ +# define IMPLEMENT_PEM_provided_write_cb_to(name, TYPE, type, str, asn1, \ OUTTYPE, outtype, writename) \ - PEM_write_cb_fnsig(name, type, OUTTYPE, writename) \ + PEM_write_cb_fnsig(name, TYPE, OUTTYPE, writename) \ { \ IMPLEMENT_PEM_provided_write_body_vars(type, asn1, NULL); \ IMPLEMENT_PEM_provided_write_body_pass(); \ @@ -126,7 +126,7 @@ IMPLEMENT_PEM_provided_write_body_fallback_cb(str, asn1, \ writename); \ } \ - PEM_write_ex_cb_fnsig(name, type, OUTTYPE, writename) \ + PEM_write_ex_cb_fnsig(name, TYPE, OUTTYPE, writename) \ { \ IMPLEMENT_PEM_provided_write_body_vars(type, asn1, propq); \ IMPLEMENT_PEM_provided_write_body_pass(); \ @@ -137,36 +137,36 @@ # ifdef OPENSSL_NO_STDIO -# define IMPLEMENT_PEM_provided_write_fp(name, type, str, asn1) -# define IMPLEMENT_PEM_provided_write_cb_fp(name, type, str, asn1) +# define IMPLEMENT_PEM_provided_write_fp(name, TYPE, type, str, asn1) +# define IMPLEMENT_PEM_provided_write_cb_fp(name, TYPE, type, str, asn1) # else -# define IMPLEMENT_PEM_provided_write_fp(name, type, str, asn1) \ - IMPLEMENT_PEM_provided_write_to(name, type, str, asn1, FILE, fp, write) -# define IMPLEMENT_PEM_provided_write_cb_fp(name, type, str, asn1) \ - IMPLEMENT_PEM_provided_write_cb_to(name, type, str, asn1, FILE, fp, write) +# define IMPLEMENT_PEM_provided_write_fp(name, TYPE, type, str, asn1) \ + IMPLEMENT_PEM_provided_write_to(name, TYPE, type, str, asn1, FILE, fp, write) +# define IMPLEMENT_PEM_provided_write_cb_fp(name, TYPE, type, str, asn1) \ + IMPLEMENT_PEM_provided_write_cb_to(name, TYPE, type, str, asn1, FILE, fp, write) # endif -# define IMPLEMENT_PEM_provided_write_bio(name, type, str, asn1) \ - IMPLEMENT_PEM_provided_write_to(name, type, str, asn1, BIO, bio, write_bio) -# define IMPLEMENT_PEM_provided_write_cb_bio(name, type, str, asn1) \ - IMPLEMENT_PEM_provided_write_cb_to(name, type, str, asn1, BIO, bio, write_bio) +# define IMPLEMENT_PEM_provided_write_bio(name, TYPE, type, str, asn1) \ + IMPLEMENT_PEM_provided_write_to(name, TYPE, type, str, asn1, BIO, bio, write_bio) +# define IMPLEMENT_PEM_provided_write_cb_bio(name, TYPE, type, str, asn1) \ + IMPLEMENT_PEM_provided_write_cb_to(name, TYPE, type, str, asn1, BIO, bio, write_bio) -# define IMPLEMENT_PEM_provided_write(name, type, str, asn1) \ - IMPLEMENT_PEM_provided_write_bio(name, type, str, asn1) \ - IMPLEMENT_PEM_provided_write_fp(name, type, str, asn1) +# define IMPLEMENT_PEM_provided_write(name, TYPE, type, str, asn1) \ + IMPLEMENT_PEM_provided_write_bio(name, TYPE, type, str, asn1) \ + IMPLEMENT_PEM_provided_write_fp(name, TYPE, type, str, asn1) -# define IMPLEMENT_PEM_provided_write_cb(name, type, str, asn1) \ - IMPLEMENT_PEM_provided_write_cb_bio(name, type, str, asn1) \ - IMPLEMENT_PEM_provided_write_cb_fp(name, type, str, asn1) +# define IMPLEMENT_PEM_provided_write_cb(name, TYPE, type, str, asn1) \ + IMPLEMENT_PEM_provided_write_cb_bio(name, TYPE, type, str, asn1) \ + IMPLEMENT_PEM_provided_write_cb_fp(name, TYPE, type, str, asn1) -# define IMPLEMENT_PEM_provided_rw(name, type, str, asn1) \ - IMPLEMENT_PEM_read(name, type, str, asn1) \ - IMPLEMENT_PEM_provided_write(name, type, str, asn1) +# define IMPLEMENT_PEM_provided_rw(name, TYPE, type, str, asn1) \ + IMPLEMENT_PEM_read(name, TYPE, str, asn1) \ + IMPLEMENT_PEM_provided_write(name, TYPE, type, str, asn1) -# define IMPLEMENT_PEM_provided_rw_cb(name, type, str, asn1) \ - IMPLEMENT_PEM_read(name, type, str, asn1) \ - IMPLEMENT_PEM_provided_write_cb(name, type, str, asn1) +# define IMPLEMENT_PEM_provided_rw_cb(name, TYPE, type, str, asn1) \ + IMPLEMENT_PEM_read(name, TYPE, str, asn1) \ + IMPLEMENT_PEM_provided_write_cb(name, TYPE, type, str, asn1) diff --git a/crypto/pem/pem_pk8.c b/crypto/pem/pem_pk8.c index 09d38855b6..62fa45f13d 100644 --- a/crypto/pem/pem_pk8.c +++ b/crypto/pem/pem_pk8.c @@ -73,8 +73,8 @@ static int do_pk8pkey(BIO *bp, const EVP_PKEY *x, int isder, int nid, int ret = 0; const char *outtype = isder ? "DER" : "PEM"; OSSL_ENCODER_CTX *ctx = - OSSL_ENCODER_CTX_new_by_EVP_PKEY(x, OSSL_KEYMGMT_SELECT_ALL, - outtype, "pkcs8", propq); + OSSL_ENCODER_CTX_new_for_pkey(x, OSSL_KEYMGMT_SELECT_ALL, + outtype, "pkcs8", propq); if (ctx == NULL) return 0; diff --git a/crypto/pem/pem_pkey.c b/crypto/pem/pem_pkey.c index c71bc24bb2..f7cc7b88c6 100644 --- a/crypto/pem/pem_pkey.c +++ b/crypto/pem/pem_pkey.c @@ -153,10 +153,10 @@ EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, pem_password_cb *cb, PEM_write_cb_ex_fnsig(PrivateKey, EVP_PKEY, BIO, write_bio) { - IMPLEMENT_PEM_provided_write_body_vars(EVP_PKEY, PrivateKey, propq); + IMPLEMENT_PEM_provided_write_body_vars(pkey, PrivateKey, propq); IMPLEMENT_PEM_provided_write_body_pass(); - IMPLEMENT_PEM_provided_write_body_main(EVP_PKEY, bio); + IMPLEMENT_PEM_provided_write_body_main(pkey, bio); legacy: if (x->ameth == NULL || x->ameth->priv_encode != NULL) @@ -218,9 +218,9 @@ EVP_PKEY *PEM_read_bio_Parameters(BIO *bp, EVP_PKEY **x) PEM_write_fnsig(Parameters, EVP_PKEY, BIO, write_bio) { char pem_str[80]; - IMPLEMENT_PEM_provided_write_body_vars(EVP_PKEY, Parameters, NULL); + IMPLEMENT_PEM_provided_write_body_vars(pkey, Parameters, NULL); - IMPLEMENT_PEM_provided_write_body_main(EVP_PKEY, bio); + IMPLEMENT_PEM_provided_write_body_main(pkey, bio); legacy: if (!x->ameth || !x->ameth->param_encode) diff --git a/crypto/store/store_result.c b/crypto/store/store_result.c index e0c0532152..6ac77b77dd 100644 --- a/crypto/store/store_result.c +++ b/crypto/store/store_result.c @@ -274,8 +274,8 @@ static EVP_PKEY *try_key_value(struct extracted_param_data_st *data, } decoderctx = - OSSL_DECODER_CTX_new_by_EVP_PKEY(&pk, "DER", NULL, data->data_type, - selection, libctx, propq); + OSSL_DECODER_CTX_new_for_pkey(&pk, "DER", NULL, data->data_type, + selection, libctx, propq); (void)OSSL_DECODER_CTX_set_passphrase_cb(decoderctx, cb, cbarg); /* No error if this couldn't be decoded */ diff --git a/crypto/x509/x_pubkey.c b/crypto/x509/x_pubkey.c index 740702d730..5d500f0690 100644 --- a/crypto/x509/x_pubkey.c +++ b/crypto/x509/x_pubkey.c @@ -122,9 +122,9 @@ int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey) unsigned char *der = NULL; size_t derlen = 0; OSSL_ENCODER_CTX *ectx = - OSSL_ENCODER_CTX_new_by_EVP_PKEY(pkey, EVP_PKEY_PUBLIC_KEY, - "DER", "SubjectPublicKeyInfo", - NULL); + OSSL_ENCODER_CTX_new_for_pkey(pkey, EVP_PKEY_PUBLIC_KEY, + "DER", "SubjectPublicKeyInfo", + NULL); if (OSSL_ENCODER_to_data(ectx, &der, &derlen)) { const unsigned char *pder = der; @@ -325,9 +325,9 @@ int i2d_PUBKEY(const EVP_PKEY *a, unsigned char **pp) X509_PUBKEY_free(xpk); } else if (a->keymgmt != NULL) { OSSL_ENCODER_CTX *ctx = - OSSL_ENCODER_CTX_new_by_EVP_PKEY(a, EVP_PKEY_PUBLIC_KEY, - "DER", "SubjectPublicKeyInfo", - NULL); + OSSL_ENCODER_CTX_new_for_pkey(a, EVP_PKEY_PUBLIC_KEY, + "DER", "SubjectPublicKeyInfo", + NULL); BIO *out = BIO_new(BIO_s_mem()); BUF_MEM *buf = NULL; diff --git a/doc/man3/OSSL_DECODER.pod b/doc/man3/OSSL_DECODER.pod index f87e693e09..9bc2a035ae 100644 --- a/doc/man3/OSSL_DECODER.pod +++ b/doc/man3/OSSL_DECODER.pod @@ -124,7 +124,7 @@ Text, because pod2xxx doesn't like empty sections =head1 SEE ALSO L, L, L, -L, L +L, L =head1 HISTORY diff --git a/doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod b/doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod deleted file mode 100644 index 38425ae7dc..0000000000 --- a/doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod +++ /dev/null @@ -1,144 +0,0 @@ -=pod - -=head1 NAME - -OSSL_DECODER_CTX_new_by_EVP_PKEY, -OSSL_DECODER_CTX_set_passphrase, -OSSL_DECODER_CTX_set_pem_password_cb, -OSSL_DECODER_CTX_set_passphrase_ui, -OSSL_DECODER_CTX_set_passphrase_cb -- Decoder routines to decode EVP_PKEYs - -=head1 SYNOPSIS - - #include - - OSSL_DECODER_CTX * - OSSL_DECODER_CTX_new_by_EVP_PKEY(EVP_PKEY **pkey, - const char *input_type, - const char *input_struct, - const char *keytype, int selection, - OSSL_LIB_CTX *libctx, const char *propquery); - - int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx, - const unsigned char *kstr, - size_t klen); - int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx, - pem_password_cb *cb, - void *cbarg); - int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx, - const UI_METHOD *ui_method, - void *ui_data); - int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx, - OSSL_PASSPHRASE_CALLBACK *cb, - void *cbarg); - -=head1 DESCRIPTION - -OSSL_DECODER_CTX_new_by_EVP_PKEY() is a utility function that creates a -B, finds all applicable decoder implementations and sets -them up, so all the caller has to do next is call functions like -L. The caller may use the optional I, -I, I and I to specify what the input is -expected to contain. - -Internally OSSL_DECODER_CTX_new_by_EVP_PKEY() searches for all available -L implementations, and then builds a list of all potential -decoder implementations that may be able to process the encoded input into -data suitable for Bs. All these implementations are implicitly -fetched using I and I. - -The search of decoder implementations can be limited with I and -I which specifies a starting input type and input structure. -NULL is valid for both of them and signifies that the decoder implementations -will find out the input type on their own. -They are set with L and -L. -See L and L below for further information. - -The search of decoder implementations can also be limited with I -and I, which specifies the expected resulting keytype and contents. -NULL and zero are valid and signify that the decoder implementations will -find out the keytype and key contents on their own from the input they get. - -If no suitable decoder implementation is found, -OSSL_DECODER_CTX_new_by_EVP_PKEY() still creates a B, but -with no associated decoder (L returns -zero). This helps the caller to distinguish between an error when creating -the B and missing encoder implementation, and allows it to -act accordingly. - -OSSL_DECODER_CTX_set_passphrase() gives the implementation a pass phrase to -use when decrypting the encoded private key. Alternatively, a pass phrase -callback may be specified with the following functions. - -OSSL_DECODER_CTX_set_pem_password_cb(), OSSL_DECODER_CTX_set_passphrase_ui() -and OSSL_DECODER_CTX_set_passphrase_cb() set up a callback method that the -implementation can use to prompt for a pass phrase, giving the caller the -choice of prefered pass phrase callback form. These are called indirectly, -through an internal B function. - -The internal B function caches the pass phrase, to -be re-used in all decodings that are performed in the same decoding run (for -example, within one L call). - -=head2 Input Types - -Available input types depend on the implementations that available providers -offer, and provider documentation should have the details. - -Among the known input types that OpenSSL decoder implementations offer -for Bs are C, C, C and C. -See L for further information on what these input -types mean. - -=head2 Input Structures - -Available input structures depend on the implementations that available -providers offer, and provider documentation should have the details. - -Among the known input structures that OpenSSL decoder implementations -offer for Bs are C and C. - -OpenSSL decoder implementations also support the input structure -C. This is the structure used for keys encoded -according to key type specific specifications. For example, RSA keys -encoded according to PKCS#1. - -=head1 RETURN VALUES - -OSSL_DECODER_CTX_new_by_EVP_PKEY() returns a pointer to a -B, or NULL if it couldn't be created. - -OSSL_DECODER_CTX_set_passphrase(), OSSL_DECODER_CTX_set_pem_password_cb(), -OSSL_DECODER_CTX_set_passphrase_ui() and -OSSL_DECODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on -failure. - -=head1 NOTES - -Parts of the function names are made to match already existing OpenSSL -names. - -B in OSSL_DECODER_CTX_new_by_EVP_PKEY() matches the type name, -thus making for the naming pattern B>() when -new types are handled. - -=head1 SEE ALSO - -L, L, L - -=head1 HISTORY - -The functions described here were added in OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 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 -L. - -=cut diff --git a/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod b/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod new file mode 100644 index 0000000000..acb28f8306 --- /dev/null +++ b/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod @@ -0,0 +1,138 @@ +=pod + +=head1 NAME + +OSSL_DECODER_CTX_new_for_pkey, +OSSL_DECODER_CTX_set_passphrase, +OSSL_DECODER_CTX_set_pem_password_cb, +OSSL_DECODER_CTX_set_passphrase_ui, +OSSL_DECODER_CTX_set_passphrase_cb +- Decoder routines to decode EVP_PKEYs + +=head1 SYNOPSIS + + #include + + OSSL_DECODER_CTX * + OSSL_DECODER_CTX_new_for_pkey(EVP_PKEY **pkey, + const char *input_type, + const char *input_struct, + const char *keytype, int selection, + OSSL_LIB_CTX *libctx, const char *propquery); + + int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx, + const unsigned char *kstr, + size_t klen); + int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx, + pem_password_cb *cb, + void *cbarg); + int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx, + const UI_METHOD *ui_method, + void *ui_data); + int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx, + OSSL_PASSPHRASE_CALLBACK *cb, + void *cbarg); + +=head1 DESCRIPTION + +OSSL_DECODER_CTX_new_for_pkey() is a utility function that creates a +B, finds all applicable decoder implementations and sets +them up, so all the caller has to do next is call functions like +L. The caller may use the optional I, +I, I and I to specify what the input is +expected to contain. The I must reference an B variable +that will be set to the newly created B on succesfull decoding. +The referenced variable must be initialized to NULL before calling the +function. + +Internally OSSL_DECODER_CTX_new_for_pkey() searches for all available +L implementations, and then builds a list of all potential +decoder implementations that may be able to process the encoded input into +data suitable for Bs. All these implementations are implicitly +fetched using I and I. + +The search of decoder implementations can be limited with I and +I which specifies a starting input type and input structure. +NULL is valid for both of them and signifies that the decoder implementations +will find out the input type on their own. +They are set with L and +L. +See L and L below for further information. + +The search of decoder implementations can also be limited with I +and I, which specifies the expected resulting keytype and contents. +NULL and zero are valid and signify that the decoder implementations will +find out the keytype and key contents on their own from the input they get. + +If no suitable decoder implementation is found, +OSSL_DECODER_CTX_new_for_pkey() still creates a B, but +with no associated decoder (L returns +zero). This helps the caller to distinguish between an error when creating +the B and missing encoder implementation, and allows it to +act accordingly. + +OSSL_DECODER_CTX_set_passphrase() gives the implementation a pass phrase to +use when decrypting the encoded private key. Alternatively, a pass phrase +callback may be specified with the following functions. + +OSSL_DECODER_CTX_set_pem_password_cb(), OSSL_DECODER_CTX_set_passphrase_ui() +and OSSL_DECODER_CTX_set_passphrase_cb() set up a callback method that the +implementation can use to prompt for a pass phrase, giving the caller the +choice of prefered pass phrase callback form. These are called indirectly, +through an internal B function. + +The internal B function caches the pass phrase, to +be re-used in all decodings that are performed in the same decoding run (for +example, within one L call). + +=head2 Input Types + +Available input types depend on the implementations that available providers +offer, and provider documentation should have the details. + +Among the known input types that OpenSSL decoder implementations offer +for Bs are C, C, C and C. +See L for further information on what these input +types mean. + +=head2 Input Structures + +Available input structures depend on the implementations that available +providers offer, and provider documentation should have the details. + +Among the known input structures that OpenSSL decoder implementations +offer for Bs are C and C. + +OpenSSL decoder implementations also support the input structure +C. This is the structure used for keys encoded +according to key type specific specifications. For example, RSA keys +encoded according to PKCS#1. + +=head1 RETURN VALUES + +OSSL_DECODER_CTX_new_for_pkey() returns a pointer to a +B, or NULL if it couldn't be created. + +OSSL_DECODER_CTX_set_passphrase(), OSSL_DECODER_CTX_set_pem_password_cb(), +OSSL_DECODER_CTX_set_passphrase_ui() and +OSSL_DECODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on +failure. + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +The functions described here were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 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 +L. + +=cut diff --git a/doc/man3/OSSL_ENCODER.pod b/doc/man3/OSSL_ENCODER.pod index da1aa475dc..6952d850f4 100644 --- a/doc/man3/OSSL_ENCODER.pod +++ b/doc/man3/OSSL_ENCODER.pod @@ -117,7 +117,7 @@ Any other API that uses keys will typically do this. =head1 SEE ALSO L, L, L, -L, L +L, L =head1 HISTORY diff --git a/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod b/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod deleted file mode 100644 index 403d7a00be..0000000000 --- a/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod +++ /dev/null @@ -1,183 +0,0 @@ -=pod - -=head1 NAME - -OSSL_ENCODER_CTX_new_by_EVP_PKEY, -OSSL_ENCODER_CTX_set_cipher, -OSSL_ENCODER_CTX_set_passphrase, -OSSL_ENCODER_CTX_set_pem_password_cb, -OSSL_ENCODER_CTX_set_passphrase_cb, -OSSL_ENCODER_CTX_set_passphrase_ui -- Encoder routines to encode EVP_PKEYs - -=head1 SYNOPSIS - - #include - - OSSL_ENCODER_CTX * - OSSL_ENCODER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey, int selection, - const char *output_type, - const char *output_structure, - const char *propquery); - - int OSSL_ENCODER_CTX_set_cipher(OSSL_ENCODER_CTX *ctx, - const char *cipher_name, - const char *propquery); - int OSSL_ENCODER_CTX_set_passphrase(OSSL_ENCODER_CTX *ctx, - const unsigned char *kstr, - size_t klen); - int OSSL_ENCODER_CTX_set_pem_password_cb(OSSL_ENCODER_CTX *ctx, - pem_password_cb *cb, void *cbarg); - int OSSL_ENCODER_CTX_set_passphrase_ui(OSSL_ENCODER_CTX *ctx, - const UI_METHOD *ui_method, - void *ui_data); - int OSSL_ENCODER_CTX_set_passphrase_cb(OSSL_ENCODER_CTX *ctx, - OSSL_PASSPHRASE_CALLBACK *cb, - void *cbarg); - -=head1 DESCRIPTION - -OSSL_ENCODER_CTX_new_by_EVP_PKEY() is a utility function that creates a -B, finds all applicable encoder implementations and sets -them up, so almost all the caller has to do next is call functions like -L. I determines the final output -encoding, and I can be used to select what parts of the I -should be included in the output. I is further discussed in -L below, and I is further described in -L. - -Internally, OSSL_ENCODER_CTX_new_by_EVP_PKEY() uses the names from the -L implementation associated with I to build a list of -applicable encoder implementations that are used to process the I into -the encoding named by I, with the outermost structure named by -I if that's relevant. All these implementations are -implicitly fetched, with I for finer selection. - -If no suitable encoder implementation is found, -OSSL_ENCODER_CTX_new_by_EVP_PKEY() still creates a B, but -with no associated encoder (L returns -zero). This helps the caller to distinguish between an error when creating -the B and missing encoder implementation, and allows it to -act accordingly. - -OSSL_ENCODER_CTX_set_cipher() tells the implementation what cipher -should be used to encrypt encoded keys. The cipher is given by -name I. The interpretation of that I is -implementation dependent. The implementation may implement the cipher -directly itself or by other implementations, or it may choose to fetch -it. If the implementation supports fetching the cipher, then it may -use I as properties to be queried for when fetching. -I may also be NULL, which will result in unencrypted -encoding. - -OSSL_ENCODER_CTX_set_passphrase() gives the implementation a -pass phrase to use when encrypting the encoded private key. -Alternatively, a pass phrase callback may be specified with the -following functions. - -OSSL_ENCODER_CTX_set_pem_password_cb(), OSSL_ENCODER_CTX_set_passphrase_ui() -and OSSL_ENCODER_CTX_set_passphrase_cb() sets up a callback method that the -implementation can use to prompt for a pass phrase, giving the caller the -choice of prefered pass phrase callback form. These are called indirectly, -through an internal B function. - -=head2 Output types - -The possible B output types depends on the available -implementations. - -OpenSSL has built in implementations for the following output types: - -=over 4 - -=item C - -The output is a human readable description of the key. -L, L and -L use this for their output. - -=item C - -The output is the DER encoding of the I of the I. - -=item C - -The output is the I of the I in PEM format. - -=back - -=head2 Selections - -=begin comment - -These constants should really be documented among the EVP manuals, but this -will have to do for now. - -=end comment - -The following constants can be used for standard I: - -=over 4 - -=item B - -Indicates that only the key parameters should be included in the output. -Where it matters, the data type in the output will indicate that the data is -parameters, not a key. - -=item B - -Indicates that the public key and eventual key parameters will be included -in the output. Where it matters, the data type in the output will indicate -that the data is a public key. - -=item B - -Indicates that the private key, the public key and eventual key parameters -should be included in the output. Where it matters, the data type in the -output will indicate that the data is a private key. - -=back - -These are only indications, the encoder implementations are free to -determine what makes sense to include in the output, and this may depend on -the desired output. For example, an EC key in a PKCS#8 structure doesn't -usually include the public key. - -=head1 RETURN VALUES - -OSSL_ENCODER_CTX_new_by_EVP_PKEY() returns a pointer to a -B, or NULL if it couldn't be created. - -OSSL_ENCODER_CTX_set_cipher(), OSSL_ENCODER_CTX_set_passphrase(), -OSSL_ENCODER_CTX_set_pem_password_cb(), OSSL_ENCODER_CTX_set_passphrase_ui() -and OSSL_ENCODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on -failure. - -=head1 NOTES - -Parts of the function names are made to match already existing OpenSSL -names. - -B in OSSL_ENCODER_CTX_new_by_EVP_PKEY() matches the type name, -thus making for the naming pattern B>() when -new types are handled. - -=head1 SEE ALSO - -L, L, L - -=head1 HISTORY - -The functions described here were added in OpenSSL 3.0. - -=head1 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 -L. - -=cut diff --git a/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod b/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod new file mode 100644 index 0000000000..dec48804c6 --- /dev/null +++ b/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod @@ -0,0 +1,174 @@ +=pod + +=head1 NAME + +OSSL_ENCODER_CTX_new_for_pkey, +OSSL_ENCODER_CTX_set_cipher, +OSSL_ENCODER_CTX_set_passphrase, +OSSL_ENCODER_CTX_set_pem_password_cb, +OSSL_ENCODER_CTX_set_passphrase_cb, +OSSL_ENCODER_CTX_set_passphrase_ui +- Encoder routines to encode EVP_PKEYs + +=head1 SYNOPSIS + + #include + + OSSL_ENCODER_CTX * + OSSL_ENCODER_CTX_new_for_pkey(const EVP_PKEY *pkey, int selection, + const char *output_type, + const char *output_structure, + const char *propquery); + + int OSSL_ENCODER_CTX_set_cipher(OSSL_ENCODER_CTX *ctx, + const char *cipher_name, + const char *propquery); + int OSSL_ENCODER_CTX_set_passphrase(OSSL_ENCODER_CTX *ctx, + const unsigned char *kstr, + size_t klen); + int OSSL_ENCODER_CTX_set_pem_password_cb(OSSL_ENCODER_CTX *ctx, + pem_password_cb *cb, void *cbarg); + int OSSL_ENCODER_CTX_set_passphrase_ui(OSSL_ENCODER_CTX *ctx, + const UI_METHOD *ui_method, + void *ui_data); + int OSSL_ENCODER_CTX_set_passphrase_cb(OSSL_ENCODER_CTX *ctx, + OSSL_PASSPHRASE_CALLBACK *cb, + void *cbarg); + +=head1 DESCRIPTION + +OSSL_ENCODER_CTX_new_for_pkey() is a utility function that creates a +B, finds all applicable encoder implementations and sets +them up, so almost all the caller has to do next is call functions like +L. I determines the final output +encoding, and I can be used to select what parts of the I +should be included in the output. I is further discussed in +L below, and I is further described in +L. + +Internally, OSSL_ENCODER_CTX_new_for_pkey() uses the names from the +L implementation associated with I to build a list of +applicable encoder implementations that are used to process the I into +the encoding named by I, with the outermost structure named by +I if that's relevant. All these implementations are +implicitly fetched, with I for finer selection. + +If no suitable encoder implementation is found, +OSSL_ENCODER_CTX_new_for_pkey() still creates a B, but +with no associated encoder (L returns +zero). This helps the caller to distinguish between an error when creating +the B and missing encoder implementation, and allows it to +act accordingly. + +OSSL_ENCODER_CTX_set_cipher() tells the implementation what cipher +should be used to encrypt encoded keys. The cipher is given by +name I. The interpretation of that I is +implementation dependent. The implementation may implement the cipher +directly itself or by other implementations, or it may choose to fetch +it. If the implementation supports fetching the cipher, then it may +use I as properties to be queried for when fetching. +I may also be NULL, which will result in unencrypted +encoding. + +OSSL_ENCODER_CTX_set_passphrase() gives the implementation a +pass phrase to use when encrypting the encoded private key. +Alternatively, a pass phrase callback may be specified with the +following functions. + +OSSL_ENCODER_CTX_set_pem_password_cb(), OSSL_ENCODER_CTX_set_passphrase_ui() +and OSSL_ENCODER_CTX_set_passphrase_cb() sets up a callback method that the +implementation can use to prompt for a pass phrase, giving the caller the +choice of prefered pass phrase callback form. These are called indirectly, +through an internal B function. + +=head2 Output types + +The possible B output types depends on the available +implementations. + +OpenSSL has built in implementations for the following output types: + +=over 4 + +=item C + +The output is a human readable description of the key. +L, L and +L use this for their output. + +=item C + +The output is the DER encoding of the I of the I. + +=item C + +The output is the I of the I in PEM format. + +=back + +=head2 Selections + +=begin comment + +These constants should really be documented among the EVP manuals, but this +will have to do for now. + +=end comment + +The following constants can be used for standard I: + +=over 4 + +=item B + +Indicates that only the key parameters should be included in the output. +Where it matters, the data type in the output will indicate that the data is +parameters, not a key. + +=item B + +Indicates that the public key and eventual key parameters will be included +in the output. Where it matters, the data type in the output will indicate +that the data is a public key. + +=item B + +Indicates that the private key, the public key and eventual key parameters +should be included in the output. Where it matters, the data type in the +output will indicate that the data is a private key. + +=back + +These are only indications, the encoder implementations are free to +determine what makes sense to include in the output, and this may depend on +the desired output. For example, an EC key in a PKCS#8 structure doesn't +usually include the public key. + +=head1 RETURN VALUES + +OSSL_ENCODER_CTX_new_for_pkey() returns a pointer to an B, +or NULL if it couldn't be created. + +OSSL_ENCODER_CTX_set_cipher(), OSSL_ENCODER_CTX_set_passphrase(), +OSSL_ENCODER_CTX_set_pem_password_cb(), OSSL_ENCODER_CTX_set_passphrase_ui() +and OSSL_ENCODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on +failure. + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +The functions described here were added in OpenSSL 3.0. + +=head1 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 +L. + +=cut diff --git a/doc/man3/d2i_RSAPrivateKey.pod b/doc/man3/d2i_RSAPrivateKey.pod index 41e8e3cb6c..475c53ca1d 100644 --- a/doc/man3/d2i_RSAPrivateKey.pod +++ b/doc/man3/d2i_RSAPrivateKey.pod @@ -222,8 +222,8 @@ The following sample code does the rest of the work: unsigned char *p = buffer; /* |buffer| is supplied by the caller */ size_t len = buffer_size; /* assumed be the size of |buffer| */ OSSL_ENCODER_CTX *ctx = - OSSL_ENCODER_CTX_new_by_EVP_PKEY(pkey, selection, "DER", structure, - NULL, NULL); + OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, "DER", structure, + NULL, NULL); if (ctx == NULL) { /* fatal error handling */ } diff --git a/include/crypto/decoder.h b/include/crypto/decoder.h index 5d055fecd8..a83615a8e6 100644 --- a/include/crypto/decoder.h +++ b/include/crypto/decoder.h @@ -32,10 +32,10 @@ void ossl_decoder_instance_free(OSSL_DECODER_INSTANCE *decoder_inst); int ossl_decoder_ctx_add_decoder_inst(OSSL_DECODER_CTX *ctx, OSSL_DECODER_INSTANCE *di); -int ossl_decoder_ctx_setup_for_EVP_PKEY(OSSL_DECODER_CTX *ctx, - EVP_PKEY **pkey, const char *keytype, - OSSL_LIB_CTX *libctx, - const char *propquery); +int ossl_decoder_ctx_setup_for_pkey(OSSL_DECODER_CTX *ctx, + EVP_PKEY **pkey, const char *keytype, + OSSL_LIB_CTX *libctx, + const char *propquery); #endif diff --git a/include/openssl/decoder.h b/include/openssl/decoder.h index 3c3a9a1ea2..29ccb0a7ff 100644 --- a/include/openssl/decoder.h +++ b/include/openssl/decoder.h @@ -120,11 +120,11 @@ int OSSL_DECODER_from_data(OSSL_DECODER_CTX *ctx, const unsigned char **pdata, * an implicit OSSL_DECODER_fetch(), suitable for the object of that type. */ OSSL_DECODER_CTX * -OSSL_DECODER_CTX_new_by_EVP_PKEY(EVP_PKEY **pkey, - const char *input_type, - const char *input_struct, - const char *keytype, int selection, - OSSL_LIB_CTX *libctx, const char *propquery); +OSSL_DECODER_CTX_new_for_pkey(EVP_PKEY **pkey, + const char *input_type, + const char *input_struct, + const char *keytype, int selection, + OSSL_LIB_CTX *libctx, const char *propquery); # ifdef __cplusplus } diff --git a/include/openssl/encoder.h b/include/openssl/encoder.h index 122a46bac9..c6a300bd9c 100644 --- a/include/openssl/encoder.h +++ b/include/openssl/encoder.h @@ -113,11 +113,11 @@ int OSSL_ENCODER_to_data(OSSL_ENCODER_CTX *ctx, unsigned char **pdata, * an implicit OSSL_ENCODER_fetch(), suitable for the object of that type. * This is more useful than calling OSSL_ENCODER_CTX_new(). */ -OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey, - int selection, - const char *output_type, - const char *output_struct, - const char *propquery); +OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new_for_pkey(const EVP_PKEY *pkey, + int selection, + const char *output_type, + const char *output_struct, + const char *propquery); # ifdef __cplusplus } diff --git a/providers/encoders.inc b/providers/encoders.inc index f2b59e0846..356e2f2f6b 100644 --- a/providers/encoders.inc +++ b/providers/encoders.inc @@ -74,16 +74,16 @@ ENCODER_TEXT("SM2", sm2, yes), * created like this: * * OSSL_ENCODER_CTX *ctx = - * OSSL_ENCODER_CTX_new_by_EVP_PKEY(pkey, selection, "DER", "type-specific", - * NULL, NULL); + * OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, "DER", "type-specific", + * NULL, NULL); * * To replace PEM_write_bio_{TYPE}PrivateKey(), PEM_write_bio_{TYPE}PublicKey() * and PEM_write_bio_{TYPE}Params(), use OSSL_ENCODER functions with an * OSSL_ENCODER_CTX created like this: * * OSSL_ENCODER_CTX *ctx = - * OSSL_ENCODER_CTX_new_by_EVP_PKEY(pkey, selection, "PEM", "type-specific", - * NULL, NULL); + * OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, "PEM", "type-specific", + * NULL, NULL); * * We only implement those for which there are current i2d_ and PEM_write_bio * implementations. @@ -197,7 +197,7 @@ ENCODER_w_structure("SM2", sm2, yes, pem, SubjectPublicKeyInfo), * Entries for key type specific output formats. These are exactly the * same as the type specific above, except that they use the key type * name as structure name instead of "type-specific", in the call on - * OSSL_ENCODER_CTX_new_by_EVP_PKEY(). + * OSSL_ENCODER_CTX_new_for_pkey(). */ /* The RSA encoders only support private key and public key output */ diff --git a/providers/implementations/storemgmt/file_store.c b/providers/implementations/storemgmt/file_store.c index a5edc53506..ab4b4055d9 100644 --- a/providers/implementations/storemgmt/file_store.c +++ b/providers/implementations/storemgmt/file_store.c @@ -59,7 +59,7 @@ static OSSL_FUNC_store_close_fn file_close; * internal OpenSSL functions, thereby bypassing the need for a surrounding * provider. This is ok, since this is a local decoder, not meant for * public consumption. It also uses the libcrypto internal decoder - * setup function ossl_decoder_ctx_setup_for_EVP_PKEY(), to allow the + * setup function ossl_decoder_ctx_setup_for_pkey(), to allow the * last resort decoder to be added first (and thereby be executed last). * Finally, it sets up its own construct and cleanup functions. * @@ -535,7 +535,7 @@ void file_load_c