xref: /freebsd/crypto/openssl/doc/man3/BIO_f_base64.pod (revision b077aed33b7b6aefca7b17ddb250cf521f938613)
1e71b7053SJung-uk Kim=pod
2e71b7053SJung-uk Kim
3e71b7053SJung-uk Kim=head1 NAME
4e71b7053SJung-uk Kim
5e71b7053SJung-uk KimBIO_f_base64 - base64 BIO filter
6e71b7053SJung-uk Kim
7e71b7053SJung-uk Kim=head1 SYNOPSIS
8e71b7053SJung-uk Kim
9*b077aed3SPierre Pronchery=for openssl multiple includes
10e71b7053SJung-uk Kim
11e71b7053SJung-uk Kim #include <openssl/bio.h>
12e71b7053SJung-uk Kim #include <openssl/evp.h>
13e71b7053SJung-uk Kim
14e71b7053SJung-uk Kim const BIO_METHOD *BIO_f_base64(void);
15e71b7053SJung-uk Kim
16e71b7053SJung-uk Kim=head1 DESCRIPTION
17e71b7053SJung-uk Kim
18e71b7053SJung-uk KimBIO_f_base64() returns the base64 BIO method. This is a filter
19e71b7053SJung-uk KimBIO that base64 encodes any data written through it and decodes
20e71b7053SJung-uk Kimany data read through it.
21e71b7053SJung-uk Kim
22e71b7053SJung-uk KimBase64 BIOs do not support BIO_gets() or BIO_puts().
23e71b7053SJung-uk Kim
245ac766abSJung-uk KimFor writing, output is by default divided to lines of length 64
255ac766abSJung-uk Kimcharacters and there is always a newline at the end of output.
265ac766abSJung-uk Kim
275ac766abSJung-uk KimFor reading, first line should be at most 1024
285ac766abSJung-uk Kimcharacters long. If it is longer then it is ignored completely.
295ac766abSJung-uk KimOther input lines can be of any length. There must be a newline
305ac766abSJung-uk Kimat the end of input.
315ac766abSJung-uk Kim
325ac766abSJung-uk KimThis behavior can be changed with BIO_FLAGS_BASE64_NO_NL flag.
335ac766abSJung-uk Kim
34e71b7053SJung-uk KimBIO_flush() on a base64 BIO that is being written through is
35e71b7053SJung-uk Kimused to signal that no more data is to be encoded: this is used
36e71b7053SJung-uk Kimto flush the final block through the BIO.
37e71b7053SJung-uk Kim
385ac766abSJung-uk KimThe flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags().
395ac766abSJung-uk KimFor writing, it causes all data to be written on one line without
405ac766abSJung-uk Kimnewline at the end.
4183eaf7aeSJung-uk KimFor reading, it expects the data to be all on one line (with or
4283eaf7aeSJung-uk Kimwithout a trailing newline).
43e71b7053SJung-uk Kim
44e71b7053SJung-uk Kim=head1 NOTES
45e71b7053SJung-uk Kim
46e71b7053SJung-uk KimBecause of the format of base64 encoding the end of the encoded
47e71b7053SJung-uk Kimblock cannot always be reliably determined.
48e71b7053SJung-uk Kim
49e71b7053SJung-uk Kim=head1 RETURN VALUES
50e71b7053SJung-uk Kim
51e71b7053SJung-uk KimBIO_f_base64() returns the base64 BIO method.
52e71b7053SJung-uk Kim
53e71b7053SJung-uk Kim=head1 EXAMPLES
54e71b7053SJung-uk Kim
55e71b7053SJung-uk KimBase64 encode the string "Hello World\n" and write the result
56e71b7053SJung-uk Kimto standard output:
57e71b7053SJung-uk Kim
58e71b7053SJung-uk Kim BIO *bio, *b64;
59e71b7053SJung-uk Kim char message[] = "Hello World \n";
60e71b7053SJung-uk Kim
61e71b7053SJung-uk Kim b64 = BIO_new(BIO_f_base64());
62e71b7053SJung-uk Kim bio = BIO_new_fp(stdout, BIO_NOCLOSE);
63e71b7053SJung-uk Kim BIO_push(b64, bio);
64e71b7053SJung-uk Kim BIO_write(b64, message, strlen(message));
65e71b7053SJung-uk Kim BIO_flush(b64);
66e71b7053SJung-uk Kim
67e71b7053SJung-uk Kim BIO_free_all(b64);
68e71b7053SJung-uk Kim
69e71b7053SJung-uk KimRead Base64 encoded data from standard input and write the decoded
70e71b7053SJung-uk Kimdata to standard output:
71e71b7053SJung-uk Kim
72e71b7053SJung-uk Kim BIO *bio, *b64, *bio_out;
73e71b7053SJung-uk Kim char inbuf[512];
74e71b7053SJung-uk Kim int inlen;
75e71b7053SJung-uk Kim
76e71b7053SJung-uk Kim b64 = BIO_new(BIO_f_base64());
77e71b7053SJung-uk Kim bio = BIO_new_fp(stdin, BIO_NOCLOSE);
78e71b7053SJung-uk Kim bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
79e71b7053SJung-uk Kim BIO_push(b64, bio);
80e71b7053SJung-uk Kim while ((inlen = BIO_read(b64, inbuf, 512)) > 0)
81e71b7053SJung-uk Kim     BIO_write(bio_out, inbuf, inlen);
82e71b7053SJung-uk Kim
83e71b7053SJung-uk Kim BIO_flush(bio_out);
84e71b7053SJung-uk Kim BIO_free_all(b64);
85e71b7053SJung-uk Kim
86e71b7053SJung-uk Kim=head1 BUGS
87e71b7053SJung-uk Kim
88e71b7053SJung-uk KimThe ambiguity of EOF in base64 encoded data can cause additional
89e71b7053SJung-uk Kimdata following the base64 encoded block to be misinterpreted.
90e71b7053SJung-uk Kim
91e71b7053SJung-uk KimThere should be some way of specifying a test that the BIO can perform
92e71b7053SJung-uk Kimto reliably determine EOF (for example a MIME boundary).
93e71b7053SJung-uk Kim
94e71b7053SJung-uk Kim=head1 COPYRIGHT
95e71b7053SJung-uk Kim
965ac766abSJung-uk KimCopyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.
97e71b7053SJung-uk Kim
98*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License").  You may not use
99e71b7053SJung-uk Kimthis file except in compliance with the License.  You can obtain a copy
100e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at
101e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>.
102e71b7053SJung-uk Kim
103e71b7053SJung-uk Kim=cut
104