diff options
Diffstat (limited to 'crypto/openssl/doc')
54 files changed, 0 insertions, 4210 deletions
diff --git a/crypto/openssl/doc/apps/rsautl.pod b/crypto/openssl/doc/apps/rsautl.pod deleted file mode 100644 index 7a334bc8d6a3..000000000000 --- a/crypto/openssl/doc/apps/rsautl.pod +++ /dev/null @@ -1,183 +0,0 @@ -=pod - -=head1 NAME - -rsautl - RSA utility - -=head1 SYNOPSIS - -B<openssl> B<rsautl> -[B<-in file>] -[B<-out file>] -[B<-inkey file>] -[B<-pubin>] -[B<-certin>] -[B<-sign>] -[B<-verify>] -[B<-encrypt>] -[B<-decrypt>] -[B<-pkcs>] -[B<-ssl>] -[B<-raw>] -[B<-hexdump>] -[B<-asn1parse>] - -=head1 DESCRIPTION - -The B<rsautl> command can be used to sign, verify, encrypt and decrypt -data using the RSA algorithm. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-in filename> - -This specifies the input filename to read data from or standard input -if this option is not specified. - -=item B<-out filename> - -specifies the output filename to write to or standard output by -default. - -=item B<-inkey file> - -the input key file, by default it should be an RSA private key. - -=item B<-pubin> - -the input file is an RSA public key. - -=item B<-certin> - -the input is a certificate containing an RSA public key. - -=item B<-sign> - -sign the input data and output the signed result. This requires -and RSA private key. - -=item B<-verify> - -verify the input data and output the recovered data. - -=item B<-encrypt> - -encrypt the input data using an RSA public key. - -=item B<-decrypt> - -decrypt the input data using an RSA private key. - -=item B<-pkcs, -oaep, -ssl, -raw> - -the padding to use: PKCS#1 v1.5 (the default), PKCS#1 OAEP, -special padding used in SSL v2 backwards compatible handshakes, -or no padding, respectively. -For signatures, only B<-pkcs> and B<-raw> can be used. - -=item B<-hexdump> - -hex dump the output data. - -=item B<-asn1parse> - -asn1parse the output data, this is useful when combined with the -B<-verify> option. - -=back - -=head1 NOTES - -B<rsautl> because it uses the RSA algorithm directly can only be -used to sign or verify small pieces of data. - -=head1 EXAMPLES - -Sign some data using a private key: - - openssl rsautl -sign -in file -inkey key.pem -out sig - -Recover the signed data - - openssl rsautl -sign -in sig -inkey key.pem - -Examine the raw signed data: - - openssl rsautl -sign -in file -inkey key.pem -raw -hexdump - - 0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ - 0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ - 0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ - 0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ - 0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ - 0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ - 0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ - 0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64 .....hello world - -The PKCS#1 block formatting is evident from this. If this was done using -encrypt and decrypt the block would have been of type 2 (the second byte) -and random padding data visible instead of the 0xff bytes. - -It is possible to analyse the signature of certificates using this -utility in conjunction with B<asn1parse>. Consider the self signed -example in certs/pca-cert.pem . Running B<asn1parse> as follows yields: - - openssl asn1parse -in pca-cert.pem - - 0:d=0 hl=4 l= 742 cons: SEQUENCE - 4:d=1 hl=4 l= 591 cons: SEQUENCE - 8:d=2 hl=2 l= 3 cons: cont [ 0 ] - 10:d=3 hl=2 l= 1 prim: INTEGER :02 - 13:d=2 hl=2 l= 1 prim: INTEGER :00 - 16:d=2 hl=2 l= 13 cons: SEQUENCE - 18:d=3 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption - 29:d=3 hl=2 l= 0 prim: NULL - 31:d=2 hl=2 l= 92 cons: SEQUENCE - 33:d=3 hl=2 l= 11 cons: SET - 35:d=4 hl=2 l= 9 cons: SEQUENCE - 37:d=5 hl=2 l= 3 prim: OBJECT :countryName - 42:d=5 hl=2 l= 2 prim: PRINTABLESTRING :AU - .... - 599:d=1 hl=2 l= 13 cons: SEQUENCE - 601:d=2 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption - 612:d=2 hl=2 l= 0 prim: NULL - 614:d=1 hl=3 l= 129 prim: BIT STRING - - -The final BIT STRING contains the actual signature. It can be extracted with: - - openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614 - -The certificate public key can be extracted with: - - openssl x509 -in test/testx509.pem -pubout -noout >pubkey.pem - -The signature can be analysed with: - - openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin - - 0:d=0 hl=2 l= 32 cons: SEQUENCE - 2:d=1 hl=2 l= 12 cons: SEQUENCE - 4:d=2 hl=2 l= 8 prim: OBJECT :md5 - 14:d=2 hl=2 l= 0 prim: NULL - 16:d=1 hl=2 l= 16 prim: OCTET STRING - 0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5 .F...Js.7...H%.. - -This is the parsed version of an ASN1 DigestInfo structure. It can be seen that -the digest used was md5. The actual part of the certificate that was signed can -be extracted with: - - openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4 - -and its digest computed with: - - openssl md5 -c tbs - MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5 - -which it can be seen agrees with the recovered value above. - -=head1 SEE ALSO - -L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)> diff --git a/crypto/openssl/doc/crypto/BIO_ctrl.pod b/crypto/openssl/doc/crypto/BIO_ctrl.pod deleted file mode 100644 index 722e8b8f46c9..000000000000 --- a/crypto/openssl/doc/crypto/BIO_ctrl.pod +++ /dev/null @@ -1,128 +0,0 @@ -=pod - -=head1 NAME - -BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset, -BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close, -BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending, -BIO_get_info_callback, BIO_set_info_callback - BIO control operations - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg); - long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long)); - char * BIO_ptr_ctrl(BIO *bp,int cmd,long larg); - long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg); - - int BIO_reset(BIO *b); - int BIO_seek(BIO *b, int ofs); - int BIO_tell(BIO *b); - int BIO_flush(BIO *b); - int BIO_eof(BIO *b); - int BIO_set_close(BIO *b,long flag); - int BIO_get_close(BIO *b); - int BIO_pending(BIO *b); - int BIO_wpending(BIO *b); - size_t BIO_ctrl_pending(BIO *b); - size_t BIO_ctrl_wpending(BIO *b); - - int BIO_get_info_callback(BIO *b,bio_info_cb **cbp); - int BIO_set_info_callback(BIO *b,bio_info_cb *cb); - - typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3); - -=head1 DESCRIPTION - -BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl() -are BIO "control" operations taking arguments of various types. -These functions are not normally called directly, various macros -are used instead. The standard macros are described below, macros -specific to a particular type of BIO are described in the specific -BIOs manual page as well as any special features of the standard -calls. - -BIO_reset() typically resets a BIO to some initial state, in the case -of file related BIOs for example it rewinds the file pointer to the -start of the file. - -BIO_seek() resets a file related BIO's (that is file descriptor and -FILE BIOs) file position pointer to B<ofs> bytes from start of file. - -BIO_tell() returns the current file position of a file related BIO. - -BIO_flush() normally writes out any internally buffered data, in some -cases it is used to signal EOF and that no more data will be written. - -BIO_eof() returns 1 if the BIO has read EOF, the precise meaning of -"EOF" varies according to the BIO type. - -BIO_set_close() sets the BIO B<b> close flag to B<flag>. B<flag> can -take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used -in a source/sink BIO to indicate that the underlying I/O stream should -be closed when the BIO is freed. - -BIO_get_close() returns the BIOs close flag. - -BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() -return the number of pending characters in the BIOs read and write buffers. -Not all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending() -return a size_t type and are functions, BIO_pending() and BIO_wpending() are -macros which call BIO_ctrl(). - -=head1 RETURN VALUES - -BIO_reset() normally returns 1 for success and 0 or -1 for failure. File -BIOs are an exception, they return 0 for success and -1 for failure. - -BIO_seek() and BIO_tell() both return the current file position on success -and -1 for failure, except file BIOs which for BIO_seek() always return 0 -for success and -1 for failure. - -BIO_flush() returns 1 for success and 0 or -1 for failure. - -BIO_eof() returns 1 if EOF has been reached 0 otherwise. - -BIO_set_close() always returns 1. - -BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE. - -BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() -return the amount of pending data. - -=head1 NOTES - -BIO_flush(), because it can write data may return 0 or -1 indicating -that the call should be retried later in a similar manner to BIO_write(). -The BIO_should_retry() call should be used and appropriate action taken -is the call fails. - -The return values of BIO_pending() and BIO_wpending() may not reliably -determine the amount of pending data in all cases. For example in the -case of a file BIO some data may be available in the FILE structures -internal buffers but it is not possible to determine this in a -portably way. For other types of BIO they may not be supported. - -Filter BIOs if they do not internally handle a particular BIO_ctrl() -operation usually pass the operation to the next BIO in the chain. -This often means there is no need to locate the required BIO for -a particular operation, it can be called on a chain and it will -be automatically passed to the relevant BIO. However this can cause -unexpected results: for example no current filter BIOs implement -BIO_seek(), but this may still succeed if the chain ends in a FILE -or file descriptor BIO. - -Source/sink BIOs return an 0 if they do not recognize the BIO_ctrl() -operation. - -=head1 BUGS - -Some of the return values are ambiguous and care should be taken. In -particular a return value of 0 can be returned if an operation is not -supported, if an error occurred, if EOF has not been reached and in -the case of BIO_seek() on a file BIO for a successful operation. - -=head1 SEE ALSO - -TBA diff --git a/crypto/openssl/doc/crypto/BIO_f_base64.pod b/crypto/openssl/doc/crypto/BIO_f_base64.pod deleted file mode 100644 index fdb603b38e30..000000000000 --- a/crypto/openssl/doc/crypto/BIO_f_base64.pod +++ /dev/null @@ -1,82 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_base64 - base64 BIO filter - -=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 diff --git a/crypto/openssl/doc/crypto/BIO_f_buffer.pod b/crypto/openssl/doc/crypto/BIO_f_buffer.pod deleted file mode 100644 index c9093c6a576c..000000000000 --- a/crypto/openssl/doc/crypto/BIO_f_buffer.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_buffer - buffering BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_f_buffer(void); - - #define BIO_get_buffer_num_lines(b) BIO_ctrl(b,BIO_C_GET_BUFF_NUM_LINES,0,NULL) - #define BIO_set_read_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,0) - #define BIO_set_write_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,1) - #define BIO_set_buffer_size(b,size) BIO_ctrl(b,BIO_C_SET_BUFF_SIZE,size,NULL) - #define BIO_set_buffer_read_data(b,buf,num) BIO_ctrl(b,BIO_C_SET_BUFF_READ_DATA,num,buf) - -=head1 DESCRIPTION - -BIO_f_buffer() returns the buffering BIO method. - -Data written to a buffering BIO is buffered and periodically written -to the next BIO in the chain. Data read from a buffering BIO comes from -an internal buffer which is filled from the next BIO in the chain. -Both BIO_gets() and BIO_puts() are supported. - -Calling BIO_reset() on a buffering BIO clears any buffered data. - -BIO_get_buffer_num_lines() returns the number of lines currently buffered. - -BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() -set the read, write or both read and write buffer sizes to B<size>. The initial -buffer size is DEFAULT_BUFFER_SIZE, currently 1024. Any attempt to reduce the -buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared -when the buffer is resized. - -BIO_set_buffer_read_data() clears the read buffer and fills it with B<num> -bytes of B<buf>. If B<num> is larger than the current buffer size the buffer -is expanded. - -=head1 NOTES - -Buffering BIOs implement BIO_gets() by using BIO_read() operations on the -next BIO in the chain. By prepending a buffering BIO to a chain it is therefore -possible to provide BIO_gets() functionality if the following BIOs do not -support it (for example SSL BIOs). - -Data is only written to the next BIO in the chain when the write buffer fills -or when BIO_flush() is called. It is therefore important to call BIO_flush() -whenever any pending data should be written such as when removing a buffering -BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate -source/sink BIO is non blocking. - -=head1 RETURN VALUES - -BIO_f_buffer() returns the buffering BIO method. - -BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0). - -BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() -return 1 if the buffer was successfully resized or 0 for failure. - -BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if -there was an error. - -=head1 SEE ALSO - -TBA diff --git a/crypto/openssl/doc/crypto/BIO_f_cipher.pod b/crypto/openssl/doc/crypto/BIO_f_cipher.pod deleted file mode 100644 index 4182f2c30903..000000000000 --- a/crypto/openssl/doc/crypto/BIO_f_cipher.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter - -=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 conjunction -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 diff --git a/crypto/openssl/doc/crypto/BIO_f_md.pod b/crypto/openssl/doc/crypto/BIO_f_md.pod deleted file mode 100644 index c32504dfb186..000000000000 --- a/crypto/openssl/doc/crypto/BIO_f_md.pod +++ /dev/null @@ -1,138 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter - -=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 initialize 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 diff --git a/crypto/openssl/doc/crypto/BIO_f_null.pod b/crypto/openssl/doc/crypto/BIO_f_null.pod deleted file mode 100644 index b057c1840832..000000000000 --- a/crypto/openssl/doc/crypto/BIO_f_null.pod +++ /dev/null @@ -1,32 +0,0 @@ -=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 diff --git a/crypto/openssl/doc/crypto/BIO_f_ssl.pod b/crypto/openssl/doc/crypto/BIO_f_ssl.pod deleted file mode 100644 index a56ee2b92f2b..000000000000 --- a/crypto/openssl/doc/crypto/BIO_f_ssl.pod +++ /dev/null @@ -1,313 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes, -BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, -BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, -BIO_ssl_shutdown - SSL BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - #include <openssl/ssl.h> - - BIO_METHOD *BIO_f_ssl(void); - - #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl) - #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp) - #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL) - #define BIO_set_ssl_renegotiate_bytes(b,num) \ - BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL); - #define BIO_set_ssl_renegotiate_timeout(b,seconds) \ - BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL); - #define BIO_get_num_renegotiates(b) \ - BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL); - - BIO *BIO_new_ssl(SSL_CTX *ctx,int client); - BIO *BIO_new_ssl_connect(SSL_CTX *ctx); - BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx); - int BIO_ssl_copy_session_id(BIO *to,BIO *from); - void BIO_ssl_shutdown(BIO *bio); - - #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL) - -=head1 DESCRIPTION - -BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which -is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to -SSL I/O. - -I/O performed on an SSL BIO communicates using the SSL protocol with -the SSLs read and write BIOs. If an SSL connection is not established -then an attempt is made to establish one on the first I/O call. - -If a BIO is appended to an SSL BIO using BIO_push() it is automatically -used as the SSL BIOs read and write BIOs. - -Calling BIO_reset() on an SSL BIO closes down any current SSL connection -by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in -the chain: this will typically disconnect the underlying transport. -The SSL BIO is then reset to the initial accept or connect state. - -If the close flag is set when an SSL BIO is freed then the internal -SSL structure is also freed using SSL_free(). - -BIO_set_ssl() sets the internal SSL pointer of BIO B<b> to B<ssl> using -the close flag B<c>. - -BIO_get_ssl() retrieves the SSL pointer of BIO B<b>, it can then be -manipulated using the standard SSL library functions. - -BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client> -is 1 client mode is set. If B<client> is 0 server mode is set. - -BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count -to B<num>. When set after every B<num> bytes of I/O (read and write) -the SSL session is automatically renegotiated. B<num> must be at -least 512 bytes. - -BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to -B<seconds>. When the renegotiate timeout elapses the session is -automatically renegotiated. - -BIO_get_num_renegotiates() returns the total number of session -renegotiations due to I/O or timeout. - -BIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using -client mode if B<client> is non zero. - -BIO_new_ssl_connect() creates a new BIO chain consisting of an -SSL BIO (using B<ctx>) followed by a connect BIO. - -BIO_new_buffer_ssl_connect() creates a new BIO chain consisting -of a buffering BIO, an SSL BIO (using B<ctx>) and a connect -BIO. - -BIO_ssl_copy_session_id() copies an SSL session id between -BIO chains B<from> and B<to>. It does this by locating the -SSL BIOs in each chain and calling SSL_copy_session_id() on -the internal SSL pointer. - -BIO_ssl_shutdown() closes down an SSL connection on BIO -chain B<bio>. It does this by locating the SSL BIO in the -chain and calling SSL_shutdown() on its internal SSL -pointer. - -BIO_do_handshake() attempts to complete an SSL handshake on the -supplied BIO and establish the SSL connection. It returns 1 -if the connection was established successfully. A zero or negative -value is returned if the connection could not be established, the -call BIO_should_retry() should be used for non blocking connect BIOs -to determine if the call should be retried. If an SSL connection has -already been established this call has no effect. - -=head1 NOTES - -SSL BIOs are exceptional in that if the underlying transport -is non blocking they can still request a retry in exceptional -circumstances. Specifically this will happen if a session -renegotiation takes place during a BIO_read() operation, one -case where this happens is when SGC or step up occurs. - -In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be -set to disable this behaviour. That is when this flag is set -an SSL BIO using a blocking transport will never request a -retry. - -Since unknown BIO_ctrl() operations are sent through filter -BIOs the servers name and port can be set using BIO_set_host() -on the BIO returned by BIO_new_ssl_connect() without having -to locate the connect BIO first. - -Applications do not have to call BIO_do_handshake() but may wish -to do so to separate the handshake process from other I/O -processing. - -=head1 RETURN VALUES - -TBA - -=head1 EXAMPLE - -This SSL/TLS client example, attempts to retrieve a page from an -SSL/TLS web server. The I/O routines are identical to those of the -unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>. - - BIO *sbio, *out; - int len; - char tmpbuf[1024]; - SSL_CTX *ctx; - SSL *ssl; - - ERR_load_crypto_strings(); - ERR_load_SSL_strings(); - OpenSSL_add_all_algorithms(); - - /* We would seed the PRNG here if the platform didn't - * do it automatically - */ - - ctx = SSL_CTX_new(SSLv23_client_method()); - - /* We'd normally set some stuff like the verify paths and - * mode here because as things stand this will connect to - * any server whose certificate is signed by any CA. - */ - - sbio = BIO_new_ssl_connect(ctx); - - BIO_get_ssl(sbio, &ssl); - - if(!ssl) { - fprintf(stderr, "Can't locate SSL pointer\n"); - /* whatever ... */ - } - - /* Don't want any retries */ - SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); - - /* We might want to do other things with ssl here */ - - BIO_set_conn_hostname(sbio, "localhost:https"); - - out = BIO_new_fp(stdout, BIO_NOCLOSE); - if(BIO_do_connect(sbio) <= 0) { - fprintf(stderr, "Error connecting to server\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ - } - - if(BIO_do_handshake(sbio) <= 0) { - fprintf(stderr, "Error establishing SSL connection\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ - } - - /* Could examine ssl here to get connection info */ - - BIO_puts(sbio, "GET / HTTP/1.0\n\n"); - for(;;) { - len = BIO_read(sbio, tmpbuf, 1024); - if(len <= 0) break; - BIO_write(out, tmpbuf, len); - } - BIO_free_all(sbio); - BIO_free(out); - -Here is a simple server example. It makes use of a buffering -BIO to allow lines to be read from the SSL BIO using BIO_gets. -It creates a pseudo web page containing the actual request from -a client and also echoes the request to standard output. - - BIO *sbio, *bbio, *acpt, *out; - int len; - char tmpbuf[1024]; - SSL_CTX *ctx; - SSL *ssl; - - ERR_load_crypto_strings(); - ERR_load_SSL_strings(); - OpenSSL_add_all_algorithms(); - - /* Might seed PRNG here */ - - ctx = SSL_CTX_new(SSLv23_server_method()); - - if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM) - || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM) - || !SSL_CTX_check_private_key(ctx)) { - - fprintf(stderr, "Error setting up SSL_CTX\n"); - ERR_print_errors_fp(stderr); - return 0; - } - - /* Might do other things here like setting verify locations and - * DH and/or RSA temporary key callbacks - */ - - /* New SSL BIO setup as server */ - sbio=BIO_new_ssl(ctx,0); - - BIO_get_ssl(sbio, &ssl); - - if(!ssl) { - fprintf(stderr, "Can't locate SSL pointer\n"); - /* whatever ... */ - } - - /* Don't want any retries */ - SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); - - /* Create the buffering BIO */ - - bbio = BIO_new(BIO_f_buffer()); - - /* Add to chain */ - sbio = BIO_push(bbio, sbio); - - acpt=BIO_new_accept("4433"); - - /* By doing this when a new connection is established - * we automatically have sbio inserted into it. The - * BIO chain is now 'swallowed' by the accept BIO and - * will be freed when the accept BIO is freed. - */ - - BIO_set_accept_bios(acpt,sbio); - - out = BIO_new_fp(stdout, BIO_NOCLOSE); - - /* Setup accept BIO */ - if(BIO_do_accept(acpt) <= 0) { - fprintf(stderr, "Error setting up accept BIO\n"); - ERR_print_errors_fp(stderr); - return 0; - } - - /* Now wait for incoming connection */ - if(BIO_do_accept(acpt) <= 0) { - fprintf(stderr, "Error in connection\n"); - ERR_print_errors_fp(stderr); - return 0; - } - - /* We only want one connection so remove and free - * accept BIO - */ - - sbio = BIO_pop(acpt); - - BIO_free_all(acpt); - - if(BIO_do_handshake(sbio) <= 0) { - fprintf(stderr, "Error in SSL handshake\n"); - ERR_print_errors_fp(stderr); - return 0; - } - - BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/html\r\n\r\n"); - BIO_puts(sbio, "<pre>\r\nConnection Established\r\nRequest headers:\r\n"); - BIO_puts(sbio, "--------------------------------------------------\r\n"); - - for(;;) { - len = BIO_gets(sbio, tmpbuf, 1024); - if(len <= 0) break; - BIO_write(sbio, tmpbuf, len); - BIO_write(out, tmpbuf, len); - /* Look for blank line signifying end of headers*/ - if((tmpbuf[0] == '\r') || (tmpbuf[0] == '\n')) break; - } - - BIO_puts(sbio, "--------------------------------------------------\r\n"); - BIO_puts(sbio, "</pre>\r\n"); - - /* Since there is a buffering BIO present we had better flush it */ - BIO_flush(sbio); - - BIO_free_all(sbio); - -=head1 SEE ALSO - -TBA diff --git a/crypto/openssl/doc/crypto/BIO_find_type.pod b/crypto/openssl/doc/crypto/BIO_find_type.pod deleted file mode 100644 index bd3b25619617..000000000000 --- a/crypto/openssl/doc/crypto/BIO_find_type.pod +++ /dev/null @@ -1,98 +0,0 @@ -=pod - -=head1 NAME - -BIO_find_type, BIO_next - BIO chain traversal - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO * BIO_find_type(BIO *b,int bio_type); - BIO * BIO_next(BIO *b); - - #define BIO_method_type(b) ((b)->method->type) - - #define BIO_TYPE_NONE 0 - #define BIO_TYPE_MEM (1|0x0400) - #define BIO_TYPE_FILE (2|0x0400) - - #define BIO_TYPE_FD (4|0x0400|0x0100) - #define BIO_TYPE_SOCKET (5|0x0400|0x0100) - #define BIO_TYPE_NULL (6|0x0400) - #define BIO_TYPE_SSL (7|0x0200) - #define BIO_TYPE_MD (8|0x0200) - #define BIO_TYPE_BUFFER (9|0x0200) - #define BIO_TYPE_CIPHER (10|0x0200) - #define BIO_TYPE_BASE64 (11|0x0200) - #define BIO_TYPE_CONNECT (12|0x0400|0x0100) - #define BIO_TYPE_ACCEPT (13|0x0400|0x0100) - #define BIO_TYPE_PROXY_CLIENT (14|0x0200) - #define BIO_TYPE_PROXY_SERVER (15|0x0200) - #define BIO_TYPE_NBIO_TEST (16|0x0200) - #define BIO_TYPE_NULL_FILTER (17|0x0200) - #define BIO_TYPE_BER (18|0x0200) - #define BIO_TYPE_BIO (19|0x0400) - - #define BIO_TYPE_DESCRIPTOR 0x0100 - #define BIO_TYPE_FILTER 0x0200 - #define BIO_TYPE_SOURCE_SINK 0x0400 - -=head1 DESCRIPTION - -The BIO_find_type() searches for a BIO of a given type in a chain, starting -at BIO B<b>. If B<type> is a specific type (such as BIO_TYPE_MEM) then a search -is made for a BIO of that type. If B<type> is a general type (such as -B<BIO_TYPE_SOURCE_SINK>) then the next matching BIO of the given general type is -searched for. BIO_find_type() returns the next matching BIO or NULL if none is -found. - -Note: not all the B<BIO_TYPE_*> types above have corresponding BIO implementations. - -BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs -in a chain or used in conjunction with BIO_find_type() to find all BIOs of a -certain type. - -BIO_method_type() returns the type of a BIO. - -=head1 RETURN VALUES - -BIO_find_type() returns a matching BIO or NULL for no match. - -BIO_next() returns the next BIO in a chain. - -BIO_method_type() returns the type of the BIO B<b>. - -=head1 NOTES - -BIO_next() was added to OpenSSL 0.9.6 to provide a 'clean' way to traverse a BIO -chain or find multiple matches using BIO_find_type(). Previous versions had to -use: - - next = bio->next_bio; - -=head1 BUGS - -BIO_find_type() in OpenSSL 0.9.5a and earlier could not be safely passed a -NULL pointer for the B<b> argument. - -=head1 EXAMPLE - -Traverse a chain looking for digest BIOs: - - BIO *btmp; - btmp = in_bio; /* in_bio is chain to search through */ - - do { - btmp = BIO_find_type(btmp, BIO_TYPE_MD); - if(btmp == NULL) break; /* Not found */ - /* btmp is a digest BIO, do something with it ...*/ - ... - - btmp = BIO_next(btmp); - } while(btmp); - - -=head1 SEE ALSO - -TBA diff --git a/crypto/openssl/doc/crypto/BIO_new.pod b/crypto/openssl/doc/crypto/BIO_new.pod deleted file mode 100644 index 2a245fc8de83..000000000000 --- a/crypto/openssl/doc/crypto/BIO_new.pod +++ /dev/null @@ -1,65 +0,0 @@ -=pod - -=head1 NAME - -BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and freeing functions - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO * BIO_new(BIO_METHOD *type); - int BIO_set(BIO *a,BIO_METHOD *type); - int BIO_free(BIO *a); - void BIO_vfree(BIO *a); - void BIO_free_all(BIO *a); - -=head1 DESCRIPTION - -The BIO_new() function returns a new BIO using method B<type>. - -BIO_set() sets the method of an already existing BIO. - -BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO -but it does not return a value. Calling BIO_free() may also have some effect -on the underlying I/O structure, for example it may close the file being -referred to under certain circumstances. For more details see the individual -BIO_METHOD descriptions. - -BIO_free_all() frees up an entire BIO chain, it does not halt if an error -occurs freeing up an individual BIO in the chain. - -=head1 RETURN VALUES - -BIO_new() returns a newly created BIO or NULL if the call fails. - -BIO_set(), BIO_free() return 1 for success and 0 for failure. - -BIO_free_all() and BIO_vfree() do not return values. - -=head1 NOTES - -Some BIOs (such as memory BIOs) can be used immediately after calling -BIO_new(). Others (such as file BIOs) need some additional initialization, -and frequently a utility function exists to create and initialize such BIOs. - -If BIO_free() is called on a BIO chain it will only free one BIO resulting -in a memory leak. - -Calling BIO_free_all() a single BIO has the same effect as calling BIO_free() -on it other than the discarded return value. - -Normally the B<type> argument is supplied by a function which returns a -pointer to a BIO_METHOD. There is a naming convention for such functions: -a source/sink BIO is normally called BIO_s_*() and a filter BIO -BIO_f_*(); - -=head1 EXAMPLE - -Create a memory BIO: - - BIO *mem = BIO_new(BIO_s_mem()); - -=head1 SEE ALSO - -TBA diff --git a/crypto/openssl/doc/crypto/BIO_new_bio_pair.pod b/crypto/openssl/doc/crypto/BIO_new_bio_pair.pod deleted file mode 100644 index 2256ba9d3410..000000000000 --- a/crypto/openssl/doc/crypto/BIO_new_bio_pair.pod +++ /dev/null @@ -1,102 +0,0 @@ -=pod - -=head1 NAME - -BIO_new_bio_pair - create a new BIO pair - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); - -=head1 DESCRIPTION - -BIO_new_bio_pair() creates a buffering BIO pair. It has two endpoints between -data can be buffered. Its typical use is to connect one endpoint as underlying -input/output BIO to an SSL and access the other one controlled by the program -instead of accessing the network connection directly. - -The two new BIOs B<bio1> and B<bio2> are symmetric with respect to their -functionality. The size of their buffers is determined by B<writebuf1> and -B<writebuf2>. If the size give is 0, the default size is used. - -BIO_new_bio_pair() does not check whether B<bio1> or B<bio2> do point to -some other BIO, the values are overwritten, BIO_free() is not called. - -The two BIOs, even though forming a BIO pair and must be BIO_free()'ed -separately. This can be of importance, as some SSL-functions like SSL_set_bio() -or SSL_free() call BIO_free() implicitly, so that the peer-BIO is left -untouched and must also be BIO_free()'ed. - -=head1 EXAMPLE - -The BIO pair can be used to have full control over the network access of an -application. The application can call select() on the socket as required -without having to go through the SSL-interface. - - BIO *internal_bio, *network_bio; - ... - BIO_new_bio_pair(internal_bio, 0, network_bio, 0); - SSL_set_bio(ssl, internal_bio); - SSL_operations(); - ... - - application | TLS-engine - | | - +----------> SSL_operations() - | /\ || - | || \/ - | BIO-pair (internal_bio) - +----------< BIO-pair (network_bio) - | | - socket | - - ... - SSL_free(ssl); /* implicitly frees internal_bio */ - BIO_free(network_bio); - ... - -As the BIO pair will only buffer the data and never directly access the -connection, it behaves non-blocking and will return as soon as the write -buffer is full or the read buffer is drained. Then the application has to -flush the write buffer and/or fill the read buffer. - -Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO -and must be transfered to the network. Use BIO_ctrl_get_read_request() to -find out, how many bytes must be written into the buffer before the -SSL_operation() can successfully be continued. - -=head1 IMPORTANT - -As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ -condition, but there is still data in the write buffer. An application must -not rely on the error value of SSL_operation() but must assure that the -write buffer is always flushed first. Otherwise a deadlock may occur as -the peer might be waiting for the data before being able to continue. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item 1 - -The BIO pair was created successfully. The new BIOs are available in -B<bio1> and B<bio2>. - -=item 0 - -The operation failed. The NULL pointer is stored into the locations for -B<bio1> and B<bio2>. Check the error stack for more information. - -=back - -=head1 SEE ALSO - -L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, -L<BIO_ctrl_pending(3)|BIO_ctrl_pending(3)>, -L<BIO_ctrl_get_read_request(3)|BIO_ctrl_get_read_request(3)> - -=cut diff --git a/crypto/openssl/doc/crypto/BIO_push.pod b/crypto/openssl/doc/crypto/BIO_push.pod deleted file mode 100644 index 8af1d3c09751..000000000000 --- a/crypto/openssl/doc/crypto/BIO_push.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=head1 NAME - -BIO_push, BIO_pop - add and remove BIOs from a chain. - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO * BIO_push(BIO *b,BIO *append); - BIO * BIO_pop(BIO *b); - -=head1 DESCRIPTION - -The BIO_push() function appends the BIO B<append> to B<b>, it returns -B<b>. - -BIO_pop() removes the BIO B<b> from a chain and returns the next BIO -in the chain, or NULL if there is no next BIO. The removed BIO then -becomes a single BIO with no association with the original chain, -it can thus be freed or attached to a different chain. - -=head1 NOTES - -The names of these functions are perhaps a little misleading. BIO_push() -joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain, -the deleted BIO does not need to be at the end of a chain. - -The process of calling BIO_push() and BIO_pop() on a BIO may have additional -consequences (a control call is made to the affected BIOs) any effects will -be noted in the descriptions of individual BIOs. - -=head1 EXAMPLES - -For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is -a base64 BIO and B<f> is a file BIO. - -If the call: - - BIO_push(b64, f); - -is made then the new chain will be B<b64-chain>. After making the calls - - BIO_push(md2, b64); - BIO_push(md1, md2); - -the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested -by B<md1> and B<md2>, B<base64> encoded and written to B<f>. - -It should be noted that reading causes data to pass in the reverse -direction, that is data is read from B<f>, base64 B<decoded> and digested -by B<md1> and B<md2>. If the call: - - BIO_pop(md2); - -The call will return B<b64> and the new chain will be B<md1-b64-f> data can -be written to B<md1> as before. - -=head1 RETURN VALUES - -BIO_push() returns the end of the chain, B<b>. - -BIO_pop() returns the next BIO in the chain, or NULL if there is no next -BIO. - -=head1 SEE ALSO - -TBA diff --git a/crypto/openssl/doc/crypto/BIO_read.pod b/crypto/openssl/doc/crypto/BIO_read.pod deleted file mode 100644 index b34528104ddf..000000000000 --- a/crypto/openssl/doc/crypto/BIO_read.pod +++ /dev/null @@ -1,66 +0,0 @@ -=pod - -=head1 NAME - -BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - int BIO_read(BIO *b, void *buf, int len); - int BIO_gets(BIO *b,char *buf, int size); - int BIO_write(BIO *b, const void *buf, int len); - int BIO_puts(BIO *b,const char *buf); - -=head1 DESCRIPTION - -BIO_read() attempts to read B<len> bytes from BIO B<b> and places -the data in B<buf>. - -BIO_gets() performs the BIOs "gets" operation and places the data -in B<buf>. Usually this operation will attempt to read a line of data -from the BIO of maximum length B<len>. There are exceptions to this -however, for example BIO_gets() on a digest BIO will calculate and -return the digest and other BIOs may not support BIO_gets() at all. - -BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>. - -BIO_puts() attempts to write a null terminated string B<buf> to BIO B<b> - -=head1 RETURN VALUES - -All these functions return either the amount of data successfully read or -written (if the return value is positive) or that no data was successfully -read or written if the result is 0 or -1. If the return value is -2 then -the operation is not implemented in the specific BIO type. - -=head1 NOTES - -A 0 or -1 return is not necessarily an indication of an error. In -particular when the source/sink is non-blocking or of a certain type -it may merely be an indication that no data is currently available and that -the application should retry the operation later. - -One technique sometimes used with blocking sockets is to use a system call -(such as select(), poll() or equivalent) to determine when data is available -and then call read() to read the data. The equivalent with BIOs (that is call -select() on the underlying I/O structure and then call BIO_read() to -read the data) should B<not> be used because a single call to BIO_read() -can cause several reads (and writes in the case of SSL BIOs) on the underlying -I/O structure and may block as a result. Instead select() (or equivalent) -should be combined with non blocking I/O so successive reads will request -a retry instead of blocking. - -See L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to -determine the cause of a retry and other I/O issues. - -If the BIO_gets() function is not supported by a BIO then it possible to -work around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)> -to the chain. - -=head1 SEE ALSO - -L<BIO_should_retry(3)|BIO_should_retry(3)> - -TBA diff --git a/crypto/openssl/doc/crypto/BIO_s_accept.pod b/crypto/openssl/doc/crypto/BIO_s_accept.pod deleted file mode 100644 index c49da7fb02c0..000000000000 --- a/crypto/openssl/doc/crypto/BIO_s_accept.pod +++ /dev/null @@ -1,184 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_accept, BIO_set_nbio, BIO_set_accept_port, BIO_get_accept_port, -BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode, -BIO_get_bind_mode, BIO_do_accept - accept BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_s_accept(void); - - #define BIO_set_accept_port(b,name) BIO_ctrl(b,BIO_C_SET_ACCEPT,0,(char *)name) - #define BIO_get_accept_port(b) BIO_ptr_ctrl(b,BIO_C_GET_ACCEPT,0) - - BIO *BIO_new_accept(char *host_port); - - #define BIO_set_nbio_accept(b,n) BIO_ctrl(b,BIO_C_SET_ACCEPT,1,(n)?"a":NULL) - #define BIO_set_accept_bios(b,bio) BIO_ctrl(b,BIO_C_SET_ACCEPT,2,(char *)bio) - - #define BIO_set_bind_mode(b,mode) BIO_ctrl(b,BIO_C_SET_BIND_MODE,mode,NULL) - #define BIO_get_bind_mode(b,mode) BIO_ctrl(b,BIO_C_GET_BIND_MODE,0,NULL) - - #define BIO_BIND_NORMAL 0 - #define BIO_BIND_REUSEADDR_IF_UNUSED 1 - #define BIO_BIND_REUSEADDR 2 - - #define BIO_do_accept(b) BIO_do_handshake(b) - -=head1 DESCRIPTION - -BIO_s_accept() returns the accept BIO method. This is a wrapper -round the platform's TCP/IP socket accept routines. - -Using accept BIOs TCP/IP connections can be accepted and data -transferred using only BIO routines. In this way any platform -specific operations are hidden by the BIO abstraction. - -Read and write operations on an accept BIO will perform I/O -on the underlying connection. If no connection is established -and the port (see below) is set up properly then the BIO -waits for an incoming connection. - -Accept BIOs support BIO_puts() but not BIO_gets(). - -If the close flag is set on an accept BIO then any active -connection on that chain is shutdown and the socket closed when -the BIO is freed. - -Calling BIO_reset() on a accept BIO will close any active -connection and reset the BIO into a state where it awaits another -incoming connection. - -BIO_get_fd() and BIO_set_fd() can be called to retrieve or set -the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)> - -BIO_set_accept_port() uses the string B<name> to set the accept -port. The port is represented as a string of the form "host:port", -where "host" is the interface to use and "port" is the port. -Either or both values can be "*" which is interpreted as meaning -any interface or port respectively. "port" has the same syntax -as the port specified in BIO_set_conn_port() for connect BIOs, -that is it can be a numerical port string or a string to lookup -using getservbyname() and a string table. - -BIO_new_accept() combines BIO_new() and BIO_set_accept_port() into -a single call: that is it creates a new accept BIO with port -B<host_port>. - -BIO_set_nbio_accept() sets the accept socket to blocking mode -(the default) if B<n> is 0 or non blocking mode if B<n> is 1. - -BIO_set_accept_bios() can be used to set a chain of BIOs which -will be duplicated and prepended to the chain when an incoming -connection is received. This is useful if, for example, a -buffering or SSL BIO is required for each connection. The -chain of BIOs must not be freed after this call, they will -be automatically freed when the accept BIO is freed. - -BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve -the current bind mode. If BIO_BIND_NORMAL (the default) is set -then another socket cannot be bound to the same port. If -BIO_BIND_REUSEADDR is set then other sockets can bind to the -same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and -attempt is first made to use BIO_BIN_NORMAL, if this fails -and the port is not in use then a second attempt is made -using BIO_BIND_REUSEADDR. - -BIO_do_accept() serves two functions. When it is first -called, after the accept BIO has been setup, it will attempt -to create the accept socket and bind an address to it. Second -and subsequent calls to BIO_do_accept() will await an incoming -connection. - -=head1 NOTES - -When an accept BIO is at the end of a chain it will await an -incoming connection before processing I/O calls. When an accept -BIO is not at then end of a chain it passes I/O calls to the next -BIO in the chain. - -When a connection is established a new socket BIO is created for -the connection and appended to the chain. That is the chain is now -accept->socket. This effectively means that attempting I/O on -an initial accept socket will await an incoming connection then -perform I/O on it. - -If any additional BIOs have been set using BIO_set_accept_bios() -then they are placed between the socket and the accept BIO, -that is the chain will be accept->otherbios->socket. - -If a server wishes to process multiple connections (as is normally -the case) then the accept BIO must be made available for further -incoming connections. This can be done by waiting for a connection and -then calling: - - connection = BIO_pop(accept); - -After this call B<connection> will contain a BIO for the recently -established connection and B<accept> will now be a single BIO -again which can be used to await further incoming connections. -If no further connections will be accepted the B<accept> can -be freed using BIO_free(). - -If only a single connection will be processed it is possible to -perform I/O using the accept BIO itself. This is often undesirable -however because the accept BIO will still accept additional incoming -connections. This can be resolved by using BIO_pop() (see above) -and freeing up the accept BIO after the initial connection. - -=head1 RETURN VALUES - -TBA - -=head1 EXAMPLE - -This example accepts two connections on port 4444, sends messages -down each and finally closes both down. - - BIO *abio, *cbio, *cbio2; - ERR_load_crypto_strings(); - abio = BIO_new_accept("4444"); - - /* First call to BIO_accept() sets up accept BIO */ - if(BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error setting up accept\n"); - ERR_print_errors_fp(stderr); - exit(0); - } - - /* Wait for incoming connection */ - if(BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error accepting connection\n"); - ERR_print_errors_fp(stderr); - exit(0); - } - fprintf(stderr, "Connection 1 established\n"); - /* Retrieve BIO for connection */ - cbio = BIO_pop(abio); - BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n"); - fprintf(stderr, "Sent out data on connection 1\n"); - /* Wait for another connection */ - if(BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error accepting connection\n"); - ERR_print_errors_fp(stderr); - exit(0); - } - fprintf(stderr, "Connection 2 established\n"); - /* Close accept BIO to refuse further connections */ - cbio2 = BIO_pop(abio); - BIO_free(abio); - BIO_puts(cbio2, "Connection 2: Sending out Data on second\n"); - fprintf(stderr, "Sent out data on connection 2\n"); - - BIO_puts(cbio, "Connection 1: Second connection established\n"); - /* Close the two established connections */ - BIO_free(cbio); - BIO_free(cbio2); - -=head1 SEE ALSO - -TBA diff --git a/crypto/openssl/doc/crypto/BIO_s_bio.pod b/crypto/openssl/doc/crypto/BIO_s_bio.pod deleted file mode 100644 index 95ae802e4724..000000000000 --- a/crypto/openssl/doc/crypto/BIO_s_bio.pod +++ /dev/null @@ -1,130 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, -BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, -BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, -BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD *BIO_s_bio(void); - - #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2) - #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL) - - #define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL) - - #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL) - #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL) - - int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); - - #define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL) - size_t BIO_ctrl_get_write_guarantee(BIO *b); - - #define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL) - size_t BIO_ctrl_get_read_request(BIO *b); - - int BIO_ctrl_reset_read_request(BIO *b); - -=head1 DESCRIPTION - -BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink -BIOs where data written to either half of the pair is buffered and can be read from -the other half. Both halves must usually by handled by the same application thread -since no locking is done on the internal data structures. - -Since BIO chains typically end in a source/sink BIO it is possible to make this -one half of a BIO pair and have all the data processed by the chain under application -control. - -One typical use of BIO pairs is to place TLS/SSL I/O under application control, this -can be used when the application wishes to use a non standard transport for -TLS/SSL or the normal socket routines are inappropriate. - -Calls to BIO_read() will read data from the buffer or request a retry if no -data is available. - -Calls to BIO_write() will place data in the buffer or request a retry if the -buffer is full. - -The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to -determine the amount of pending data in the read or write buffer. - -BIO_reset() clears any data in the write buffer. - -BIO_make_bio_pair() joins two separate BIOs into a connected pair. - -BIO_destroy_pair() destroys the association between two connected BIOs. Freeing -up any half of the pair will automatically destroy the association. - -BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further -writes on BIO B<b> are allowed (they will return an error). Reads on the other -half of the pair will return any pending data or EOF when all pending data has -been read. - -BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>. -If the size is not initialized a default value is used. This is currently -17K, sufficient for a maximum size TLS record. - -BIO_get_write_buf_size() returns the size of the write buffer. - -BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and -BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2> -with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is -zero then the default size is used. - -BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum -length of data that can be currently written to the BIO. Writes larger than this -value will return a value from BIO_write() less than the amount requested or if the -buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function -whereas BIO_get_write_guarantee() is a macro. - -BIO_get_read_request() and BIO_ctrl_get_read_request() return the -amount of data requested, or the buffer size if it is less, if the -last read attempt at the other half of the BIO pair failed due to an -empty buffer. This can be used to determine how much data should be -written to the BIO so the next read will succeed: this is most useful -in TLS/SSL applications where the amount of data read is usually -meaningful rather than just a buffer size. After a successful read -this call will return zero. It also will return zero once new data -has been written satisfying the read request or part of it. -Note that BIO_get_read_request() never returns an amount larger -than that returned by BIO_get_write_guarantee(). - -BIO_ctrl_reset_read_request() can also be used to reset the value returned by -BIO_get_read_request() to zero. - -=head1 NOTES - -Both halves of a BIO pair should be freed. That is even if one half is implicit -freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed. - -When used in bidirectional applications (such as TLS/SSL) care should be taken to -flush any data in the write buffer. This can be done by calling BIO_pending() -on the other half of the pair and, if any data is pending, reading it and sending -it to the underlying transport. This must be done before any normal processing -(such as calling select() ) due to a request and BIO_should_read() being true. - -To see why this is important consider a case where a request is sent using -BIO_write() and a response read with BIO_read(), this can occur during an -TLS/SSL handshake for example. BIO_write() will succeed and place data in the write -buffer. BIO_read() will initially fail and BIO_should_read() will be true. If -the application then waits for data to be available on the underlying transport -before flushing the write buffer it will never succeed because the request was -never sent! - -=head1 EXAMPLE - -TBA - -=head1 SEE ALSO - -L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, -L<BIO_should_retry(3)|BIO_should_retry(3)>, L<BIO_read(3)|BIO_read(3)> - -=cut diff --git a/crypto/openssl/doc/crypto/BIO_s_connect.pod b/crypto/openssl/doc/crypto/BIO_s_connect.pod deleted file mode 100644 index fe1aa679d441..000000000000 --- a/crypto/openssl/doc/crypto/BIO_s_connect.pod +++ /dev/null @@ -1,182 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port, -BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname, -BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port, -BIO_set_nbio, BIO_do_connect - connect BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_s_connect(void); - - #define BIO_set_conn_hostname(b,name) BIO_ctrl(b,BIO_C_SET_CONNECT,0,(char *)name) - #define BIO_set_conn_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,1,(char *)port) - #define BIO_set_conn_ip(b,ip) BIO_ctrl(b,BIO_C_SET_CONNECT,2,(char *)ip) - #define BIO_set_conn_int_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,3,(char *)port) - #define BIO_get_conn_hostname(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,0) - #define BIO_get_conn_port(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,1) - #define BIO_get_conn_ip(b,ip) BIO_ptr_ctrl(b,BIO_C_SET_CONNECT,2) - #define BIO_get_conn_int_port(b,port) BIO_int_ctrl(b,BIO_C_SET_CONNECT,3,port) - - #define BIO_set_nbio(b,n) BIO_ctrl(b,BIO_C_SET_NBIO,(n),NULL) - - #define BIO_do_connect(b) BIO_do_handshake(b) - -=head1 DESCRIPTION - -BIO_s_connect() returns the connect BIO method. This is a wrapper -round the platform's TCP/IP socket connection routines. - -Using connect BIOs TCP/IP connections can be made and data -transferred using only BIO routines. In this way any platform -specific operations are hidden by the BIO abstraction. - -Read and write operations on a connect BIO will perform I/O -on the underlying connection. If no connection is established -and the port and hostname (see below) is set up properly then -a connection is established first. - -Connect BIOs support BIO_puts() but not BIO_gets(). - -If the close flag is set on a connect BIO then any active -connection is shutdown and the socket closed when the BIO -is freed. - -Calling BIO_reset() on a connect BIO will close any active -connection and reset the BIO into a state where it can connect -to the same host again. - -BIO_get_fd() places the underlying socket in B<c> if it is not NULL, -it also returns the socket . If B<c> is not NULL it should be of -type (int *). - -BIO_set_conn_hostname() uses the string B<name> to set the hostname -The hostname can be an IP address. The hostname can also include the -port in the form hostname:port . It is also acceptable to use the -form "hostname/any/other/path" or "hostname:port/any/other/path". - -BIO_set_conn_port() sets the port to B<port>. B<port> can be the -numerical form or a string such as "http". A string will be looked -up first using getservbyname() on the host platform but if that -fails a standard table of port names will be used. Currently the -list is http, telnet, socks, https, ssl, ftp, gopher and wais. - -BIO_set_conn_ip() sets the IP address to B<ip> using binary form, -that is four bytes specifying the IP address in big-endian form. - -BIO_set_conn_int_port() sets the port using B<port>. B<port> should -be of type (int *). - -BIO_get_conn_hostname() returns the hostname of the connect BIO or -NULL if the BIO is initialized but no hostname is set. -This return value is an internal pointer which should not be modified. - -BIO_get_conn_port() returns the port as a string. - -BIO_get_conn_ip() returns the IP address in binary form. - -BIO_get_conn_int_port() returns the port as an int. - -BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is -zero then blocking I/O is set. If B<n> is 1 then non blocking I/O -is set. Blocking I/O is the default. The call to BIO_set_nbio() -should be made before the connection is established because -non blocking I/O is set during the connect process. - -BIO_do_connect() attempts to connect the supplied BIO. It returns 1 -if the connection was established successfully. A zero or negative -value is returned if the connection could not be established, the -call BIO_should_retry() should be used for non blocking connect BIOs -to determine if the call should be retried. - -=head1 NOTES - -If blocking I/O is set then a non positive return value from any -I/O call is caused by an error condition, although a zero return -will normally mean that the connection was closed. - -If the port name is supplied as part of the host name then this will -override any value set with BIO_set_conn_port(). This may be undesirable -if the application does not wish to allow connection to arbitrary -ports. This can be avoided by checking for the presence of the ':' -character in the passed hostname and either indicating an error or -truncating the string at that point. - -The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(), -BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a -connection attempt is made. Before any connection attempt the values -returned are those set by the application itself. - -Applications do not have to call BIO_do_connect() but may wish to do -so to separate the connection process from other I/O processing. - -If non blocking I/O is set then retries will be requested as appropriate. - -It addition to BIO_should_read() and BIO_should_write() it is also -possible for BIO_should_io_special() to be true during the initial -connection process with the reason BIO_RR_CONNECT. If this is returned -then this is an indication that a connection attempt would block, -the application should then take appropriate action to wait until -the underlying socket has connected and retry the call. - -=head1 RETURN VALUES - -BIO_s_connect() returns the connect BIO method. - -BIO_get_fd() returns the socket or -1 if the BIO has not -been initialized. - -BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and -BIO_set_conn_int_port() always return 1. - -BIO_get_conn_hostname() returns the connected hostname or NULL is -none was set. - -BIO_get_conn_port() returns a string representing the connected -port or NULL if not set. - -BIO_get_conn_ip() returns a pointer to the connected IP address in -binary form or all zeros if not set. - -BIO_get_conn_int_port() returns the connected port or 0 if none was -set. - -BIO_set_nbio() always returns 1. - -BIO_do_connect() returns 1 if the connection was successfully -established and 0 or -1 if the connection failed. - -=head1 EXAMPLE - -This is example connects to a webserver on the local host and attempts -to retrieve a page and copy the result to standard output. - - - BIO *cbio, *out; - int len; - char tmpbuf[1024]; - ERR_load_crypto_strings(); - cbio = BIO_new_connect("localhost:http"); - out = BIO_new_fp(stdout, BIO_NOCLOSE); - if(BIO_do_connect(cbio) <= 0) { - fprintf(stderr, "Error connecting to server\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ - } - BIO_puts(cbio, "GET / HTTP/1.0\n\n"); - for(;;) { - len = BIO_read(cbio, tmpbuf, 1024); - if(len <= 0) break; - BIO_write(out, tmpbuf, len); - } - BIO_free(cbio); - BIO_free(out); - - -=head1 SEE ALSO - -TBA diff --git a/crypto/openssl/doc/crypto/BIO_s_fd.pod b/crypto/openssl/doc/crypto/BIO_s_fd.pod deleted file mode 100644 index b1de1d101549..000000000000 --- a/crypto/openssl/doc/crypto/BIO_s_fd.pod +++ /dev/null @@ -1,89 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_s_fd(void); - - #define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd) - #define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c) - - BIO *BIO_new_fd(int fd, int close_flag); - -=head1 DESCRIPTION - -BIO_s_fd() returns the file descriptor BIO method. This is a wrapper -round the platforms file descriptor routines such as read() and write(). - -BIO_read() and BIO_write() read or write the underlying descriptor. -BIO_puts() is supported but BIO_gets() is not. - -If the close flag is set then then close() is called on the underlying -file descriptor when the BIO is freed. - -BIO_reset() attempts to change the file pointer to the start of file -using lseek(fd, 0, 0). - -BIO_seek() sets the file pointer to position B<ofs> from start of file -using lseek(fd, ofs, 0). - -BIO_tell() returns the current file position by calling lseek(fd, 0, 1). - -BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close -flag to B<c>. - -BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also -returns the file descriptor. If B<c> is not NULL it should be of type -(int *). - -BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>. - -=head1 NOTES - -The behaviour of BIO_read() and BIO_write() depends on the behavior of the -platforms read() and write() calls on the descriptor. If the underlying -file descriptor is in a non blocking mode then the BIO will behave in the -manner described in the L<BIO_read(3)|BIO_read(3)> and L<BIO_should_retry(3)|BIO_should_retry(3)> -manual pages. - -File descriptor BIOs should not be used for socket I/O. Use socket BIOs -instead. - -=head1 RETURN VALUES - -BIO_s_fd() returns the file descriptor BIO method. - -BIO_reset() returns zero for success and -1 if an error occurred. -BIO_seek() and BIO_tell() return the current file position or -1 -is an error occurred. These values reflect the underlying lseek() -behaviour. - -BIO_set_fd() always returns 1. - -BIO_get_fd() returns the file descriptor or -1 if the BIO has not -been initialized. - -BIO_new_fd() returns the newly allocated BIO or NULL is an error -occurred. - -=head1 EXAMPLE - -This is a file descriptor BIO version of "Hello World": - - BIO *out; - out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE); - BIO_printf(out, "Hello World\n"); - BIO_free(out); - -=head1 SEE ALSO - -L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>, -L<BIO_reset(3)|BIO_reset(3)>, L<BIO_read(3)|BIO_read(3)>, -L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>, -L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>, -L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)> diff --git a/crypto/openssl/doc/crypto/BIO_s_file.pod b/crypto/openssl/doc/crypto/BIO_s_file.pod deleted file mode 100644 index b2a29263f4cd..000000000000 --- a/crypto/openssl/doc/crypto/BIO_s_file.pod +++ /dev/null @@ -1,144 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp, -BIO_read_filename, BIO_write_filename, BIO_append_filename, -BIO_rw_filename - 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); - - 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() attempts to change the file pointer to the start of file -using fseek(stream, 0, 0). - -BIO_seek() sets the file pointer to position B<ofs> from start of file -using fseek(stream, ofs, 0). - -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_write_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 BUGS - -BIO_reset() and BIO_seek() are implemented using fseek() on the underlying -stream. The return value for fseek() is 0 for success or -1 if an error -occurred this differs from other types of BIO which will typically return -1 for success and a non positive value if an error occurred. - -=head1 SEE ALSO - -L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>, -L<BIO_reset(3)|BIO_reset(3)>, L<BIO_flush(3)|BIO_flush(3)>, -L<BIO_read(3)|BIO_read(3)>, -L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>, -L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>, -L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)> diff --git a/crypto/openssl/doc/crypto/BIO_s_mem.pod b/crypto/openssl/doc/crypto/BIO_s_mem.pod deleted file mode 100644 index 19648acfae0f..000000000000 --- a/crypto/openssl/doc/crypto/BIO_s_mem.pod +++ /dev/null @@ -1,115 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf, -BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_s_mem(void); - - BIO_set_mem_eof_return(BIO *b,int v) - long BIO_get_mem_data(BIO *b, char **pp) - BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c) - BIO_get_mem_ptr(BIO *b,BUF_MEM **pp) - - BIO *BIO_new_mem_buf(void *buf, int len); - -=head1 DESCRIPTION - -BIO_s_mem() return the memory BIO method function. - -A memory BIO is a source/sink BIO which uses memory for its I/O. Data -written to a memory BIO is stored in a BUF_MEM structure which is extended -as appropriate to accommodate the stored data. - -Any data written to a memory BIO can be recalled by reading from it. -Unless the memory BIO is read only any data read from it is deleted from -the BIO. - -Memory BIOs support BIO_gets() and BIO_puts(). - -If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying -BUF_MEM structure is also freed. - -Calling BIO_reset() on a read write memory BIO clears any data in it. On a -read only BIO it restores the BIO to its original state and the read only -data can be read again. - -BIO_eof() is true if no data is in the BIO. - -BIO_ctrl_pending() returns the number of bytes currently stored. - -BIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is -empty. If the B<v> is zero then an empty memory BIO will return EOF (that is -it will return zero and BIO_should_retry(b) will be false. If B<v> is non -zero then it will return B<v> when it is empty and it will set the read retry -flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal -positive return value B<v> should be set to a negative value, typically -1. - -BIO_get_mem_data() sets B<pp> to a pointer to the start of the memory BIOs data -and returns the total amount of data available. It is implemented as a macro. - -BIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the -close flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE. -It is a macro. - -BIO_get_mem_ptr() places the underlying BUF_MEM structure in B<pp>. It is -a macro. - -BIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>, -if B<len> is -1 then the B<buf> is assumed to be null terminated and its -length is determined by B<strlen>. The BIO is set to a read only state and -as a result cannot be written to. This is useful when some data needs to be -made available from a static area of memory in the form of a BIO. The -supplied data is read directly from the supplied buffer: it is B<not> copied -first, so the supplied area of memory must be unchanged until the BIO is freed. - -=head1 NOTES - -Writes to memory BIOs will always succeed if memory is available: that is -their size can grow indefinitely. - -Every read from a read write memory BIO will remove the data just read with -an internal copy operation, if a BIO contains a lots of data and it is -read in small chunks the operation can be very slow. The use of a read only -memory BIO avoids this problem. If the BIO must be read write then adding -a buffering BIO to the chain will speed up the process. - -=head1 BUGS - -There should be an option to set the maximum size of a memory BIO. - -There should be a way to "rewind" a read write BIO without destroying -its contents. - -The copying operation should not occur after every small read of a large BIO -to improve efficiency. - -=head1 EXAMPLE - -Create a memory BIO and write some data to it: - - BIO *mem = BIO_new(BIO_s_mem()); - BIO_puts(mem, "Hello World\n"); - -Create a read only memory BIO: - - char data[] = "Hello World"; - BIO *mem; - mem = BIO_new_mem_buf(data, -1); - -Extract the BUF_MEM structure from a memory BIO and then free up the BIO: - - BUF_MEM *bptr; - BIO_get_mem_ptr(mem, &bptr); - BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */ - BIO_free(mem); - - -=head1 SEE ALSO - -TBA diff --git a/crypto/openssl/doc/crypto/BIO_s_null.pod b/crypto/openssl/doc/crypto/BIO_s_null.pod deleted file mode 100644 index e5514f723898..000000000000 --- a/crypto/openssl/doc/crypto/BIO_s_null.pod +++ /dev/null @@ -1,37 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_null - null data sink - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_s_null(void); - -=head1 DESCRIPTION - -BIO_s_null() returns the null sink BIO method. Data written to -the null sink is discarded, reads return EOF. - -=head1 NOTES - -A null sink BIO behaves in a similar manner to the Unix /dev/null -device. - -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 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 - -BIO_s_null() returns the null sink BIO method. - -=head1 SEE ALSO - -TBA diff --git a/crypto/openssl/doc/crypto/BIO_s_socket.pod b/crypto/openssl/doc/crypto/BIO_s_socket.pod deleted file mode 100644 index 253185185c7f..000000000000 --- a/crypto/openssl/doc/crypto/BIO_s_socket.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_socket, BIO_new_socket - socket BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_s_socket(void); - - #define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd) - #define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c) - - BIO *BIO_new_socket(int sock, int close_flag); - -=head1 DESCRIPTION - -BIO_s_socket() returns the socket BIO method. This is a wrapper -round the platform's socket routines. - -BIO_read() and BIO_write() read or write the underlying socket. -BIO_puts() is supported but BIO_gets() is not. - -If the close flag is set then the socket is shut down and closed -when the BIO is freed. - -BIO_set_fd() sets the socket of BIO B<b> to B<fd> and the close -flag to B<c>. - -BIO_get_fd() places the socket in B<c> if it is not NULL, it also -returns the socket . If B<c> is not NULL it should be of type (int *). - -BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>. - -=head1 NOTES - -Socket BIOs also support any relevant functionality of file descriptor -BIOs. - -The reason for having separate file descriptor and socket BIOs is that on some -platforms sockets are not file descriptors and use distinct I/O routines, -Windows is one such platform. Any code mixing the two will not work on -all platforms. - -=head1 RETURN VALUES - -BIO_s_socket() returns the socket BIO method. - -BIO_set_fd() always returns 1. - -BIO_get_fd() returns the socket or -1 if the BIO has not been -initialized. - -BIO_new_socket() returns the newly allocated BIO or NULL is an error -occurred. - -=head1 SEE ALSO - -TBA diff --git a/crypto/openssl/doc/crypto/BIO_set_callback.pod b/crypto/openssl/doc/crypto/BIO_set_callback.pod deleted file mode 100644 index 9b6961ca8d4a..000000000000 --- a/crypto/openssl/doc/crypto/BIO_set_callback.pod +++ /dev/null @@ -1,108 +0,0 @@ -=pod - -=head1 NAME - -BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, -BIO_debug_callback - BIO callback functions - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - #define BIO_set_callback(b,cb) ((b)->callback=(cb)) - #define BIO_get_callback(b) ((b)->callback) - #define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg)) - #define BIO_get_callback_arg(b) ((b)->cb_arg) - - long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi, - long argl,long ret); - - typedef long callback(BIO *b, int oper, const char *argp, - int argi, long argl, long retvalue); - -=head1 DESCRIPTION - -BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback, -they are both macros. The callback is called during most high level BIO -operations. It can be used for debugging purposes to trace operations on -a BIO or to modify its operation. - -BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be -used to set and retrieve an argument for use in the callback. - -BIO_debug_callback() is a standard debugging callback which prints -out information relating to each BIO operation. If the callback -argument is set if is interpreted as a BIO to send the information -to, otherwise stderr is used. - -callback() is the callback function itself. The meaning of each -argument is described below. - -The BIO the callback is attached to is passed in B<b>. - -B<oper> is set to the operation being performed. For some operations -the callback is called twice, once before and once after the actual -operation, the latter case has B<oper> or'ed with BIO_CB_RETURN. - -The meaning of the arguments B<argp>, B<argi> and B<argl> depends on -the value of B<oper>, that is the operation being performed. - -B<retvalue> is the return value that would be returned to the -application if no callback were present. The actual value returned -is the return value of the callback itself. In the case of callbacks -called before the actual BIO operation 1 is placed in retvalue, if -the return value is not positive it will be immediately returned to -the application and the BIO operation will not be performed. - -The callback should normally simply return B<retvalue> when it has -finished processing, unless if specifically wishes to modify the -value returned to the application. - -=head1 CALLBACK OPERATIONS - -=over 4 - -=item B<BIO_free(b)> - -callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the -free operation. - -=item B<BIO_read(b, out, outl)> - -callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before -the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue) -after. - -=item B<BIO_write(b, in, inl)> - -callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before -the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue) -after. - -=item B<BIO_gets(b, out, outl)> - -callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before -the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue) -after. - -=item B<BIO_puts(b, in)> - -callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before -the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue) -after. - -=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)> - -callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and -callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after. - -=back - -=head1 EXAMPLE - -The BIO_debug_callback() function is a good example, its source is -in crypto/bio/bio_cb.c - -=head1 SEE ALSO - -TBA diff --git a/crypto/openssl/doc/crypto/BIO_should_retry.pod b/crypto/openssl/doc/crypto/BIO_should_retry.pod deleted file mode 100644 index 539c3912728c..000000000000 --- a/crypto/openssl/doc/crypto/BIO_should_retry.pod +++ /dev/null @@ -1,114 +0,0 @@ -=pod - -=head1 NAME - -BIO_should_retry, BIO_should_read, BIO_should_write, -BIO_should_io_special, BIO_retry_type, BIO_should_retry, -BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - #define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ) - #define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE) - #define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL) - #define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS) - #define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY) - - #define BIO_FLAGS_READ 0x01 - #define BIO_FLAGS_WRITE 0x02 - #define BIO_FLAGS_IO_SPECIAL 0x04 - #define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL) - #define BIO_FLAGS_SHOULD_RETRY 0x08 - - BIO * BIO_get_retry_BIO(BIO *bio, int *reason); - int BIO_get_retry_reason(BIO *bio); - -=head1 DESCRIPTION - -These functions determine why a BIO is not able to read or write data. -They will typically be called after a failed BIO_read() or BIO_write() -call. - -BIO_should_retry() is true if the call that produced this condition -should then be retried at a later time. - -If BIO_should_retry() is false then the cause is an error condition. - -BIO_should_read() is true if the cause of the condition is that a BIO -needs to read data. - -BIO_should_write() is true if the cause of the condition is that a BIO -needs to read data. - -BIO_should_io_special() is true if some "special" condition, that is a -reason other than reading or writing is the cause of the condition. - -BIO_get_retry_reason() returns a mask of the cause of a retry condition -consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>, -B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of -these. - -BIO_get_retry_BIO() determines the precise reason for the special -condition, it returns the BIO that caused this condition and if -B<reason> is not NULL it contains the reason code. The meaning of -the reason code and the action that should be taken depends on -the type of BIO that resulted in this condition. - -BIO_get_retry_reason() returns the reason for a special condition if -passed the relevant BIO, for example as returned by BIO_get_retry_BIO(). - -=head1 NOTES - -If BIO_should_retry() returns false then the precise "error condition" -depends on the BIO type that caused it and the return code of the BIO -operation. For example if a call to BIO_read() on a socket BIO returns -0 and BIO_should_retry() is false then the cause will be that the -connection closed. A similar condition on a file BIO will mean that it -has reached EOF. Some BIO types may place additional information on -the error queue. For more details see the individual BIO type manual -pages. - -If the underlying I/O structure is in a blocking mode almost all current -BIO types will not request a retry, because the underlying I/O -calls will not. If the application knows that the BIO type will never -signal a retry then it need not call BIO_should_retry() after a failed -BIO I/O call. This is typically done with file BIOs. - -SSL BIOs are the only current exception to this rule: they can request a -retry even if the underlying I/O structure is blocking, if a handshake -occurs during a call to BIO_read(). An application can retry the failed -call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY -on the underlying SSL structure. - -While an application may retry a failed non blocking call immediately -this is likely to be very inefficient because the call will fail -repeatedly until data can be processed or is available. An application -will normally wait until the necessary condition is satisfied. How -this is done depends on the underlying I/O structure. - -For example if the cause is ultimately a socket and BIO_should_read() -is true then a call to select() may be made to wait until data is -available and then retry the BIO operation. By combining the retry -conditions of several non blocking BIOs in a single select() call -it is possible to service several BIOs in a single thread, though -the performance may be poor if SSL BIOs are present because long delays -can occur during the initial handshake process. - -It is possible for a BIO to block indefinitely if the underlying I/O -structure cannot process or return any data. This depends on the behaviour of -the platforms I/O functions. This is often not desirable: one solution -is to use non blocking I/O and use a timeout on the select() (or -equivalent) call. - -=head1 BUGS - -The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O: -that is they cannot retry after a partial read or write. This is usually -worked around by only passing the relevant data to ASN1 functions when -the entire structure can be read or written. - -=head1 SEE ALSO - -TBA diff --git a/crypto/openssl/doc/crypto/bio.pod b/crypto/openssl/doc/crypto/bio.pod deleted file mode 100644 index 24f61dfb5626..000000000000 --- a/crypto/openssl/doc/crypto/bio.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -bio - I/O abstraction - -=head1 SYNOPSIS - - #include <openssl/bio.h> - -TBA - - -=head1 DESCRIPTION - -A BIO is an I/O abstraction, it hides many of the underlying I/O -details from an application. If an application uses a BIO for its -I/O it can transparently handle SSL connections, unencrypted network -connections and file I/O. - -There are two type of BIO, a source/sink BIO and a filter BIO. - -As its name implies a source/sink BIO is a source and/or sink of data, -examples include a socket BIO and a file BIO. - -A filter BIO takes data from one BIO and passes it through to -another, or the application. The data may be left unmodified (for -example a message digest BIO) or translated (for example an -encryption BIO). The effect of a filter BIO may change according -to the I/O operation it is performing: for example an encryption -BIO will encrypt data if it is being written to and decrypt data -if it is being read from. - -BIOs can be joined together to form a chain (a single BIO is a chain -with one component). A chain normally consist of one source/sink -BIO and one or more filter BIOs. Data read from or written to the -first BIO then traverses the chain to the end (normally a source/sink -BIO). - -=head1 SEE ALSO - -L<BIO_ctrl(3)|BIO_ctrl(3)>, -L<BIO_f_base64(3)|BIO_f_base64(3)>, -L<BIO_f_cipher(3)|BIO_f_cipher(3)>, L<BIO_f_md(3)|BIO_f_md(3)>, -L<BIO_f_null(3)|BIO_f_null(3)>, L<BIO_f_ssl(3)|BIO_f_ssl(3)>, -L<BIO_find_type(3)|BIO_find_type(3)>, L<BIO_new(3)|BIO_new(3)>, -L<BIO_new_bio_pair(3)|BIO_new_bio_pair(3)>, -L<BIO_push(3)|BIO_push(3)>, L<BIO_read(3)|BIO_read(3)>, -L<BIO_s_accept(3)|BIO_s_accept(3)>, L<BIO_s_bio(3)|BIO_s_bio(3)>, -L<BIO_s_connect(3)|BIO_s_connect(3)>, L<BIO_s_fd(3)|BIO_s_fd(3)>, -L<BIO_s_file(3)|BIO_s_file(3)>, L<BIO_s_mem(3)|BIO_s_mem(3)>, -L<BIO_s_null(3)|BIO_s_null(3)>, L<BIO_s_socket(3)|BIO_s_socket(3)>, -L<BIO_set_callback(3)|BIO_set_callback(3)>, -L<BIO_should_retry(3)|BIO_should_retry(3)> diff --git a/crypto/openssl/doc/crypto/evp.pod b/crypto/openssl/doc/crypto/evp.pod deleted file mode 100644 index f089dd49a219..000000000000 --- a/crypto/openssl/doc/crypto/evp.pod +++ /dev/null @@ -1,37 +0,0 @@ -=pod - -=head1 NAME - -evp - high-level cryptographic functions - -=head1 SYNOPSIS - - #include <openssl/evp.h> - -=head1 DESCRIPTION - -The EVP library provided a high-level interface to cryptographic -functions. - -B<EVP_Seal>I<...> and B<EVP_Open>I<...> provide public key encryption -and decryption to implement digital "envelopes". - -The B<EVP_Sign>I<...> and B<EVP_Verify>I<...> functions implement -digital signatures. - -Symmetric encryption is available with the B<EVP_Encrypt>I<...> -functions. The B<EVP_Digest>I<...> functions provide message digests. - -Algorithms are loaded with OpenSSL_add_all_algorithms(3). - -=head1 SEE ALSO - -L<EVP_DigestInit(3)|EVP_DigestInit(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, -L<EVP_OpenInit(3)|EVP_OpenInit(3)>, -L<EVP_SealInit(3)|EVP_SealInit(3)>, -L<EVP_SignInit(3)|EVP_SignInit(3)>, -L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, -L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod b/crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod deleted file mode 100644 index 7fea14ee6867..000000000000 --- a/crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, -SSL_CIPHER_description - get SSL_CIPHER properties - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - const char *SSL_CIPHER_get_name(SSL_CIPHER *cipher); - int SSL_CIPHER_get_bits(SSL_CIPHER *cipher, int *alg_bits); - char *SSL_CIPHER_get_version(SSL_CIPHER *cipher); - char *SSL_CIPHER_description(SSL_CIPHER *cipher, char *buf, int size); - -=head1 DESCRIPTION - -SSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the -argument is the NULL pointer, a pointer to the constant value "NONE" is -returned. - -SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>. If -B<alg_bits> is not NULL, it contains the number of bits processed by the -chosen algorithm. If B<cipher> is NULL, 0 is returned. - -SSL_CIPHER_get_version() returns the protocol version for B<cipher>, currently -"SSLv2", "SSLv3", or "TLSv1". If B<cipher> is NULL, "(NONE)" is returned. - -SSL_CIPHER_description() returns a textual description of the cipher used -into the buffer B<buf> of length B<len> provided. B<len> must be at least -128 bytes, otherwise the string "Buffer too small" is returned. If B<buf> -is NULL, a buffer of 128 bytes is allocated using OPENSSL_malloc(). If the -allocation fails, the string "OPENSSL_malloc Error" is returned. - -=head1 NOTES - -The number of bits processed can be different from the secret bits. An -export cipher like e.g. EXP-RC4-MD5 has only 40 secret bits. The algorithm -does use the full 128 bits (which would be returned for B<alg_bits>), of -which however 88bits are fixed. The search space is hence only 40 bits. - -=head1 BUGS - -If SSL_CIPHER_description() is called with B<cipher> being NULL, the -library crashes. - -=head1 RETURN VALUES - -See DESCRIPTION - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_get_current_cipher(3)|SSL_get_current_cipher(3)>, -L<SSL_get_ciphers(3)|SSL_get_ciphers(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_free.pod b/crypto/openssl/doc/ssl/SSL_CTX_free.pod deleted file mode 100644 index de6967242220..000000000000 --- a/crypto/openssl/doc/ssl/SSL_CTX_free.pod +++ /dev/null @@ -1,29 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_free - free an allocated SSL_CTX object - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_free(SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_free() decrements the reference count of B<ctx>, and removes the -SSL_CTX object pointed to by B<ctx> and frees up the allocated memory if the -the reference count has reached 0. - -It also calls the free()ing procedures for indirectly affected items, if -applicable: the session cacahe, the list of ciphers, the list of Client CAs, -the certificates and keys. - -=head1 RETURN VALUES - -SSL_CTX_free() does not provide diagnostic information. - -L<SSL_CTX_new(3)|SSL_CTX_new(3)>, L<ssl(3)|ssl(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_new.pod b/crypto/openssl/doc/ssl/SSL_CTX_new.pod deleted file mode 100644 index e166c692c355..000000000000 --- a/crypto/openssl/doc/ssl/SSL_CTX_new.pod +++ /dev/null @@ -1,93 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_new - create a new SSL_CTX object as framework for TLS/SSL enabled functions - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - SSL_CTX *SSL_CTX_new(SSL_METHOD *method); - -=head1 DESCRIPTION - -SSL_CTX_new() creates a new B<SSL_CTX> object as framework to establish -TLS/SSL enabled connections. - -=head1 NOTES - -The SSL_CTX object uses B<method> as connection method. The methods exist -in a generic type (for client and server use), a server only type, and a -client only type. B<method> can be of the following types: - -=over 4 - -=item SSLv2_method(void), SSLv2_server_method(void), SSLv2_client_method(void) - -A TLS/SSL connection established with these methods will only understand -the SSLv2 protocol. A client will send out SSLv2 client hello messages -and will also indicate that it only understand SSLv2. A server will only -understand SSLv2 client hello messages. - -=item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void) - -A TLS/SSL connection established with these methods will only understand the -SSLv3 and TLSv1 protocol. A client will send out SSLv3 client hello messages -and will indicate that it also understands TLSv1. A server will only understand -SSLv3 and TLSv1 client hello messages. This especially means, that it will -not understand SSLv2 client hello messages which are widely used for -compatibility reasons, see SSLv23_*_method(). - -=item TLSv1_method(void), TLSv1_server_method(void), TLSv1_client_method(void) - -A TLS/SSL connection established with these methods will only understand the -TLSv1 protocol. A client will send out TLSv1 client hello messages -and will indicate that it only understands TLSv1. A server will only understand -TLSv1 client hello messages. This especially means, that it will -not understand SSLv2 client hello messages which are widely used for -compatibility reasons, see SSLv23_*_method(). - -=item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void) - -A TLS/SSL connection established with these methods will understand the SSLv2, -SSLv3, and TLSv1 protocol. A client will send out SSLv2 client hello messages -and will indicate that it also understands SSLv3 and TLSv1. A server will -understand SSLv2, SSLv3, and TLSv1 client hello messages. This is the best -choice when compatibility is a concern. - -=back - -The list of protocols available can later be limited using the SSL_OP_NO_SSLv2, -SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1 options of the B<SSL_CTX_set_options()> or -B<SSL_set_options()> functions. Using these options it is possible to choose -e.g. SSLv23_server_method() and be able to negotiate with all possible -clients, but to only allow newer protocols like SSLv3 or TLSv1. - -SSL_CTX_new() initializes the list of ciphers, the session cache setting, -the callbacks, the keys and certificates, and the options to its default -values. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -The creation of a new SSL_CTX object failed. Check the error stack to -find out the reason. - -=item Pointer to an SSL_CTX object - -The return value points to an allocated SSL_CTX object. - -=back - -=head1 SEE ALSO - -L<SSL_CTX_free(3)|SSL_CTX_free(3)>, L<SSL_accept(3)|SSL_accept(3)>, -L<ssl(3)|ssl(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod deleted file mode 100644 index 272d6b3de282..000000000000 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod +++ /dev/null @@ -1,52 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_cipher_list, SSL_set_cipher_list -- choose list of available SSL_CIPHERs - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str); - int SSL_set_cipher_list(SSL *ssl, const char *str); - -=head1 DESCRIPTION - -SSL_CTX_set_cipher_list() sets the list of available ciphers for B<ctx> -using the control string B<str>. The format of the string is described -in L<ciphers(1)|ciphers(1)>. The list of ciphers is inherited by all -B<ssl> objects created from B<ctx>. - -SSL_set_cipher_list() sets the list of ciphers only for B<ssl>. - -=head1 NOTES - -The control string B<str> should be universally usable and not depend -on details of the library configuration (ciphers compiled in). Thus no -syntax checking takes place. Items that are not recognized, because the -corresponding ciphers are not compiled in or because they are mistyped, -are simply ignored. Failure is only flagged if no ciphers could be collected -at all. - -It should be noted, that inclusion of a cipher to be used into the list is -a necessary condition. On the client side, the inclusion into the list is -also sufficient. On the server side, additional restrictions apply. All ciphers -have additional requirements. ADH ciphers don't need a certificate, but -DH-parameters must have been set. All other ciphers need a corresponding -certificate and key. A RSA cipher can only be chosen, when a RSA certificate is -available, the respective is valid for DSA ciphers. Ciphers using EDH need -a certificate and key and DH-parameters. - -=head1 RETURN VALUES - -SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher -could be selected and 0 on complete failure. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, -L<ciphers(1)|ciphers(1)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod deleted file mode 100644 index 3091bd6895f8..000000000000 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_ssl_version, SSL_set_ssl_method, SSL_get_ssl_method -- choose a new TLS/SSL method - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_set_ssl_version(SSL_CTX *ctx, SSL_METHOD *method); - int SSL_set_ssl_method(SSL *s, SSL_METHOD *method); - SSL_METHOD *SSL_get_ssl_method(SSL *ssl); - -=head1 DESCRIPTION - -SSL_CTX_set_ssl_version() sets a new default TLS/SSL B<method> for SSL objects -newly created from this B<ctx>. SSL objects already created with -L<SSL_new(3)|SSL_new(3)> are not affected, except when SSL_clear() is -being called. - -SSL_set_ssl_method() sets a new TLS/SSL B<method> for a particular B<ssl> -object. It may be reset, when SSL_clear() is called. - -SSL_get_ssl_method() returns a function pointer to the TLS/SSL method -set in B<ssl>. - -=head1 NOTES - -The available B<method> choices are described in -L<SSL_CTX_new(3)|SSL_CTX_new(3)>. - -When SSL_clear() is called and no session is connected to an SSL object, -the method of the SSL object is reset to the method currently set in -the corresponding SSL_CTX object. - -=head1 RETURN VALUES - -The following return values can occur for SSL_CTX_set_ssl_version() -and SSL_set_ssl_method(): - -=over 4 - -=item 0 - -The new choice failed, check the error stack to find out the reason. - -=item 1 - -The operation succeeded. - -=back - -=head1 SEE ALSO - -L<SSL_CTX_new(3)|SSL_CTX_new(3)>, L<SSL_new(3)|SSL_new(3)>, -L<SSL_clear(3)|SSL_clear(3)>, L<ssl(3)|ssl(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_SESSION_free.pod b/crypto/openssl/doc/ssl/SSL_SESSION_free.pod deleted file mode 100644 index df30ccbb320f..000000000000 --- a/crypto/openssl/doc/ssl/SSL_SESSION_free.pod +++ /dev/null @@ -1,25 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_free - free an allocated SSL_SESSION structure - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_SESSION_free(SSL_SESSION *session); - -=head1 DESCRIPTION - -SSL_SESSION_free() decrements the reference count of B<session> and removes -the B<SSL_SESSION> structure pointed to by B<session> and frees up the allocated -memory, if the the reference count has reached 0. - -=head1 RETURN VALUES - -SSL_SESSION_free() does not provide diagnostic information. - -L<ssl(3)|ssl(3)>, L<SSL_get_session(3)|SSL_get_session(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_accept.pod b/crypto/openssl/doc/ssl/SSL_accept.pod deleted file mode 100644 index 0c79ac515e1d..000000000000 --- a/crypto/openssl/doc/ssl/SSL_accept.pod +++ /dev/null @@ -1,72 +0,0 @@ -=pod - -=head1 NAME - -SSL_accept - wait for a TLS/SSL client to initiate a TLS/SSL handshake - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_accept(SSL *ssl); - -=head1 DESCRIPTION - -SSL_accept() waits for a TLS/SSL client to initiate the TLS/SSL handshake. -The communication channel must already have been set and assigned to the -B<ssl> by setting an underlying B<BIO>. - -=head1 NOTES - -The behaviour of SSL_accept() depends on the underlying BIO. - -If the underlying BIO is B<blocking>, SSL_accept() will only return once the -handshake has been finished or an error occurred, except for SGC (Server -Gated Cryptography). For SGC, SSL_accept() may return with -1, but -SSL_get_error() will yield B<SSL_ERROR_WANT_READ/WRITE> and SSL_accept() -should be called again. - -If the underlying BIO is B<non-blocking>, SSL_accept() will also return -when the underlying BIO could not satisfy the needs of SSL_accept() -to continue the handshake. In this case a call to SSL_get_error() with the -return value of SSL_accept() will yield B<SSL_ERROR_WANT_READ> or -B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after -taking appropriate action to satisfy the needs of SSL_accept(). -The action depends on the underlying BIO. When using a non-blocking socket, -nothing is to be done, but select() can be used to check for the required -condition. When using a buffering BIO, like a BIO pair, data must be written -into or retrieved out of the BIO before being able to continue. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item 1 - -The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been -established. - -=item 0 - -The TLS/SSL handshake was not successful but was shut down controlled and -by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the -return value B<ret> to find out the reason. - -=item -1 - -The TLS/SSL handshake was not successful because a fatal error occurred either -at the protocol level or a connection failure occurred. The shutdown was -not clean. It can also occur of action is need to continue the operation -for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> -to find out the reason. - -=back - -=head1 SEE ALSO - -L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, -L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_clear.pod b/crypto/openssl/doc/ssl/SSL_clear.pod deleted file mode 100644 index 862fd8291df1..000000000000 --- a/crypto/openssl/doc/ssl/SSL_clear.pod +++ /dev/null @@ -1,39 +0,0 @@ -=pod - -=head1 NAME - -SSL_clear - reset SSL object to allow another connection - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_clear(SSL *ssl); - -=head1 DESCRIPTION - -Reset B<ssl> to allow another connection. All settings (method, ciphers, -BIOs) are kept. A completely negotiated B<SSL_SESSION> is not freed but left -untouched for the underlying B<SSL_CTX>. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item 0 - -The SSL_clear() operation could not be performed. Check the error stack to -find out the reason. - -=item 1 - -The SSL_clear() operation was successful. - -=back - -L<SSL_new(3)|SSL_new(3)>, L<SSL_free(3)|SSL_free(3)>, -L<ssl(3)|ssl(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_connect.pod b/crypto/openssl/doc/ssl/SSL_connect.pod deleted file mode 100644 index debe41744f0a..000000000000 --- a/crypto/openssl/doc/ssl/SSL_connect.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=head1 NAME - -SSL_connect - initiate the TLS/SSL handshake with an TLS/SSL server - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_connect(SSL *ssl); - -=head1 DESCRIPTION - -SSL_connect() initiates the TLS/SSL handshake with a server. The communication -channel must already have been set and assigned to the B<ssl> by setting an -underlying B<BIO>. - -=head1 NOTES - -The behaviour of SSL_connect() depends on the underlying BIO. - -If the underlying BIO is B<blocking>, SSL_connect() will only return once the -handshake has been finished or an error occurred. - -If the underlying BIO is B<non-blocking>, SSL_connect() will also return -when the underlying BIO could not satisfy the needs of SSL_connect() -to continue the handshake. In this case a call to SSL_get_error() with the -return value of SSL_connect() will yield B<SSL_ERROR_WANT_READ> or -B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after -taking appropriate action to satisfy the needs of SSL_connect(). -The action depends on the underlying BIO. When using a non-blocking socket, -nothing is to be done, but select() can be used to check for the required -condition. When using a buffering BIO, like a BIO pair, data must be written -into or retrieved out of the BIO before being able to continue. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item 1 - -The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been -established. - -=item 0 - -The TLS/SSL handshake was not successful but was shut down controlled and -by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the -return value B<ret> to find out the reason. - -=item -1 - -The TLS/SSL handshake was not successful, because a fatal error occurred either -at the protocol level or a connection failure occurred. The shutdown was -not clean. It can also occur of action is need to continue the operation -for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> -to find out the reason. - -=back - -=head1 SEE ALSO - -L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_accept(3)|SSL_accept(3)>, -L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_free.pod b/crypto/openssl/doc/ssl/SSL_free.pod deleted file mode 100644 index f3f0c345f8a1..000000000000 --- a/crypto/openssl/doc/ssl/SSL_free.pod +++ /dev/null @@ -1,33 +0,0 @@ -=pod - -=head1 NAME - -SSL_free - free an allocated SSL structure - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_free(SSL *ssl); - -=head1 DESCRIPTION - -SSL_free() decrements the reference count of B<ssl>, and removes the SSL -structure pointed to by B<ssl> and frees up the allocated memory if the -the reference count has reached 0. - -It also calls the free()ing procedures for indirectly affected items, if -applicable: the buffering BIO, the read and write BIOs, -cipher lists specially created for this B<ssl>, the B<SSL_SESSION>. -Do not explicitly free these indirectly freed up items before or after -calling SSL_free(), as trying to free things twice may lead to program -failure. - -=head1 RETURN VALUES - -SSL_free() does not provide diagnostic information. - -L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, -L<ssl(3)|ssl(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_get_ciphers.pod b/crypto/openssl/doc/ssl/SSL_get_ciphers.pod deleted file mode 100644 index 2a57455c235d..000000000000 --- a/crypto/openssl/doc/ssl/SSL_get_ciphers.pod +++ /dev/null @@ -1,42 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_ciphers, SSL_get_cipher_list - get list of available SSL_CIPHERs - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - STACK_OF(SSL_CIPHER) *SSL_get_ciphers(SSL *ssl); - const char *SSL_get_cipher_list(SSL *ssl, int priority); - -=head1 DESCRIPTION - -SSL_get_ciphers() returns the stack of available SSL_CIPHERs for B<ssl>, -sorted by preference. If B<ssl> is NULL or no ciphers are available, NULL -is returned. - -SSL_get_cipher_list() returns a pointer to the name of the SSL_CIPHER -listed for B<ssl> with B<priority>. If B<ssl> is NULL, no ciphers are -available, or there are less ciphers than B<priority> available, NULL -is returned. - -=head1 NOTES - -The details of the ciphers obtained by SSL_get_ciphers() can be obtained using -the L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> family of functions. - -Call SSL_get_cipher_list() with B<priority> starting from 0 to obtain the -sorted list of available ciphers, until NULL is returned. - -=head1 RETURN VALUES - -See DESCRIPTION - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, -L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_get_current_cipher.pod b/crypto/openssl/doc/ssl/SSL_get_current_cipher.pod deleted file mode 100644 index 2dd7261d89dc..000000000000 --- a/crypto/openssl/doc/ssl/SSL_get_current_cipher.pod +++ /dev/null @@ -1,43 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_current_cipher, SSL_get_cipher, SSL_get_cipher_name, -SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - SSL_CIPHER *SSL_get_current_cipher(SSL *ssl); - #define SSL_get_cipher(s) \ - SSL_CIPHER_get_name(SSL_get_current_cipher(s)) - #define SSL_get_cipher_name(s) \ - SSL_CIPHER_get_name(SSL_get_current_cipher(s)) - #define SSL_get_cipher_bits(s,np) \ - SSL_CIPHER_get_bits(SSL_get_current_cipher(s),np) - #define SSL_get_cipher_version(s) \ - SSL_CIPHER_get_version(SSL_get_current_cipher(s)) - -=head1 DESCRIPTION - -SSL_get_current_cipher() returns a pointer to an SSL_CIPHER object containing -the description of the actually used cipher of a connection established with -the B<ssl> object. - -SSL_get_cipher() and SSL_get_cipher_name() are identical macros to obtain the -name of the currently used cipher. SSL_get_cipher_bits() is a -macro to obtain the number of secret/algorithm bits used and -SSL_get_cipher_version() returns the protocol name. -See L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> for more details. - -=head1 RETURN VALUES - -SSL_get_current_cipher() returns the cipher actually used or NULL, when -no session has been established. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_get_fd.pod b/crypto/openssl/doc/ssl/SSL_get_fd.pod deleted file mode 100644 index a3f76259316f..000000000000 --- a/crypto/openssl/doc/ssl/SSL_get_fd.pod +++ /dev/null @@ -1,44 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_fd - get file descriptor linked to an SSL object - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_get_fd(SSL *ssl); - int SSL_get_rfd(SSL *ssl); - int SSL_get_wfd(SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_fd() returns the file descriptor which is linked to B<ssl>. -SSL_get_rfd() and SSL_get_wfd() return the file descriptors for the -read or the write channel, which can be different. If the read and the -write channel are different, SSL_get_fd() will return the file descriptor -of the read channel. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item -1 - -The operation failed, because the underlying BIO is not of the correct type -(suitable for file descriptors). - -=item E<gt>=0 - -The file descriptor linked to B<ssl>. - -=back - -=head1 SEE ALSO - -L<SSL_set_fd(3)|SSL_set_fd(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_get_peer_cert_chain.pod b/crypto/openssl/doc/ssl/SSL_get_peer_cert_chain.pod deleted file mode 100644 index e93e8206faf5..000000000000 --- a/crypto/openssl/doc/ssl/SSL_get_peer_cert_chain.pod +++ /dev/null @@ -1,52 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_peer_cert_chain - get the X509 certificate chain of the peer - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - STACKOF(X509) *SSL_get_peer_cert_chain(SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_peer_cert_chain() returns a pointer to STACKOF(X509) certificates -forming the certificate chain of the peer. If called on the client side, -the stack also contains the peer's certificate; if called on the server -side, the peer's certificate must be obtained seperately using -L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>. -If the peer did not present a certificate, NULL is returned. - -=head1 NOTES - -The peer certificate chain is not necessarily available after reusing -a session, in which case a NULL pointer is returned. - -The reference count of the STACKOF(X509) object is not incremented. -If the corresponding session is freed, the pointer must not be used -any longer. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -No certificate was presented by the peer or no connection was established -or the certificate chain is no longer available when a session is reused. - -=item Pointer to a STACKOF(X509) - -The return value points to the certificate chain presented by the peer. - -=back - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_get_peer_certificate.pod b/crypto/openssl/doc/ssl/SSL_get_peer_certificate.pod deleted file mode 100644 index 79c089aa5172..000000000000 --- a/crypto/openssl/doc/ssl/SSL_get_peer_certificate.pod +++ /dev/null @@ -1,48 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_peer_certificate - get the X509 certificate of the peer - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - X509 *SSL_get_peer_certificate(SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_peer_certificate() returns a pointer to the X509 certificate the -peer presented. If the peer did not present a certificate, NULL is returned. - -=head1 NOTES - -That a certificate is returned does not indicate information about the -verification state, use L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> -to check the verification state. - -The reference count of the X509 object is incremented by one, so that it -will not be destroyed when the session containing the peer certificate is -freed. The X509 object must be explicitely freed using X509_free(). - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -No certificate was presented by the peer or no connection was established. - -=item Pointer to an X509 certificate - -The return value points to the certificate presented by the peer. - -=back - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_get_rbio.pod b/crypto/openssl/doc/ssl/SSL_get_rbio.pod deleted file mode 100644 index 3d98233cacee..000000000000 --- a/crypto/openssl/doc/ssl/SSL_get_rbio.pod +++ /dev/null @@ -1,40 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_rbio - get BIO linked to an SSL object - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - BIO *SSL_get_rbio(SSL *ssl); - BIO *SSL_get_wbio(SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_rbio() and SSL_get_wbio() return pointers to the BIOs for the -read or the write channel, which can be different. The reference count -of the BIO is not incremented. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -No BIO was connected to the SSL object - -=item Any other pointer - -The BIO linked to B<ssl>. - -=back - -=head1 SEE ALSO - -L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_get_session.pod b/crypto/openssl/doc/ssl/SSL_get_session.pod deleted file mode 100644 index aff41fb9cf62..000000000000 --- a/crypto/openssl/doc/ssl/SSL_get_session.pod +++ /dev/null @@ -1,48 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_session - retrieve TLS/SSL session data - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - SSL_SESSION *SSL_get_session(SSL *ssl); - SSL_SESSION *SSL_get0_session(SSL *ssl); - SSL_SESSION *SSL_get1_session(SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_session() returns a pointer to the B<SSL_SESSION> actually used in -B<ssl>. The reference count of the B<SSL_SESSION> is not incremented, so -that the pointer can become invalid when the B<ssl> is freed and -SSL_SESSION_free() is implicitly called. - -SSL_get0_session() is the same as SSL_get_session(). - -SSL_get1_session() is the same as SSL_get_session(), but the reference -count of the B<SSL_SESSION> is incremented by one. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -There is no session available in B<ssl>. - -=item Pointer to an SSL - -The return value points to the data of an SSL session. - -=back - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_free(3)|SSL_free(3)>, -L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_get_verify_result.pod b/crypto/openssl/doc/ssl/SSL_get_verify_result.pod deleted file mode 100644 index 4d66236a05ea..000000000000 --- a/crypto/openssl/doc/ssl/SSL_get_verify_result.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_verify_result - get result of peer certificate verification - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - long SSL_get_verify_result(SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_verify_result() returns the result of the verification of the -X509 certificate presented by the peer, if any. - -=head1 NOTES - -SSL_get_verify_result() can only return one error code while the verification -of a certificate can fail because of many reasons at the same time. Only -the last verification error that occured during the processing is available -from SSL_get_verify_result(). - -The verification result is part of the established session and is restored -when a session is reused. - -=head1 BUGS - -If no peer certificate was presented, the returned result code is -X509_V_OK. This is because no verification error occured, it does however -not indicate success. SSL_get_verify_result() is only useful in connection -with L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>. - -=head1 RETURN VALUES - -The following return values can currently occur: - -=over 4 - -=item X509_V_OK - -The verification succeeded or no peer certificate was presented. - -=item Any other value - -Documented in L<verify(1)|verify(1)>. - -=back - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_set_verify_result(3)|SSL_set_verify_result(3)>, -L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, -L<verify(1)|verify(1)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_library_init.pod b/crypto/openssl/doc/ssl/SSL_library_init.pod deleted file mode 100644 index ecf3c4858e52..000000000000 --- a/crypto/openssl/doc/ssl/SSL_library_init.pod +++ /dev/null @@ -1,52 +0,0 @@ -=pod - -=head1 NAME - -SSL_library_init, OpenSSL_add_ssl_algorithms, SSLeay_add_ssl_algorithms -- initialize SSL library by registering algorithms - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_library_init(void); - #define OpenSSL_add_ssl_algorithms() SSL_library_init() - #define SSLeay_add_ssl_algorithms() SSL_library_init() - -=head1 DESCRIPTION - -SSL_library_init() registers the available ciphers and digests. - -OpenSSL_add_ssl_algorithms() and SSLeay_add_ssl_algorithms() are synonyms -for SSL_library_init(). - -=head1 NOTES - -SSL_library_init() must be called before any other action takes place. - -=head1 WARNING - -SSL_library_init() only registers ciphers. Another important initialization -is the seeding of the PRNG (Pseudo Random Number Generator), which has to -be performed separately. - -=head1 EXAMPLES - -A typical TLS/SSL application will start with the library initialization, -will provide readable error messages and will seed the PRNG. - - SSL_load_error_strings(); /* readable error messages */ - SSL_library_init(); /* initialize library */ - actions_to_seed_PRNG(); - -=head1 RETURN VALUES - -SSL_library_init() always returns "1", so it is safe to discard the return -value. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>, -L<RAND_add(3)|RAND_add(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_new.pod b/crypto/openssl/doc/ssl/SSL_new.pod deleted file mode 100644 index 8e8638fa9561..000000000000 --- a/crypto/openssl/doc/ssl/SSL_new.pod +++ /dev/null @@ -1,42 +0,0 @@ -=pod - -=head1 NAME - -SSL_new - create a new SSL structure for a connection - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - SSL *SSL_new(SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_new() creates a new B<SSL> structure which is needed to hold the -data for a TLS/SSL connection. The new structure inherits the settings -of the underlying context B<ctx>: connection method (SSLv2/v3/TLSv1), -options, verification settings, timeout settings. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -The creation of a new SSL structure failed. Check the error stack to -find out the reason. - -=item Pointer to an SSL structure - -The return value points to an allocated SSL structure. - -=back - -=head1 SEE ALSO - -L<SSL_free(3)|SSL_free(3)>, L<SSL_clear(3)|SSL_clear(3)>, -L<ssl(3)|ssl(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_pending.pod b/crypto/openssl/doc/ssl/SSL_pending.pod deleted file mode 100644 index 744e1855e151..000000000000 --- a/crypto/openssl/doc/ssl/SSL_pending.pod +++ /dev/null @@ -1,30 +0,0 @@ -=pod - -=head1 NAME - -SSL_pending - obtain number of readable bytes buffered in an SSL object - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_pending(SSL *ssl); - -=head1 DESCRIPTION - -SSL_pending() returns the number of bytes which are available inside -B<ssl> for immediate read. - -=head1 NOTES - -Data are received in blocks from the peer. Therefore data can be buffered -inside B<ssl> and are ready for immediate retrieval with -L<SSL_read(3)|SSL_read(3)>. - -=head1 RETURN VALUES - -The number of bytes pending is returned. - -L<SSL_read(3)|SSL_read(3)>, L<ssl(3)|ssl(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_read.pod b/crypto/openssl/doc/ssl/SSL_read.pod deleted file mode 100644 index 072dc26cf284..000000000000 --- a/crypto/openssl/doc/ssl/SSL_read.pod +++ /dev/null @@ -1,77 +0,0 @@ -=pod - -=head1 NAME - -SSL_read - read bytes from a TLS/SSL connection. - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_read(SSL *ssl, char *buf, int num); - -=head1 DESCRIPTION - -SSL_read() tries to read B<num> bytes from the specified B<ssl> into the -buffer B<buf>. - -=head1 NOTES - -If necessary, SSL_read() will negotiate a TLS/SSL session, if -not already explicitly performed by SSL_connect() or SSL_accept(). If the -peer requests a re-negotiation, it will be performed transparently during -the SSL_read() operation. The behaviour of SSL_read() depends on the -underlying BIO. - -If the underlying BIO is B<blocking>, SSL_read() will only return, once the -read operation has been finished or an error occurred. - -If the underlying BIO is B<non-blocking>, SSL_read() will also return -when the underlying BIO could not satisfy the needs of SSL_read() -to continue the operation. In this case a call to SSL_get_error() with the -return value of SSL_read() will yield B<SSL_ERROR_WANT_READ> or -B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a -call to SSL_read() can also cause write operations! The calling process -then must repeat the call after taking appropriate action to satisfy the -needs of SSL_read(). The action depends on the underlying BIO. When using a -non-blocking socket, nothing is to be done, but select() can be used to check -for the required condition. When using a buffering BIO, like a BIO pair, data -must be written into or retrieved out of the BIO before being able to continue. - -=head1 WARNING - -When an SSL_read() operation has to be repeated because of -B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated -with the same arguments. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item E<gt>0 - -The read operation was successful; the return value is the number of -bytes actually read from the TLS/SSL connection. - -=item 0 - -The read operation was not successful, probably because no data was -available. Call SSL_get_error() with the return value B<ret> to find out, -whether an error occurred. - -=item -1 - -The read operation was not successful, because either an error occurred -or action must be taken by the calling process. Call SSL_get_error() with the -return value B<ret> to find out the reason. - -=back - -=head1 SEE ALSO - -L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>, -L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_set_bio.pod b/crypto/openssl/doc/ssl/SSL_set_bio.pod deleted file mode 100644 index 67c9756d3fe5..000000000000 --- a/crypto/openssl/doc/ssl/SSL_set_bio.pod +++ /dev/null @@ -1,34 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_bio - connect the SSL object with a BIO - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio); - -=head1 DESCRIPTION - -SSL_set_bio() connects the BIOs B<rbio> and B<wbio> for the read and write -operations of the TLS/SSL (encrypted) side of B<ssl>. - -The SSL engine inherits the behaviour of B<rbio> and B<wbio>, respectively. -If a BIO is non-blocking, the B<ssl> will also have non-blocking behaviour. - -If there was already a BIO connected to B<ssl>, BIO_free() will be called -(for both the reading and writing side, if different). - -=head1 RETURN VALUES - -SSL_set_bio() cannot fail. - -=head1 SEE ALSO - -L<SSL_get_rbio(3)|SSL_get_rbio(3)>, -L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>, -L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_set_fd.pod b/crypto/openssl/doc/ssl/SSL_set_fd.pod deleted file mode 100644 index 70291128fcec..000000000000 --- a/crypto/openssl/doc/ssl/SSL_set_fd.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_fd - connect the SSL object with a file descriptor - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_set_fd(SSL *ssl, int fd); - int SSL_set_rfd(SSL *ssl, int fd); - int SSL_set_wfd(SSL *ssl, int fd); - -=head1 DESCRIPTION - -SSL_set_fd() sets the file descriptor B<fd> as the input/output facility -for the TLS/SSL (encrypted) side of B<ssl>. B<fd> will typically be the -socket file descriptor of a network connection. - -When performing the operation, a B<socket BIO> is automatically created to -interface between the B<ssl> and B<fd>. The BIO and hence the SSL engine -inherit the behaviour of B<fd>. If B<fd> is non-blocking, the B<ssl> will -also have non-blocking behaviour. - -If there was already a BIO connected to B<ssl>, BIO_free() will be called -(for both the reading and writing side, if different). - -SSL_set_rfd() and SSL_set_wfd() perform the respective action, but only -for the read channel or the write channel, which can be set independently. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item 0 - -The operation failed. Check the error stack to find out why. - -=item 1 - -The operation succeeded. - -=back - -=head1 SEE ALSO - -L<SSL_get_fd(3)|SSL_get_fd(3)>, L<SSL_set_bio(3)|SSL_set_bio(3)>, -L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>, -L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_set_session.pod b/crypto/openssl/doc/ssl/SSL_set_session.pod deleted file mode 100644 index 9f78d9e434ae..000000000000 --- a/crypto/openssl/doc/ssl/SSL_set_session.pod +++ /dev/null @@ -1,45 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_session - set a TLS/SSL session to be used during TLS/SSL connect - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_set_session(SSL *ssl, SSL_SESSION *session); - -=head1 DESCRIPTION - -SSL_set_session() sets B<session> to be used when the TLS/SSL connection -is to be established. SSL_set_session() is only useful for TLS/SSL clients. -When the session is set, the reference count of B<session> is incremented -by 1. If the session is not reused, the reference count is decremented -again during SSL_connect(). - -If there is already a session set inside B<ssl> (because it was set with -SSL_set_session() before or because the same B<ssl> was already used for -a connection), SSL_SESSION_free() will be called for that session. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item 0 - -The operation failed; check the error stack to find out the reason. - -=item 1 - -The operation succeeded. - -=back - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_set_verify_result.pod b/crypto/openssl/doc/ssl/SSL_set_verify_result.pod deleted file mode 100644 index 04ab101aad2e..000000000000 --- a/crypto/openssl/doc/ssl/SSL_set_verify_result.pod +++ /dev/null @@ -1,38 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_verify_result - override result of peer certificate verification - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_set_verify_result(SSL *ssl, long verify_result); - -=head1 DESCRIPTION - -SSL_set_verify_result() sets B<verify_result> of the object B<ssl> to be the -result of the verification of the X509 certificate presented by the peer, -if any. - -=head1 NOTES - -SSL_set_verify_result() overrides the verification result. It only changes -the verification result of the B<ssl> object. It does not become part of the -established session, so if the session is to be reused later, the original -value will reappear. - -The valid codes for B<verify_result> are documented in L<verify(1)|verify(1)>. - -=head1 RETURN VALUES - -SSL_set_verify_result() does not provide a return value. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, -L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, -L<verify(1)|verify(1)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_shutdown.pod b/crypto/openssl/doc/ssl/SSL_shutdown.pod deleted file mode 100644 index 20e273bd4d58..000000000000 --- a/crypto/openssl/doc/ssl/SSL_shutdown.pod +++ /dev/null @@ -1,62 +0,0 @@ -=pod - -=head1 NAME - -SSL_shutdown - shut down a TLS/SSL connection - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_shutdown(SSL *ssl); - -=head1 DESCRIPTION - -SSL_shutdown() shuts down an active TLS/SSL connection. It sends the shutdown -alert to the peer. The behaviour of SSL_shutdown() depends on the underlying -BIO. - -If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the -handshake has been finished or an error occurred. - -If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return -when the underlying BIO could not satisfy the needs of SSL_shutdown() -to continue the handshake. In this case a call to SSL_get_error() with the -return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or -B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after -taking appropriate action to satisfy the needs of SSL_shutdown(). -The action depends on the underlying BIO. When using a non-blocking socket, -nothing is to be done, but select() can be used to check for the required -condition. When using a buffering BIO, like a BIO pair, data must be written -into or retrieved out of the BIO before being able to continue. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item 1 - -The shutdown was successfully completed. - -=item 0 - -The shutdown was not successful. Call SSL_get_error() with the return -value B<ret> to find out the reason. - -=item -1 - -The shutdown was not successful because a fatal error occurred either -at the protocol level or a connection failure occurred. It can also occur of -action is need to continue the operation for non-blocking BIOs. -Call SSL_get_error() with the return value B<ret> to find out the reason. - -=back - -=head1 SEE ALSO - -L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, -L<SSL_accept(3)|SSL_accept(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> - -=cut diff --git a/crypto/openssl/doc/ssl/SSL_write.pod b/crypto/openssl/doc/ssl/SSL_write.pod deleted file mode 100644 index db67c187e0ee..000000000000 --- a/crypto/openssl/doc/ssl/SSL_write.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -SSL_read - write bytes to a TLS/SSL connection. - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_write(SSL *ssl, char *buf, int num); - -=head1 DESCRIPTION - -SSL_write() writes B<num> bytes from the buffer B<buf> into the specified -B<ssl> connection. - -=head1 NOTES - -If necessary, SSL_write() will negotiate a TLS/SSL session, if -not already explicitly performed by SSL_connect() or SSL_accept(). If the -peer requests a re-negotiation, it will be performed transparently during -the SSL_write() operation. The behaviour of SSL_write() depends on the -underlying BIO. - -If the underlying BIO is B<blocking>, SSL_write() will only return, once the -write operation has been finished or an error occurred. - -If the underlying BIO is B<non-blocking>, SSL_write() will also return, -when the underlying BIO could not satisfy the needs of SSL_write() -to continue the operation. In this case a call to SSL_get_error() with the -return value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or -B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a -call to SSL_write() can also cause write operations! The calling process -then must repeat the call after taking appropriate action to satisfy the -needs of SSL_write(). The action depends on the underlying BIO. When using a -non-blocking socket, nothing is to be done, but select() can be used to check -for the required condition. When using a buffering BIO, like a BIO pair, data -must be written into or retrieved out of the BIO before being able to continue. - -=head1 WARNING - -When an SSL_write() operation has to be repeated because of -B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated -with the same arguments. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item E<gt>0 - -The write operation was successful, the return value is the number of -bytes actually written to the TLS/SSL connection. - -=item 0 - -The write operation was not successful. Call SSL_get_error() with the return -value B<ret> to find out, whether an error occurred. - -=item -1 - -The read operation was not successful, because either an error occurred -or action must be taken by the calling process. Call SSL_get_error() with the -return value B<ret> to find out the reason. - -=back - -=head1 SEE ALSO - -L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_read(3)|SSL_read(3)>, -L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> - -=cut diff --git a/crypto/openssl/doc/standards.txt b/crypto/openssl/doc/standards.txt deleted file mode 100644 index 61ccc5d7e0af..000000000000 --- a/crypto/openssl/doc/standards.txt +++ /dev/null @@ -1,121 +0,0 @@ -Standards related to OpenSSL -============================ - -[Please, this is currently a draft. I made a first try at finding - documents that describe parts of what OpenSSL implements. There are - big gaps, and I've most certainly done something wrong. Please - correct whatever is... Also, this note should be removed when this - file is reaching a somewhat correct state. -- Richard Levitte] - - -All pointers in here will be either URL's or blobs of text borrowed -from miscellaneous indexes, like rfc-index.txt (index of RFCs), -1id-index.txt (index of Internet drafts) and the like. - -To find the latest possible RFCs, it's recommended to either browse -ftp://ftp.isi.edu/in-notes/ or go to http://www.rfc-editor.org/ and -use the search mechanism found there. -To find the latest possible Internet drafts, it's recommended to -browse ftp://ftp.isi.edu/internet-drafts/. -To find the latest possible PKCS, it's recommended to browse -http://www.rsasecurity.com/rsalabs/pkcs/. - - -Implemented: ------------- - -These are documents that describe things that are implemented in OpenSSL. - -1319 The MD2 Message-Digest Algorithm. B. Kaliski. April 1992. - (Format: TXT=25661 bytes) (Status: INFORMATIONAL) - -1320 The MD4 Message-Digest Algorithm. R. Rivest. April 1992. (Format: - TXT=32407 bytes) (Status: INFORMATIONAL) - -1321 The MD5 Message-Digest Algorithm. R. Rivest. April 1992. (Format: - TXT=35222 bytes) (Status: INFORMATIONAL) - -2246 The TLS Protocol Version 1.0. T. Dierks, C. Allen. January 1999. - (Format: TXT=170401 bytes) (Status: PROPOSED STANDARD) - -2268 A Description of the RC2(r) Encryption Algorithm. R. Rivest. - January 1998. (Format: TXT=19048 bytes) (Status: INFORMATIONAL) - -2314 PKCS 10: Certification Request Syntax Version 1.5. B. Kaliski. - March 1998. (Format: TXT=15814 bytes) (Status: INFORMATIONAL) - -2315 PKCS 7: Cryptographic Message Syntax Version 1.5. B. Kaliski. - March 1998. (Format: TXT=69679 bytes) (Status: INFORMATIONAL) - -2437 PKCS #1: RSA Cryptography Specifications Version 2.0. B. Kaliski, - J. Staddon. October 1998. (Format: TXT=73529 bytes) (Obsoletes - RFC2313) (Status: INFORMATIONAL) - -2459 Internet X.509 Public Key Infrastructure Certificate and CRL - Profile. R. Housley, W. Ford, W. Polk, D. Solo. January 1999. - (Format: TXT=278438 bytes) (Status: PROPOSED STANDARD) - -PKCS#8: Private-Key Information Syntax Standard - -PKCS#12: Personal Information Exchange Syntax Standard, version 1.0. - - -Related: --------- - -These are documents that are close to OpenSSL, for example the -STARTTLS documents. - -1421 Privacy Enhancement for Internet Electronic Mail: Part I: Message - Encryption and Authentication Procedures. J. Linn. February 1993. - (Format: TXT=103894 bytes) (Obsoletes RFC1113) (Status: PROPOSED - STANDARD) - -1422 Privacy Enhancement for Internet Electronic Mail: Part II: - Certificate-Based Key Management. S. Kent. February 1993. (Format: - TXT=86085 bytes) (Obsoletes RFC1114) (Status: PROPOSED STANDARD) - -1423 Privacy Enhancement for Internet Electronic Mail: Part III: - Algorithms, Modes, and Identifiers. D. Balenson. February 1993. - (Format: TXT=33277 bytes) (Obsoletes RFC1115) (Status: PROPOSED - STANDARD) - -1424 Privacy Enhancement for Internet Electronic Mail: Part IV: Key - Certification and Related Services. B. Kaliski. February 1993. - (Format: TXT=17537 bytes) (Status: PROPOSED STANDARD) - -2487 SMTP Service Extension for Secure SMTP over TLS. P. Hoffman. - January 1999. (Format: TXT=15120 bytes) (Status: PROPOSED STANDARD) - -2585 Internet X.509 Public Key Infrastructure Operational Protocols: - FTP and HTTP. R. Housley, P. Hoffman. May 1999. (Format: TXT=14813 - bytes) (Status: PROPOSED STANDARD) - -2595 Using TLS with IMAP, POP3 and ACAP. C. Newman. June 1999. - (Format: TXT=32440 bytes) (Status: PROPOSED STANDARD) - -2712 Addition of Kerberos Cipher Suites to Transport Layer Security - (TLS). A. Medvinsky, M. Hur. October 1999. (Format: TXT=13763 bytes) - (Status: PROPOSED STANDARD) - -2817 Upgrading to TLS Within HTTP/1.1. R. Khare, S. Lawrence. May - 2000. (Format: TXT=27598 bytes) (Updates RFC2616) (Status: PROPOSED - STANDARD) - -2818 HTTP Over TLS. E. Rescorla. May 2000. (Format: TXT=15170 bytes) - (Status: INFORMATIONAL) - - "Securing FTP with TLS", 01/27/2000, <draft-murray-auth-ftp-ssl-05.txt> - - -To be implemented: ------------------- - -These are documents that describe things that are planed to be -implemented in the hopefully short future. - -2560 X.509 Internet Public Key Infrastructure Online Certificate - Status Protocol - OCSP. M. Myers, R. Ankney, A. Malpani, S. Galperin, - C. Adams. June 1999. (Format: TXT=43243 bytes) (Status: PROPOSED - STANDARD) - |