Class: Telsa

Telsa(opts)

States

Telsa has four internal states:

  • Connecting
  • Handshaking
  • Established
  • Terminated

The following operations or events are external events in terms of a state machine.

  • _write
  • _final
  • _read
  • socket error
  • read path error when processing socket data, including:
    • tls protocol error, defined as alert description
    • operation errors returned from asynchronous operation
      • some errors are protocol error, such as certificate not verified
      • others are operation errors, such as child process crashed.
    • other exceptions
  • write path error when executing _write operation:
    • all errors are exceptions (which is internal error in alert description)
  • server alert
    • fatal alert
    • close_notify
    • other warning alerts other than close_notify
  • close without a server alert

Stateful Resources

  • write path
    • if a _write operation cannot be performed immediately, it is blocked.
    • if the underlying socket write returns false during a _write operation.
  • read path
    • the underlying socket may be paused

Finish write path

  • the underlying socket could be finished by end method.

Finish read path

  • the read path could be finished by push a null. This is only necessary after the tls is connected.

Connecting State

In connecting state, only the following

Constructor

new Telsa(opts)

Parameters:
Name Type Description
opts object
Source:

Members

ca

root ca in forge format

Source:

caStore

forge ca store

Source:

cipher :CipherFunction

Type:
Source:

clientRandom

client random

Source:

clientWriteKey

client key

Source:

clientWriteMacKey

client write mac key

Source:

decipher :DecipherFunction

Type:
Source:

fragment :Fragment|null

current fragment, contains 0, 1 or more records of the same type.

Type:
Source:

incomming :Buffer

incomming data buffer, may contain fragmented records.

Type:
  • Buffer
Source:

masterSecret

master secret

Source:

msgs

handshake messages

Source:

opts

options

Source:

preMasterSecret

pre-master secret

Source:

serverRandom

server random

Source:

serverWriteKey

server key

Source:

serverWriteMacKey

server write mac key

Source:

sessionId

session id

Source:

socket :net.Socket

tcp connection

Type:
  • net.Socket
Source:

writing :object|function

blocked or draining _write operation

  • null if no blocked _write
  • { chunk, encoding, callback } if a _write is blocked
  • callback if the operation is waiting for draining
Type:
  • object | function
Source:

Methods

_final()

implement Duplex _final

Source:

_read()

implement Duplex _read

Source:

_write()

implements Duplex _write

Source:

assertLast()

assert last handshake message from and type

Source:

changeCipherSpec()

send change cipher spec message and set cipher

Source:

clientVerifyData()

generates client verify data in client Finished message

Source:

deriveKeys()

derive keys from pre-master secret, client and server random

Source:

handleAlert(data)

handle alert message, all warnings are bypassed except close_notify

Parameters:
Name Type Description
data Buffer
Source:

handleApplicationData()

handle application data

Source:

handleCertificate()

extracts and verifies server certificates. If succeeded, extracts server public key for futher usage.

struct {
  ASN.1Cert certificate_list<0..2^24-1>;
} Certificate;
Source:

handleCertificateRequest()

struct {
  ClientCertificateType certificate_types<1..2^8-1>;
  SignatureAndHashAlgorithm
    supported_signature_algorithms<2^16-1>;
  DistinguishedName certificate_authorities<0..2^16-1>;
} CertificateRequest;
Source:

handleChangeCipherSpec()

handle change cipher spec

Source:

handleError()

handle errors from data handler, asynchronous operations, but not socket error

Source:

handleHandshakeMessage(msg)

handle handshake message

Parameters:
Name Type Description
msg Buffer

full message data, including type, length, and body

Source:

handleServerFinished(data)

checks verify_data in server Finished message, transits to Established state or throw error

struct {
  opaque verify_data[verify_data_length];
} Finished;
Parameters:
Name Type Description
data Buffer
Source:

handleServerHello()

struct {
  ProtocolVersion server_version;
  Random random;
  SessionID session_id;
  CipherSuite cipher_suite;
  CompressionMethod compression_method;
  select (extensions_present) {
    case false:
      struct {};
    case true:
      Extension extensions<0..2^16-1>;
  };
} ServerHello;
Source:

handleServerHelloDone()

struct { } ServerHelloDone;

Source:

handleSocketData(data)

handle socket data

Parameters:
Name Type Description
data Buffer

socket data

Source:

maxFragmentLength()

Source:
Returns:

max fragment length

readFragment() → {Fragment}

read a record out of incomming data buffer

Source:
Returns:

the record type and payload

Type
Fragment

readMessage() → {Message}

read a message

Source:
Returns:
Type
Message

readMessageFromFragment() → {Message}

read a message from current fragment

Source:
Returns:
Type
Message

saveMessage()

save handshake message

Source:

send(type, data)

constructs a record layer packet and send

Parameters:
Name Type Description
type number

content type

data Buffer

content

Source:

sendAlert() → {boolean}

Source:
Returns:

false if buffer full

Type
boolean

sendApplicationData() → {boolean}

Source:
Returns:

false if buffer full

Type
boolean

sendCertificateVerify()

send CertificateVerify

Source:

sendChangeCipherSpec() → {boolean}

Source:
Returns:

false if buffer full

Type
boolean

sendClientCertificate()

send client certificate if ServerHelloDone and server public key available (which also means server certificates verified)

Source:

sendClientHello()

send ClientHello handshake message

Source:

sendClientKeyExchange()

send ClientKeyExchange message, preMasterSecret is encrypted using server's public key

Source:

sendFinished()

send Finished handshake message

Source:

sendHandshakeMessage() → {boolean}

Source:
Returns:

false if buffer full

Type
boolean

serverVerifyData()

generates server verify data in server Finsihed message

Source:

setServerRandom(random)

set server random and derives keys

Parameters:
Name Type Description
random buffer

server random

Source:

shiftFragment() → {Fragment}

shift data chunk with given size from current fragment

Source:
Returns:
Type
Fragment

sign()

sign all handshake messages sent and received so far

Source:

terminate()

terminate is the one-for-all method to end the telsa. unlike node tls, telsa terminates synchronously, which means that there is no closing state. This is allowed in TLS spec.

  • final
  • destroy
  • socket, [err]
  • error, TLSError | Error
  • alert, TLSAlert
  • (close_notify) redefined from alert
Source: