From c19b6c922a6575974455404be3c1409de60fb1eb Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Thu, 21 Sep 2000 06:46:15 +0000 Subject: [PATCH] Clarifications and new documents. Submitted by Lutz Jaenicke --- doc/ssl/SSL_CTX_set_ssl_version.pod | 60 +++++++++++++++++++++++++++++ doc/ssl/SSL_accept.pod | 7 +++- doc/ssl/SSL_connect.pod | 7 +++- doc/ssl/SSL_pending.pod | 30 +++++++++++++++ doc/ssl/SSL_read.pod | 12 +++++- doc/ssl/SSL_write.pod | 12 +++++- 6 files changed, 122 insertions(+), 6 deletions(-) create mode 100644 doc/ssl/SSL_CTX_set_ssl_version.pod create mode 100644 doc/ssl/SSL_pending.pod diff --git a/doc/ssl/SSL_CTX_set_ssl_version.pod b/doc/ssl/SSL_CTX_set_ssl_version.pod new file mode 100644 index 0000000000..3091bd6895 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_ssl_version.pod @@ -0,0 +1,60 @@ +=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 + + 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 for SSL objects +newly created from this B. SSL objects already created with +L are not affected, except when SSL_clear() is +being called. + +SSL_set_ssl_method() sets a new TLS/SSL B for a particular B +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. + +=head1 NOTES + +The available B choices are described in +L. + +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, L, +L, L + +=cut diff --git a/doc/ssl/SSL_accept.pod b/doc/ssl/SSL_accept.pod index fc6a57b5da..0c79ac515e 100644 --- a/doc/ssl/SSL_accept.pod +++ b/doc/ssl/SSL_accept.pod @@ -14,8 +14,11 @@ SSL_accept - wait for a TLS/SSL client to initiate a TLS/SSL handshake 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 by setting an underlying B. The behaviour of SSL_accept() depends -on the underlying BIO. +B by setting an underlying B. + +=head1 NOTES + +The behaviour of SSL_accept() depends on the underlying BIO. If the underlying BIO is B, SSL_accept() will only return once the handshake has been finished or an error occurred, except for SGC (Server diff --git a/doc/ssl/SSL_connect.pod b/doc/ssl/SSL_connect.pod index 7123bf3257..debe41744f 100644 --- a/doc/ssl/SSL_connect.pod +++ b/doc/ssl/SSL_connect.pod @@ -14,8 +14,11 @@ SSL_connect - initiate the TLS/SSL handshake with an TLS/SSL server SSL_connect() initiates the TLS/SSL handshake with a server. The communication channel must already have been set and assigned to the B by setting an -underlying B. The behaviour of SSL_connect() depends on the underlying -BIO. +underlying B. + +=head1 NOTES + +The behaviour of SSL_connect() depends on the underlying BIO. If the underlying BIO is B, SSL_connect() will only return once the handshake has been finished or an error occurred. diff --git a/doc/ssl/SSL_pending.pod b/doc/ssl/SSL_pending.pod new file mode 100644 index 0000000000..744e1855e1 --- /dev/null +++ b/doc/ssl/SSL_pending.pod @@ -0,0 +1,30 @@ +=pod + +=head1 NAME + +SSL_pending - obtain number of readable bytes buffered in an SSL object + +=head1 SYNOPSIS + + #include + + int SSL_pending(SSL *ssl); + +=head1 DESCRIPTION + +SSL_pending() returns the number of bytes which are available inside +B for immediate read. + +=head1 NOTES + +Data are received in blocks from the peer. Therefore data can be buffered +inside B and are ready for immediate retrieval with +L. + +=head1 RETURN VALUES + +The number of bytes pending is returned. + +L, L + +=cut diff --git a/doc/ssl/SSL_read.pod b/doc/ssl/SSL_read.pod index 3b082a7c90..708b20fdb5 100644 --- a/doc/ssl/SSL_read.pod +++ b/doc/ssl/SSL_read.pod @@ -13,7 +13,11 @@ SSL_read - read bytes from a TLS/SSL connection. =head1 DESCRIPTION SSL_read() tries to read B bytes from the specified B into the -buffer B. If necessary, SSL_read() will negotiate a TLS/SSL session, if +buffer B. + +=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 @@ -34,6 +38,12 @@ 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 IMPORTANT + +When an SSL_read() operation has to be repeated because of +B or B, it must be repeated +with the same arguments. + =head1 RETURN VALUES The following return values can occur: diff --git a/doc/ssl/SSL_write.pod b/doc/ssl/SSL_write.pod index b086258e82..0a1adaba73 100644 --- a/doc/ssl/SSL_write.pod +++ b/doc/ssl/SSL_write.pod @@ -13,7 +13,11 @@ SSL_read - write bytes to a TLS/SSL connection. =head1 DESCRIPTION SSL_write() writes B bytes from the buffer B into the specified -B. If necessary, SSL_write() will negotiate a TLS/SSL session, if +B 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 @@ -34,6 +38,12 @@ 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 IMPORTANT + +When an SSL_write() operation has to be repeated because of +B or B, it must be repeated +with the same arguments. + =head1 RETURN VALUES The following return values can occur: -- 2.34.1