[thirdparty/openssl.git] / doc / man3 / BIO_f_base64.pod

=pod

=head1 NAME

BIO_f_base64 - base64 BIO filter

=head1 SYNOPSIS

=for comment multiple includes

 #include <openssl/bio.h>
 #include <openssl/evp.h>

 const BIO_METHOD *BIO_f_base64(void);

=head1 DESCRIPTION

BIO_f_base64() returns the base64 BIO method. This is a filter
BIO that base64 encodes any data written through it and decodes
any data read through it.

Base64 BIOs do not support BIO_gets() or BIO_puts().

BIO_flush() on a base64 BIO that is being written through is
used to signal that no more data is to be encoded: this is used
to flush the final block through the BIO.

The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags()
to encode the data all on one line or expect the data to be all
on one line.

=head1 NOTES

Because of the format of base64 encoding the end of the encoded
block cannot always be reliably determined.

=head1 RETURN VALUES

BIO_f_base64() returns the base64 BIO method.

=head1 EXAMPLES

Base64 encode the string "Hello World\n" and write the result
to standard output:

 BIO *bio, *b64;
 char message[] = "Hello World \n";

 b64 = BIO_new(BIO_f_base64());
 bio = BIO_new_fp(stdout, BIO_NOCLOSE);
 BIO_push(b64, bio);
 BIO_write(b64, message, strlen(message));
 BIO_flush(b64);

 BIO_free_all(b64);

Read Base64 encoded data from standard input and write the decoded
data to standard output:

 BIO *bio, *b64, *bio_out;
 char inbuf[512];
 int inlen;

 b64 = BIO_new(BIO_f_base64());
 bio = BIO_new_fp(stdin, BIO_NOCLOSE);
 bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
 BIO_push(b64, bio);
 while ((inlen = BIO_read(b64, inbuf, 512)) > 0)
     BIO_write(bio_out, inbuf, inlen);

 BIO_flush(bio_out);
 BIO_free_all(b64);

=head1 BUGS

The ambiguity of EOF in base64 encoded data can cause additional
data following the base64 encoded block to be misinterpreted.

There should be some way of specifying a test that the BIO can perform
to reliably determine EOF (for example a MIME boundary).

=head1 COPYRIGHT

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (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<https://www.openssl.org/source/license.html>.

=cut
Commit	Line	Data
b1ccd57b DSH	1	=pod
	2
	3	=head1 NAME
	4
8eec1389	5	BIO_f_base64 - base64 BIO filter
b1ccd57b DSH	6
	7	=head1 SYNOPSIS
	8
b97fdb57 RL	9	=for comment multiple includes
b97fdb57 RL	10
b1ccd57b DSH	11	#include <openssl/bio.h>
	12	#include <openssl/evp.h>
	13
35d2e327	14	const BIO_METHOD *BIO_f_base64(void);
b1ccd57b DSH	15
	16	=head1 DESCRIPTION
	17
	18	BIO_f_base64() returns the base64 BIO method. This is a filter
	19	BIO that base64 encodes any data written through it and decodes
	20	any data read through it.
	21
1bc74519	22	Base64 BIOs do not support BIO_gets() or BIO_puts().
b1ccd57b DSH	23
	24	BIO_flush() on a base64 BIO that is being written through is
	25	used to signal that no more data is to be encoded: this is used
	26	to flush the final block through the BIO.
	27
	28	The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags()
	29	to encode the data all on one line or expect the data to be all
	30	on one line.
	31
	32	=head1 NOTES
	33
	34	Because of the format of base64 encoding the end of the encoded
	35	block cannot always be reliably determined.
	36
	37	=head1 RETURN VALUES
	38
	39	BIO_f_base64() returns the base64 BIO method.
	40
	41	=head1 EXAMPLES
	42
	43	Base64 encode the string "Hello World\n" and write the result
	44	to standard output:
	45
	46	BIO bio, b64;
	47	char message[] = "Hello World \n";
	48
	49	b64 = BIO_new(BIO_f_base64());
	50	bio = BIO_new_fp(stdout, BIO_NOCLOSE);
fc1d88f0 RS	51	BIO_push(b64, bio);
	52	BIO_write(b64, message, strlen(message));
	53	BIO_flush(b64);
b1ccd57b	54
fc1d88f0	55	BIO_free_all(b64);
b1ccd57b DSH	56
	57	Read Base64 encoded data from standard input and write the decoded
	58	data to standard output:
	59
c2dac35a	60	BIO bio, b64, *bio_out;
b1ccd57b DSH	61	char inbuf[512];
b1ccd57b DSH	62	int inlen;
b1ccd57b DSH	63
	64	b64 = BIO_new(BIO_f_base64());
	65	bio = BIO_new_fp(stdin, BIO_NOCLOSE);
	66	bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
fc1d88f0	67	BIO_push(b64, bio);
2947af32 BB	68	while ((inlen = BIO_read(b64, inbuf, 512)) > 0)
2947af32 BB	69	BIO_write(bio_out, inbuf, inlen);
b1ccd57b	70
fc1d88f0 RS	71	BIO_flush(bio_out);
fc1d88f0 RS	72	BIO_free_all(b64);
b1ccd57b DSH	73
	74	=head1 BUGS
	75
	76	The ambiguity of EOF in base64 encoded data can cause additional
	77	data following the base64 encoded block to be misinterpreted.
	78
	79	There should be some way of specifying a test that the BIO can perform
	80	to reliably determine EOF (for example a MIME boundary).
	81
e2f92610 RS	82	=head1 COPYRIGHT
	83
	84	Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
	85
	86	Licensed under the OpenSSL license (the "License"). You may not use
	87	this file except in compliance with the License. You can obtain a copy
	88	in the file LICENSE in the source distribution or at
	89	L<https://www.openssl.org/source/license.html>.
	90
	91	=cut