### para_write ###
A modular audio stream writer. It supports a simple file writer
-output plug-in and optional WAV/raw players for ALSA (Linux) and for
-coreaudio (Mac OS). para_write can also be used as a stand-alone WAV
-or raw audio player.
+output plug-in and optional WAV/raw players for ALSA (Linux) and OSS.
+para_write can also be used as a stand-alone WAV or raw audio player.
### para_play ###
you need libogg, libvorbis, libvorbisfile. The corresponding Debian
packages are called `libogg-dev` and `libvorbis-dev`.
-- [libfaad](http://www.audiocoding.com/). For aac files (m4a) you
-need libfaad (`libfaad-dev`).
+- [libfaad and mp4ff](http://www.audiocoding.com/). For aac files
+(m4a) you need libfaad and libmp4ff (package: `libfaad-dev`). Note
+that for some distributions, e.g. Ubuntu, mp4ff is not part of the
+libfaad package. Install the faad library from sources (available
+through the above link) to get the mp4ff library and header files.
- [speex](http://www.speex.org/). In order to stream or decode speex
files, libspeex (`libspeex-dev`) is required.
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
-a stream cipher, either RC4 or AES in integer counter mode.
+the AES stream cipher in integer counter mode.
-In this chapter we briefly describe RSA, RC4 and AES, and sketch the
+In this chapter we briefly describe RSA and AES, and sketch the
[authentication handshake](#Client-server.authentication)
between para_client and para_server. User management is discussed
in the section on [the user_list file](#The.user_list.file).
server. Connecting para_audiod is a different matter and is described
in a [separate section](#Connecting.para_audiod).
-RSA, RC4, AES
--------------
+RSA and 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,
+A block cipher is a transformation which operates on fixed-length
+blocks. For symmetric block ciphers the transformation is determined
+by a single key for both encryption and decryption. For asymmetric
+block ciphers, on the other hand, the key consists of two parts,
called the public key and the private key. A message can be encrypted
-with either key and only the counterpart of that key can decrypt
-the message. While RSA can be used for both signing and encrypting
-a message, paraslash uses RSA only for the latter purpose. The
-RSA public key encryption and signatures algorithms are defined in
-detail in RFC 2437.
-
-RC4 is a stream cipher, i.e. the input is XORed with a pseudo-random
-key stream to produce the output. Decryption uses the same function
-calls as encryption. While RC4 supports variable key lengths,
-paraslash uses a fixed length of 256 bits, which is considered a
-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.
+with either key and only the counterpart of that key can decrypt the
+message. Asymmetric block ciphers can be used for both signing and
+encrypting a message.
+
+RSA is an asymmetric block cipher which is used in many applications,
+including ssh and gpg. The RSA public key encryption and signatures
+algorithms are defined in detail in RFC 2437. Paraslash relies on
+RSA for authentication.
+
+Stream ciphers XOR the input with a pseudo-random key stream to produce
+the output. Decryption uses the same function calls as encryption.
+Any block cipher can be turned into a stream cipher by generating the
+pseudo-random key stream by encrypting successive values of a counter
+(counter mode).
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.
+cipher. Paraslash employs AES in counter mode as described above to
+encrypt communications. Since a stream cipher key must not be used
+twice, a random key is generated for every new connection.
Client-server authentication
----------------------------
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, RC4 and AES crypto routines and on the
+by the crypto library (openssl or libgcrypt), on the security of
+the implementation of the RSA and AES crypto routines and on the
infeasibility to invert the SHA1 function.
Neither para_server or para_client create RSA keys on their
also limited. For example only one application can open the device
at any time. The OSS writer is activated by default on BSD Systems.
-- *OSX*. Mac OS X has yet another API called CoreAudio. The OSX writer
-for this API is only compiled in on such systems and is of course
-the default there.
-
- *FILE*. The file writer allows to capture the audio stream and
write the PCM data to a file on the file system rather than playing
it through a sound device. It is supported on all platforms and is
Development
===========
+Contributing
+------------
+
+Paraslash is an open source project and contributions are
+welcome. Here's a list of things you can do to help the project:
+
+- Report problems with building, installing or running the software.
+ In particular, test the experimental git branches ("next" and "pu").
+ This helps to identify and fix problems before the code gets merged
+ and thus keeps the master branch as stable as possible.
+- Proofread the documentation (manual, web pages, man pages, source
+ code documentation) and point out unclear or poorly written parts. If
+ you are a native English speaker you will easily find a lot of text
+ that could be improved.
+- Run analysis tools (coverity, afl, sparse, etc.) and report issues
+ found by those tools.
+- Suggest new features you would like to see implemented.
+- Compile and test on your favorite architecture or operating
+ system. The code is tested only on a limited set of systems, so you
+ will probably encounter problems when building on different systems.
+- Post about about paraslash on your blog or on social networks.
+- Build and maintain Debian/RPM packages for your favorite distribution.
+
+Note that there is no mailing list, no bug tracker and no discussion
+forum for paraslash. If you'd like to contribute, or have questions
+about contributing, send email to Andre Noll <maan@tuebingen.mpg.de>.
+
Tools
-----
The preferred coding style for paraslash coincides more or less
with the style of the Linux kernel. So rather than repeating what is
-written [there](http://www.kernel.org/doc/Documentation/CodingStyle),
+written [there](http://www.kernel.org/doc/Documentation/process/coding-style.rst),
here are the most important points.
- Burn the GNU coding standards.