From: Dr. Stephen Henson Date: Mon, 11 Sep 2000 01:04:09 +0000 (+0000) Subject: Docs for cipher and base64 BIOs. X-Git-Tag: OpenSSL-engine-0_9_6-beta1~3^2 X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff_plain;h=b1ccd57b18c4c2ea6f1a1199c3afdd33eb070baa Docs for cipher and base64 BIOs. --- diff --git a/doc/crypto/BIO_f_base64.pod b/doc/crypto/BIO_f_base64.pod new file mode 100644 index 0000000000..ec90fc2228 --- /dev/null +++ b/doc/crypto/BIO_f_base64.pod @@ -0,0 +1,82 @@ +=pod + +=head1 NAME + + BIO_f_base64 - base64 BIO + +=head1 SYNOPSIS + + #include + #include + + 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 diff --git a/doc/crypto/BIO_f_cipher.pod b/doc/crypto/BIO_f_cipher.pod new file mode 100644 index 0000000000..7270c743c5 --- /dev/null +++ b/doc/crypto/BIO_f_cipher.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + + BIO_f_cipher - cipher BIO + +=head1 SYNOPSIS + + #include + #include + + 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 to B using key B +and IV B. B 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 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 diff --git a/doc/crypto/BIO_f_md.pod b/doc/crypto/BIO_f_md.pod index 67ba6e8516..a5bb692221 100644 --- a/doc/crypto/BIO_f_md.pod +++ b/doc/crypto/BIO_f_md.pod @@ -39,8 +39,6 @@ in B, it is a BIO_ctrl() macro. BIO_get_md_ctx() returns the digest BIOs context into B. - - =head1 NOTES The context returned by BIO_get_md_ctx() can be used in calls diff --git a/doc/crypto/BIO_s_null.pod b/doc/crypto/BIO_s_null.pod index b9a3c2cf3f..c64c9838bc 100644 --- a/doc/crypto/BIO_s_null.pod +++ b/doc/crypto/BIO_s_null.pod @@ -13,7 +13,7 @@ =head1 DESCRIPTION BIO_s_null() returns the null sink BIO method. Data written to -the null sink is discraded, reads return EOF. +the null sink is discarded, reads return EOF. =head1 NOTES @@ -24,9 +24,9 @@ A null bio can be placed on the end of a chain to discard any data passed through it. A null sink is useful if, for example, an application wishes to digest some -data but not write the result anywhere. Since a BIO chain must normally -include a source/sink BIO this can be achieved by adding a null sink BIO -to the end of the chain +data by writing through a digest bio but not send the digested data anywhere. +Since a BIO chain must normally include a source/sink BIO this can be achieved +by adding a null sink BIO to the end of the chain =head1 RETURN VALUES