Protocol++® (Protocolpp®)  v5.6.2
jtlsa Class Reference

#include "include/jtlsa.h"

Detailed Description

Transport Layer Security Association (TLSA)

For additional information see http://en.wikipedia.org/wiki/Transport_Layer_Security

The TLS protocol exchanges records—which encapsulate the data to be exchanged in a specific format (see below). Each record can be compressed, padded, appended with a message authentication code (MAC), or encrypted, all depending on the state of the connection. Each record has a content type field that designates the type of data encapsulated, a length field and a TLS version field. The data encapsulated may be control or procedural messages of the TLS itself, or simply the application data needed to be transferred by TLS. The specifications (cipher suite, keys etc.) required to exchange application data by TLS, are agreed upon in the "TLS handshake" between the client requesting the data and the server responding to requests. The protocol therefore defines both the structure of payloads transferred in TLS and the procedure to establish and monitor the transfer

TLS Records

This is the general format for all TLS records (packets) [1]

General Format for TLS Records (Packets)

Content Type

This field identifies the Record Layer Protocol Type contained in this Record

TLS Content Types
HexDecType
0x1420ChangeCipherSpec
0x1521Alert
0x1622Handshake
0x1723Application
0x1824Heartbeat

Version

This field identifies the major and minor version of TLS for the contained message. For a ClientHello message, this need not be the highest version supported by the client

TLS Versions
Major VersionMinor VersionVersion Type
0x030x00SSL3.0
0x030x01TLS1.0
0x030x02TLS1.1
0x030x03TLS1.2
0xFF0xFEDTLS

Length

The length of Protocol message(s), MAC and Padding, not to exceed ${2}^{14}$ bytes (16KB)

Protocol Message(s)

One or more messages identified by the Protocol field. Note that this field may be encrypted depending on the state of the connection

MAC and Padding

A message authentication code computed over the Protocol message, with additional key material included Note that this field may be encrypted, or not included entirely, depending on the state of the connection No MAC or Padding can be present at end of TLS records before all cipher algorithms and parameters have been negotiated and handshaked and then confirmed by sending a CipherStateChange record (see below) for signaling that these parameters will take effect in all further records sent by the same peer

Handshake protocol

Most messages exchanged during the setup of the TLS session are based on this record, unless an error or warning occurs and needs to be signaled by an Alert protocol record (see below), or the encryption mode of the session is modified by another record (see ChangeCipherSpec protocol below)

TLS Handshake Protocol
+Byte0Byte1Byte2Byte3
Byte 0
0x16
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Byte 1-4
Version
Length
Byte 5..8Message Type
Handshake Message Data Length
Byte 9-(n-1)
Handshake Message Data
. . .
. . .

Message type

This field identifies the handshake message type

TLS Message Types
CodeDescription
0HelloRequest
1ClientHello
2ServerHello
4NewSessionTicket
11Certificate
12ServerKeyExchange
13CertificateRequest
14ServerHelloDone
15CertificateVerify
16ClientExchange
20Finished

Handshake message data length

This is a 3-byte field indicating the length of the handshake data, not including the header Note that multiple handshake messages may be combined within one record

Alert protocol

This record should normally not be sent during normal handshaking or application exchanges. However, this message can be sent at any time during the handshake and up to the closure of the session. If this is used to signal a fatal error, the session will be closed immediately after sending this record, so this record is used to give a reason for this closure. If the alert level is flagged as a warning, the remote can decide to close the session if it decides that the session is not reliable enough for its needs (before doing so, the remote may also send its own signal)

TLS Alert Protocol
+Byte0Byte1Byte2Byte3
Byte 0
0x15
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Byte 1-4
Version
Length
Byte 5..6
Level
Description
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Byte 7-(n-1)
MAC (optional)
Byte p-(q-1)
Padding (block ciphers only)

Level

This field identifies the level of alert. If the level is fatal, the sender should close the session immediately. Otherwise, the recipient may decide to terminate the session itself, by sending its own fatal alert and closing the session itself immediately after sending it. The use of Alert records is optional, however if it is missing before the session closure, the session may be resumed automatically (with its handshakes)

Normal closure of a session after termination of the transported application should preferably be alerted with at least the Close notify Alert type (with a simple warning level) to prevent such automatic resume of a new session. Signaling explicitly the normal closure of a secure session before effectively closing its transport layer is useful to prevent or detect attacks (like attempts to truncate the securely transported data, if it intrinsically does not have a predetermined length or duration that the recipient of the secured data may expect)

ChangeCipherSpec protocol

TLS ChangeCipherSpec Protocol
+Byte0Byte1Byte2Byte3
Byte 0
0x14
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Byte 1-4
Version
Length
Byte 5
CCS Prot Type
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

CCS protocol type

Currently only 1

Application protocol

TLS Application Protocol
+Byte0Byte1Byte2Byte3
Byte 0
0x17
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Byte 1-4
Version
Length
Byte 5-(m-1)
Application Data
Byte m-(p-1)
MAC (optional)
Byte p-(q-1)
Padding (block ciphers only)
DTLS Datagram
+Byte0Byte1Byte2Byte3
Byte 0
0x17
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Byte 1-4
Version
Epoch
Byte 5-8
Seqnum
Byte 9-12
Seqnum
Length
Byte 13-(m-1)
Seqnum
Byte m-(p-1)
MAC (optional)
Byte p-(q-1)
Padding (block ciphers only)

Length

Length of the application data (excluding the protocol header and including the MAC and padding trailers)

MAC

20 bytes for the SHA1 based HMAC, 16 bytes for the MD5 based HMAC

Padding

Variable length; last byte contains the padding length

[1] http://orm-chimera-prod.s3.amazonaws.com/1230000000545/ch04.html

[2] https://tools.ietf.org/html/rfc7366

For API Documentation:

See also
ProtocolPP::jprotocol
ProtocolPP::jtlsa
ProtocolPP::jtls

For Additional Documentation:

See also
jprotocol
jtlsa
jtls
Protocol++® (ProtocolPP®) written by : John Peter Greninger • © John Peter Greninger 2015-2024 • All Rights Reserved
All copyrights and trademarks are the property of their respective owners

The source code contained or described herein and all documents related to the source code (herein called "Material") are owned by John Peter Greninger and Sheila Rocha Greninger. Title to the Material remains with John Peter Greninger and Sheila Rocha Greninger. The Material contains trade secrets and proprietary and confidential information of John Peter Greninger and Sheila Rocha Greninger. The Material is protected by worldwide copyright and trade secret laws and treaty provisions. No part of the Material may be used, copied, reproduced, modified, published, uploaded, posted, transmitted, distributed, or disclosed in any way without prior express written consent of John Peter Greninger and Sheila Rocha Greninger (both are required)

No license under any patent, copyright, trade secret, or other intellectual property right is granted to or conferred upon you by disclosure or delivery of the Materials, either expressly, by implication, inducement, estoppel, or otherwise. Any license under such intellectual property rights must be express and approved by John Peter Greninger and Sheila Rocha Greninger in writing

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution
  • Any and all modifications must be returned to John Peter Greninger at GitHub.com https://github.com/jpgreninger/protocolpp for evaluation. Inclusion of modifications in the source code shall be determined solely by John Peter Greninger. Failure to provide modifications shall render this license NULL and VOID and revoke any rights to use of Protocol++®
  • Commercial use requires a fee-based license obtainable at www.protocolpp.com
  • Academic use requires written and notarized permission from John Peter and Sheila Rocha Greninger
  • US Copyrights at https://www.copyright.gov/
    • TXu002059872 (Version 1.0.0)
    • TXu002066632 (Version 1.2.7)
    • TXu002082674 (Version 1.4.0)
    • TXu002097880 (Version 2.0.0)
    • TXu002169236 (Version 3.0.1)
    • TXu002182417 (Version 4.0.0)
    • TXu002219402 (Version 5.0.0)
    • TXu002272076 (Version 5.2.1)
    • TXu002383571 (Version 5.4.3)

The names of its contributors may not be used to endorse or promote products derived from this software without specific prior written permission

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE

The documentation for this class was generated from the following file: