1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryOSSL_DECODER_from_data, 6*b077aed3SPierre ProncheryOSSL_DECODER_from_bio, 7*b077aed3SPierre ProncheryOSSL_DECODER_from_fp 8*b077aed3SPierre Pronchery- Routines to perform a decoding 9*b077aed3SPierre Pronchery 10*b077aed3SPierre Pronchery=head1 SYNOPSIS 11*b077aed3SPierre Pronchery 12*b077aed3SPierre Pronchery #include <openssl/decoder.h> 13*b077aed3SPierre Pronchery 14*b077aed3SPierre Pronchery int OSSL_DECODER_from_bio(OSSL_DECODER_CTX *ctx, BIO *in); 15*b077aed3SPierre Pronchery int OSSL_DECODER_from_fp(OSSL_DECODER_CTX *ctx, FILE *fp); 16*b077aed3SPierre Pronchery int OSSL_DECODER_from_data(OSSL_DECODER_CTX *ctx, const unsigned char **pdata, 17*b077aed3SPierre Pronchery size_t *pdata_len); 18*b077aed3SPierre Pronchery 19*b077aed3SPierre ProncheryFeature availability macros: 20*b077aed3SPierre Pronchery 21*b077aed3SPierre Pronchery=over 4 22*b077aed3SPierre Pronchery 23*b077aed3SPierre Pronchery=item OSSL_DECODER_from_fp() is only available when B<OPENSSL_NO_STDIO> 24*b077aed3SPierre Proncheryis undefined. 25*b077aed3SPierre Pronchery 26*b077aed3SPierre Pronchery=back 27*b077aed3SPierre Pronchery 28*b077aed3SPierre Pronchery=head1 DESCRIPTION 29*b077aed3SPierre Pronchery 30*b077aed3SPierre ProncheryOSSL_DECODER_from_data() runs the decoding process for the context I<ctx>, 31*b077aed3SPierre Proncherywith input coming from I<*pdata>, I<*pdata_len> bytes long. Both I<*pdata> 32*b077aed3SPierre Proncheryand I<*pdata_len> must be non-NULL. When OSSL_DECODER_from_data() returns, 33*b077aed3SPierre ProncheryI<*pdata> is updated to point at the location after what has been decoded, 34*b077aed3SPierre Proncheryand I<*pdata_len> to have the number of remaining bytes. 35*b077aed3SPierre Pronchery 36*b077aed3SPierre ProncheryOSSL_DECODER_from_bio() runs the decoding process for the context I<ctx>, 37*b077aed3SPierre Proncherywith the input coming from the B<BIO> I<in>. Should it make a difference, 38*b077aed3SPierre Proncheryit's recommended to have the BIO set in binary mode rather than text mode. 39*b077aed3SPierre Pronchery 40*b077aed3SPierre ProncheryOSSL_DECODER_from_fp() does the same thing as OSSL_DECODER_from_bio(), 41*b077aed3SPierre Proncheryexcept that the input is coming from the B<FILE> I<fp>. 42*b077aed3SPierre Pronchery 43*b077aed3SPierre Pronchery=head1 RETURN VALUES 44*b077aed3SPierre Pronchery 45*b077aed3SPierre ProncheryOSSL_DECODER_from_bio(), OSSL_DECODER_from_data() and OSSL_DECODER_from_fp() 46*b077aed3SPierre Proncheryreturn 1 on success, or 0 on failure. 47*b077aed3SPierre Pronchery 48*b077aed3SPierre Pronchery=head1 EXAMPLES 49*b077aed3SPierre Pronchery 50*b077aed3SPierre ProncheryTo decode an RSA key encoded with PEM from a bio: 51*b077aed3SPierre Pronchery 52*b077aed3SPierre Pronchery OSSL_DECODER_CTX *dctx; 53*b077aed3SPierre Pronchery EVP_PKEY *pkey = NULL; 54*b077aed3SPierre Pronchery const char *format = "PEM"; /* NULL for any format */ 55*b077aed3SPierre Pronchery const char *structure = NULL; /* any structure */ 56*b077aed3SPierre Pronchery const char *keytype = "RSA"; /* NULL for any key */ 57*b077aed3SPierre Pronchery const unsigned char *pass = "my password"; 58*b077aed3SPierre Pronchery 59*b077aed3SPierre Pronchery dctx = OSSL_DECODER_CTX_new_for_pkey(&pkey, format, structure, 60*b077aed3SPierre Pronchery keytype, 61*b077aed3SPierre Pronchery OSSL_KEYMGMT_SELECT_KEYPAIR, 62*b077aed3SPierre Pronchery NULL, NULL); 63*b077aed3SPierre Pronchery if (dctx == NULL) { 64*b077aed3SPierre Pronchery /* error: no suitable potential decoders found */ 65*b077aed3SPierre Pronchery } 66*b077aed3SPierre Pronchery if (pass != NULL) 67*b077aed3SPierre Pronchery OSSL_DECODER_CTX_set_passphrase(dctx, pass, strlen(pass)); 68*b077aed3SPierre Pronchery if (OSSL_DECODER_from_bio(dctx, bio)) { 69*b077aed3SPierre Pronchery /* pkey is created with the decoded data from the bio */ 70*b077aed3SPierre Pronchery } else { 71*b077aed3SPierre Pronchery /* decoding failure */ 72*b077aed3SPierre Pronchery } 73*b077aed3SPierre Pronchery OSSL_DECODER_CTX_free(dctx); 74*b077aed3SPierre Pronchery 75*b077aed3SPierre ProncheryTo decode an EC key encoded with DER from a buffer: 76*b077aed3SPierre Pronchery 77*b077aed3SPierre Pronchery OSSL_DECODER_CTX *dctx; 78*b077aed3SPierre Pronchery EVP_PKEY *pkey = NULL; 79*b077aed3SPierre Pronchery const char *format = "DER"; /* NULL for any format */ 80*b077aed3SPierre Pronchery const char *structure = NULL; /* any structure */ 81*b077aed3SPierre Pronchery const char *keytype = "EC"; /* NULL for any key */ 82*b077aed3SPierre Pronchery const unsigned char *pass = NULL 83*b077aed3SPierre Pronchery const unsigned char *data = buffer; 84*b077aed3SPierre Pronchery size_t datalen = sizeof(buffer); 85*b077aed3SPierre Pronchery 86*b077aed3SPierre Pronchery dctx = OSSL_DECODER_CTX_new_for_pkey(&pkey, format, structure, 87*b077aed3SPierre Pronchery keytype, 88*b077aed3SPierre Pronchery OSSL_KEYMGMT_SELECT_KEYPAIR 89*b077aed3SPierre Pronchery | OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS, 90*b077aed3SPierre Pronchery NULL, NULL); 91*b077aed3SPierre Pronchery if (dctx == NULL) { 92*b077aed3SPierre Pronchery /* error: no suitable potential decoders found */ 93*b077aed3SPierre Pronchery } 94*b077aed3SPierre Pronchery if (pass != NULL) 95*b077aed3SPierre Pronchery OSSL_DECODER_CTX_set_passphrase(dctx, pass, strlen(pass)); 96*b077aed3SPierre Pronchery if (OSSL_DECODER_from_data(dctx, &data, &datalen)) { 97*b077aed3SPierre Pronchery /* pkey is created with the decoded data from the buffer */ 98*b077aed3SPierre Pronchery } else { 99*b077aed3SPierre Pronchery /* decoding failure */ 100*b077aed3SPierre Pronchery } 101*b077aed3SPierre Pronchery OSSL_DECODER_CTX_free(dctx); 102*b077aed3SPierre Pronchery 103*b077aed3SPierre Pronchery=head1 SEE ALSO 104*b077aed3SPierre Pronchery 105*b077aed3SPierre ProncheryL<provider(7)>, L<OSSL_DECODER_CTX(3)> 106*b077aed3SPierre Pronchery 107*b077aed3SPierre Pronchery=head1 HISTORY 108*b077aed3SPierre Pronchery 109*b077aed3SPierre ProncheryThe functions described here were added in OpenSSL 3.0. 110*b077aed3SPierre Pronchery 111*b077aed3SPierre Pronchery=head1 COPYRIGHT 112*b077aed3SPierre Pronchery 113*b077aed3SPierre ProncheryCopyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved. 114*b077aed3SPierre Pronchery 115*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 116*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 117*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 118*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 119*b077aed3SPierre Pronchery 120*b077aed3SPierre Pronchery=cut 121