diff --git a/crypto/dso/dso_vms.c b/crypto/dso/dso_vms.c new file mode 100644 index 000000000..58b902739 --- /dev/null +++ b/crypto/dso/dso_vms.c @@ -0,0 +1,364 @@ +/* dso_vms.c */ +/* Written by Richard Levitte (richard@levitte.org) for the OpenSSL + * project 2000. + */ +/* ==================================================================== + * Copyright (c) 2000 The OpenSSL Project. All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. All advertising materials mentioning features or use of this + * software must display the following acknowledgment: + * "This product includes software developed by the OpenSSL Project + * for use in the OpenSSL Toolkit. (http://www.OpenSSL.org/)" + * + * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to + * endorse or promote products derived from this software without + * prior written permission. For written permission, please contact + * licensing@OpenSSL.org. + * + * 5. Products derived from this software may not be called "OpenSSL" + * nor may "OpenSSL" appear in their names without prior written + * permission of the OpenSSL Project. + * + * 6. Redistributions of any form whatsoever must retain the following + * acknowledgment: + * "This product includes software developed by the OpenSSL Project + * for use in the OpenSSL Toolkit (http://www.OpenSSL.org/)" + * + * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY + * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + * OF THE POSSIBILITY OF SUCH DAMAGE. + * ==================================================================== + * + * This product includes cryptographic software written by Eric Young + * (eay@cryptsoft.com). This product includes software written by Tim + * Hudson (tjh@cryptsoft.com). + * + */ + +#include +#include +#include +#ifdef VMS +#include +#include +#include +#include +#include +#endif +#include "cryptlib.h" +#include + +#ifndef VMS +DSO_METHOD *DSO_METHOD_vms(void) + { + return NULL; + } +#else +#pragma message disable DOLLARID + +static int vms_load(DSO *dso, const char *filename); +static int vms_unload(DSO *dso); +static void *vms_bind_var(DSO *dso, const char *symname); +static DSO_FUNC_TYPE vms_bind_func(DSO *dso, const char *symname); +#if 0 +static int vms_unbind_var(DSO *dso, char *symname, void *symptr); +static int vms_unbind_func(DSO *dso, char *symname, DSO_FUNC_TYPE symptr); +static int vms_init(DSO *dso); +static int vms_finish(DSO *dso); +#endif +static long vms_ctrl(DSO *dso, int cmd, long larg, void *parg); + +static DSO_METHOD dso_meth_vms = { + "OpenSSL 'VMS' shared library method", + vms_load, + NULL, /* unload */ + vms_bind_var, + vms_bind_func, +/* For now, "unbind" doesn't exist */ +#if 0 + NULL, /* unbind_var */ + NULL, /* unbind_func */ +#endif + vms_ctrl, + NULL, /* init */ + NULL /* finish */ + }; + +/* On VMS, the only "handle" is the file name. LIB$FIND_IMAGE_SYMBOL depends + * on the reference to the file name being the same for all calls regarding + * one shared image, so we'll just store it in an instance of the following + * structure and put a pointer to that instance in the meth_data stack. + */ +typedef struct dso_internal_st + { + /* This should contain the name only, no directory, + * no extension, nothing but a name. */ + struct dsc$descriptor_s filename_dsc; + char filename[FILENAME_MAX+1]; + /* This contains whatever is not in filename, if needed. + * Normally not defined. */ + struct dsc$descriptor_s imagename_dsc; + char imagename[FILENAME_MAX+1]; + } DSO_VMS_INTERNAL; + + +DSO_METHOD *DSO_METHOD_vms(void) + { + return(&dso_meth_vms); + } + +static int vms_load(DSO *dso, const char *filename) + { + DSO_VMS_INTERNAL *p; + const char *sp1, *sp2; /* Search result */ + + /* A file specification may look like this: + * + * node::dev:[dir-spec]name.type;ver + * + * or (for compatibility with TOPS-20): + * + * node::dev:name.type;ver + * + * and the dir-spec uses '.' as separator. Also, a dir-spec + * may consist of several parts, with mixed use of [] and <>: + * + * [dir1.] + * + * We need to split the file specification into the name and + * the rest (both before and after the name itself). + */ + /* Start with trying to find the end of a dir-spec, and save the + position of the byte after in sp1 */ + sp1 = strrchr(filename, ']'); + sp2 = strrchr(filename, '>'); + if (sp1 == NULL) sp1 = sp2; + if (sp2 != NULL && sp2 > sp1) sp1 = sp2; + if (sp1 == NULL) sp1 = strrchr(filename, ':'); + if (sp1 == NULL) + sp1 = filename; + else + sp1++; /* The byte after the found character */ + /* Now, let's see if there's a type, and save the position in sp2 */ + sp2 = strchr(sp1, '.'); + /* If we found it, that's where we'll cut. Otherwise, look for a + version number and save the position in sp2 */ + if (sp2 == NULL) sp2 = strchr(sp1, ';'); + /* If there was still nothing to find, set sp2 to point at the end of + the string */ + if (sp2 == NULL) sp2 = sp1 + strlen(sp1); + + /* Check that we won't get buffer overflows */ + if (sp2 - sp1 > FILENAME_MAX + || (sp1 - filename) + strlen(sp2) > FILENAME_MAX) + { + DSOerr(DSO_F_VMS_LOAD,DSO_R_FILENAME_TOO_BIG); + return(0); + } + + p = (DSO_VMS_INTERNAL *)OPENSSL_malloc(sizeof(DSO_VMS_INTERNAL)); + if(p == NULL) + { + DSOerr(DSO_F_VMS_LOAD,ERR_R_MALLOC_FAILURE); + return(0); + } + + strncpy(p->filename, sp1, sp2-sp1); + p->filename[sp2-sp1] = '\0'; + + strncpy(p->imagename, filename, sp1-filename); + p->imagename[sp1-filename] = '\0'; + strcat(p->imagename, sp2); + + p->filename_dsc.dsc$w_length = strlen(p->filename); + p->filename_dsc.dsc$b_dtype = DSC$K_DTYPE_T; + p->filename_dsc.dsc$b_class = DSC$K_CLASS_S; + p->filename_dsc.dsc$a_pointer = p->filename; + p->imagename_dsc.dsc$w_length = strlen(p->imagename); + p->imagename_dsc.dsc$b_dtype = DSC$K_DTYPE_T; + p->imagename_dsc.dsc$b_class = DSC$K_CLASS_S; + p->imagename_dsc.dsc$a_pointer = p->imagename; + + if(!sk_push(dso->meth_data, (char *)p)) + { + DSOerr(DSO_F_VMS_LOAD,DSO_R_STACK_ERROR); + OPENSSL_free(p); + return(0); + } + return(1); + } + +/* Note that this doesn't actually unload the shared image, as there is no + * such thing in VMS. Next time it get loaded again, a new copy will + * actually be loaded. + */ +static int vms_unload(DSO *dso) + { + DSO_VMS_INTERNAL *p; + if(dso == NULL) + { + DSOerr(DSO_F_VMS_UNLOAD,ERR_R_PASSED_NULL_PARAMETER); + return(0); + } + if(sk_num(dso->meth_data) < 1) + return(1); + p = (DSO_VMS_INTERNAL *)sk_pop(dso->meth_data); + if(p == NULL) + { + DSOerr(DSO_F_VMS_UNLOAD,DSO_R_NULL_HANDLE); + return(0); + } + /* Cleanup */ + OPENSSL_free(p); + return(1); + } + +/* We must do this in a separate function because of the way the exception + handler works (it makes this function return */ +static int do_find_symbol(DSO_VMS_INTERNAL *ptr, + struct dsc$descriptor_s *symname_dsc, void **sym, + unsigned long flags) + { + /* Make sure that signals are caught and returned instead of + aborting the program. The exception handler gets unestablished + automatically on return from this function. */ + lib$establish(lib$sig_to_ret); + + if(ptr->imagename_dsc.dsc$w_length) + return lib$find_image_symbol(&ptr->filename_dsc, + symname_dsc, sym, + &ptr->imagename_dsc, flags); + else + return lib$find_image_symbol(&ptr->filename_dsc, + symname_dsc, sym, + 0, flags); + } + +static void *vms_bind_sym(DSO *dso, const char *symname) + { + DSO_VMS_INTERNAL *ptr; + void *sym = 0; + int status; + int flags = LIB$M_FIS_MIXEDCASE; + struct dsc$descriptor_s symname_dsc; + + symname_dsc.dsc$w_length = strlen(symname); + symname_dsc.dsc$b_dtype = DSC$K_DTYPE_T; + symname_dsc.dsc$b_class = DSC$K_CLASS_S; + symname_dsc.dsc$a_pointer = (char *)symname; /* The cast is needed */ + + if((dso == NULL) || (symname == NULL)) + { + DSOerr(DSO_F_VMS_BIND_VAR,ERR_R_PASSED_NULL_PARAMETER); + return(NULL); + } + if(sk_num(dso->meth_data) < 1) + { + DSOerr(DSO_F_VMS_BIND_VAR,DSO_R_STACK_ERROR); + return(NULL); + } + ptr = (DSO_VMS_INTERNAL *)sk_value(dso->meth_data, + sk_num(dso->meth_data) - 1); + if(ptr == NULL) + { + DSOerr(DSO_F_VMS_BIND_VAR,DSO_R_NULL_HANDLE); + return(NULL); + } + + if(dso->flags & DSO_FLAG_UPCASE_SYMBOL) flags = 0; + + status = do_find_symbol(ptr, &symname_dsc, &sym, flags); + + if(!$VMS_STATUS_SUCCESS(status)) + { + unsigned short length; + char errstring[257]; + struct dsc$descriptor_s errstring_dsc; + + errstring_dsc.dsc$w_length = sizeof(errstring); + errstring_dsc.dsc$b_dtype = DSC$K_DTYPE_T; + errstring_dsc.dsc$b_class = DSC$K_CLASS_S; + errstring_dsc.dsc$a_pointer = errstring; + + status = sys$getmsg(status, &length, &errstring_dsc, 1, 0); + + if (!$VMS_STATUS_SUCCESS(status)) + lib$signal(status); /* This is really bad. Abort! */ + else + { + errstring[length] = '\0'; + + DSOerr(DSO_F_VMS_BIND_VAR,DSO_R_SYM_FAILURE); + if (ptr->imagename_dsc.dsc$w_length) + ERR_add_error_data(9, + "Symbol ", symname, + " in ", ptr->filename, + " (", ptr->imagename, ")", + ": ", errstring); + else + ERR_add_error_data(6, + "Symbol ", symname, + " in ", ptr->filename, + ": ", errstring); + } + return(NULL); + } + return(sym); + } + +static void *vms_bind_var(DSO *dso, const char *symname) + { + return vms_bind_sym(dso, symname); + } + +static DSO_FUNC_TYPE vms_bind_func(DSO *dso, const char *symname) + { + return (DSO_FUNC_TYPE)vms_bind_sym(dso, symname); + } + +static long vms_ctrl(DSO *dso, int cmd, long larg, void *parg) + { + if(dso == NULL) + { + DSOerr(DSO_F_VMS_CTRL,ERR_R_PASSED_NULL_PARAMETER); + return(-1); + } + switch(cmd) + { + case DSO_CTRL_GET_FLAGS: + return dso->flags; + case DSO_CTRL_SET_FLAGS: + dso->flags = (int)larg; + return(0); + case DSO_CTRL_OR_FLAGS: + dso->flags |= (int)larg; + return(0); + default: + break; + } + DSOerr(DSO_F_VMS_CTRL,DSO_R_UNKNOWN_COMMAND); + return(-1); + } + +#endif /* VMS */ diff --git a/doc/crypto/BIO_ctrl_get_read_request.pod b/doc/crypto/BIO_ctrl_get_read_request.pod new file mode 100644 index 000000000..4325fd16f --- /dev/null +++ b/doc/crypto/BIO_ctrl_get_read_request.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + + BIO_ctrl_get_read_request - Find out how much bytes are were requested from the BIO + +=head1 SYNOPSIS + + #include + + size_t BIO_ctrl_get_read_request(BIO *bio); + +=head1 DESCRIPTION + +BIO_ctrl_get_read_request() returns the number of bytes that were last +requested from B by a BIO_read() operation. This is useful e.g. for +BIO pairs, so that the application knows how much bytes to supply to B. + +=head1 BUGS + +When B is NULL, the OpenSSL library calls assert(). + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item E=0 + +The number of bytes requested. + +=back + +=head1 SEE ALSO + +L, L, +L diff --git a/doc/crypto/BIO_ctrl_pending.pod b/doc/crypto/BIO_ctrl_pending.pod new file mode 100644 index 000000000..235119130 --- /dev/null +++ b/doc/crypto/BIO_ctrl_pending.pod @@ -0,0 +1,36 @@ +=pod + +=head1 NAME + +BIO_ctrl_pending - Find out how much bytes are buffered in a BIO + +=head1 SYNOPSIS + + #include + + size_t BIO_ctrl_pending(BIO *bio); + +=head1 DESCRIPTION + +BIO_ctrl_pending() returns the number of bytes buffered in a BIO. + +=head1 BUGS + +When B is NULL, the OpenSSL library calls assert(). + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item E=0 + +The number of bytes pending the BIO. + +=back + +=head1 SEE ALSO + +L, L, +L diff --git a/doc/crypto/BIO_new_bio_pair.pod b/doc/crypto/BIO_new_bio_pair.pod new file mode 100644 index 000000000..c331bd02b --- /dev/null +++ b/doc/crypto/BIO_new_bio_pair.pod @@ -0,0 +1,102 @@ +=pod + +=head1 NAME + +BIO_new_bio_pair - create a new BIO pair + +=head1 SYNOPSIS + + #include + + 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 and B are symmetric with respect to their +functionality. The size of their buffers is determined by B and +B. If the size give is 0, the default size is used. + +BIO_new_bio_pair() does not check whether B or B 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 +seperately. This can be of importance, as some SSL-functions like SSL_set_bio() +or SSL_free() call BIO_free() implicitely, 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); /* implicitely 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 and B. + +=item 0 + +The operation failed. The NULL pointer is stored into the locations for +B and B. Check the error stack for more information. + +=back + +=head1 SEE ALSO + +L, L, L, +L, +L + +=cut diff --git a/doc/crypto/BIO_s_accept.pod b/doc/crypto/BIO_s_accept.pod new file mode 100644 index 000000000..17fd54a9c --- /dev/null +++ b/doc/crypto/BIO_s_accept.pod @@ -0,0 +1,182 @@ +=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 + + 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_set_accept_port() uses the string B 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. + +BIO_set_nbio_accept() sets the accept socket to blocking mode +(the default) if B is 0 or non blocking mode if B 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 BIO is required for each connection. + +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 conection 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 will contain a BIO for the recently +established connection and B 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 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/doc/crypto/BIO_s_bio.pod b/doc/crypto/BIO_s_bio.pod new file mode 100644 index 000000000..2c93f179b --- /dev/null +++ b/doc/crypto/BIO_s_bio.pod @@ -0,0 +1,118 @@ +=pod + +=head1 NAME + +BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, 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 + + 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_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_set_write_buf_size() sets the write buffer size of BIO B to B. +If the size is not initialised 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, B +with write buffer sizes B and B. If either size is +zero then the default size is used. + +BIO_get_write_guarantee() and BIO_ctrl_get_write_guarentee() 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 failed due to an +empty buffer. This can be used to determine how much data should be written to the +other half of the pair 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. + +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 implicity +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 flusing the write buffer it will never succeed because the request was +never sent! + +=head1 EXAMPLE + +TBA + +=head1 SEE ALSO + +L, L, L, +L, L + +=cut diff --git a/doc/crypto/BIO_s_connect.pod b/doc/crypto/BIO_s_connect.pod new file mode 100644 index 000000000..65723a70a --- /dev/null +++ b/doc/crypto/BIO_s_connect.pod @@ -0,0 +1,182 @@ +=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 + + 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 if it is not NULL, +it also returns the socket . If B is not NULL it should be of +type (int *). + +BIO_set_conn_hostname() uses the string B 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. B 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 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. B should +be of type (int *). + +BIO_get_conn_hostname() returns the hostname of the connect BIO or +NULL if the BIO is initialised 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. If B is +zero then blocking I/O is set. If B 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 appropiate 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 initialised. + +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/doc/crypto/BIO_s_socket.pod b/doc/crypto/BIO_s_socket.pod new file mode 100644 index 000000000..ec450e11f --- /dev/null +++ b/doc/crypto/BIO_s_socket.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +BIO_s_socket, BIO_new_socket - socket BIO + +=head1 SYNOPSIS + + #include + + 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 to B and the close +flag to B. + +BIO_get_fd() places the socket in B if it is not NULL, it also +returns the socket . If B is not NULL it should be of type (int *). + +BIO_new_socket() returns a socket BIO using B and B. + +=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 +initialised. + +BIO_new_socket() returns the newly allocated BIO or NULL is an error +occurred. + +=head1 SEE ALSO + +TBA diff --git a/doc/crypto/BIO_seek.pod b/doc/crypto/BIO_seek.pod new file mode 100644 index 000000000..3f92d5cbd --- /dev/null +++ b/doc/crypto/BIO_seek.pod @@ -0,0 +1,30 @@ +=pod + +=head1 NAME + +BIO_seek, BIO_tell - file BIO operations + +=head1 SYNOPSIS + + #include + + #define BIO_seek(b,ofs) (int)BIO_ctrl(b,BIO_C_FILE_SEEK,ofs,NULL) + #define BIO_tell(b) (int)BIO_ctrl(b,BIO_C_FILE_TELL,0,NULL) + +=head1 DESCRIPTION + +BIO_seek() sets the file position pointer to B bytes from start of file. + +BIO_tell() returns the current file position. + +=head1 RETURN VALUES + +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. + +=head1 SEE ALSO + +TBA + diff --git a/doc/ssl/SSL_SESSION_free.pod b/doc/ssl/SSL_SESSION_free.pod new file mode 100644 index 000000000..2ec7544ca --- /dev/null +++ b/doc/ssl/SSL_SESSION_free.pod @@ -0,0 +1,25 @@ +=pod + +=head1 NAME + +SSL_SESSION_free - Free up an allocated SSL_SESSION structure + +=head1 SYNOPSIS + + #include + + void *SSL_SESSION_free(SSL_SESSION *session); + +=head1 DESCRIPTION + +SSL_SESSION_free() decrements the reference count of B and removes +the SSL_SESSION structure pointed to by B 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, L + +=cut diff --git a/doc/ssl/SSL_accept.pod b/doc/ssl/SSL_accept.pod new file mode 100644 index 000000000..d21a391cb --- /dev/null +++ b/doc/ssl/SSL_accept.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + +SSL_accept - Wait for a TLS client to initiate a TLS handshake + +=head1 SYNOPSIS + + #include + + int SSL_accept(SSL *ssl); + +=head1 DESCRIPTION + +SSL_accept() waits for a TLS client to initiate the TLS 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. + +If the underlying BIO is B, SSL_accept() will only return, once the +handshake has been finished or an error occured, except for SGC (Server +Gated Cryptography). For SGC SSL_accept() may return with -1 but +SSL_get_error() will yield SSL_ERROR_WANT_READ/WRITE and SSL_accept() +should be called again. + +If the underlying BIO is B, 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 SSL_ERROR_WANT_READ or +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 handshake was successfully completed, a TLS connection has been +established. + +=item 0 + +The TLS handshake was not successfull but was shut down controlled and +by the specifications of the TLS protocol. Call SSL_get_error() with the +return value B to find out the reason. + +=item -1 + +The TLS handshake was not successfull, because a fatal error occured either +at the protocol level or a connection failure occured. The shutdown was +not clean. It can also occure of action is need to continue the operation +for non-blocking BIOs. Call SSL_get_error() with the return value B +to find out the reason. + +=back + +=head1 SEE ALSO + +L, L, +L, L, L + +=cut diff --git a/doc/ssl/SSL_clear.pod b/doc/ssl/SSL_clear.pod new file mode 100644 index 000000000..c68938b4b --- /dev/null +++ b/doc/ssl/SSL_clear.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +SSL_clear - Reset SSL to allow another connection + +=head1 SYNOPSIS + + #include + + int *SSL_clear(SSL *ssl); + +=head1 DESCRIPTION + +Reset the B to allow another connection. All settings (method, ciphers, +BIOs) are kept. A completely negotiated SSL_SESSION is not freed but left +untouched for the underlying 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 successfull. + +=back + +L, L, +L + +=cut diff --git a/doc/ssl/SSL_connect.pod b/doc/ssl/SSL_connect.pod new file mode 100644 index 000000000..269edd0e7 --- /dev/null +++ b/doc/ssl/SSL_connect.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +SSL_connect - Initiate the TLS handshake with an TLS server + +=head1 SYNOPSIS + + #include + + int SSL_connect(SSL *ssl); + +=head1 DESCRIPTION + +SSL_connect() initiates the TLS 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. + +If the underlying BIO is B, SSL_connect() will only return, once the +handshake has been finished or an error occured. + +If the underlying BIO is B, 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 SSL_ERROR_WANT_READ or +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 handshake was successfully completed, a TLS connection has been +established. + +=item 0 + +The TLS handshake was not successfull but was shut down controlled and +by the specifications of the TLS protocol. Call SSL_get_error() with the +return value B to find out the reason. + +=item -1 + +The TLS handshake was not successfull, because a fatal error occured either +at the protocol level or a connection failure occured. The shutdown was +not clean. It can also occure of action is need to continue the operation +for non-blocking BIOs. Call SSL_get_error() with the return value B +to find out the reason. + +=back + +=head1 SEE ALSO + +L, L, +L, L , L + +=cut diff --git a/doc/ssl/SSL_free.pod b/doc/ssl/SSL_free.pod new file mode 100644 index 000000000..3d01234a8 --- /dev/null +++ b/doc/ssl/SSL_free.pod @@ -0,0 +1,33 @@ +=pod + +=head1 NAME + +SSL_free - Free up an allocated SSL structure + +=head1 SYNOPSIS + + #include + + void *SSL_free(SSL *ssl); + +=head1 DESCRIPTION + +SSL_free() decrements the reference count of B and removes the SSL +structure pointed to by B 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 especially created for this B, the 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, L, +L + +=cut diff --git a/doc/ssl/SSL_get_fd.pod b/doc/ssl/SSL_get_fd.pod new file mode 100644 index 000000000..0ed21d5f1 --- /dev/null +++ b/doc/ssl/SSL_get_fd.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +SSL_get_fd - Get file descriptor linked to an SSL + +=head1 SYNOPSIS + + #include + + 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_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=0 + +The file descriptor linked to B. + +=back + +=head1 SEE ALSO + +L, L , L + +=cut diff --git a/doc/ssl/SSL_get_rbio.pod b/doc/ssl/SSL_get_rbio.pod new file mode 100644 index 000000000..40a5f12e7 --- /dev/null +++ b/doc/ssl/SSL_get_rbio.pod @@ -0,0 +1,40 @@ +=pod + +=head1 NAME + +SSL_get_rbio - Get BIO linked to an SSL + +=head1 SYNOPSIS + + #include + + 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 + +=item Any other pointer + +The BIO linked to B. + +=back + +=head1 SEE ALSO + +L, L , L + +=cut diff --git a/doc/ssl/SSL_get_session.pod b/doc/ssl/SSL_get_session.pod new file mode 100644 index 000000000..0b3f50af4 --- /dev/null +++ b/doc/ssl/SSL_get_session.pod @@ -0,0 +1,48 @@ +=pod + +=head1 NAME + +SSL_get_session - Retrieve SSL session data + +=head1 SYNOPSIS + + #include + + 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 SSL session actually used in +B. The reference count of the SSL session is not incremented, so +that the pointer can become invalid when the B 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 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. + +=item Pointer to an SSL + +The return value points to the data of an SSL session. + +=back + +=head1 SEE ALSO + +L, L, +L + +=cut diff --git a/doc/ssl/SSL_new.pod b/doc/ssl/SSL_new.pod new file mode 100644 index 000000000..a393c94c0 --- /dev/null +++ b/doc/ssl/SSL_new.pod @@ -0,0 +1,42 @@ +=pod + +=head1 NAME + +SSL_new - Create a new SSL structure for a connection + +=head1 SYNOPSIS + + #include + + SSL *SSL_new(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_new() creates a new B structure which is needed to hold the data +for a SSL connection. The new SSL inherits the settings of the underlying +context B: 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 failed. Check the error stack to find out the +reason. + +=item Pointer to an SSL + +The return value points to an allocated SSL structure. + +=back + +=head1 SEE ALSO + +L, L, +L + +=cut diff --git a/doc/ssl/SSL_read.pod b/doc/ssl/SSL_read.pod new file mode 100644 index 000000000..9df51030c --- /dev/null +++ b/doc/ssl/SSL_read.pod @@ -0,0 +1,67 @@ +=pod + +=head1 NAME + +SSL_read - Read bytes from a TLS connection. + +=head1 SYNOPSIS + + #include + + int SSL_read(SSL *ssl, char *buf, int num); + +=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 session, if +not already explicitely 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, SSL_read() will only return, once the +read operation has been finished or an error occured. + +If the underlying BIO is B, 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 SSL_ERROR_WANT_READ or +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 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item E0 + +The read operation was successfull, the return value is the number of +bytes actually read from the TLS connection. + +=item 0 + +The read operation was not successfull, probably because no data was +available. Call SSL_get_error() with the return value B to find out, +whether an error occured. + +=item -1 + +The read operation was not successfull, because either an error occured +or action must be taken by the calling process. Call SSL_get_error() with the +return value B to find out the reason. + +=back + +=head1 SEE ALSO + +L, L, +L, L + +=cut diff --git a/doc/ssl/SSL_set_bio.pod b/doc/ssl/SSL_set_bio.pod new file mode 100644 index 000000000..24fa77e71 --- /dev/null +++ b/doc/ssl/SSL_set_bio.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +SSL_set_bio - Connect the SSL with a BIO + +=head1 SYNOPSIS + + #include + + void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio); + +=head1 DESCRIPTION + +SSL_set_bio() connects the BIOs B and B for the read and write +operations of the TLS (encrypted) side of B. + +The SSL engine inherits the behaviour of B and B, respectively. +If a BIO is non-blocking, the B will also have non-blocking behaviour. + +If there was already a BIO connected to B, 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, +L, L, +L, L , L + +=cut diff --git a/doc/ssl/SSL_set_fd.pod b/doc/ssl/SSL_set_fd.pod new file mode 100644 index 000000000..076791e17 --- /dev/null +++ b/doc/ssl/SSL_set_fd.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + +SSL_set_fd - Connect the SSL with a file descriptor + +=head1 SYNOPSIS + + #include + + 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 as the input/output facility +for the TLS (encrypted) side of SSL engine. B will typically be the +socket file descriptor of a network connection. + +When performing the operation, a B is automatically created to +interface between the B and B. The BIO and hence the SSL engine +inherit the behaviour of B. If B is non-blocking, the B will +also have non-blocking behaviour. + +If there was already a BIO connected to B, 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 independantly. + +=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, L, +L, L, +L, L , L + +=cut diff --git a/doc/ssl/SSL_set_session.pod b/doc/ssl/SSL_set_session.pod new file mode 100644 index 000000000..b1162ba61 --- /dev/null +++ b/doc/ssl/SSL_set_session.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + +SSL_set_session - Set an SSL session to be used during SSL connect + +=head1 SYNOPSIS + + #include + + int *SSL_set_session(SSL *ssl, SSL_SESSION *session); + +=head1 DESCRIPTION + +SSL_set_session() sets B to be used, when the SSL connection +is to be established. SSL_set_session() is only useful for SSL clients. +When the session is set, the reference count of B 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 (because it was set with +SSL_set_session() before or because the same B 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, L + +=cut diff --git a/doc/ssl/SSL_shutdown.pod b/doc/ssl/SSL_shutdown.pod new file mode 100644 index 000000000..be1166b59 --- /dev/null +++ b/doc/ssl/SSL_shutdown.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +SSL_shutdown - Shut down a TLS connection + +=head1 SYNOPSIS + + #include + + int SSL_shutdown(SSL *ssl); + +=head1 DESCRIPTION + +SSL_shutdown() shuts down an active TLS 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, SSL_shutdown() will only return, once the +handshake has been finished or an error occured. + +If the underlying BIO is B, 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 SSL_ERROR_WANT_READ or +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 successfull. Call SSL_get_error() with the return +value B to find out the reason. + +=item -1 + +The shutdown was not successfull, because a fatal error occured either +at the protocol level or a connection failure occured. It can also occure of +action is need to continue the operation for non-blocking BIOs. +Call SSL_get_error() with the return value B to find out the reason. + +=back + +=head1 SEE ALSO + +L, L, +L, L, L + +=cut diff --git a/doc/ssl/SSL_write.pod b/doc/ssl/SSL_write.pod new file mode 100644 index 000000000..9b433c0e2 --- /dev/null +++ b/doc/ssl/SSL_write.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +SSL_read - Write bytes to a TLS connection. + +=head1 SYNOPSIS + + #include + + int SSL_write(SSL *ssl, char *buf, int num); + +=head1 DESCRIPTION + +SSL_write() writes B bytes from the buffer B into the specified +B. If necessary, SSL_write() will negotiate a TLS session, if +not already explicitely 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, SSL_write() will only return, once the +write operation has been finished or an error occured. + +If the underlying BIO is B, 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 SSL_ERROR_WANT_READ or +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 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item E0 + +The write operation was successfull, the return value is the number of +bytes actually written to the TLS connection. + +=item 0 + +The write operation was not successfull. Call SSL_get_error() with the return +value B to find out, whether an error occured. + +=item -1 + +The read operation was not successfull, because either an error occured +or action must be taken by the calling process. Call SSL_get_error() with the +return value B to find out the reason. + +=back + +=head1 SEE ALSO + +L, L, +L, L + +=cut diff --git a/openssl.spec b/openssl.spec new file mode 100644 index 000000000..46c9acec9 --- /dev/null +++ b/openssl.spec @@ -0,0 +1,210 @@ +%define libmaj 0 +%define libmin 9 +%define librel 6 +#%define librev +Release: 1 + +%define openssldir /var/ssl + +Summary: Secure Sockets Layer and cryptography libraries and tools +Name: openssl +Version: %{libmaj}.%{libmin}.%{librel} +#Version: %{libmaj}.%{libmin}.%{librel}%{librev} +Source0: ftp://ftp.openssl.org/source/%{name}-%{version}.tar.gz +Copyright: Freely distributable +Group: System Environment/Libraries +Provides: SSL +URL: http://www.openssl.org/ +Packager: Damien Miller +BuildRoot: /var/tmp/%{name}-%{version}-root + +%description +The OpenSSL Project is a collaborative effort to develop a robust, +commercial-grade, fully featured, and Open Source toolkit implementing the +Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) +protocols with full-strength cryptography world-wide. The project is +managed by a worldwide community of volunteers that use the Internet to +communicate, plan, and develop the OpenSSL tookit and its related +documentation. + +OpenSSL is based on the excellent SSLeay library developed from Eric A. +Young and Tim J. Hudson. The OpenSSL toolkit is licensed under an +Apache-style licence, which basically means that you are free to get and +use it for commercial and non-commercial purposes. + +This package contains the base OpenSSL cryptography and SSL/TLS +libraries and tools. + +%package devel +Summary: Secure Sockets Layer and cryptography static libraries and headers +Group: Development/Libraries +Requires: openssl +%description devel +The OpenSSL Project is a collaborative effort to develop a robust, +commercial-grade, fully featured, and Open Source toolkit implementing the +Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) +protocols with full-strength cryptography world-wide. The project is +managed by a worldwide community of volunteers that use the Internet to +communicate, plan, and develop the OpenSSL tookit and its related +documentation. + +OpenSSL is based on the excellent SSLeay library developed from Eric A. +Young and Tim J. Hudson. The OpenSSL toolkit is licensed under an +Apache-style licence, which basically means that you are free to get and +use it for commercial and non-commercial purposes. + +This package contains the the OpenSSL cryptography and SSL/TLS +static libraries and header files required when developing applications. + +%package doc +Summary: OpenSSL miscellaneous files +Group: Documentation +Requires: openssl +%description doc +The OpenSSL Project is a collaborative effort to develop a robust, +commercial-grade, fully featured, and Open Source toolkit implementing the +Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) +protocols with full-strength cryptography world-wide. The project is +managed by a worldwide community of volunteers that use the Internet to +communicate, plan, and develop the OpenSSL tookit and its related +documentation. + +OpenSSL is based on the excellent SSLeay library developed from Eric A. +Young and Tim J. Hudson. The OpenSSL toolkit is licensed under an +Apache-style licence, which basically means that you are free to get and +use it for commercial and non-commercial purposes. + +This package contains the the OpenSSL cryptography and SSL/TLS extra +documentation and POD files from which the man pages were produced. + +%prep + +%setup -q + +%build + +%define CONFIG_FLAGS -DSSL_ALLOW_ADH --prefix=/usr + +perl util/perlpath.pl /usr/bin/perl + +%ifarch i386 i486 i586 i686 +./Configure %{CONFIG_FLAGS} --openssldir=%{openssldir} linux-elf shared +%endif +%ifarch ppc +./Configure %{CONFIG_FLAGS} --openssldir=%{openssldir} linux-ppc shared +%endif +%ifarch alpha +./Configure %{CONFIG_FLAGS} --openssldir=%{openssldir} linux-alpha shared +%endif +LD_LIBRARY_PATH=`pwd` make +LD_LIBRARY_PATH=`pwd` make rehash +LD_LIBRARY_PATH=`pwd` make test + +%install +rm -rf $RPM_BUILD_ROOT +make install MANDIR=/usr/man INSTALL_PREFIX="$RPM_BUILD_ROOT" + +# Rename manpages +for x in $RPM_BUILD_ROOT/usr/man/man*/* + do mv ${x} ${x}ssl +done + +# Install RSAref stuff +install -m644 rsaref/rsaref.h $RPM_BUILD_ROOT/usr/include/openssl +install -m644 libRSAglue.a $RPM_BUILD_ROOT/usr/lib + +# Make backwards-compatibility symlink to ssleay +ln -s /usr/bin/openssl $RPM_BUILD_ROOT/usr/bin/ssleay + +# Install shared libs +install -m644 libcrypto.a $RPM_BUILD_ROOT/usr/lib +install -m755 libcrypto.so.%{libmaj}.%{libmin}.%{librel} $RPM_BUILD_ROOT/usr/lib +install -m644 libssl.a $RPM_BUILD_ROOT/usr/lib +install -m755 libssl.so.%{libmaj}.%{libmin}.%{librel} $RPM_BUILD_ROOT/usr/lib +( + cd $RPM_BUILD_ROOT/usr/lib + ln -s libcrypto.so.%{libmaj}.%{libmin}.%{librel} libcrypto.so.%{libmaj} + ln -s libcrypto.so.%{libmaj}.%{libmin}.%{librel} libcrypto.so + ln -s libssl.so.%{libmaj}.%{libmin}.%{librel} libssl.so.%{libmaj} + ln -s libssl.so.%{libmaj}.%{libmin}.%{librel} libssl.so +) + +%clean +rm -rf $RPM_BUILD_ROOT + +%files +%defattr(0644,root,root,0755) +%doc CHANGES CHANGES.SSLeay LICENSE NEWS README + +%attr(0755,root,root) /usr/bin/* +%attr(0755,root,root) /usr/lib/*.so* +%attr(0755,root,root) %{openssldir}/misc/* +%attr(0644,root,root) /usr/man/man[157]/* + +%config %attr(0644,root,root) %{openssldir}/openssl.cnf +%dir %attr(0755,root,root) %{openssldir}/certs +%dir %attr(0755,root,root) %{openssldir}/lib +%dir %attr(0755,root,root) %{openssldir}/misc +%dir %attr(0750,root,root) %{openssldir}/private + +%files devel +%doc CHANGES CHANGES.SSLeay LICENSE NEWS README + +%defattr(0644,root,root,0755) +%attr(0644,root,root) /usr/lib/*.a +%attr(0644,root,root) /usr/include/openssl/* +%attr(0644,root,root) /usr/man/man[3]/* + +%files doc +%doc CHANGES CHANGES.SSLeay LICENSE NEWS README +%doc doc + +%post +ldconfig + +%postun +ldconfig + +%changelog +* Thu Sep 14 2000 Richard Levitte +- Changed to adapt to the new (supported) way of making shared libraries +- Installs all static libraries, not just libRSAglue.a +- Extra documents now end up in a separate document package +* Sun Feb 27 2000 Damien Miller +- Merged patches to spec +- Updated to 0.9.5beta2 (now with manpages) +* Sat Feb 5 2000 Michal Jaegermann +- added 'linux-alpha' to configuration +- fixed nasty absolute links +* Tue Jan 25 2000 Bennett Todd +- Added -DSSL_ALLOW_ADH, bumped Release to 4 +* Thu Oct 14 1999 Damien Miller +- Set default permissions +- Removed documentation from devel sub-package +* Thu Sep 30 1999 Damien Miller +- Added "make test" stage +- GPG signed +* Tue Sep 10 1999 Damien Miller +- Updated to version 0.9.4 +* Tue May 25 1999 Damien Miller +- Updated to version 0.9.3 +- Added attributes for all files +- Paramatised openssl directory +* Sat Mar 20 1999 Carlo M. Arenas Belon +- Added "official" bnrec patch and taking other out +- making a link from ssleay to openssl binary +- putting all changelog together on SPEC file +* Fri Mar 5 1999 Henri Gomez +- Added bnrec patch +* Tue Dec 29 1998 Jonathan Ruano +- minimum spec and patches changes for openssl +- modified for openssl sources +* Sat Aug 8 1998 Khimenko Victor +- shared library creating process honours $RPM_OPT_FLAGS +- shared libarry supports threads (as well as static library) +* Wed Jul 22 1998 Khimenko Victor +- building of shared library completely reworked +* Tue Jul 21 1998 Khimenko Victor +- RPM is BuildRoot'ed +* Tue Feb 10 1998 Khimenko Victor +- all stuff is moved out of /usr/local