Name

OpenXPKI::Transport::Simple - basic transport protocol.

Description

This is the interface specification for all common OpenXPKI transport protocol implementations. Please note that every read operation returns an interpretable answer. We do not return partial messages.

To handle utf8 transparently, we assume that data stream are always utf8 sequences. Therefore the transport will corrupt data that might be missinterpreted by the utf8::upgrade pragma and we strongly recommend to base64 encode all data that is neither UTF8 nor plain ASCII!

Functions

new

accepts only INFILE and OUTFILE as parameters. It takes over the complete communication via STDIN and STDOUT. If INFILE is specified then messages are written to INFILE instead of STDIN. If OUTFILE is present than messages are read from OUTFILE instead of STDOUT.

Example:

my $transport = OpenXPKI::Transport::Simple->new ({});

close

close the connection and calls DESTROY.

write

send a message.

read

read a message.

internal communication protocol

A header is added to the data to correctly handle reading from the socket.

The header has a fixed format::

  type::=final
  length::=12345678
  <data>

type

The default type is final, which means this is the last message (most times the only one) and all data was transmitted after this package was read. If the data is too large to fit into a single package, it is splitted into several parts, each one with the maximum allowed size. Those intermediate packages are transmitted wit the type set to chunk.

The maximum allowed size is a fixed value of 1048544 bytes (2^20 - 32). The 32 bytes are sufficient to place the header, so the total size is always below 1MB.

length

The length of the raw data portion in bytes, to ease parsing this is always written with 8 digit using decimal notation.