From fb29c0f0704a488b9e282caf7643cde0119223b8 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Tue, 18 Apr 2017 17:53:54 +0100 Subject: [PATCH] Document the new SSL_CTX_use_serverinfo_ex() function Also document other releated changes to the serverinfo capability. Reviewed-by: Rich Salz (Merged from https://github.com/openssl/openssl/pull/3298) --- doc/man3/SSL_CTX_use_serverinfo.pod | 46 ++++++++++++++++++++++------- 1 file changed, 35 insertions(+), 11 deletions(-) diff --git a/doc/man3/SSL_CTX_use_serverinfo.pod b/doc/man3/SSL_CTX_use_serverinfo.pod index bd496ff8c5..b1412432f6 100644 --- a/doc/man3/SSL_CTX_use_serverinfo.pod +++ b/doc/man3/SSL_CTX_use_serverinfo.pod @@ -2,12 +2,19 @@ =head1 NAME -SSL_CTX_use_serverinfo, SSL_CTX_use_serverinfo_file - use serverinfo extension +SSL_CTX_use_serverinfo_ex, +SSL_CTX_use_serverinfo, +SSL_CTX_use_serverinfo_file +- use serverinfo extension =head1 SYNOPSIS #include + int SSL_CTX_use_serverinfo_ex(SSL_CTX *ctx, unsigned int version, + const unsigned char *serverinfo, + size_t serverinfo_length); + int SSL_CTX_use_serverinfo(SSL_CTX *ctx, const unsigned char *serverinfo, size_t serverinfo_length); @@ -15,20 +22,37 @@ SSL_CTX_use_serverinfo, SSL_CTX_use_serverinfo_file - use serverinfo extension =head1 DESCRIPTION -These functions load "serverinfo" TLS ServerHello Extensions into the SSL_CTX. -A "serverinfo" extension is returned in response to an empty ClientHello +These functions load "serverinfo" TLS extensions into the SSL_CTX. A +"serverinfo" extension is returned in response to an empty ClientHello Extension. -SSL_CTX_use_serverinfo() loads one or more serverinfo extensions from -a byte array into B. The extensions must be concatenated into a -sequence of bytes. Each extension must consist of a 2-byte Extension Type, -a 2-byte length, and then length bytes of extension_data. +SSL_CTX_use_serverinfo_ex() loads one or more serverinfo extensions from +a byte array into B. The B parameter specifies the format of the +byte array provided in B<*serverinfo> which is of length B. + +If B is B then the extensions in the array must +consist of a 4-byte context, a 2-byte Extension Type, a 2-byte length, and then +length bytes of extension_data. The context and type values have the same +meaning as for L. + +If B is B then the extensions in the array must +consist of a 2-byte Extension Type, a 2-byte length, and then length bytes of +extension_data. The type value has the same meaning as for +L. The following default context value will be used +in this case: + + SSL_EXT_TLS1_2_AND_BELOW_ONLY | SSL_EXT_CLIENT_HELLO + | SSL_EXT_TLS1_2_SERVER_HELLO | SSL_EXT_IGNORE_ON_RESUMPTION + +SSL_CTX_use_serverinfo() does the same thing as SSL_CTX_use_serverinfo_ex() +except that there is no B parameter so a default version of +SSL_SERVERINFOV1 is used instead. SSL_CTX_use_serverinfo_file() loads one or more serverinfo extensions from B into B. The extensions must be in PEM format. Each extension -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 ". +must be in a format as described above for SSL_CTX_use_serverinfo_ex(). Each +PEM extension name must begin with the phrase "BEGIN SERVERINFOV2 FOR " for +SSL_SERVERINFOV2 data or "BEGIN SERVERINFO FOR " for SSL_SERVERINFOV1 data. If more than one certificate (RSA/DSA) is installed using SSL_CTX_use_certificate(), the serverinfo extension will be loaded into the @@ -46,7 +70,7 @@ the reason. =head1 COPYRIGHT -Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2013-2017 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 -- 2.25.1