NaCl and TweetNaCl expose the same functions under multiple names: for example crypto_stream() is the same as crypto_stream_xsalsa20(). There are "operations" like stream or onetimeauth, and within that there are primitives (algorithms) like xsalsa20.
In the original NaCl tree, there are also alternate implementations (with various portability/performance tradeoffs) that usually include a portable "ref" version. NaCl compiles every flavor, with each of a dozen different compilers, compiler flags, and ABI options, to decide which gets included in the resulting library.
This naming system also aims to provide some measure of forward-compatibility for source code and library-selected defaults for algorithms. From the NaCl features page:
NaCl has a side mechanism through which a cryptographer can easily
specify the choice of signature system. Furthermore, NaCl is shipped with
a preselected choice, namely a state-of-the-art signature system suitable
for worldwide use in a wide range of applications.
For example, TweetNaCl offers crypto_sign(), which is the "preselected choice" for the specific underlying function named crypto_sign_ed25519().
These python bindings currently expose both the operation names (crypto_sign) and the primitive/algorithm-specific name (crypto_sign_ed25519). In particular, the C glue code (tweetnaclmodule.c) contains a different glue function for both names, even though tweetnacl.c only defines one of them. (A #define in tweetnacl.h replaces all instances of crypto_sign with crypto_sign_ed25519, in both the glue code and tweetnacl.c, so in fact both glue functions invoke the same thing).
This ticket is about removing the second glue function, leaving only the crypto_sign variant. The python-side code (in src/raw.py) can provide the aliases, for compatibility with the NaCl docs (allowing folks to transliterate C NaCl examples into Python by prefixing all calls with nacl.raw.). I'd like to prefer the shorter names (in docs and sample code).
There's a weak argument that using the longer names is better for forward-compatibility, based on the notion that a future version of NaCl might remap e.g. crypto_sign() to something better than Ed25519, but I don't buy it. Making a change like that would break any code that ever used the shorter name, rendering it incompatible with its peers that were still using the older NaCl. So I believe that the short-named functions are effectively locked to their current algorithms, and that new ones must be deployed (in the future) by adding new names.
NaCl and TweetNaCl expose the same functions under multiple names: for example
crypto_stream()is the same ascrypto_stream_xsalsa20(). There are "operations" likestreamoronetimeauth, and within that there are primitives (algorithms) likexsalsa20.In the original NaCl tree, there are also alternate implementations (with various portability/performance tradeoffs) that usually include a portable "ref" version. NaCl compiles every flavor, with each of a dozen different compilers, compiler flags, and ABI options, to decide which gets included in the resulting library.
This naming system also aims to provide some measure of forward-compatibility for source code and library-selected defaults for algorithms. From the NaCl features page:
For example, TweetNaCl offers
crypto_sign(), which is the "preselected choice" for the specific underlying function namedcrypto_sign_ed25519().These python bindings currently expose both the operation names (
crypto_sign) and the primitive/algorithm-specific name (crypto_sign_ed25519). In particular, the C glue code (tweetnaclmodule.c) contains a different glue function for both names, even though tweetnacl.c only defines one of them. (A#definein tweetnacl.h replaces all instances ofcrypto_signwithcrypto_sign_ed25519, in both the glue code and tweetnacl.c, so in fact both glue functions invoke the same thing).This ticket is about removing the second glue function, leaving only the
crypto_signvariant. The python-side code (in src/raw.py) can provide the aliases, for compatibility with the NaCl docs (allowing folks to transliterate C NaCl examples into Python by prefixing all calls withnacl.raw.). I'd like to prefer the shorter names (in docs and sample code).There's a weak argument that using the longer names is better for forward-compatibility, based on the notion that a future version of NaCl might remap e.g.
crypto_sign()to something better than Ed25519, but I don't buy it. Making a change like that would break any code that ever used the shorter name, rendering it incompatible with its peers that were still using the older NaCl. So I believe that the short-named functions are effectively locked to their current algorithms, and that new ones must be deployed (in the future) by adding new names.