From patchwork Wed May 24 16:27:19 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Watson X-Patchwork-Id: 9746389 X-Patchwork-Delegate: herbert@gondor.apana.org.au Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 5697E60209 for ; Wed, 24 May 2017 16:27:59 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 46677287F5 for ; Wed, 24 May 2017 16:27:59 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 3AF7B2899F; Wed, 24 May 2017 16:27:59 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.0 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 6836F287F5 for ; Wed, 24 May 2017 16:27:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1031123AbdEXQ1x (ORCPT ); Wed, 24 May 2017 12:27:53 -0400 Received: from mx0b-00082601.pphosted.com ([67.231.153.30]:48396 "EHLO mx0a-00082601.pphosted.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1032529AbdEXQ1m (ORCPT ); Wed, 24 May 2017 12:27:42 -0400 Received: from pps.filterd (m0089730.ppops.net [127.0.0.1]) by m0089730.ppops.net (8.16.0.20/8.16.0.20) with SMTP id v4OGNn1d019705; Wed, 24 May 2017 09:27:29 -0700 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=fb.com; h=date : from : to : cc : subject : message-id : references : mime-version : content-type : in-reply-to; s=facebook; bh=IuAPmOq2KrNUSbALB9YU2jJ2ZnJfWA/pJ8fznj4iPxY=; b=VsHBK9fpUQJ1dpt9CjoiEzot1Ba0fZOrVO49CMBaag6O+zZZzPP2zP9LyltAIoWsNOo4 QtgiEVD4KqQ1FDzBmv9vxZ7s3x3Iu6FeVjbXg3TIk76S1JZRWxvxDuenHLfgdNzaGvyC ykHWHQ3qKepXMcTnD56s0fGNY6CHWdi4tYI= Received: from mail.thefacebook.com ([199.201.64.23]) by m0089730.ppops.net with ESMTP id 2an80fh6gj-1 (version=TLSv1 cipher=ECDHE-RSA-AES256-SHA bits=256 verify=NOT); Wed, 24 May 2017 09:27:29 -0700 Received: from NAM01-BN3-obe.outbound.protection.outlook.com (192.168.54.28) by o365-in.thefacebook.com (192.168.16.15) with Microsoft SMTP Server (TLS) id 14.3.319.2; Wed, 24 May 2017 09:27:26 -0700 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=fb.onmicrosoft.com; s=selector1-fb-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=IuAPmOq2KrNUSbALB9YU2jJ2ZnJfWA/pJ8fznj4iPxY=; b=akqmfcg4gVev6mau7OSy/CR1m0iTNdWP83u0Ydm2s2KotkW3VZK1O197GWXIRgFW4t4z/t1bss7h3jffea2QNAEAFk2EGr40mS6Qh1HxJmaTW+O4xJXZJVQ3wZfQ3Mv0j+2xmZAM32HWR+BItTZDQOKdZshLiXLlJfNOzApZw38= Authentication-Results: mellanox.com; dkim=none (message not signed) header.d=none; mellanox.com; dmarc=none action=none header.from=fb.com; Received: from localhost (2620:10d:c090:180::df6b) by MWHPR15MB1760.namprd15.prod.outlook.com (10.174.255.13) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256_P256) id 15.1.1124.9; Wed, 24 May 2017 16:27:24 +0000 Date: Wed, 24 May 2017 09:27:19 -0700 From: Dave Watson To: Ilya Lesokhin , Aviad Yehezkel , Boris Pismenny , Liran Liss , Matan Barak , David Miller , , Tom Herbert , , , Hannes Frederic Sowa CC: Alexei Starovoitov , , Subject: [PATCH net-next 4/4] tls: Documentation Message-ID: <20170524162719.GA24240@davejwatson-mba.local> References: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.6.0 (2016-04-01) X-Originating-IP: [2620:10d:c090:180::df6b] X-ClientProxiedBy: BN6PR04CA0001.namprd04.prod.outlook.com (10.172.194.11) To MWHPR15MB1760.namprd15.prod.outlook.com (10.174.255.13) X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: MWHPR15MB1760: X-MS-Office365-Filtering-Correlation-Id: d91ac398-8ee2-4920-8080-08d4a2c1c2bb X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(22001)(201703131423075)(201703031133081); SRVR:MWHPR15MB1760; X-Microsoft-Exchange-Diagnostics: 1; MWHPR15MB1760; 3:hL6FBMQDRlH1afG8qdfhQnPsRAl1Q8YT183mRSTu0zVivnU/yJYqqhkOFgtF6l/eIcEU/TlazV8K5I0RK0k5hwO5XyBJ+H8+vCwFxz1R3I2tOhRSkKARoFw9YeXyAUDSrxbl7JRAOGpE3SR9dCPgO+wJgHKdHC/TPmqI6284WOmV9GUhNPlHHsII/ibUe3MCNq27Huk53ExUOSlyCEFXUIxKxYniR0y8V2ZsiVDRmjO/fsUhL5GeavGZzGWowDld+N49Rrw1jN6T3Ziw+BPH7sKy0Iirbqbebyw+wEGNqgTPNQwiVBgmnQV8Vtp0CHu/XENAor1ngI4Ii6vC/nvZzg==; 25:9v910ebF9JC+SiCCf8Yg18x5nFGtn0C50CwpgGqw0ilD5cNRVtDFfPjLMQRONT88ImZQ5J296JODOeeDGWBN5ZOCuM0HBgdA+s+U/ZxOS2c1hF0DSfLdW3KK3FhlM3rIn6u+Rtz/6CzM6IRpAV/I1sxv0DF3dFgMv8+jdwXBDZ2BJnuEVd7Vbdk2ek76KJsHu0i4wQcNSMv0AJ1JdAt4PWs81Mjb+S8cw51+i1EUZVrqGUE8OQO0JXbnrc+Z4tT4y+icEkpqdRe6l7KEse0RiVi4ieCVnAKCZeitJhMckkOPU8NfsLQUJWCuvaTPSYAgglKr82uYS/GtVRJqktYfwBSLbqqixPmR7UnlVytL4ZXol9aBPitG6/U+y63EJQx4l4k4aaVUiDgkBL7zaO7FgfZXoRCVVCn6wTRPSarhKZVYtcu1dNPb1FnaKnaIklWdSw0IUSW6kk7//4+SHNeGlojsOpZHqi7gag5ux3vnbYA= X-Microsoft-Exchange-Diagnostics: 1; MWHPR15MB1760; 31:KalX69FGJcSLEr5yPhSYK2X23BJBJlab/1QSqSKUD9NjE6Us8XK2HOAsmzYa4E3VAzmFk7c2DddWUGpNS+suTLTquaP9Jg0zMnpjgPjhnxfHATZY0sjUIszk46SotLKfcK1zNo2vsEdhE2Q/wZ7n4SVV/M4qPCmZZ2seuAMF82VHojoLwF2TDMZIXT92+9yQQy9aY8Z7D15LBd+FAaKDVLddH51xY5+mq8dkkVaQXqaCE+oTsF8AL7XeaTUZgGRIl92rZKLRwLaEE7Zud5uHLA==; 20:U/vVS8Ut8pNG9PgTKVfJEqH6cQo3E3TCZ1d+FsOJRABH7sTM47gmShF0VRW4gAzEUGZ1gL+lyTvZt+Qi7ZupKt6UGl61OI8kRJe2KXS5SZzQmU9dGrmh8za5TmJnV/mVAtAoYD1F3ZadSsxnC6+O37pZEuJWvxWVldci4M5K216b+yBVVrsggCl/mdzOaeKKPWuBuqvWVyh+ksk6ssA1u8kPwus56i3CUnGgDlszGI49zJKWD/IztF5uUuBNLQQOBbwNfAJfu9Zz6pux3t1uYXmih/N+1Hwu4jRqVFF8v0N9lEs2Gk1CKokY0qyirDq76ILn9BUzu4rCsP2lkIE3/2CYkfVZwFgtRa6xmsmImJXn28nVQrSaCgMj0Xrq92qseIRRT1UafAIm/WK1Sc3denLqkJli6046NNmLl8naStEMSBk1PYoUxb2sREwHSE1HUiPZKMbaI9uT5KONK5zv9Ey1skCord+GcTaOLK9A8w/VeQYAJfxLrYWjkJBJZHmt X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:(192374486261705)(67672495146484)(266576461109395); X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(6040450)(601004)(2401047)(8121501046)(5005006)(93006095)(93001095)(10201501046)(3002001)(6041248)(20161123564025)(20161123555025)(201703131423075)(201702281528075)(201703061421075)(201703061406153)(20161123558100)(20161123560025)(20161123562025)(6072148); SRVR:MWHPR15MB1760; BCL:0; PCL:0; RULEID:; SRVR:MWHPR15MB1760; X-Microsoft-Exchange-Diagnostics: 1; MWHPR15MB1760; 4:32uF0v3SkMk2J5wZRHnhvvzx3208XeAu6rOsJ2QcUPmMTOpwnvZTVUo1/D2xG537VNvu6pMX4RlKpaMjgBCYAgVl4jJTGeu1iwXIoL+yqccqq2voqNHpg1l5XdIWPkHLqtI2MQa17PL3QjCn9FGJ1Y4JrSsFDRWBEk7PBHFxI7glyOcwJ16thEyAkh4Dm+kIQmKh1ecbGFcjsHgP6OyPAbUswcCmmz7SMb0e2MGIu4nMX/qvCHbylZPZRWZLYZLMa847pFBilWcMJvYGXMJrJP2GfQhhQdIDe56oNB6klCTePoJkJ4xBauKT80DqJe6pUNZpEJK55hyVxUKv2J2xpDdFKrHWzo2GGk2IrCOMd/IoYzt7tKHNv45FlgO5qd1AxJKA6P8Cu5DuvQCuaGIr43hnBN3rwA+ikQUCR9jJ0olBvpPzIe22eO6Q4kchR2jQABPRKjdOLqDZtDHvJT0oB/ySXPnJZ2MA/mJULeI7ZrS1Xv1OIOv/fz3scGRAnrgCqJBpumYdRqziuIvVuZkq/CZSiixk2ldLcu+OzNGBgXmzA/sjQX86oJW4ADD/NTCa3571Bfw+BDoUEDN7E9KEiv8Ls7cyvTw5ccZvPY6xxQMxf+gpRgENl5UsYfu8/WTVmwLzpmv7iSoyziNvqJPpYhF6iSlHBPerwfXdbWDj92CNxISHOjHlbhzHeZTAAp0Viw6darfpb/8u7aOlLJbhNepqCuIzi3J3T07NBc95sQmJBHELX4ujC5a02lERmV980sIh6vzW25M9rYO8nBmVIMHytjMluqoF+8Yy2gGVq1v88avtnqOjks0m3VwxVHVd5PS0bgiRc0cQrc0zqGvm2XAXolkEAQRACkGFT7c2IInslUzg9EkpcvXyYgdhjqth6/KLTowiOdGLQ5vJbbdW1w== X-Forefront-PRVS: 031763BCAF X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10019020)(4630300001)(6069001)(6009001)(39400400002)(39850400002)(39410400002)(39450400003)(39840400002)(6666003)(86362001)(2950100002)(42186005)(25786009)(478600001)(6496005)(38730400002)(53936002)(76176999)(6486002)(4326008)(305945005)(5660300001)(50986999)(54356999)(76506005)(7736002)(9686003)(7416002)(33656002)(98436002)(81166006)(23726003)(1076002)(8676002)(6116002)(189998001)(47776003)(50466002)(2906002)(83506001)(4001350100001)(18370500001)(921003)(1121003); DIR:OUT; SFP:1102; SCL:1; SRVR:MWHPR15MB1760; H:localhost; FPR:; SPF:None; MLV:sfv; LANG:en; X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1; MWHPR15MB1760; 23:wSuTWRo3/WIXPY60QvLoQ27o7lWKLUmfIiYg0qPHO?= =?us-ascii?Q?ViS5AO54Ht2GJRRuc7TrLqJh5yMze/VRrxXYpnR3H/2rLQ6sXmQMMqCcQmJ/?= =?us-ascii?Q?pjk6kRvI/OwGBfEvv1rdRKYzB+KABX8QXGvhtydv8i9Xv1NEgQ/fzVCeuiQi?= =?us-ascii?Q?0Fp7xpPh9zTVBaF33fvbj7Brj7yImDI+ZnMYaRjl6YZCTSp00B+lA2VMQ58M?= =?us-ascii?Q?+SICqVSeTXrlWOdWinXvBevs28t9Cs0YpcnxuU1FfFXAE1SnMSmESG58ip5E?= =?us-ascii?Q?NjkmXSamrrbMNuylcEhLEj7y1JyBxPTf3XqphVASTAO6E94pZWTdW4raCbX2?= =?us-ascii?Q?xSSXzuDqHV/5ssFPb88MiZ4UdnEhSCB94rGZgqKVsWgbGEUyRpRweWKTP3q3?= =?us-ascii?Q?wgVbcdVqcPpB8M/vVyu3FN47Te/hZMRmyBmYJHNngY0uN76Lwehc7LEfXc2B?= =?us-ascii?Q?ork4XuFprZq4U5BMMHTg1nub09vpzW0wgs4zTwpx8l5Kqjzq1+1WEz+DDxJA?= =?us-ascii?Q?ea9lrQoSJSa4rvy++8L5mD8xpDKGblGlyNZ/h5x5IPd/Sj0ASGbXejoJfOUf?= =?us-ascii?Q?jPxU4x56Vby7QDy4k9OGoxAUMQNxWruYTG2SG+o433xR0CQh3n0dWyT8OkTX?= =?us-ascii?Q?Pel8fkE/NJ2nghzzWDEkf22Si24NFqLGhq7kGRb9S8UmsgEc1wdf+0bb5HAM?= =?us-ascii?Q?zYMwsXudsRYxLkPHYbMYq5mKd219Jn3zXhhiDdILTraRgFpAxzHBPm51uw2Y?= =?us-ascii?Q?APYXNhwgkW8/5Gp2MX6QxKG7aGZMGj+UyaC4Bjz2iwTL4oh38Vdy9PSUWbgl?= =?us-ascii?Q?15+dICuW5qopN52RYGM6Z/ICsbKVBp3igpu+YV/ajHmBC8hiNq3guVsONPP/?= =?us-ascii?Q?+Gtw/vb7Rs0/3Xi/2qCz86eWmjxBBsftutCUVb3r3kyAhsIphO9nQSZ0+pxh?= =?us-ascii?Q?vE5niue2HgGN6nruHxazmuhBLZ5FPALMYs652VbD0fJObts5frYKGwjAZcqv?= =?us-ascii?Q?W8nURqorx9SPWE+iE8fMo/srPvqv18AM4SmePW43jt2Zp3yhWwSoxAX4ZX2G?= =?us-ascii?Q?NaXvGA6uI8SHdcelB7UgXzSnxo5JsjWdDbjIXO9ZO/O/A3hpw=3D=3D?= X-Microsoft-Exchange-Diagnostics: 1; MWHPR15MB1760; 6:CeIh1IJfFB50nMfTx5apx+I4rDXbzneNtNwOU21EAawPqjO2NC6L9jdtIe6cjij9cGhZYoJV3un/jp3SVUY8eIsaEq1qdfufpD6mR7FUdyJ+WxYICjskBua2Ih2BHzy7td0JJQ/GK/rLUpKDkGtK9/oPULLeScoMWXGFq/4TMJbA4Mk+7LukUQiqrwIUEucXmTg0bA1OJ576HHTZaccpjGlbqdU4/NETBwap2kNug8Pnz1higGzFEX4woX1aGv8IZ30MI/wtZVSb7F1xSQe5+kokMbvkb+kHmVBh9iACezFwx8AOoYSf3tMiUPfRMq9Iu/0+ByfLf485mgBOfcjavp2GV/HzvfABqWQp3/F4Sow/M5UeUfryYDpFAvRpGkhA+K1IEE18/UpMwLJEb2kO92XjzVTxIJrrzlJ2Lc3KvzpnEcaU13KFnDblM8xqk11SpimrLLoT95E91MfZei2tjwe/rkAeQCGxpwbtYbpexx5adyimJQCz6zHuxPk+aHUMcnZHfIivlDI7suXxh58KcA==; 5:+CuEwwyhdMRIh83WuodMViJ1OKUtn0uGWQohzqdoc8X6sSrF5sW4etWrWqfyfNAkK5DqzGnPGRwu7AS+rQeRDkVdBT4ekBrIJgfotE+ojO9b5wB2yDhrEH/v5alKRo/LTBGNHAF4Hn0XrppMKAY3rK/U7MND/tHbxEMFyVQrjKE=; 24:7GWJc+vjODl0b3rZfrLprgbZEkrrHuVayJB1tm0P5iJk8Lty5fF9mNuljWCcWHLzzQ4njWDkaXlh4BOEyVd7WEt0u+aZ+d3gTLQK2Jhkw3o= SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-Microsoft-Exchange-Diagnostics: 1; MWHPR15MB1760; 7:nck9CsL8GukUWx+9+64drjZtwLh0LgWa1xHzL58ZdIhbzqu0/eNj18fAxITXFST+DJ9+7MVOXLtdqWmdkEkHRgiKthLH8CqG++2OI8/FnuUVk7ryPvmWPk8apPuCqabS+gdV5/3eFZM38Uhc00aTdAZ06YzGt8gFBFu/5X29Ek5AJ8Z6DK002UDvDAjDusUNyp5syKald547mURUQdLAk5QMy1Yz5ATcREKT1LydEUG8YyPKPqDxrwp4bVKG2+OmhdTAXM4qctRfRgBrm9wU/ZX+8kYttu9fQgcnCZSH/b8bf6WL8D98xN3Ub5RagWFPtXcJpNEBVEoUHiTCL2pmEw==; 20:MX9MhQeO6yIGULP7s8jFhZ2lYU1rRoDAsnwG/G5aDS6YLqRrsZjjqtKkU8bE/NeAYvDdoNCXBFRUd6EMw0v4vW0ysXq+bgnAlimbfbymN2hPtFyKXQZeq257sHRQtbgeaC4MDKb/1TiHW7d//1L5HR1AeZ1Q0t83XOAocQMVZrE= X-MS-Exchange-CrossTenant-OriginalArrivalTime: 24 May 2017 16:27:24.0850 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-Transport-CrossTenantHeadersStamped: MWHPR15MB1760 X-OriginatorOrg: fb.com X-Proofpoint-Spam-Reason: safe X-FB-Internal: Safe X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:, , definitions=2017-05-24_12:, , signatures=0 Sender: linux-crypto-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-crypto@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Add documentation for the tcp ULP tls interface. Signed-off-by: Boris Pismenny Signed-off-by: Dave Watson --- Documentation/networking/tls.txt | 120 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 Documentation/networking/tls.txt diff --git a/Documentation/networking/tls.txt b/Documentation/networking/tls.txt new file mode 100644 index 0000000..7bfb256 --- /dev/null +++ b/Documentation/networking/tls.txt @@ -0,0 +1,120 @@ +Overview +======== + +Transport Layer Security (TLS) is a Upper Layer Protocol (ULP) that runs over +TCP. TLS provides end-to-end data integrity and confidentiality. + +User interface +============== + +Creating a TLS connection +------------------------- + +First create a new TCP socket and set the TLS ULP. + + sock = socket(AF_INET, SOCK_STREAM, 0); + setsockopt(sock, SOL_TCP, TCP_ULP, "tls", sizeof("tls")); + +Setting the TLS ULP allows us to set/get TLS socket options. Currently +only the symmetric encryption is handled in the kernel. After the TLS +handshake is complete, we have all the parameters required to move the +data-path to the kernel. There is a separate socket option for moving +the transmit and the receive into the kernel. + + /* From linux/tls.h */ + struct tls_crypto_info { + unsigned short version; + unsigned short cipher_type; + }; + + struct tls12_crypto_info_aes_gcm_128 { + struct tls_crypto_info info; + unsigned char iv[TLS_CIPHER_AES_GCM_128_IV_SIZE]; + unsigned char key[TLS_CIPHER_AES_GCM_128_KEY_SIZE]; + unsigned char salt[TLS_CIPHER_AES_GCM_128_SALT_SIZE]; + unsigned char rec_seq[TLS_CIPHER_AES_GCM_128_REC_SEQ_SIZE]; + }; + + + struct tls12_crypto_info_aes_gcm_128 crypto_info; + + crypto_info.info.version = TLS_1_2_VERSION; + crypto_info.info.cipher_type = TLS_CIPHER_AES_GCM_128; + memcpy(crypto_info.iv, iv_write, TLS_CIPHER_AES_GCM_128_IV_SIZE); + memcpy(crypto_info.rec_seq, seq_number_write, + TLS_CIPHER_AES_GCM_128_REC_SEQ_SIZE); + memcpy(crypto_info.key, cipher_key_write, TLS_CIPHER_AES_GCM_128_KEY_SIZE); + memcpy(crypto_info.salt, implicit_iv_write, TLS_CIPHER_AES_GCM_128_SALT_SIZE); + + setsockopt(sock, SOL_TLS, TLS_TX, &crypto_info, sizeof(crypto_info)); + +Sending TLS application data +---------------------------- + +After setting the TLS_TX socket option all application data sent over this +socket is encrypted using TLS and the parameters provided in the socket option. +For example, we can send an encrypted hello world record as follows: + + const char *msg = "hello world\n"; + send(sock, msg, strlen(msg)); + +send() data is directly encrypted from the userspace buffer provided +to the encrypted kernel send buffer if possible. + +The sendfile system call will send the file's data over TLS records of maximum +length (2^14). + + file = open(filename, O_RDONLY); + fstat(file, &stat); + sendfile(sock, file, &offset, stat.st_size); + +TLS records are created and sent after each send() call, unless +MSG_MORE is passed. MSG_MORE will delay creation of a record until +MSG_MORE is not passed, or the maximum record size is reached. + +The kernel will need to allocate a buffer for the encrypted data. +This buffer is allocated at the time send() is called, such that +either the entire send() call will return -ENOMEM (or block waiting +for memory), or the encryption will always succeed. If send() returns +-ENOMEM and some data was left on the socket buffer from a previous +call using MSG_MORE, the MSG_MORE data is left on the socket buffer. + +Send TLS control messages +------------------------- + +Other than application data, TLS has control messages such as alert +messages (record type 21) and handshake messages (record type 22), etc. +These messages can be sent over the socket by providing the TLS record type +via a CMSG. For example the following function sends @data of @length bytes +using a record of type @record_type. + +/* send TLS control message using record_type */ + static int klts_send_ctrl_message(int sock, unsigned char record_type, + void *data, size_t length) + { + struct msghdr msg = {0}; + int cmsg_len = sizeof(record_type); + struct cmsghdr *cmsg; + char buf[CMSG_SPACE(cmsg_len)]; + struct iovec msg_iov; /* Vector of data to send/receive into. */ + + msg.msg_control = buf; + msg.msg_controllen = sizeof(buf); + cmsg = CMSG_FIRSTHDR(&msg); + cmsg->cmsg_level = SOL_TLS; + cmsg->cmsg_type = TLS_SET_RECORD_TYPE; + cmsg->cmsg_len = CMSG_LEN(cmsg_len); + *CMSG_DATA(cmsg) = record_type; + msg.msg_controllen = cmsg->cmsg_len; + + msg_iov.iov_base = data; + msg_iov.iov_len = length; + msg.msg_iov = &msg_iov; + msg.msg_iovlen = 1; + + return sendmsg(sock, &msg, 0); + } + +Control message data should be provided unencrypted, and will be +encrypted by the kernel. At a high level, the kernel TLS ULP is a +replacement for the record layer of a userspace TLS library.