aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorJung-uk Kim <jkim@FreeBSD.org>2016-05-03 18:00:27 +0000
committerJung-uk Kim <jkim@FreeBSD.org>2016-05-03 18:00:27 +0000
commit57f1256b1a087adbdf8e5c080dd9ed7975de939a (patch)
tree2dd85c58056a364765d9ae59d6a1774d41f88523 /doc
parent9aeed18ad799c20d3accf6e1535817538dc983f6 (diff)
downloadsrc-57f1256b1a087adbdf8e5c080dd9ed7975de939a.tar.gz
src-57f1256b1a087adbdf8e5c080dd9ed7975de939a.zip
Import OpenSSL 1.0.2h.vendor/openssl/1.0.2h
Notes
Notes: svn path=/vendor-crypto/openssl/dist/; revision=298991 svn path=/vendor-crypto/openssl/1.0.2h/; revision=298992; tag=vendor/openssl/1.0.2h
Diffstat (limited to 'doc')
-rw-r--r--doc/apps/ciphers.pod2
-rw-r--r--doc/apps/ocsp.pod2
-rw-r--r--doc/crypto/EVP_EncodeInit.pod127
-rw-r--r--doc/crypto/evp.pod5
-rw-r--r--doc/ssl/SSL_CTX_set_alpn_select_cb.pod126
-rw-r--r--doc/ssl/SSL_CTX_use_serverinfo.pod8
6 files changed, 268 insertions, 2 deletions
diff --git a/doc/apps/ciphers.pod b/doc/apps/ciphers.pod
index 9643b4d48ca8..9224557255ed 100644
--- a/doc/apps/ciphers.pod
+++ b/doc/apps/ciphers.pod
@@ -107,7 +107,7 @@ The following is a list of all permitted cipher strings and their meanings.
The default cipher list.
This is determined at compile time and is normally
-B<ALL:!EXPORT:!aNULL:!eNULL:!SSLv2>.
+B<ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2>.
When used, this must be the first cipherstring specified.
=item B<COMPLEMENTOFDEFAULT>
diff --git a/doc/apps/ocsp.pod b/doc/apps/ocsp.pod
index 4639502a0fb1..9833f0813ef1 100644
--- a/doc/apps/ocsp.pod
+++ b/doc/apps/ocsp.pod
@@ -29,7 +29,7 @@ B<openssl> B<ocsp>
[B<-path>]
[B<-CApath dir>]
[B<-CAfile file>]
-[B<-no_alt_chains>]]
+[B<-no_alt_chains>]
[B<-VAfile file>]
[B<-validity_period n>]
[B<-status_age n>]
diff --git a/doc/crypto/EVP_EncodeInit.pod b/doc/crypto/EVP_EncodeInit.pod
new file mode 100644
index 000000000000..c6f12674f632
--- /dev/null
+++ b/doc/crypto/EVP_EncodeInit.pod
@@ -0,0 +1,127 @@
+=pod
+
+=head1 NAME
+
+EVP_EncodeInit, EVP_EncodeUpdate, EVP_EncodeFinal, EVP_EncodeBlock,
+EVP_DecodeInit, EVP_DecodeUpdate, EVP_DecodeFinal, EVP_DecodeBlock - EVP base 64
+encode/decode routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ void EVP_EncodeInit(EVP_ENCODE_CTX *ctx);
+ void EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl,
+ const unsigned char *in, int inl);
+ void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl);
+ int EVP_EncodeBlock(unsigned char *t, const unsigned char *f, int n);
+
+ void EVP_DecodeInit(EVP_ENCODE_CTX *ctx);
+ int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl,
+ const unsigned char *in, int inl);
+ int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned
+ char *out, int *outl);
+ int EVP_DecodeBlock(unsigned char *t, const unsigned char *f, int n);
+
+=head1 DESCRIPTION
+
+The EVP encode routines provide a high level interface to base 64 encoding and
+decoding. Base 64 encoding converts binary data into a printable form that uses
+the characters A-Z, a-z, 0-9, "+" and "/" to represent the data. For every 3
+bytes of binary data provided 4 bytes of base 64 encoded data will be produced
+plus some occasional newlines (see below). If the input data length is not a
+multiple of 3 then the output data will be padded at the end using the "="
+character.
+
+Encoding of binary data is performed in blocks of 48 input bytes (or less for
+the final block). For each 48 byte input block encoded 64 bytes of base 64 data
+is output plus an additional newline character (i.e. 65 bytes in total). The
+final block (which may be less than 48 bytes) will output 4 bytes for every 3
+bytes of input. If the data length is not divisible by 3 then a full 4 bytes is
+still output for the final 1 or 2 bytes of input. Similarly a newline character
+will also be output.
+
+EVP_EncodeInit() initialises B<ctx> for the start of a new encoding operation.
+
+EVP_EncodeUpdate() encode B<inl> bytes of data found in the buffer pointed to by
+B<in>. The output is stored in the buffer B<out> and the number of bytes output
+is stored in B<*outl>. It is the caller's responsibility to ensure that the
+buffer at B<out> is sufficiently large to accommodate the output data. Only full
+blocks of data (48 bytes) will be immediately processed and output by this
+function. Any remainder is held in the B<ctx> object and will be processed by a
+subsequent call to EVP_EncodeUpdate() or EVP_EncodeFinal(). To calculate the
+required size of the output buffer add together the value of B<inl> with the
+amount of unprocessed data held in B<ctx> and divide the result by 48 (ignore
+any remainder). This gives the number of blocks of data that will be processed.
+Ensure the output buffer contains 65 bytes of storage for each block, plus an
+additional byte for a NUL terminator. EVP_EncodeUpdate() may be called
+repeatedly to process large amounts of input data. In the event of an error
+EVP_EncodeUpdate() will set B<*outl> to 0.
+
+EVP_EncodeFinal() must be called at the end of an encoding operation. It will
+process any partial block of data remaining in the B<ctx> object. The output
+data will be stored in B<out> and the length of the data written will be stored
+in B<*outl>. It is the caller's responsibility to ensure that B<out> is
+sufficiently large to accommodate the output data which will never be more than
+65 bytes plus an additional NUL terminator (i.e. 66 bytes in total).
+
+EVP_EncodeBlock() encodes a full block of input data in B<f> and of length
+B<dlen> and stores it in B<t>. For every 3 bytes of input provided 4 bytes of
+output data will be produced. If B<dlen> is not divisible by 3 then the block is
+encoded as a final block of data and the output is padded such that it is always
+divisible by 4. Additionally a NUL terminator character will be added. For
+example if 16 bytes of input data is provided then 24 bytes of encoded data is
+created plus 1 byte for a NUL terminator (i.e. 25 bytes in total). The length of
+the data generated I<without> the NUL terminator is returned from the function.
+
+EVP_DecodeInit() initialises B<ctx> for the start of a new decoding operation.
+
+EVP_DecodeUpdate() decodes B<inl> characters of data found in the buffer pointed
+to by B<in>. The output is stored in the buffer B<out> and the number of bytes
+output is stored in B<*outl>. It is the caller's responsibility to ensure that
+the buffer at B<out> is sufficiently large to accommodate the output data. This
+function will attempt to decode as much data as possible in 4 byte chunks. Any
+whitespace, newline or carriage return characters are ignored. Any partial chunk
+of unprocessed data (1, 2 or 3 bytes) that remains at the end will be held in
+the B<ctx> object and processed by a subsequent call to EVP_DecodeUpdate(). If
+any illegal base 64 characters are encountered or if the base 64 padding
+character "=" is encountered in the middle of the data then the function returns
+-1 to indicate an error. A return value of 0 or 1 indicates successful
+processing of the data. A return value of 0 additionally indicates that the last
+input data characters processed included the base 64 padding character "=" and
+therefore no more non-padding character data is expected to be processed. For
+every 4 valid base 64 bytes processed (ignoring whitespace, carriage returns and
+line feeds), 3 bytes of binary output data will be produced (or less at the end
+of the data where the padding character "=" has been used).
+
+EVP_DecodeFinal() must be called at the end of a decoding operation. If there
+is any unprocessed data still in B<ctx> then the input data must not have been
+a multiple of 4 and therefore an error has occurred. The function will return -1
+in this case. Otherwise the function returns 1 on success.
+
+EVP_DecodeBlock() will decode the block of B<n> characters of base 64 data
+contained in B<f> and store the result in B<t>. Any leading whitespace will be
+trimmed as will any trailing whitespace, newlines, carriage returns or EOF
+characters. After such trimming the length of the data in B<f> must be divisbile
+by 4. For every 4 input bytes exactly 3 output bytes will be produced. The
+output will be padded with 0 bits if necessary to ensure that the output is
+always 3 bytes for every 4 input bytes. This function will return the length of
+the data decoded or -1 on error.
+
+=head1 RETURN VALUES
+
+EVP_EncodeBlock() returns the number of bytes encoded excluding the NUL
+terminator.
+
+EVP_DecodeUpdate() returns -1 on error and 0 or 1 on success. If 0 is returned
+then no more non-padding base 64 characters are expected.
+
+EVP_DecodeFinal() returns -1 on error or 1 on success.
+
+EVP_DecodeBlock() returns the length of the data decoded or -1 on error.
+
+=head1 SEE ALSO
+
+L<evp(3)>
+
+=cut
diff --git a/doc/crypto/evp.pod b/doc/crypto/evp.pod
index 29fab9fd5173..303cd95a70d1 100644
--- a/doc/crypto/evp.pod
+++ b/doc/crypto/evp.pod
@@ -61,6 +61,10 @@ based encryption. Careful selection of the parameters will provide a PKCS#5 PBKD
implementation. However, new applications should not typically use this (preferring, for example,
PBKDF2 from PCKS#5).
+The L<B<EVP_Encode>I<...>|EVP_EncodeInit(3)> and
+L<B<EVP_Decode>I<...>|EVP_EncodeInit(3)> functions implement base 64 encoding
+and decoding.
+
Algorithms are loaded with L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>.
All the symmetric algorithms (ciphers), digests and asymmetric algorithms
@@ -86,6 +90,7 @@ L<EVP_SealInit(3)|EVP_SealInit(3)>,
L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)>,
L<EVP_SignInit(3)|EVP_SignInit(3)>,
L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>,
+L<EVP_EncodeInit(3)>,
L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>,
L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)>,
L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>,
diff --git a/doc/ssl/SSL_CTX_set_alpn_select_cb.pod b/doc/ssl/SSL_CTX_set_alpn_select_cb.pod
new file mode 100644
index 000000000000..80ba8ab9c499
--- /dev/null
+++ b/doc/ssl/SSL_CTX_set_alpn_select_cb.pod
@@ -0,0 +1,126 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb,
+SSL_select_next_proto, SSL_get0_alpn_selected - handle application layer
+protocol negotiation (ALPN)
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
+ unsigned protos_len);
+ int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
+ unsigned protos_len);
+ void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
+ int (*cb) (SSL *ssl,
+ const unsigned char **out,
+ unsigned char *outlen,
+ const unsigned char *in,
+ unsigned int inlen,
+ void *arg), void *arg);
+ int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
+ const unsigned char *server,
+ unsigned int server_len,
+ const unsigned char *client,
+ unsigned int client_len)
+ void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
+ unsigned int *len);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to
+set the list of protocols available to be negotiated. The B<protos> must be in
+protocol-list format, described below. The length of B<protos> is specified in
+B<protos_len>.
+
+SSL_CTX_set_alpn_select_cb() sets the application callback B<cb> used by a
+server to select which protocol to use for the incoming connection. When B<cb>
+is NULL, ALPN is not used. The B<arg> value is a pointer which is passed to
+the application callback.
+
+B<cb> is the application defined callback. The B<in>, B<inlen> parameters are a
+vector in protocol-list format. The value of the B<out>, B<outlen> vector
+should be set to the value of a single protocol selected from the B<in>,
+B<inlen> vector. The B<arg> parameter is the pointer set via
+SSL_CTX_set_alpn_select_cb().
+
+SSL_select_next_proto() is a helper function used to select protocols. It
+implements the standard protocol selection. It is expected that this function
+is called from the application callback B<cb>. The protocol data in B<server>,
+B<server_len> and B<client>, B<client_len> must be in the protocol-list format
+described below. The first item in the B<server>, B<server_len> list that
+matches an item in the B<client>, B<client_len> list is selected, and returned
+in B<out>, B<outlen>. The B<out> value will point into either B<server> or
+B<client>, so it should be copied immediately. If no match is found, the first
+item in B<client>, B<client_len> is returned in B<out>, B<outlen>. This
+function can also be used in the NPN callback.
+
+SSL_get0_alpn_selected() returns a pointer to the selected protocol in B<data>
+with length B<len>. It is not NUL-terminated. B<data> is set to NULL and B<len>
+is set to 0 if no protocol has been selected. B<data> must not be freed.
+
+=head1 NOTES
+
+The protocol-lists must be in wire-format, which is defined as a vector of
+non-empty, 8-bit length-prefixed, byte strings. The length-prefix byte is not
+included in the length. Each string is limited to 255 bytes. A byte-string
+length of 0 is invalid. A truncated byte-string is invalid. The length of the
+vector is not in the vector itself, but in a separate variable.
+
+Example:
+
+ unsigned char vector[] = {
+ 6, 's', 'p', 'd', 'y', '/', '1',
+ 8, 'h', 't', 't', 'p', '/', '1', '.', '1'
+ };
+ unsigned int length = sizeof(vector);
+
+The ALPN callback is executed after the servername callback; as that servername
+callback may update the SSL_CTX, and subsequently, the ALPN callback.
+
+If there is no ALPN proposed in the ClientHello, the ALPN callback is not
+invoked.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and
+non-0 on failure. WARNING: these functions reverse the return value convention.
+
+SSL_select_next_proto() returns one of the following:
+
+=over 4
+
+=item OPENSSL_NPN_NEGOTIATED
+
+A match was found and is returned in B<out>, B<outlen>.
+
+=item OPENSSL_NPN_NO_OVERLAP
+
+No match was found. The first item in B<client>, B<client_len> is returned in
+B<out>, B<outlen>.
+
+=back
+
+The ALPN select callback B<cb>, must return one of the following:
+
+=over 4
+
+=item SSL_TLSEXT_ERR_OK
+
+ALPN protocol selected.
+
+=item SSL_TLSEXT_ERR_NOACK
+
+ALPN protocol not selected.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
+L<SSL_CTX_set_tlsext_servername_arg(3)>
+
+=cut
diff --git a/doc/ssl/SSL_CTX_use_serverinfo.pod b/doc/ssl/SSL_CTX_use_serverinfo.pod
index 318e052e2b25..caeb28de765b 100644
--- a/doc/ssl/SSL_CTX_use_serverinfo.pod
+++ b/doc/ssl/SSL_CTX_use_serverinfo.pod
@@ -30,6 +30,14 @@ must consist of a 2-byte Extension Type, a 2-byte length, and then length
bytes of extension_data. Each PEM extension name must begin with the phrase
"BEGIN SERVERINFO FOR ".
+If more than one certificate (RSA/DSA) is installed using
+SSL_CTX_use_certificate(), the serverinfo extension will be loaded into the
+last certificate installed. If e.g. the last item was a RSA certificate, the
+loaded serverinfo extension data will be loaded for that certificate. To
+use the serverinfo extension for multiple certificates,
+SSL_CTX_use_serverinfo() needs to be called multiple times, once B<after>
+each time a certificate is loaded.
+
=head1 NOTES
=head1 RETURN VALUES