diff options
Diffstat (limited to 'crypto/openssl/doc')
| -rw-r--r-- | crypto/openssl/doc/apps/ciphers.pod | 2 | ||||
| -rw-r--r-- | crypto/openssl/doc/apps/ocsp.pod | 2 | ||||
| -rw-r--r-- | crypto/openssl/doc/crypto/EVP_EncodeInit.pod | 127 | ||||
| -rw-r--r-- | crypto/openssl/doc/crypto/evp.pod | 5 | ||||
| -rw-r--r-- | crypto/openssl/doc/ssl/SSL_CTX_set_alpn_select_cb.pod | 126 | ||||
| -rw-r--r-- | crypto/openssl/doc/ssl/SSL_CTX_use_serverinfo.pod | 8 |
6 files changed, 268 insertions, 2 deletions
diff --git a/crypto/openssl/doc/apps/ciphers.pod b/crypto/openssl/doc/apps/ciphers.pod index 9643b4d..9224557 100644 --- a/crypto/openssl/doc/apps/ciphers.pod +++ b/crypto/openssl/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/crypto/openssl/doc/apps/ocsp.pod b/crypto/openssl/doc/apps/ocsp.pod index 4639502..9833f08 100644 --- a/crypto/openssl/doc/apps/ocsp.pod +++ b/crypto/openssl/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/crypto/openssl/doc/crypto/EVP_EncodeInit.pod b/crypto/openssl/doc/crypto/EVP_EncodeInit.pod new file mode 100644 index 0000000..c6f1267 --- /dev/null +++ b/crypto/openssl/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/crypto/openssl/doc/crypto/evp.pod b/crypto/openssl/doc/crypto/evp.pod index 29fab9f..303cd95 100644 --- a/crypto/openssl/doc/crypto/evp.pod +++ b/crypto/openssl/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/crypto/openssl/doc/ssl/SSL_CTX_set_alpn_select_cb.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_alpn_select_cb.pod new file mode 100644 index 0000000..80ba8ab --- /dev/null +++ b/crypto/openssl/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/crypto/openssl/doc/ssl/SSL_CTX_use_serverinfo.pod b/crypto/openssl/doc/ssl/SSL_CTX_use_serverinfo.pod index 318e052..caeb28d 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_use_serverinfo.pod +++ b/crypto/openssl/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 |
