Add BIO_bind function to bind local address for a socket.

Add -bind option to s_client application to allow specification of
local address for connection.

Reviewed-by: Andy Polyakov <appro@openssl.org>
Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5272)

2 files changed, 18 insertions, 3 deletions

diff --git a/doc/man1/s_client.pod b/doc/man1/s_client.pod
index 8d8eac76f4..6e47140f41 100644
--- a/doc/man1/s_client.pod
+++ b/doc/man1/s_client.pod
@@ -10,6 +10,7 @@ s_client - SSL/TLS client program
 B<openssl> B<s_client>
 [B<-help>]
 [B<-connect host:port>]
+[B<-bind host:port>]
 [B<-proxy host:port>]
 [B<-unix path>]
 [B<-4>]
@@ -147,6 +148,12 @@ select the host and port using the optional target positional argument instead.
 If neither this nor the target positonal argument are specified then an attempt
 is made to connect to the local host on port 4433.
 
+=item B<-bind host:port>]
+
+This specifies the host address and or port to bind as the source for the
+connection.  For Unix-domain sockets the port is ignored and the host is
+used as the source socket address.
+
 =item B<-proxy host:port>
 
 When used with the B<-connect> flag, the program uses the host and port
@@ -686,6 +693,9 @@ applications should B<not> do this as it makes them vulnerable to a MITM
 attack. This behaviour can be changed by with the B<-verify_return_error>
 option: any verify errors are then returned aborting the handshake.
 
+The B<-bind> option may be useful if the server or a firewall requires
+connections to come from some particular address and or port.
+
 =head1 BUGS
 
 Because this program has a lot of options and also because some of the
diff --git a/doc/man3/BIO_connect.pod b/doc/man3/BIO_connect.pod
index 91dcab1178..454832e7e0 100644
--- a/doc/man3/BIO_connect.pod
+++ b/doc/man3/BIO_connect.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-BIO_socket, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket - BIO
+BIO_socket, BIO_bind, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket - BIO
 socket communication setup routines
 
 =head1 SYNOPSIS
@@ -10,6 +10,7 @@ socket communication setup routines
  #include <openssl/bio.h>
 
  int BIO_socket(int domain, int socktype, int protocol, int options);
+ int BIO_bind(int sock, const BIO_ADDR *addr, int options);
  int BIO_connect(int sock, const BIO_ADDR *addr, int options);
  int BIO_listen(int sock, const BIO_ADDR *addr, int options);
  int BIO_accept_ex(int accept_sock, BIO_ADDR *peer, int options);
@@ -21,6 +22,10 @@ BIO_socket() creates a socket in the domain B<domain>, of type
 B<socktype> and B<protocol>.  Socket B<options> are currently unused,
 but is present for future use.
 
+BIO_bind() binds the source address and service to a socket and
+may be useful before calling BIO_connect().  The options may include
+B<BIO_SOCK_REUSADDR>, which is described in L</FLAGS> below.
+
 BIO_connect() connects B<sock> to the address and service given by
 B<addr>.  Connection B<options> may be zero or any combination of
 B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK> and B<BIO_SOCK_NODELAY>.
@@ -81,7 +86,7 @@ BIO_socket() returns the socket number on success or B<INVALID_SOCKET>
 (-1) on error.  When an error has occurred, the OpenSSL error stack
 will hold the error data and errno has the system error.
 
-BIO_connect() and BIO_listen() return 1 on success or 0 on error.
+BIO_bind(), BIO_connect() and BIO_listen() return 1 on success or 0 on error.
 When an error has occurred, the OpenSSL error stack will hold the error
 data and errno has the system error.
 
@@ -102,7 +107,7 @@ L<BIO_ADDR(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy