Programs - Full Options
The section Programs lists the options that are relevant to S-Fifteen Instruments’s QKDServer implementation. This section lists all program options of the qcrypto suite.
chopper.c
Program to digest the binary input from a timestamp card, separate it into sections corresponding to one epoc, and emit packets for sifting/coincidence purpose both for transmission over the classical channel and for local storage for later key usage.
The file formats emitted are tagged compressed packages of filetype 2 and 3 according to the crypto transfer file format spec whitepaper.
IMPLEMENTED OPTIONS:
DATA STREAM OPTIONS
- -i infilename
Filename of source events. Can be a file or a socket and has to supply binary data according to the raw data spec from thetimestamp unit.
- -O fname2
Outfile name for type 2 compressed sifting time files. This option saves all type 2 packets into a the file/FIFO named fname2
- -D dir2
All type-2 packets are saved into the directory dir2, with the file name being the epoch (filling zero expanded) in hex. Filename is not padded at end.
- -o fname3
Same as option -O, but for type-3 files
- -d dir3
Same as option -d, but for type-3 files
ENCODING OPTIONS
- -U
Universal epoch; the epoch is not only derived from the timestamp unit digits, but normalized to unix time origin. This needs the timestamp unit to emit event data with an absolute time tag. For this to work, the received data cannot be older than xxx hours, or an unnoted ambiguity error will occur.
- -L
Local timestamps only. The epoch is calculated from the unmodified timestamp info as received from the unit. This is the default.
- -q depth
Number of bits used to compress the timing data. default is 17, which should be optimal for … kevents/sec.
- -Q num
Filter time constant for bitlength optimizer. The larger the num, the longer the memory of the filter. for num=0, no change will take place. This is also the default.
LOGGING & NOTIFICATION
- -l logfile
Each emitted epoch packet index is logged into this file. The verbosity level controls the granularity of details logged. If no filename is specified, logging is sent to STDOUT.
- -V level
Verbosity level control. level is integer, and by default set to 0. The logging verbosity criteria are: level<0 : no logging 0 : log only epoc number (in hex) 1 : log epoch, length without text 2 : log epoch, length with text 3 : log epoch, length, bitlength with text 4 : log epoch, detector histos without text
- -4
Sets the number of detectors to be logged to 4 (default) in service mode. Has no effect in crypto modes
- -6
Sets the number of detectors to be logged to 6. This option has only an effect in service mode
- -F
Flushmode. If set, the logging info is flushed after every write. useful if used for driving the transfer deamon.
- -e debugfile
Choose a file for debug logging. This used to be hardcoded to the file /tmp/cryptostuff/chopdebug, but is turned off for use with other applications.
PROTOCOL OPTION
- -p num
Select protocol option. Defines what transmission protocol is run by selecting what event bits are saved in which stream. option 1 is default.
- 0: Service protocol. Both type-2 stream and type-3 stream
contain the raw detector information.
- 1: BB84 standard protocol. The type-2 stream contains one bit
of basis information, the type-3 stream one bit of value information. The detector sequence is hardcoded in the header.
- 2: Rich BB84. As before, but two bits are transmitted. if the
msb is 0, the lsb has BB84 meaning, if msb is 1, a multi- or no-coincidence event was recorded (lsb=1), or a pair coincidence was detected (lsb=0).
- ———modifications for device-independent ——–
- 3: Six detectors connected to this side, used for the
device-independent mode. three transmitted bits, indicating bell basis or key basis
- 4: Four detectors connected to this side, device-indep
operation. only time is transmitted.
- ———modifications to BC protocol—————–
- 5: Like 1, but no basis is transmitted, but basis/result
kept in local file
PROTECTION OPTION
- -m maxnum
Maximum time for a consecutive event to be meaningful. If the time difference to a previous event exceeds this time, the event is discarded assuming it has to be an error in the timing information. Default set to 0, which corresponds to this option being switched off. Time units is in microseconds.
chopper2.c
Program to partition the output of the timestamp card on the comparator side. Consumes the timestamp signal, and generates type-1 packets out of it, either in a single file/pipe, or a directory. A logfile for process control can be generated. Filespecs for input and type-1 stream can be found in the filespec whitepaper.
IMPLEMENTED OPTIONS:
DATA STREAM OPTIONS
- -i infilename
Filename of source events. Can be a file or a socket and has to supply binary data according to the raw data spec from thetimestamp unit.
- -O fname1
Outfile name for type 1 raw sifting time files. This option saves all type 1 packets into a the file/FIFO named fname1
- -D dir1
All type-1 packets are saved into the directory dir1, with the file name being the epoch (filling zero expanded) in hex. Filename is not padded at end.
ENCODING OPTIONS
- -U
Universal epoch; the epoch is not only derived from the timestamp unit digits, but normalized to unix time origin. This needs the timestamp unit to emit event data with an absolute time tag. For this to work, the received data cannot be older than xxx hours, or an unnoted ambiguity error will occur.
- -L
Local timestamps only. The epoch is calculated from the unmodified timestamp info as received from the unit. This is the default.
LOGGING & NOTIFICATION
- -l logfile
Each emitted epoch packet index is logged into this file. The verbosity level controls the granularity of details logged. if nothing is specified, STDOUT is used for logging.
- -V level
Verbosity level control. level is integer, and by default set to 0. The logging verbosity criteria are: level<0 : no logging 0 : log only epoc number (in hex) 1 : log epoch, length without text 2 : log epoch, length with text 3 : log epoch and detailled event numbers for single event counting. format: epoch and 5 cnts spc separated
- -F
Flushmode. If set, the logging output gets flushed after every write attempt.
- -4
Full backwards compatibility option with logging where single counts include local coincidences. Also reduces the number of events in the output log to five (total cnts and individual detector lines).
- -d debugname
Specifies the file name of an optional debugging log file. If this file is not provided, no debugging log file is generated. The old debug filename was hardcoded as /tmp/cryptostuff/choplog2 and has now been removed. Check downstream processing if needed.
PROTECTION OPTION
- -m maxnum
Maximum time for a consecutive event to be meaningful. If the time difference to a previous event exceeds this time, the event is discarded assuming it has to be an error in the timing information. Default set to 0, which corresponds to this option being switched off. Time units is in microseconds.
costream.c
Program to process type-1 and type-2 streams on side b to recover coincidences between different timings. As an output, the program generates type-4 streams of acknowlegements to party A, and type-3 streams for local raw key storage. File type descriptions can be found in the filespec whitepaper. Besides the streams, logging information is given for notification of various digesting consumers, and coinidence time tracking parameters can be supplied and logged.
IMPLEMENTED OPTIONS:
DATA STREAM OPTIONS
- -i infile2
Filename of type-2 packets. Can be a file or a socket and has to supply binary data according to the type-2 data spec from the chopper program.
- -d dir2
All type-2 packets are saved into the directory dir2, with the file name being the epoch (filling zero expanded) in hex. Filename is not padded at end.
- -I infile1
filename of type-1 packets. Can be a file or a socket and has to supply binary data according to the type-1 data spec from the chopper2 program.
- -D dir1
All type-1 packets are saved into the directory dir1, with the file name being the epoch (filling zero expanded) in hex. Filename is not padded at end.
- -O fname4
Outfile name for type 4 compressed sifting index files. This option saves all type 4 packets into a the file/FIFO named fname4
- -F dir4
All type-4 packets are saved into the directory dir4, with the file name being the epoch (filling zero expanded) in hex. Filename is not padded at end.
- -o fname3
Same as option -O, but for type-3 files
- -f dir3
Same as option -d, but for type-3 files
- -b bellfile
Same as option -O, but for type-3 BELL files
- -B belldir
Same as option -d, but for type-3 BELL directories
- -k
If set, type-2 streams are removed after consumption if the directory input has been chosen.
- -K
If set, type-1 streams are removed after consumption if the directory input has been chosen.
DATA MANAGEMENT OPTIONS
- -e startepoch
Epoch to start with.
- -w window
Coincidence time window in 1/8 nsec
- -u window
Coincidence time window in for tracking purpose.
- -Q filter
filter constant for tracking coincidences. positive numbers refer to events, negative to time constants in microseconds. A value of zero switches tracking off; this is the default.
- -a accdist
Distance between the real coincidence winow and the window for accidental coincidences in 1/8 nsec. default is 160 (corresp. to 20 nsec)
- -p protocolindex
Defines the working protocol. Currently implemented:
0: service mode, emits all bits into stream 3 locally
1: standard BB84, emits only result in stream 3
(2: rich bb84: emits data and base/error info in stream 3)
3: deviceindep protocol with the 6det connected to the chopper side (low cnt rate)
4: deviceindep proto with the 4det connected to the chopper side
5: BC protocol; similar to standard BB84, but handles basis differently.
- -q epochnum
Defines how many epochs should be converted before the program stops. When set to 0, it loops forever; this is the default.
- -r bitnumber
Number of bits for coding the difference in stream 4. default is 8.
- -R servoconst
Filter time constant for stream 4 bitlength optimizer. The larger the num, the longer the memory of the filter. for num=0, no change will take place. This is also the default.
- -t timediff
Time difference between the t1 and t2 input streams. This is a mandatory option, and defines the initial time difference between the two local reference clocks in multiples of 125ps.
- -T zeropolicy
Policy how to deal with no valid coincidences in present epoch. Implemented:
0: do not emit a stream-3 and stream-4 file.
1: only emit a stream-4 file, no stream-3 file to notify the other side to discard the corresp. package. This is the default.
2: emit both stream-3 and stream-4 files and leave the cleanup to a later stage
- -H histoname
Defines a file containing the histogram of time differences between different detector combinations. If this is empty, no histogram is taken or sent. For a histogram to be prepred the mode of operation must be 0 (service info) to obtain the full 4x4 matrix (or 4x6 for proto3+4).
- -h histolen
Number of epochs to be included in a histogram file. default is 10.
- -S <s1,s1,s3,s4>
Detector skew information. This option adds a detector- dependent skew time to single-detection events. This option makes only sense for some nonstandard applications and is similar to the detector skew option in readevent3.c
LOGGING & NOTIFICATION
- -l logfile1
notification target for consumed epochs of type-1 packets. logged are epoch numbers in hex form.
- -L logfile2
notification target for consumed epochs of type-2 packets. logged are epoch numbers in hex form.
- -m logfile3
notification target for type-3 files packets. logged are epoch numbers in hex form.
- -M logfile4
notification target for type-4 files packets. logged are epoch numbers in hex form.
- -n logfile5
notification target for general information. The logging content is defined by the verbosity level. If no file is specified, or - as a filename, STDOUT is chosen.
- -V level
Verbosity level control. level is integer, and by default set to 0. The logging verbosity criteria are:
level<0 : no output
0 : output bare hex names of processed data sets
1 : output handle and number of key events in this epoch
2 : same as option 1 but with text
3 : output epoch, processed events, sream-4 events, current bit with for stream 4 compression with text
4 : output epoch, processed events, sream-4 events, current bit with for stream 4 compression, servoed time difference,estimated accidental coincidences, and accepted coincidences with text
5 : same as verbo 4, but without any text inbetween
- -G mode
flushmode. If 0, no fflush takes place after each processed packet. Different levels:
0: no flushing
1: logfile4 gets flushed
2: logfiles for stream3, stream4, standardlog get flushed
3: all logs get flushed
pfind.c
Program on side B to find a coincidence time difference. Takes a directory or file with type-2 and type-1 files, and concatenates a given number of packets starting with a given epoch number, evaluates the time difference in multiples of 1/8 nsec, and returns that to stdout or any other file, eventually with some reliability information on the found timing difference.
IMPLEMENTED OPTIONS:
DATA STREAM OPTIONS
- -i infile2
Filename of type-2 packets. Can be a file or a socket and has to supply binary data according to the type-2 data spec from the chopper program.
- -d dir2
All type-2 packets are saved into the directory dir2, with the file name being the epoch (filling zero expanded) in hex. Filename is not padded at end.
- -I infile1
Filename of type-1 packets. Can be a file or a socket and has to supply binary data according to the type-1 data spec from the chopper2 program.
- -D dir1
All type-1 packets are saved into the directory dir1, with the file name being the epoch (filling zero expanded) in hex. Filename is not padded at end.
- -k
If set, type-2 streams are removed after consumption if the directory input has been chosen.
- -K
If set, type-1 streams are removed after consumption if the directory input has been chosen.
DATA MANAGEMENT OPTIONS
- -e startepoch
Epoch to start with. Default is 0.
- -n epochnums
Define a runtime of epochums epochs before looking for a time delay. Default is 1.
RESOLUTION
- -r resolution
Resolution of timing info in nanoseconds. Will be rounded to closest power of 1 nsec. Default is 2 nsec.
- -q bufferwidth
Order of FFT buffer size. Defines the wraparound size of the coarse / fine periode finding part. Defaults to 17 (128k entries), must lie within 12 and 23.
LOGGING & NOTIFICATION
- -l logfile
The resulting time difference or details are logged into this file. if this option is not specified, STDOUT is used. The verbosity level controls the granularity of details.
- -V level
Verbosity level control. level is integer, and by default set to 0. The logging verbosity criteria are:
level<0 : no output
0 : output difference (in plaintext decimal ascii)
1 : output difference and reliability info w/o text
2 : output difference and reliability info with text
3 : more text
splicer.c
Program to process the saved results in a type-3 file on side A together with a type-4 file from the coincidence/sifting unit on side B. Result is a reduced type-3 stream which should contain the raw key information. This code integrates BB84 and Ekert protocols.
IMPLEMENTED OPTIONS:
DATA STREAM OPTIONS
- -i infile3
Filename of unsifted type-3 packets. Can be a file or a socket and has to supply binary data according to the type-3 data spec from the chopper program.
- -d dir3
All input type-3 packets are saved into the directory dir3, with the file name being the epoch (filling zero expanded) in hex. Filename is not padded at end.
- -I infile4
Filename of type-4 packets. Can be a file or a socket and has to supply packed sifting index data to the type-4 data spec from the costream program.
- -D dir4
All type-4 packets are saved into the directory dir4, with the file name being the epoch (filling zero expanded) in hex. Filename is not padded at end.
- -o outfile3
Outfile name for type-3 sifted key packets. This option saves all type-3 packets into a the file/FIFO named outfile3.
- -b outfile5
Target file name for a test file for carrying out a Ekert-type protocol.
- -B outdir5
All type-5 packets are saved in this directory, file name is the epoch in hex.
- -f outdir3
All type-3 sifted key packets are saved into the directory outdir4, with the file name being the epoch (filling zero expanded) in hex. Filename is not padded at end.
- -e epoch
If only directories are given, an epoch index has to be supplied.
- -E cmdpipe
If this option is supplied, the t4 files are taken from a directory, but processing takes place on files where the name (i.e., epoch number) is piped as text into the pipe specified in this option. If cmdpipe does not exist, it is created.
- -k
If set, type-3 input streams are removed after consumption if the directory input has been chosen.
- -K
If set, type-4 input streams are removed after consumption if the directory input has been chosen.
- -p protocol
Selection of the protocol type. implemented:
0: service mode, emits all bits into stream 3 locally for those entries marked in stream 4
1: selects basebits from stream 3in which are marked in stream4
2: same as mode 0
3: device-independent protocol, this side has 6 detectors
4: device-independent proto, this side has 4 detectors
5: BC version of proto1, just copies received tags from stream 3 into rawkey
- -q epochunum
Number of epocs to be read. When set to 0, it loops forever; this is the default.
LOGGING & NOTIFICATION
- -l logfile
Notification target for consumed epochs of type-3 packets. logged are epoch numbers in hex form.
- -L logfile2
Notification target for consumed epochs of type-4 packets. logged are epoch numbers in hex form.
- -m logfile3
Notification target for generated output type-3 packets. log format is specified by -V option
- -V level
Verbosity level control. controls format for logfile in the -m option. level is integer, and by default set to 0. The logging verbosity criteria are:
level<0 : no output
0 : epoch (in plaintext hex). This is default.
transferd.c
Program to arrange for file transfer from one machine to the other. This is taking care of the sockets between two machines. Each machine has a version of it running. This deamon listens to a command port for file names to be transferred, which are specified relative to a initially agreed directory, and transmitts the underlying file to the other side. On the receiving side, files are saved in a directory, and a notofication is placed in a file.
The communication is implemented via tcp/ip packets. the program acts either as a server or a client, depending on the status of the other side. if client mode fails, it goes into server mode. if no connection is available within a few seconds, it tries to connect to the client again.
Transfer rationale: The same channel will be used for messages, files and error correction packets. Since there is no simple way to extract the length of the file for all possible future extensions, the transmission of whatever is preceeded by a header involving a:
typedef struct stream_header {int type;
unsigned int length; };
where type is 0 for simple files, 1 for messages, 2 for errc packets and length designates the length of the data in bytes. In a later stage, the messages might be sent via an out-of-band marker, but this is currently not implemented.
IMPLEMENTED OPTIONS:
- -d srcdir
Source directory for files to be transferred
- -c commandpipe
Where to create a fifo in the file system to listen to files to be transferred. the path has to be absolute.
- -t target
IP address of target machine
- -D destdir
Destination directory
- -l notify
If a packet arrives and has been saved, a notification (the file name itself) is sent to the file or pipe named in the parameter of this option
- -s sourceIP
Listen to connections on the local ip identified by the paremeter. By default, the system listens on all ip addresses of the machine.
- -k
Killoption. If this is activated, a file gets destroyed in the source directory after it has been sent.
- -m src
Message source pipe. this opens a local fifo in the file tree where commands can be tunneled over to the other side.
- -M dest
If a command message is sent in from the other side, it will be transferred into the file or pipe named in the parameter of this file.
- -p portnum
Port number used for communication. By default, this is port number 4852.
- -v verbosity
Choose verbosity. 0: no normal output to stdout
1: connect/disconnect to stdout
2: talk about receive/send events
3: include file error events
- -e ec_in_pipe
Pipe for receiving packets from errorcorrecting demon
- -E ec_out_pipe
Pipe to send packes to the error correcting deamon
ecd2.c
Error correction demon. (modifications to original errcd see below). Runs in the background and performs a cascade error correction algorithm on a block of raw keys. Communication with a higher level controller is done via a command pipeline, and communication with the other side is done via packets which are sent and received via pipes in the filesystem. Some parameters (connection locations, destinations) are communicated via command line parameters, others are sent via the command interface. The program is capable to handle several blocks simultaneously, and to connect corresponding messages to the relevant blocks. The final error-corrected key is stored in a file named after the first epoch. If a block processing is requested on one side, it will fix the role to “Alice”, and the remote side will be the “Bob” which changes the bits accordingly.
Note
Modified version of errcd.c to take care of the following problems:
Initial key permutation
More efficient biconf check
Allow recursive correction after biconf error discoveries status: seems to work. needs some cleanup, and needs to be tested for longer key lenghts to confirm the BER below 10^-7 with some confidence.
Inserted error margin option to allow for a few std deviations of the detected error
IMPLEMENTED OPTIONS:
DIRECTORY / CONNECTION PARAMETERS:
- -c commandpipe
Pipe for receiving commands. A command is typically an epoch name and a number of blocks to follow, separated by a whitespace. An optional error argument can be passed as a third parameter. Commands are read via fscanf, and should be terminated with a newline.
- -s sendpipe
Binary connection which reaches to the transfer program. This is for packets to be sent out to the other side. Could be replaced by sockets later.
- -r receivepipe
Same as sendpipe, but for incoming packets.
- -d rawkeydirectory
Directory which contains epoch files for raw keys in stream-3 format
- -f finalkeydirectory
Directory which contains the final key files.
- -l notificationpipe
Whenever a final key block is processed, its epoch name is written into this pipe or file. The content of the message is determined by the verbosity flag.
- -Q querypipe
To request the current status of a particular epoch block, requests may be sent into this pipe. Syntax TBD.
- -q respondpipe
Answers to requests will be written into this pipe or file.
CONTROL OPTIONS
- -e errormargin
A float parameter for how many standard deviations of the detected errors should be added to the information leakage estimation to eve, assuming a poissonian statistics on the found errors (i.e., if 100 error bits are found, one standard deviation in the error rate QBER is QBER /Sqrt(10). ) Default is set to 0.
- -E expectederror
An initial error rate can be given for choosing the length of the first test. Default is 0.05. This may be overridden by a servoed quantity or by an explicit statement in a command.
- -k
Killfile option. If set, the raw key files will be deleted after writing the final key into a file.
- -J basicerror
Error rate which is assumed to be generated outside the influence of an eavesdropper.
- -T errorbehavior
Determines the way how to react on errors which should not stop the demon. Default is 0. detailed behavior:
0: terminate program on everything
1: ignore errors on wrong packets???
2: ignore errors inherited from other side
- -V verbosity
Defines verbosity mode on the logging output after a block has been processed. options:
0: just output the raw block name (epoch number in hex)
1: output the block name, number of final bits
2: output block name, num of initial bits, number of final bits, error rate
3: same as 2, but in plain text
4: same as 2, but with explicit number of leaked bits in the error correction procedure
5: same as 4, but with plain text comments
- -I
Ignoreerroroption. If this option is on, the initial error measurement for block optimization is skipped, and the default value or supplied value is chosen. This option should increase the efficiency of the key regeneration if a servo for the error rate is on.
- -i
Deviceindependent option. If this option is set, the deamon expects to receive a value for the Bell violation parameter to estimate the knowledge of an eavesdropper.
- -p
Avoid privacy amplification. For debugging purposes, to find the residual error rate
- -B BER
Choose the number of BICONF rounds to meet a final bit error probability of BER. This assumes a residual error rate of 10^-4 after the first two rounds.
- -b rounds
Choose the number of BICONF rounds. Defaults to 10, corresponding to a BER of 10^-7.