X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=blobdiff_plain;f=web%2Fmanual.m4;h=e809c8b22be7ddea6a6e9335550670098a303b06;hp=3f5f148fba7819ac03395792ebabec54d84ed6a4;hb=d1e6b28f66e243516d01916f9125baee75dd98d6;hpb=1775d4d4147730e79e48aa941aee88580b8beb08 diff --git a/web/manual.m4 b/web/manual.m4 index 3f5f148f..e809c8b2 100644 --- a/web/manual.m4 +++ b/web/manual.m4 @@ -112,7 +112,7 @@ can be used by any scripting language to produce user interfaces with little programming effort. All connections between para_server and para_client are encrypted -with a symmetric RC4 session key. For each user of paraslash you must +with a symmetric session key. For each user of paraslash you must create a public/secret RSA key pair for authentication. If para_client is started without non-option arguments, an interactive @@ -232,14 +232,6 @@ Detailed description: In any case you'll need scripts which run during compilation require the EMPH(Bourne again shell). It is most likely already installed. - - XREFERENCE(http://www.openssl.org/, openssl) or - XREFERENCE(ftp://ftp.gnupg.org/gcrypt/libgcrypt/, libgcrypt). - At least one of these two libraries is needed as the backend - for cryptographic routines on both the server and the client - side. Both openssl and libgcrypt are usually shipped with the - distro, but you might have to install the development package - (libssl-dev or libgcrypt-dev on debian systems) as well. - - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/gengetopt/, gengetopt) is needed to generate the C code for the command line parsers of all paraslash executables. @@ -249,6 +241,14 @@ Detailed description: In any case you'll need Optional: + - XREFERENCE(http://www.openssl.org/, openssl) or + XREFERENCE(ftp://ftp.gnupg.org/gcrypt/libgcrypt/, libgcrypt). + At least one of these two libraries is needed as the backend + for cryptographic routines on both the server and the client + side. Both openssl and libgcrypt are usually shipped with the + distro, but you might have to install the development package + (libssl-dev or libgcrypt-dev on debian systems) as well. + - XREFERENCE(http://www.underbit.com/products/mad/, libmad). To compile in MP3 support for paraslash, the development package must be installed. It is called libmad0-dev on @@ -406,7 +406,7 @@ the directory /var/paraslash that has been created during installation: sudo chown $LOGNAME /var/paraslash -Alternatively, use the --afs_socket Option to specify a different +Alternatively, use the --afs-socket Option to specify a different location for the AFS command socket. For this first try, we'll use the info loglevel to make the output @@ -505,9 +505,9 @@ User management para_server uses a challenge-response mechanism to authenticate requests from incoming connections, similar to ssh's public key authentication method. Authenticated connections are encrypted using -the RC4 stream cipher. +a stream cipher, either RC4 or AES in integer counter mode. -In this chapter we briefly describe RSA and RC4 and sketch the +In this chapter we briefly describe RSA, RC4 and AES, and sketch the REFERENCE(Client-server authentication, authentication handshake) between para_client and para_server. User management is discussed in the section on REFERENCE(The user_list file, the user_list file). @@ -517,8 +517,8 @@ in a REFERENCE(Connecting para_audiod, separate section). -RSA and RC4 -~~~~~~~~~~~ +RSA, RC4, AES +~~~~~~~~~~~~~ RSA is an asymmetric block cipher which is used in many applications, including ssh and gpg. An RSA key consists in fact of two keys, @@ -537,6 +537,15 @@ strong encryption by today's standards. Since the same key must never be used twice, a different, randomly-generated key is used for every new connection. +AES, the advanced encryption standard, is a well-known symmetric block +cipher, i.e. a transformation operating on fixed-length blocks which +is determined by a single key for both encryption and decryption. Any +block cipher can be turned into a stream cipher by generating +a pseudo-random key stream by encrypting successive values of a +counter. The AES_CTR128 stream cipher used in paraslash is obtained +in this way from the AES block cipher with a 128 bit block size. + + Client-server authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -557,7 +566,7 @@ as follows: fixed-length buffer with random bytes, encrypts that buffer using the public key and sends the encrypted buffer to the client. The first part of the buffer is the challenge which - is used for authentication while the second part is the RC4 + is used for authentication while the second part is the session key. - para_client receives the encrypted buffer and decrypts it @@ -574,12 +583,12 @@ as follows: - Otherwise the user is considered authenticated and the client is allowed to proceed by sending a command to be executed. From - this point on the communication is encrypted using the RC4 - stream cipher with the session key known to both peers. + this point on the communication is encrypted using the stream + cipher with the session key known to both peers. paraslash relies on the quality of the pseudo-random bytes provided by the crypto library (openssl or libgcrypt), on the security of -the implementation of the RSA and RC4 crypto routines and on the +the implementation of the RSA, RC4 and AES crypto routines and on the infeasibility to invert the SHA1 function. Neither para_server or para_client create RSA keys on their own. This @@ -592,7 +601,7 @@ The user_list file At startup para_server reads the user list file which contains one line per user. The default location of the user list file may be -changed with the --user_list option. +changed with the --user-list option. There should be at least one user in this file. Each user must have an RSA key pair. The public part of the key is needed by para_server @@ -639,7 +648,7 @@ restricted on platforms that support UNIX socket credentials which allow para_audiod to obtain the Unix credentials of the connecting process. -Use para_audiod's --user_allow option to allow connections only for +Use para_audiod's --user-allow option to allow connections only for a limited set of users. ----------------------- @@ -1071,17 +1080,18 @@ It is possible to change the behaviour of the add command by using the Troubleshooting ~~~~~~~~~~~~~~~ -Use the debug loglevel (option -l debug for most commands) to show -debugging info. Almost all paraslash executables have a brief online -help which is displayed by using the -h switch. The --detailed-help -option prints the full help text. +Use the debug loglevel (-l debug) to show debugging info. All paraslash +executables have a brief online help which is displayed when -h is +given. The --detailed-help option prints the full help text. If para_server crashed or was killed by SIGKILL (signal 9), it may refuse to start again because of "dirty osl tables". In this case you'll have to run the oslfsck program of libosl to fix your -database. It might be necessary to use --force (even if your name -isn't Luke). However, make sure para_server isn't running before -executing oslfsck --force. +database: + + oslfsck -fd ~/.paraslash/afs_database-0.4 + +However, make sure para_server isn't running before executing oslfsck. If you don't mind to recreate your database you can start from scratch by removing the entire database directory, i.e. @@ -1099,6 +1109,14 @@ care about the table contents. To check for invalid table contents, use This prints out references to missing audio files as well as invalid playlists and mood definitions. +Similarly, para_audiod refuses to start if its socket file exists, since +this indicates that another instance of para_audiod is running. After +a crash a stale socket file might remain and you must run + + para_audiod --force + +once to fix it up. + --------------------------------------- Audio formats and audio format handlers --------------------------------------- @@ -1135,7 +1153,17 @@ Excited Linear Prediction) coding. It is designed for voice over IP applications, has modest complexity and a small memory footprint. Wideband and narrowband (telephone quality) speech are supported. As for Vorbis audio, Speex bit-streams are often stored -in OGG files. +in OGG files. As of 2012 this codec is considered obsolete since the +Oppus codec, described below, surpasses its performance in all areas. + +*OGG/Opus* + +Opus is a lossy audio compression format standardized through RFC +6716 in 2012. It combines the speech-oriented SILK codec and the +low-latency CELT (Constrained Energy Lapped Transform) codec. Like +OGG/Vorbis and OGG/Speex, Opus data is usually encapsulated in OGG +containers. All known software patents which cover Opus are licensed +under royalty-free terms. *AAC* @@ -1218,9 +1246,7 @@ chunk table and reads the meta data. The audio format handler code is linked into para_server and executed via the _add_ command. The same code is also available as a stand-alone tool, para_afh, which can be used to print the technical data, the -chunk table and the meta data of a file. Furthermore, one can use -para_afh to cut an audio file, i.e. to select some of its chunks to -produce a new file containing only these chunks. +chunk table and the meta data of a file. ---------- Networking @@ -1506,10 +1532,10 @@ the output to STDOUT, the filter modules of para_audiod are always connected to a receiver which produces the input stream and a writer which absorbs the output stream. -Some filters depend on a specific library being installed and are -not compiled in if this library was not found at compile time. To -see the list of supported filters, run para_filter and para_audiod -with the --help option. The output looks similar to the following: +Some filters depend on a specific library and are not compiled in +if this library was not found at compile time. To see the list of +supported filters, run para_filter and para_audiod with the --help +option. The output looks similar to the following: Available filters: compress wav amp fecdec wmadec prebuffer oggdec aacdec mp3dec @@ -1770,7 +1796,7 @@ a curses window. By default the command para_audioc -- stat -p -is executed, but this can be customized via the --stat_cmd option. In +is executed, but this can be customized via the --stat-cmd option. In particular it possible to use para_client -- stat -p @@ -2181,6 +2207,8 @@ RFCs Congestion Control ID 2: TCP-like Congestion Control - XREFERENCE(http://www.ietf.org/rfc/rfc4342.txt, RFC 4342) (2006): Congestion Control ID 3: TCP-Friendly Rate Control (TFRC) + - XREFERENCE(http://www.ietf.org/rfc/rfc6716.txt, RFC 6716) (2012): + Definition of the Opus Audio Codec Application web pages ~~~~~~~~~~~~~~~~~~~~~