changes

NAMESPACE

@@ -15,8 +15,7 @@ export(keygen)
 export(password_store)
 export(password_verify)
 export(pubkey)
-export(rand_bytes)
-export(rand_num)
+export(random)
 export(salsa20)
 export(scrypt)
 export(sha256)

R/messaging.R → R/auth-encrypt.R

@@ -49,7 +49,7 @@
 #' @param key your own private key
 #' @param pubkey other person's public key
 #' @param nonce non-secret unique data to randomize the cipher
-auth_encrypt <- function(msg, key, pubkey, nonce = rand_bytes(24)){
+auth_encrypt <- function(msg, key, pubkey, nonce = random(24)){
   stopifnot(is.raw(msg))
   stopifnot(is.raw(key))
   stopifnot(is.raw(pubkey))
@@ -61,8 +61,8 @@ auth_encrypt <- function(msg, key, pubkey, nonce = rand_bytes(24)){
 #' @export
 #' @rdname messaging
 #' @useDynLib sodium R_secure_recv
-auth_decrypt <- function(bin, key, pubkey, nonce = attr(cipher, "nonce")){
-  stopifnot(is.raw(msg))
+auth_decrypt <- function(bin, key, pubkey, nonce = attr(bin, "nonce")){
+  stopifnot(is.raw(bin))
   stopifnot(is.raw(key))
   stopifnot(is.raw(pubkey))
   stopifnot(is.raw(nonce))

R/secret.R → R/data-encrypt.R

@@ -2,15 +2,15 @@
 #'
 #' Secret key encryption with authentication using a 256 bit key. Mostly useful for
 #' encrypting local data. For secure communication use public-key encryption instead
-#' (\link{secure_send}).
+#' (\link{auth_encrypt}).
 #'
 #' Symmetric encryption uses a secret key to encode and decode a message. This can be
 #' used to encrypt local data on disk, or as a building block for more complex methods.
 #'
 #' Because the same \code{secret} is used for both encryption and decryption, symmetric
 #' encryption by itself is impractical for communication. For exchanging secure messages
-#' with other parties, use assymetric (public-key) methods (see \link{encrypt} or
-#' \link{secure_send}).
+#' with other parties, use assymetric (public-key) methods (see \link{simple_encrypt} or
+#' \link{auth_encrypt}).
 #'
 #' The \code{nonce} is not confidential but required for decryption, and should be
 #' stored or sent along with the ciphertext. The purpose of the \code{nonce} is to
@@ -24,51 +24,51 @@
 #' @rdname symmetric
 #' @name symmetric methods
 #' @useDynLib sodium R_crypto_secret_encrypt
-#' @param msg raw vector with message to encrypt or sign
-#' @param secret raw vector of length 32 with secret key
-#' @param nonce raw vector of length 24 with non-secret random data
+#' @param msg message to be encrypted
+#' @param key shared secret key used for both encryption and decryption
+#' @param bin encrypted ciphertext
+#' @param nonce non-secret unique data to randomize the cipher
 #' @references \url{https://download.libsodium.org/doc/secret-key_cryptography/authenticated_encryption.html}
 #' @examples # 256-bit key
-#' secret <- sha256(charToRaw("This is a secret passphrase"))
+#' key <- sha256(charToRaw("This is a secret passphrase"))
 #' msg <- serialize(iris, NULL)
 #'
 #' # Encrypts with random nonce
-#' cipher <- data_encrypt(msg, secret)
-#' orig <- data_decrypt(cipher, secret)
+#' cipher <- data_encrypt(msg, key)
+#' orig <- data_decrypt(cipher, key)
 #' stopifnot(identical(msg, orig))
 #'
 #' # Tag the message with your key (HMAC)
-#' tag <- secret_tag(msg, key)
-data_encrypt <- function(msg, secret, nonce = rand_bytes(24)){
+#' tag <- data_tag(msg, key)
+data_encrypt <- function(msg, key, nonce = random(24)){
   stopifnot(is.raw(msg))
-  stopifnot(is.raw(secret))
-  out <- .Call(R_crypto_secret_encrypt, msg, secret, nonce)
+  stopifnot(is.raw(key))
+  out <- .Call(R_crypto_secret_encrypt, msg, key, nonce)
   structure(out, nonce = nonce)
 }
 
 #' @export
 #' @rdname symmetric
 #' @useDynLib sodium R_crypto_secret_decrypt
-#' @param bin raw vector with ciphertext as returned by \code{secret_encrypt}
-data_decrypt <- function(bin, secret, nonce = attr(cyphertext, "nonce")){
-  stopifnot(is.raw(msg))
-  stopifnot(is.raw(secret))
-  .Call(R_crypto_secret_decrypt, bin, secret, nonce)
+data_decrypt <- function(bin, key, nonce = attr(bin, "nonce")){
+  stopifnot(is.raw(bin))
+  stopifnot(is.raw(key))
+  .Call(R_crypto_secret_decrypt, bin, key, nonce)
 }
 
 #' @export
 #' @rdname symmetric
 #' @useDynLib sodium R_crypto_secret_auth
-data_tag <- function(msg, secret){
+data_tag <- function(msg, key){
   stopifnot(is.raw(msg))
-  stopifnot(is.raw(secret))
-  .Call(R_crypto_secret_auth, msg, secret)
+  stopifnot(is.raw(key))
+  .Call(R_crypto_secret_auth, msg, key)
 }
 
 #' @useDynLib sodium R_crypto_secret_verify
-data_verify <- function(msg, secret, tag){
+data_verify <- function(msg, key, tag){
   stopifnot(is.raw(msg))
   stopifnot(is.raw(tag))
-  stopifnot(is.raw(secret))
-  .Call(R_crypto_secret_verify, msg, secret, tag)
+  stopifnot(is.raw(key))
+  .Call(R_crypto_secret_verify, msg, key, tag)
 }

R/diffie.R

@@ -1,33 +1,36 @@
 #' Diffie-Hellman
 #'
-#' The Diffie-Hellman key exchange method allows two parties that have no prior knowledge of each
-#' other to jointly establish a shared secret key over an insecure channel. This key can then be
-#' used to encrypt subsequent communications using a symmetric key cipher.
+#' The Diffie-Hellman key exchange method allows two parties that have no prior knowledge
+#' of each other to jointly establish a shared secret key over an insecure channel. This
+#' key can then be used to encrypt subsequent communications using a symmetric key cipher.
 #'
-#' Encryption methods as implemented in \link{secret_encrypt} require that parties have a shared
-#' shared secret key. But often we wish to establish a secure channel with a party we have no prior
-#' relationship with. Diffie-hellman is a method for jointly agreeing on a shared secret without
-#' ever exchanging the secret itself. Sodium implements
+#' Encryption methods as implemented in \link{data_encrypt} require that parties have a
+#' shared secret key. But often we wish to establish a secure channel with a party we have
+#' no prior relationship with. Diffie-hellman is a method for jointly agreeing on a shared
+#' secret without ever exchanging the secret itself. Sodium implements
 #' \href{https://en.wikipedia.org/wiki/Curve25519}{Curve25519}, a state-of-the-art Diffie-Hellman
 #' function suitable for a wide variety of applications.
 #'
 #' The method conists of two steps (see examples). First, both parties generate a random private
 #' key and derive the corresponding public key using \link{pubkey}. These public keys are not
 #' confidential and can be exchanged over an insecure channel. After the public keys are exchanged,
 #' both parties will be able to calculate the (same) shared secret by combining his/her own private
-#' key with the other person's public key using \link{diffie_secret}.
+#' key with the other person's public key using \link{diffie_hellman}.
 #'
-#' After the shared secret has been established, the private and public keys are disposed, and
-#' parties can start encrypting communications based on the shared secret using e.g. \link{secret_encrypt}.
-#' Because the shared secret cannot be calculated using only the public keys, the process is safe
-#' from eavesdroppers.
+#' After the shared secret has been established, the private and public keys are disposed,
+#' and parties can start encrypting communications based on the shared secret using e.g.
+#' \link{data_encrypt}. Because the shared secret cannot be calculated using only the public
+#' keys, the process is safe from eavesdroppers.
 #'
 #' @export
 #' @rdname diffie
 #' @name Diffie-Hellman
 #' @aliases diffie
 #' @useDynLib sodium R_diffie_hellman
 #' @references \url{http://doc.libsodium.org/advanced/scalar_multiplication.html}
+#' @param key your private key
+#' @param pubkey other person's public key
+#' @return Returns a shared secret key which can be used in e.g. \link{data_encrypt}.
 #' @examples # Bob generates keypair
 #' bob_key <- keygen()
 #' bob_pubkey <- pubkey(bob_key)

R/hashing.R

@@ -27,8 +27,8 @@
 #' @aliases hashing
 #' @references \url{https://download.libsodium.org/doc/hashing/generic_hashing.html}
 #' @useDynLib sodium R_crypto_generichash
-#' @param buf raw vector with data to be hashed
-#' @param key raw vector with key for HMAC hashing. Optional, except for in \code{shorthash}.
+#' @param buf data to be hashed
+#' @param key key for HMAC hashing. Optional, except for in \code{shorthash}.
 #' @export
 #' @examples # Basic hashing
 #' msg <- serialize(iris, NULL)
@@ -88,7 +88,7 @@ sha512 <- function(buf, key = NULL){
 }
 
 #' @rdname hash
-#' @param size the size of the output hash. Must be between 16 and 64, recommended is 32.
+#' @param size length of the output hash. Must be between 16 and 64 (recommended is 32)
 #' @useDynLib sodium R_sha256 R_auth_sha256
 #' @export
 sha256 <- function(buf, key = NULL){

R/helpers.R

@@ -44,19 +44,11 @@ hex2bin <- function(hex, ignore = ":"){
 #' @export
 #' @rdname helpers
 #' @param n number of random bytes or numbers to generate
-rand_bytes <- function(n = 1){
+random <- function(n = 1){
   stopifnot(is.numeric(n))
   .Call(R_randombytes_buf, as.integer(n))
 }
 
-#' @rdname helpers
-#' @export
-rand_num <- function(n = 1){
-  # 64 bit double requires 8 bytes.
-  x <- matrix(as.numeric(rand_bytes(n*8)), ncol = 8)
-  as.numeric(x %*% 256^-(1:8))
-}
-
 #' @useDynLib sodium R_xor
 xor <- function(x, y){
   stopifnot(is.raw(x))

R/keygen.R

@@ -14,7 +14,7 @@
 #' decrypted using the corresponding private key. This allows anyone to send somebody a
 #' secure message by encrypting it with the receivers public key. The encrypted message
 #' will only be readable by the owner of the corresponding private key. Basic encryption
-#' is implemented in \link{seal_box} and \link{seal_open}.
+#' is implemented in \link{simple_encrypt}.
 #'
 #' Authentication works the other way around. In public key authentication, the owner of the
 #' private key creates a 'signature' (an authenticated checksum) for a message in a way that
@@ -29,20 +29,19 @@
 #' @export
 #' @rdname keygen
 #' @name keygen
+#' @param key private key for which to calculate the public key
+#' @param seed random data to seed the keygen
 #' @useDynLib sodium R_keygen
 #' @examples # Create keypair
 #' key <- keygen()
 #' pub <- pubkey(key)
 #'
 #' # Basic encryption
 #' msg <- serialize(iris, NULL)
-#' ciphertext <- seal_box(msg, pub)
-#' out <- seal_open(ciphertext, key)
+#' ciphertext <- simple_encrypt(msg, pub)
+#' out <- simple_decrypt(ciphertext, key)
 #' stopifnot(identical(msg, out))
-#'
-#' # Basic authentication
-#'
-keygen <- function(seed = rand_bytes(32)){
+keygen <- function(seed = random(32)){
   stopifnot(is.raw(seed))
   .Call(R_keygen, seed)
 }

R/signing.R → R/signatures.R

@@ -13,7 +13,7 @@
 #' that the binaries were not modified by intermediate parties in the distribution
 #' process.
 #'
-#' For confidential data, use authenticated encryption (\link{secure_send})
+#' For confidential data, use authenticated encryption (\link{auth_encrypt})
 #' which allows for sending signed and encrypted messages in a single method.
 #'
 #' Currently sodium uses a different type of key pair (ed25519) for signatures than
@@ -24,6 +24,10 @@
 #' @aliases sig
 #' @export
 #' @useDynLib sodium R_sig_sign
+#' @param msg message to sign
+#' @param key private key to sign message with
+#' @param sig a signature generated by \code{signature_sign}
+#' @param pubkey a public key of the keypair used by the signature
 #' @examples # Generate keypair
 #' key <- signature_keygen()
 #' pubkey <- signature_pubkey(key)
@@ -51,7 +55,8 @@ signature_verify <- function(msg, sig, pubkey){
 #' @export
 #' @rdname sig
 #' @useDynLib sodium R_sig_keygen
-signature_keygen <- function(seed = rand_bytes(32)){
+#' @param seed random data to seed the keygen
+signature_keygen <- function(seed = random(32)){
   stopifnot(is.raw(seed))
   .Call(R_sig_keygen, seed)
 }

R/sealing.R → R/simple-encrypt.R

@@ -8,7 +8,7 @@
 #'
 #' While the recipient can verify the integrity of the message, it cannot verify the
 #' identity of the sender. For sending authenticated encrypted messages, use
-#' \link{secure_send} and \link{secure_recv}.
+#' \link{auth_encrypt} and \link{auth_decrypt}.
 #'
 #' @export
 #' @rdname simple

R/stream.R

@@ -3,8 +3,8 @@
 #' Generate deterministic streams of random data based off a secret key and random nonce.
 #'
 #' You usually don't need to call these methods directly. For local encryption
-#' use the high-level functions \link{secret_encrypt} and \link{secret_decrypt}.
-#' For secure communication use \link{secure_send} and \link{secure_recv}.
+#' use \link{data_encrypt}. For secure communication use \link{simple_encrypt} or
+#' \link{auth_encrypt}.
 #'
 #' Random streams form the basis for most cryptographic methods. Based a shared secret
 #' (the key) we generate a predictable random data stream of equal length as the message
@@ -25,17 +25,17 @@
 #' @rdname stream
 #' @aliases stream
 #' @name streaming
-#' @param n integer, how many random bytes to generate
+#' @param n integer how many bytes to generate
 #' @param key raw vector of size 32 with secret data
-#' @param nonce non-confidental random data to make the stream unique
+#' @param nonce non-secret unique data to randomize the cipher
 #' @examples # Very basic encryption
 #' myfile <- file.path(R.home(), "COPYING")
 #' message <- readBin(myfile, raw(), file.info(myfile)$size)
 #' passwd <- charToRaw("My secret passphrase")
 #'
 #' # Encrypt:
 #' key <- hash(passwd)
-#' nonce8 <- rand_bytes(8)
+#' nonce8 <- random(8)
 #' stream <- chacha20(length(message), key, nonce8)
 #' ciphertext <- base::xor(stream, message)
 #'
@@ -46,10 +46,10 @@
 #'
 #' # Other stream ciphers
 #' stream <- salsa20(10000, key, nonce8)
-#' stream <- xsalsa20(10000, key, rand_bytes(24))
+#' stream <- xsalsa20(10000, key, random(24))
 #'
 #' shortkey <- hash(passwd, size = 16)
-#' stream <- aes128(10000, shortkey, rand_bytes(16))
+#' stream <- aes128(10000, shortkey, random(16))
 chacha20 <- function(n, key, nonce){
   stopifnot(is.numeric(n))
   stopifnot(is.raw(key))

man/diffie.Rd

@@ -8,29 +8,37 @@
 \usage{
 diffie_hellman(key, pubkey)
 }
+\arguments{
+\item{key}{your private key}
+
+\item{pubkey}{other person's public key}
+}
+\value{
+Returns a shared secret key which can be used in e.g. \link{data_encrypt}.
+}
 \description{
-The Diffie-Hellman key exchange method allows two parties that have no prior knowledge of each
-other to jointly establish a shared secret key over an insecure channel. This key can then be
-used to encrypt subsequent communications using a symmetric key cipher.
+The Diffie-Hellman key exchange method allows two parties that have no prior knowledge
+of each other to jointly establish a shared secret key over an insecure channel. This
+key can then be used to encrypt subsequent communications using a symmetric key cipher.
 }
 \details{
-Encryption methods as implemented in \link{secret_encrypt} require that parties have a shared
-shared secret key. But often we wish to establish a secure channel with a party we have no prior
-relationship with. Diffie-hellman is a method for jointly agreeing on a shared secret without
-ever exchanging the secret itself. Sodium implements
+Encryption methods as implemented in \link{data_encrypt} require that parties have a
+shared secret key. But often we wish to establish a secure channel with a party we have
+no prior relationship with. Diffie-hellman is a method for jointly agreeing on a shared
+secret without ever exchanging the secret itself. Sodium implements
 \href{https://en.wikipedia.org/wiki/Curve25519}{Curve25519}, a state-of-the-art Diffie-Hellman
 function suitable for a wide variety of applications.
 
 The method conists of two steps (see examples). First, both parties generate a random private
 key and derive the corresponding public key using \link{pubkey}. These public keys are not
 confidential and can be exchanged over an insecure channel. After the public keys are exchanged,
 both parties will be able to calculate the (same) shared secret by combining his/her own private
-key with the other person's public key using \link{diffie_secret}.
+key with the other person's public key using \link{diffie_hellman}.
 
-After the shared secret has been established, the private and public keys are disposed, and
-parties can start encrypting communications based on the shared secret using e.g. \link{secret_encrypt}.
-Because the shared secret cannot be calculated using only the public keys, the process is safe
-from eavesdroppers.
+After the shared secret has been established, the private and public keys are disposed,
+and parties can start encrypting communications based on the shared secret using e.g.
+\link{data_encrypt}. Because the shared secret cannot be calculated using only the public
+keys, the process is safe from eavesdroppers.
 }
 \examples{
 # Bob generates keypair

man/hash.Rd

@@ -20,11 +20,11 @@ sha512(buf, key = NULL)
 sha256(buf, key = NULL)
 }
 \arguments{
-\item{buf}{raw vector with data to be hashed}
+\item{buf}{data to be hashed}
 
-\item{key}{raw vector with key for HMAC hashing. Optional, except for in \code{shorthash}.}
+\item{key}{key for HMAC hashing. Optional, except for in \code{shorthash}.}
 
-\item{size}{the size of the output hash. Must be between 16 and 64, recommended is 32.}
+\item{size}{length of the output hash. Must be between 16 and 64 (recommended is 32)}
 
 \item{salt}{non-confidential random data to seed the algorithm}
 }