1=pod 2 3=head1 NAME 4 5OSSL_ENCODER_to_data, 6OSSL_ENCODER_to_bio, 7OSSL_ENCODER_to_fp 8- Routines to perform an encoding 9 10=head1 SYNOPSIS 11 12 #include <openssl/encoder.h> 13 14 int OSSL_ENCODER_to_data(OSSL_ENCODER_CTX *ctx, unsigned char **pdata, 15 size_t *pdata_len); 16 int OSSL_ENCODER_to_bio(OSSL_ENCODER_CTX *ctx, BIO *out); 17 int OSSL_ENCODER_to_fp(OSSL_ENCODER_CTX *ctx, FILE *fp); 18 19Feature availability macros: 20 21=over 4 22 23=item OSSL_ENCODER_to_fp() is only available when B<OPENSSL_NO_STDIO> 24is undefined. 25 26=back 27 28=head1 DESCRIPTION 29 30OSSL_ENCODER_to_data() runs the encoding process for the context I<ctx>, 31with the output going to the I<*pdata> and I<*pdata_len>. 32If I<*pdata> is NULL when OSSL_ENCODER_to_data() is called, a buffer will be 33allocated using L<OPENSSL_zalloc(3)>, and I<*pdata> will be set to point at 34the start of that buffer, and I<*pdata_len> will be assigned its length when 35OSSL_ENCODER_to_data() returns. 36If I<*pdata> is non-NULL when OSSL_ENCODER_to_data() is called, I<*pdata_len> 37is assumed to have its size. In this case, I<*pdata> will be set to point 38after the encoded bytes, and I<*pdata_len> will be assigned the number of 39remaining bytes. 40 41OSSL_ENCODER_to_bio() runs the encoding process for the context I<ctx>, with 42the output going to the B<BIO> I<out>. 43 44OSSL_ENCODER_to_fp() does the same thing as OSSL_ENCODER_to_bio(), except 45that the output is going to the B<FILE> I<fp>. 46 47=for comment Know your encoder! 48 49For OSSL_ENCODER_to_bio() and OSSL_ENCODER_to_fp(), the application is 50required to set up the B<BIO> or B<FILE> properly, for example to have 51it in text or binary mode as is appropriate for the encoder output type. 52 53=head1 RETURN VALUES 54 55OSSL_ENCODER_to_bio(), OSSL_ENCODER_to_fp() and OSSL_ENCODER_to_data() 56return 1 on success, or 0 on failure. 57 58=head1 EXAMPLES 59 60To encode a pkey as PKCS#8 with PEM format into a bio: 61 62 OSSL_ENCODER_CTX *ectx; 63 const char *format = "PEM"; 64 const char *structure = "PrivateKeyInfo"; /* PKCS#8 structure */ 65 const unsigned char *pass = "my password"; 66 67 ectx = OSSL_ENCODER_CTX_new_for_pkey(pkey, 68 OSSL_KEYMGMT_SELECT_KEYPAIR 69 | OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS, 70 format, structure, 71 NULL); 72 if (ectx == NULL) { 73 /* error: no suitable potential encoders found */ 74 } 75 if (pass != NULL) 76 OSSL_ENCODER_CTX_set_passphrase(ectx, pass, strlen(pass)); 77 if (OSSL_ENCODER_to_bio(ectx, bio)) { 78 /* pkey was successfully encoded into the bio */ 79 } else { 80 /* encoding failure */ 81 } 82 OSSL_ENCODER_CTX_free(ectx); 83 84To encode a pkey as PKCS#8 with DER format encrypted with 85AES-256-CBC into a buffer: 86 87 OSSL_ENCODER_CTX *ectx; 88 const char *format = "DER"; 89 const char *structure = "PrivateKeyInfo"; /* PKCS#8 structure */ 90 const unsigned char *pass = "my password"; 91 unsigned char *data = NULL; 92 size_t datalen; 93 94 ectx = OSSL_ENCODER_CTX_new_for_pkey(pkey, 95 OSSL_KEYMGMT_SELECT_KEYPAIR 96 | OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS, 97 format, structure, 98 NULL); 99 if (ectx == NULL) { 100 /* error: no suitable potential encoders found */ 101 } 102 if (pass != NULL) { 103 OSSL_ENCODER_CTX_set_passphrase(ectx, pass, strlen(pass)); 104 OSSL_ENCODER_CTX_set_cipher(ctx, "AES-256-CBC", NULL); 105 } 106 if (OSSL_ENCODER_to_data(ectx, &data, &datalen)) { 107 /* 108 * pkey was successfully encoded into a newly allocated 109 * data buffer 110 */ 111 } else { 112 /* encoding failure */ 113 } 114 OSSL_ENCODER_CTX_free(ectx); 115 116=head1 SEE ALSO 117 118L<provider(7)>, L<OSSL_ENCODER_CTX(3)> 119 120=head1 HISTORY 121 122The functions described here were added in OpenSSL 3.0. 123 124=head1 COPYRIGHT 125 126Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. 127 128Licensed under the Apache License 2.0 (the "License"). You may not use 129this file except in compliance with the License. You can obtain a copy 130in the file LICENSE in the source distribution or at 131L<https://www.openssl.org/source/license.html>. 132 133=cut 134