diff options
author | Richard Levitte <levitte@openssl.org> | 2000-09-21 06:46:15 +0000 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2000-09-21 06:46:15 +0000 |
commit | c19b6c922a6575974455404be3c1409de60fb1eb (patch) | |
tree | 9028e11834ce68083ad559adaf34f83c4e12a7e7 /doc | |
parent | c5f8bbbc0b94f3ec3f3f8f2aabbe3cc81f7b8158 (diff) |
Clarifications and new documents.
Submitted by Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ssl/SSL_CTX_set_ssl_version.pod | 60 | ||||
-rw-r--r-- | doc/ssl/SSL_accept.pod | 7 | ||||
-rw-r--r-- | doc/ssl/SSL_connect.pod | 7 | ||||
-rw-r--r-- | doc/ssl/SSL_pending.pod | 30 | ||||
-rw-r--r-- | doc/ssl/SSL_read.pod | 12 | ||||
-rw-r--r-- | doc/ssl/SSL_write.pod | 12 |
6 files changed, 122 insertions, 6 deletions
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 <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/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<ssl> by setting an underlying B<BIO>. The behaviour of SSL_accept() depends -on the underlying BIO. +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 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<ssl> by setting an -underlying B<BIO>. The behaviour of SSL_connect() depends on the underlying -BIO. +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. 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 <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/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<num> bytes from the specified B<ssl> into the -buffer B<buf>. If necessary, SSL_read() will negotiate a TLS/SSL session, if +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 @@ -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<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: 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<num> bytes from the buffer B<buf> into the specified -B<ssl>. If necessary, SSL_write() will negotiate a TLS/SSL session, if +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 @@ -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<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: |