[ALX] 2016-08-19 17:05:00: 
See https://tcfossil.sowaswie.de/repos/fossil/nacl/timeline (fossil repository) or
http://sourceforge.net/projects/tclsnippets/files/nacl/ for precompiled binaries, source, ...

The package has [TEA] Tcl Extension Architecture and has been tested under AIX, Linux, Mac OS X and Windows XP - 7.

This package is licensed unter BSD-3.

----
[AMG]: "NaCl" also refers to Google Chrome's Native Client sandbox.  See [NaTcl].

NaCl is an unfortunate choice of name, it conflicts with Google's "Native Client" (NaCl) library https://www.chromium.org/nativeclient which could well use a Tcl interface to enable full standard Tcl to run "native" within a browser at normal compiled speeds, and as such, we might prefer to rename this newer piece of software since Native Client has been around a while and probably has prior claim. [Larry Smith]

(2016-08-22) Note: according to Wikipedia, the NaCl crypto library has prior claim: 2008 vs. 2011 for Google's Native Client.

[EMJ] - 2016-08-22: See also http://nacl.cr.yp.to/.

(2021-07-29) Google Native Client was deprecated in 2020, and de-supported in June 2021. It's dead, while this NaCl cryptography library is still alive, so concerns about any potential naming conflict now belong in the past.

----

** NAME **
nacl - tcl package for Networking and Cryptography library (pronounced "salt")

** SYNOPSIS **
    :   nacl::info
    :   nacl::rcsid

    :   nacl::randombytes names
    :   nacl::randombytes source ?random|urandom|secrandomcopybytes|cryptgenrandom|default?
    :   nacl::randombytes lengthValue
    :   nacl::randombytes box ?-nonce?
    :   nacl::randombytes scalarmult ?-scalar|-group?
    :   nacl::randombytes secretbox ?-nonce|-key?
    :   nacl::randombytes stream ?-nonce|-key?
    :   nacl::randombytes auth ?-key?
    :   nacl::randombytes onetimeauth ?-key?
Public-key cryptography
    :   nacl::box info
    :   nacl::box keypair publicKeyVariable secretKeyVariable
    :   nacl::box cipherVariable messageValue nonceValue publicKeyValue secretKeyValue
    :   nacl::box open messageVariable cipherValue nonceValue publicKeyValue secretKeyValue

    :   nacl::scalarmult info
    :   nacl::scalarmult resultVariable scalarValue groupValue
    :   nacl::scalarmult base resultVariable scalarValue

    :   nacl::sign info
    :   nacl::sign keypair publicKeyVariable secretKeyVariable
    :   nacl::sign signedVariable messageValue secretKeyValue
    :   nacl::sign verify messageVariable signedValue publicKeyValue
Secret-key cryptography
    :   nacl::secretbox info
    :   nacl::secretbox cipherVariable messageValue nonceValue keyValue
    :   nacl::secretbox open messageVariable cipherValue nonceValue keyValue

    :   nacl::stream info
    :   nacl::stream generate cipherVariable nonceValue keyValue
    :   nacl::stream cipherVariable messageValue nonceValue keyValue

    :   nacl::auth info
    :   nacl::auth ?-hmac256|-hmac512256? authVariable messageValue keyValue
    :   nacl::auth verify -hmac256|-hmac512256 authValue messageValue keyValue

    :   nacl::onetimeauth info
    :   nacl::onetimeauth authVariable messageValue keyValue
    :   nacl::onetimeauth verify authValue messageValue keyValue
Low-level functions
    :   nacl::hash info
    :   nacl::hash ?-sha256|-sha512? hashVariable messageValue
 
** DESCRIPTION **
NaCl (pronounced "salt") is a new easy-to-use high-speed software library for network communication, encryption, decryption, signatures, etc. NaCl's goal is to provide all of the core operations needed to build higher-level cryptographic tools.
Of course, other libraries already exist for these core operations. NaCl advances the state of the art by improving security, by improving usability, and by improving speed.

** Key features **
No data flow from secrets to load addresses.
No data flow from secrets to branch conditions.
No padding oracles.
Centralizing randomness.
Avoiding unnecessary randomness.
Extremely high speed.

** Functions supported ** 
Simple NaCl applications need only six high-level NaCl functions: crypto_box for
public-key authenticated encryption; crypto_box_open for verification and decryption;
crypto_box_keypair to create a public key in the first place; and similarly for
signatures crypto_sign, crypto_sign_open, and crypto_sign_keypair.

A minimalist implementation of the NaCl API would provide just these six functions.
TweetNaCl is more ambitious, supporting all 25 of the NaCl functions listed below,
which as mentioned earlier are all of the C NaCl functions used by applications. This
list includes all of NaCl's "default" primitives except for crypto_auth_hmacsha512256,
which was included in NaCl only for compatibility with standards and is superseded
by crypto_onetimeauth.

The Ed25519 signature system has not yet been integrated into NaCl, since the Ed25519
software has not yet been fully audited; NaCl currently provides an older signature
system. However, NaCl has announced that it will transition to Ed25519, so TweetNaCl
provides Ed25519.

'''Public-key cryptography'''
   * Authenticated encryption using Curve25519, Salsa20, and Poly1305
   ** crypto_box = crypto_box_curve25519xsalsa20poly1305
   ** Not implemented: crypto_box_beforenm + crypto_box_afternm
   ** crypto_scalarmult = crypto_scalarmult_curve25519
   * Signatures using Ed25519
   ** crypto_sign = crypto_sign_ed25519
'''Secret-key cryptography'''
   * Authenticated encryption using Salsa20 and Poly1305
   ** crypto_secretbox = crypto_secretbox_xsalsa20poly1305
   * Encryption using Salsa20
   ** crypto_stream = crypto_stream_xsalsa20
   * Authentication using HMAC-SHA-512-256
   ** crypto_auth_hmacsha256_ref, crypto_auth_hmacsha512256_ref
   * One-time authentication using Poly1305
   ** crypto_onetimeauth = crypto_onetimeauth_poly1305
'''Low-level functions'''
   * Hashing using SHA-512 or SHA-256
   ** crypto_hash_sha256_ref, crypto_hash = crypto_hash_sha512

** HINTS ** 

'''How does crypto_box work?'''

   * `crypto_box` uses a Diffie-Hellman key exchange on the two keys and hashes the result. Then it uses that as the key for `secret_box`.

   * `crypto_box` is equivalent to `crypto_box_beforenm` followed by `crypto_box_afternm`.

   * `crypto_box_beforenm` is the hashed key-exchange which works as described in the Curve25519 paper, using elliptic curve Diffie-Hellman key exchange on Curve25519 hashing the result with HSalsa. This yields a 32 byte shared key.<<br>>`k = Hash(Curve25519(b, A)) = Hash(Curve25519(a, B))`

   * `crypto_box_afternm` is identical to `crypto_secret_box`. It takes a 24 byte nonce and a 32 byte key. It's an authenticated stream cipher using XSalsa20 for encryption and Poly1305 as MAC. The first 32 bytes of the output of XSalsa20 are used for the MAC, the rest are xored into the plaintext to encrypt it.

'''What happens if you use it multiple times?'''

If you take two fixed key-pairs, the result of the key exchange will always be the same.

But the symmetric part `secret_box` is secure even when you use a key several times, as long as you never reuse a nonce for that key, i.e. the (key, nonce) pair must be unique.

This property is pretty much the same for all modern authenticated stream ciphers, such as AES-GCM or XSalsa20-Poly1305.

Common ways to create a unique nonce are:

   * Use an 8 byte prefix and a random 16 byte value (stateless, random 16 bytes are most likely unique)
   * Use a 16 byte prefix and a 8 byte counter (stateful, useful in a connection where you increment for each packet)

from http://stackoverflow.com/questions/13663604/questions-about-the-nacl-crypto-library

** EXAMPLES **
Public-key cryptography authenticated encryption using '''nacl::box'''
======tcl
package require nacl

nacl::box keypair pub1 sec1
nacl::box keypair pub2 sec2
set nonce [nacl::randombytes box -nonce]
set message {My Secret Message}

if {[nacl::box encrypted $message $nonce $pub2 $sec1] == 0} {
  if {[nacl::box open decrypted $encrypted $nonce $pub1 $sec2] == 0} {
    puts "message decrypted = '$decrypted'"
  }
}
======
Public-key cryptography signatures using '''nacl::sign'''
======tcl
package require nacl

nacl::sign keypair pub sec
set message {My Message}

if {[nacl::sign encrypted $message $sec] == 0} {
  if {[nacl::sign verify decrypted $encrypted $pub] == 0} {
    puts "signed message decrypted = '$decrypted'"
  }
}
======
Secret-key cryptography authenticated encryption using '''nacl::secretbox'''
======tcl
package require nacl

set key [nacl::randombytes secretbox -key]
set nonce [nacl::randombytes secretbox -nonce]
set message {My Secret Message}

if {[nacl::secretbox encrypted $message $nonce $key] == 0} {
  if {[nacl::secretbox open decrypted $encrypted $nonce $key] == 0} {
    puts "message decrypted = '$decrypted'"
  }
}
======
Secret-key cryptography encryption using '''nacl::stream'''
======tcl
package require nacl

set key [nacl::randombytes stream -key]
set nonce [nacl::randombytes stream -nonce]
set message {My Secret Message}

if {[nacl::stream encrypted $message $nonce $key] == 0} {
  if {[nacl::stream decrypted $encrypted $nonce $key] == 0} {
    puts "message decrypted = '$decrypted'"
  }
}
======
Secret-key cryptography authentication using '''nacl::auth'''
======tcl
package require nacl

set key [nacl::randombytes auth -key]
set message {My Message}

if {[nacl::auth -hmac512256 auth $message $key] == 0} {
  if {[nacl::auth verify -hmac512256 $auth $message $key] == 0} {
    puts {authentication OK}
  }
}
======
Secret-key cryptography one-time authentication using '''nacl::onetimeauth'''
======tcl
package require nacl

set key [nacl::randombytes onetimeauth -key]
set message {My Message}

if {[nacl::onetimeauth auth $message $key] == 0} {
  if {[nacl::onetimeauth verify $auth $message $key] == 0} {
    puts {one-time authentication OK}
  }
}
======
Hashing using '''nacl::hash'''
======tcl
package require nacl

if {[nacl::hash -sha256 hash {NaCl does SHA256}] == 0} {
}
======
or
======tcl
package require nacl

if {[nacl::hash -sha512 hash {NaCl does SHA512}] == 0} {
}
======
** SEE ALSO **

WEB: nacl.cr.yp.to 20110221 [https://nacl.cr.yp.to]
<<br>>
PDF: The security impact of a new cryptographic library [https://cr.yp.to/highspeed/coolnacl-20120725.pdf]
<<br>><<br>>
WEB: tweetnacl.cr.yp.to 20140427 [https://tweetnacl.cr.yp.to]
<<br>>
PDF: TweetNaCl: A crypto library in 100 tweets [https://tweetnacl.cr.yp.to/tweetnacl-20140917.pdf]
<<br>><<br>>
WEB: en.wikipedia.org/wiki/NaCl_(software) [https://en.wikipedia.org/wiki/NaCl_(software)]
<<br>>
WEB: en.wikipedia.org/wiki/Elliptic_curve_cryptography [https://en.wikipedia.org/wiki/Elliptic_curve_cryptography]
<<br>>
WEB: en.wikipedia.org/wiki/Curve25519 [https://en.wikipedia.org/wiki/Curve25519]
<<br>>
WEB: RFC-7905: ChaCha20-Poly1305 Cipher Suites for Transport Layer Security (TLS) [https://tools.ietf.org/html/rfc7905]
<<br>>
WEB: RFC-8410: Algorithm Identifiers for Ed25519, Ed448, X25519, and X448 for Use in the Internet X.509 Public Key Infrastructure [https://tools.ietf.org/html/rfc8410]
<<br>>
WEB: [BAWT] Build Automation With Tcl / Batteries included [http://www.bawt.tcl3d.org/index.html]
** LEGAL NOTICE **
Copyright (C) 2016 Alexander Schoepe, Bochum, DE

NaCl and TweetNaCl crypto library are public domain and the Tcl package BSD-3 license

Contributors (alphabetical order)
<<br>>
Daniel J. Bernstein, University of Illinois at Chicago and Technische Universiteit Eindhoven
<<br>>
Bernard van Gastel, Radboud Universiteit Nijmegen
<<br>>
Wesley Janssen, Radboud Universiteit Nijmegen
<<br>>
Tanja Lange, Technische Universiteit Eindhoven
<<br>>
Peter Schwabe, Radboud Universiteit Nijmegen
<<br>>
Sjaak Smetsers, Radboud Universiteit Nijmegen

<<categories>> Category Command | Tcl syntax | Arts and Crafts of Tcl-tk Programming | Security | Cryptography