Class: RbNaCl::SecretBoxes::XSalsa20Poly1305

Inherits:
Object
  • Object
show all
Extended by:
RbNaCl::Sodium
Defined in:
lib/rbnacl/secret_boxes/xsalsa20poly1305.rb

Overview

The SecretBox class boxes and unboxes messages

This class uses the given secret key to encrypt and decrypt messages.

It is VITALLY important that the nonce is a nonce, i.e. it is a number used only once for any given pair of keys. If you fail to do this, you compromise the privacy of the messages encrypted. Give your nonces a different prefix, or have one side use an odd counter and one an even counter. Just make sure they are different.

The ciphertexts generated by this class include a 16-byte authenticator which is checked as part of the decryption. An invalid authenticator will cause the unbox function to raise. The authenticator is not a signature. Once you've looked in the box, you've demonstrated the ability to create arbitrary valid messages, so messages you send are repudiable. For non-repudiable messages, sign them before or after encryption.

Class Method Summary collapse

Instance Method Summary collapse

Methods included from RbNaCl::Sodium

sodium_constant, sodium_function, sodium_primitive, sodium_type

Constructor Details

#initialize(key) ⇒ RbNaCl::SecretBox

Create a new SecretBox

Sets up the Box with a secret key fro encrypting and decrypting messages.

Parameters:

  • key (String) —

    The key to encrypt and decrypt with

Raises:



47
48
49
 
# File 'lib/rbnacl/secret_boxes/xsalsa20poly1305.rb', line 47

def initialize(key)
  @key = Util.check_string(key, KEYBYTES, "Secret key")
end

Class Method Details

.key_bytes ⇒ Integer

The key bytes for the SecretBox class

Returns:

  • (Integer) —

    The number of bytes in a valid key



127
128
129
 
# File 'lib/rbnacl/secret_boxes/xsalsa20poly1305.rb', line 127

def self.key_bytes
  KEYBYTES
end

.nonce_bytes ⇒ Integer

The nonce bytes for the SecretBox class

Returns:

  • (Integer) —

    The number of bytes in a valid nonce



113
114
115
 
# File 'lib/rbnacl/secret_boxes/xsalsa20poly1305.rb', line 113

def self.nonce_bytes
  NONCEBYTES
end

Instance Method Details

#box(nonce, message) ⇒ String Also known as: encrypt

Encrypts a message

Encrypts the message with the given nonce to the key set up when initializing the class. Make sure the nonce is unique for any given key, or you might as well just send plain text.

This function takes care of the padding required by the NaCL C API.

Parameters:

  • nonce (String) —

    A 24-byte string containing the nonce.

  • message (String) —

    The message to be encrypted.

Returns:

  • (String) —

    The ciphertext without the nonce prepended (BINARY encoded)

Raises:



65
66
67
68
69
70
71
72
73
74
 
# File 'lib/rbnacl/secret_boxes/xsalsa20poly1305.rb', line 65

def box(nonce, message)
  Util.check_length(nonce, nonce_bytes, "Nonce")
  msg = Util.prepend_zeros(ZEROBYTES, message)
  ct  = Util.zeros(msg.bytesize)

  success = self.class.secretbox_xsalsa20poly1305(ct, msg, msg.bytesize, nonce, @key)
  fail CryptoError, "Encryption failed" unless success

  Util.remove_zeros(BOXZEROBYTES, ct)
end

#key_bytes ⇒ Integer

The key bytes for the SecretBox instance

Returns:

  • (Integer) —

    The number of bytes in a valid key



134
135
136
 
# File 'lib/rbnacl/secret_boxes/xsalsa20poly1305.rb', line 134

def key_bytes
  KEYBYTES
end

#nonce_bytes ⇒ Integer

The nonce bytes for the SecretBox instance

Returns:

  • (Integer) —

    The number of bytes in a valid nonce



120
121
122
 
# File 'lib/rbnacl/secret_boxes/xsalsa20poly1305.rb', line 120

def nonce_bytes
  NONCEBYTES
end

#open(nonce, ciphertext) ⇒ String Also known as: decrypt

Decrypts a ciphertext

Decrypts the ciphertext with the given nonce using the key setup when initializing the class.

This function takes care of the padding required by the NaCL C API.

Parameters:

  • nonce (String) —

    A 24-byte string containing the nonce.

  • ciphertext (String) —

    The message to be decrypted.

Returns:

  • (String) —

    The decrypted message (BINARY encoded)

Raises:



91
92
93
94
95
96
97
98
99
100
 
# File 'lib/rbnacl/secret_boxes/xsalsa20poly1305.rb', line 91

def open(nonce, ciphertext)
  Util.check_length(nonce, nonce_bytes, "Nonce")
  ct = Util.prepend_zeros(BOXZEROBYTES, ciphertext)
  message = Util.zeros(ct.bytesize)

  success = self.class.secretbox_xsalsa20poly1305_open(message, ct, ct.bytesize, nonce, @key)
  fail CryptoError, "Decryption failed. Ciphertext failed verification." unless success

  Util.remove_zeros(ZEROBYTES, message)
end

#primitive ⇒ Symbol

The crypto primitive for the SecretBox instance

Returns:

  • (Symbol) —

    The primitive used



106
107
108
 
# File 'lib/rbnacl/secret_boxes/xsalsa20poly1305.rb', line 106

def primitive
  self.class.primitive
end