NAME

       CurveCP — Message-handling programs

SYNOPSIS

       curvecpclient  [-q  (optional)]   [-Q  (optional)]  [-v (optional)]  [-c keydir(optional)]
       [sname]  [pk]  [ip]  [port]  [ext]  [prog]

DESCRIPTION

       This manual page documents briefly the CurveCP commands.

       A traditional UNIX-style server such as ftpd handles just one network connection,  reading
       input  from stdin and writing output to stdout. A "superserver" such as inetd or tcpserver
       listens for network connections and starts a separate server process for each connection.

       The CurveCP command-line tools have  an  extra  level  of  modularity.  The  curvecpserver
       superserver listens for network connections. For each connection, curvecpserver starts the
       curvecpmessage message handler; curvecpmessage then starts a server such  as  ftpd.   Then
       ftpd  sends  a  stream  of  data  to  curvecpmessage,  which  in  turn  sends  messages to
       curvecpserver, which encrypts and authenticates the messages and sends them inside network
       packets.  At  the  same time curvecpclient receives network packets, verifies and decrypts
       messages inside the packets, and passes the  messages  to  curvecpmessage;  curvecpmessage
       sends  a  stream  of  data  to  ftpd.   The  same  curvecpmessage  tool  is  also  used by
       curvecpclient.

       curvecpserver and curvecpclient can use programs other than curvecpmessage. Those programs
       can  directly  generate messages in the CurveCP message format without talking to separate
       tools such as ftpd; or they can  support  a  completely  different  protocol  that  reuses
       CurveCP's cryptographic layer but transmits different kinds of messages.

       This  page  explains what programmers have to do to write curvecpmessage replacements that
       talk to curvecpserver and curvecpclient.

Incoming messagess

       File descriptor 8 is a pipe. Read from this pipe a length byte n, between 1 and 68, and  a
       16*n-byte  message.  Repeat.  The pipe is set to non-blocking mode; be prepared for EAGAIN
       and EWOULDBLOCK, even in the middle of a message.

       This pipe reading must always be active.  The  curvecpclient  and  curvecpserver  programs
       assume  that every message is read immediately. If you can't handle a message immediately,
       read it and put it onto a queue. If you don't have queue space, throw  the  message  away;
       this  shouldn't cause trouble, since you have to be able to handle missing messages in any
       case.

Outgoing messagess

       File descriptor 9 is a pipe. Write to this pipe a length byte n, between 1 and 68,  and  a
       16*n-byte  message.  Repeat.  The pipe is set to non-blocking mode; be prepared for EAGAIN
       and EWOULDBLOCK, even in the middle of a message.

       As a client, do not use length bytes above 40 until a message has arrived from the server.
       (The messages inside CurveCP Initiate packets are limited to 640 bytes.)

       The  CurveCP  server  does  not  start  until  it  has received a message from the client.
       Furthermore, the CurveCP server must receive this message within 60 seconds of the  client
       starting  up.  (The  CurveCP  Initiate  packet  is  valid  for  only  60 seconds after the
       corresponding CurveCP Cookie packet.)  This does not  mean  that  the  client  must  start
       sending messages immediately, but it does mean that waiting for more than a second to send
       a message is a bad idea.

OPTIONS

       How to use curvecpclient:

       -q           optional
                 no error messages

       -Q           optional
                 print error messages (default)

       -v           optional
                 print extra information

       -c keydir           optional
                 use this public-key directory

       sname     server's name

       pk        server's public key

       ip        server's IP address

       port      server's UDP port

       ext       server's extension

       prog      run this client

SEE ALSO

       curvecpserver (1), curvecpmessage (1), inetd (8), tcpserver (1).

AUTHOR

       This manual page was written by Sergiusz Pawlowicz debian@pawlowicz.name  for  the  Debian
       system   (and   may   be   used  by  others).  The  source  of  this  page  is  a  webpage
       https://curvecp.org/messageapi.html .  Permission is granted to  copy,  distribute  and/or
       modify this document under public domain.

       This  manual  page  was rewritten for the Debian distribution because the original program
       does not have a manual page.

                                                                                          NaCl(1)