This commit was manufactured by cvs2svn to create branch 'BRANCH_engine'.

=pod

=head1 NAME

	BIO_f_base64 - base64 BIO

=head1 SYNOPSIS

 #include <openssl/bio.h>

 #include <openssl/evp.h>

 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 = BIO_push(b64, bio);

 BIO_write(bio, message, strlen(message));

 BIO_flush(bio);

 BIO_free_all(bio);

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;

 char message[] = "Hello World \n";

 b64 = BIO_new(BIO_f_base64());

 bio = BIO_new_fp(stdin, BIO_NOCLOSE);

 bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);

 bio = BIO_push(b64, bio);

 while((inlen = BIO_read(bio, inbuf, strlen(message))) > 0) 

	BIO_write(bio_out, inbuf, inlen);

 BIO_free_all(bio);

=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 SEE ALSO

TBA

=pod

=head1 NAME

	BIO_f_cipher - cipher BIO

=head1 SYNOPSIS

 #include <openssl/bio.h>

 #include <openssl/evp.h>

 BIO_METHOD *	BIO_f_cipher(void);

 void BIO_set_cipher(BIO *b,const EVP_CIPHER *cipher,

		unsigned char *key, unsigned char *iv, int enc);

 int BIO_get_cipher_status(BIO *b)

 int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx)

=head1 DESCRIPTION

BIO_f_cipher() returns the cipher BIO method. This is a filter

BIO that encrypts any data written through it, and decrypts any data

read from it. It is a BIO wrapper for the cipher routines

EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal().

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

BIO_flush() on an encryption BIO that is being written through is

used to signal that no more data is to be encrypted: this is used

to flush and possibly pad the final block through the BIO.

BIO_set_cipher() sets the cipher of BIO <b> to B<cipher> using key B<key>

and IV B<iv>. B<enc> should be set to 1 for encryption and zero for

decryption.

When reading from an encryption BIO the final block is automatically

decrypted and checked when EOF is detected. BIO_get_cipher_status()

is a BIO_ctrl() macro which can be called to determine whether the

decryption operation was successful.

BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal

BIO cipher context. The retrieved context can be used in conjustion

with the standard cipher routines to set it up. This is useful when

BIO_set_cipher() is not flexible enough for the applications needs.

=head1 NOTES

When encrypting BIO_flush() B<must> be called to flush the final block

through the BIO. If it is not then the final block will fail a subsequent

decrypt.

When decrypting an error on the final block is signalled by a zero

return value from the read operation. A successful decrypt followed

by EOF will also return zero for the final read. BIO_get_cipher_status()

should be called to determine if the decrypt was successful.

As always, if BIO_gets() or BIO_puts() support is needed then it can

be achieved by preceding the cipher BIO with a buffering BIO.

=head1 RETURN VALUES

BIO_f_cipher() returns the cipher BIO method.

BIO_set_cipher() does not return a value.

BIO_get_cipher_status() returns 1 for a successful decrypt and 0

for failure.

BIO_get_cipher_ctx() currently always returns 1.

=head1 EXAMPLES

TBA

=head1 SEE ALSO

TBA

=pod

=head1 NAME

	BIO_f_md - message digest BIO

=head1 SYNOPSIS

 #include <openssl/bio.h>

 #include <openssl/evp.h>

 BIO_METHOD *	BIO_f_md(void);

 int BIO_set_md(BIO *b,EVP_MD *md);

 int BIO_get_md(BIO *b,EVP_MD **mdp);

 int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp);

=head1 DESCRIPTION

BIO_f_md() returns the message digest BIO method. This is a filter

BIO that digests any data passed through it, it is a BIO wrapper

for the digest routines EVP_DigestInit(), EVP_DigestUpdate()

and EVP_DigestFinal().

Any data written or read through a digest BIO using BIO_read() and

BIO_write() is digested.

BIO_gets(), if its B<size> parameter is large enough finishes the

digest calculation and returns the digest value. BIO_puts() is

not supported.

BIO_reset() reinitializes a digest BIO.

BIO_set_md() sets the message digest of BIO B<b> to B<md>: this

must be called to initialise a digest BIO before any data is

passed through it. It is a BIO_ctrl() macro.

BIO_get_md() places the a pointer to the digest BIOs digest method

in B<mdp>, it is a BIO_ctrl() macro.

BIO_get_md_ctx() returns the digest BIOs context into B<mdcp>.

=head1 NOTES

The context returned by BIO_get_md_ctx() can be used in calls

to EVP_DigestFinal() and also the signature routines EVP_SignFinal()

and EVP_VerifyFinal().

The context returned by BIO_get_md_ctx() is an internal context

structure. Changes made to this context will affect the digest

BIO itself and the context pointer will become invalid when the digest

BIO is freed.

After the digest has been retrieved from a digest BIO it must be

reinitialized by calling BIO_reset(), or BIO_set_md() before any more

data is passed through it.

If an application needs to call BIO_gets() or BIO_puts() through

a chain containing digest BIOs then this can be done by prepending

a buffering BIO.

=head1 RETURN VALUES

BIO_f_md() returns the digest BIO method.

BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and

0 for failure.

=head1 EXAMPLES

The following example creates a BIO chain containing an SHA1 and MD5

digest BIO and passes the string "Hello World" through it. Error

checking has been omitted for clarity.

 BIO *bio, *mdtmp;

 char message[] = "Hello World";

 bio = BIO_new(BIO_s_null());

 mdtmp = BIO_new(BIO_f_md());

 BIO_set_md(mdtmp, EVP_sha1());

 /* For BIO_push() we want to append the sink BIO and keep a note of

  * the start of the chain.

  */

 bio = BIO_push(mdtmp, bio);

 mdtmp = BIO_new(BIO_f_md());

 BIO_set_md(mdtmp, EVP_md5());

 bio = BIO_push(mdtmp, bio);

 /* Note: mdtmp can now be discarded */

 BIO_write(bio, message, strlen(message));

The next example digests data by reading through a chain instead:

 BIO *bio, *mdtmp;

 char buf[1024];

 int rdlen;

 bio = BIO_new_file(file, "rb");

 mdtmp = BIO_new(BIO_f_md());

 BIO_set_md(mdtmp, EVP_sha1());

 bio = BIO_push(mdtmp, bio);

 mdtmp = BIO_new(BIO_f_md());

 BIO_set_md(mdtmp, EVP_md5());

 bio = BIO_push(mdtmp, bio);

 do {

 	rdlen = BIO_read(bio, buf, sizeof(buf));

        /* Might want to do something with the data here */

 } while(rdlen > 0);

This next example retrieves the message digests from a BIO chain and

outputs them. This could be used with the examples above.

 BIO *mdtmp;

 unsigned char mdbuf[EVP_MAX_MD_SIZE];

 int mdlen;

 int i;

 mdtmp = bio;	/* Assume bio has previously been set up */

 do {

	EVP_MD *md;

 	mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);

        if(!mdtmp) break;

	BIO_get_md(mdtmp, &md);

        printf("%s digest", OBJ_nid2sn(EVP_MD_type(md)));

	mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);

	for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);

	printf("\n");

	mdtmp = BIO_next(mdtmp);

 } while(mdtmp);

 BIO_free_all(bio);

=head1 BUGS

The lack of support for BIO_puts() and the non standard behaviour of

BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets()

and BIO_puts() should be passed to the next BIO in the chain and digest

the data passed through and that digests should be retrieved using a

separate BIO_ctrl() call.

=head1 SEE ALSO

TBA

=pod

=head1 NAME

	BIO_f_null - null filter

=head1 SYNOPSIS

 #include <openssl/bio.h>

 BIO_METHOD *	BIO_f_null(void);

=head1 DESCRIPTION

BIO_f_null() returns the null filter BIO method. This is a filter BIO

that does nothing.

All requests to a null filter BIO are passed through to the next BIO in

the chain: this means that a BIO chain containing a null filter BIO

behaves just as though the BIO was not there.

=head1 NOTES

As may be apparent a null filter BIO is not particularly useful.

=head1 RETURN VALUES

BIO_f_null() returns the null filter BIO method.

=head1 SEE ALSO

TBA

=pod

=head1 NAME

	BIO_s_file - FILE bio.

=head1 SYNOPSIS

 #include <openssl/bio.h>

 BIO_METHOD *	BIO_s_file(void);

 BIO *BIO_new_file(const char *filename, const char *mode);

 BIO *BIO_new_fp(FILE *stream, int flags);

 BIO_set_fp(BIO *b,FILE *fp, int flags);

 BIO_get_fp(BIO *b,FILE **fpp);

 BIO_seek(BIO *b,int offset);

 int BIO_tell(BIO *b);

 int BIO_read_filename(BIO *b, char *name)

 int BIO_write_filename(BIO *b, char *name)

 int BIO_append_filename(BIO *b, char *name)

 int BIO_rw_filename(BIO *b, char *name)

=head1 DESCRIPTION

BIO_s_file() returns the BIO file method. As its name implies it

is a wrapper round the stdio FILE structure and it is a

source/sink BIO.

Calls to BIO_read() and BIO_write() read and write data to the

underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs.

BIO_flush() on a file BIO calls the fflush() function on the wrapped

stream.

BIO_reset() on a file BIO calls fseek() to reset the position indicator

to the start of the file.

BIO_eof() calls feof().

Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO

is freed.

BIO_new_file() creates a new file BIO with mode B<mode> the meaning

of B<mode> is the same as the stdio function fopen(). The BIO_CLOSE

flag is set on the returned BIO.

BIO_new_fp() creates a file BIO wrapping B<stream>. Flags can be:

BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying

stream to text mode, default is binary: this only has any effect under

Win32).

BIO_set_fp() set the fp of a file BIO to B<fp>. B<flags> has the same

meaning as in BIO_new_fp(), it is a macro.

BIO_get_fp() retrieves the fp of a file BIO, it is a macro.

BIO_seek() is a macro that sets the position pointer to B<offset> bytes

from the start of file.

BIO_tell() returns the value of the position pointer.

BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and

BIO_rw_filename() set the file BIO B<b> to use file B<name> for

reading, writing, append or read write respectively.

=head1 NOTES

When wrapping stdout, stdin or stderr the underlying stream should not

normally be closed so the BIO_NOCLOSE flag should be set.

Because the file BIO calls the underlying stdio functions any quirks

in stdio behaviour will be mirrored by the corresponding BIO.

=head1 EXAMPLES

File BIO "hello world":

 BIO *bio_out;

 bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);

 BIO_printf(bio_out, "Hello World\n");

Alternative technique:

 BIO *bio_out;

 bio_out = BIO_new(BIO_s_file());

 if(bio_out == NULL) /* Error ... */

 if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */

 BIO_printf(bio_out, "Hello World\n");

Write to a file:

 BIO *out;

 out = BIO_new_file("filename.txt", "w");

 if(!out) /* Error occurred */

 BIO_printf(out, "Hello World\n");

 BIO_free(out);

Alternative technique:

 BIO *out;

 out = BIO_new(BIO_s_file());

 if(out == NULL) /* Error ... */

 if(!BIO_read_filename(out, "filename.txt")) /* Error ... */

 BIO_printf(out, "Hello World\n");

 BIO_free(out);

=head1 RETURN VALUES

BIO_s_file() returns the file BIO method.

BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error

occurred.

BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure

(although the current implementation never return 0).

BIO_seek() returns the same value as the underlying fseek() function:

0 for success or -1 for failure.

BIO_tell() returns the current file position.

BIO_read_filename(), BIO_write_filename(),  BIO_append_filename() and

BIO_rw_filename() return 1 for success or 0 for failure.

=head1 SEE ALSO

TBA