§ 4.40 - [encrypt] Built-In

Mnemonic aid: encrypt for ENCRYPT content

See also:  [decrypt] 

(Optionally re-) encrypts content (optionally from a hexadecimal block produced by a previous invocation of  [encrypt] ) into a hexadecimal block.

This encryption is asymmetrically reversible; therefore multiply encrypted content is not sensitive to order of decryption. It is useful to think of this as "multiple locks on a box"; you can put such locks on in any order, and take them off in any order.

The mode=1 option tells  [encrypt]  to use a more robust random number generator. Use of mode=1 is recommended. The mode option, if supplied, must be either 0 (which is also the default) or 1, and must match the mode used in the corresponding  [decrypt]  operation(s.)

The breakat=N option sets how many columns the result returns in. The default is 16 columns. This does not affect the encryption decoding or re-encoding, both of which only "see" sequences of hexadecimal digits.

In mode=0, the default mode, the seed=N option is a positive integer that affects the encryption encoding. The default is 1. In mode=1, the seed can be an integer or a string.

The icount=N option is a positive integer that affects the encryption encoding. The default is 1.

The salt=string option is a text string that affects the encryption encoding. The default is no salt.

The again=1 option allows for additional levels of encryption and decryption. This, in turn, is the the enabling mechanism which provides for double-locked box, or triple-exchange, two-party, non-public, non-shared, dual-key-based encryption. Here's how that works:

1. Each party owns a lock with a unique key.
2. Party one puts a message in a box locked by their own key
3. Party one then sends the box to party two.
4. Party two puts an additional lock on the box using their own key
5. Party two then sends the box back to party one.
6. Party one removes their lock on the box using their own key.
7. Party one sends the box, now locked only by party two's key, back to party two.
8. Party two removes their lock on the box using their own key: the contents are free.

As you can see from the above sequence, at no time does party one have party two's key, and at no time does party two have party one's key. In addition, the information in the box is never transferred in an unlocked (unencrypted) box.

Here's the sequence to use; p1=party one and p2=party two:

1. p1 actions: oneLockedBox =  [encrypt seed=1234,message]  ==> (send to p2)
2. p2 actions: twoLockedBox =  [encrypt again=1,seed=5678,oneLockedBox]  ==> (send back to p1)
3. p1 actions: oneLockedBox =  [encrypt again=1,1234,twoLockedBox]  ==> (send back to p2)
4. p2 actions: message =  [decrypt seed=5678,oneLockedBox] 

Multiple levels of encryption are created when  [encrypt]  is used normally first, then with the again=1 parameter on each subsequent result.

Decrypting multiply-encrypted blocks is done by running  [encrypt]  with again=1 on all but the last result, in any order, and then running  [decrypt]  on the final result. Here's a three-level example demonstrating out-of order decryption:

• result1 =  [encrypt seed=123,mystuff]  - first level of encryption
• result2 =  [encrypt seed=456,again=1, result1]  - second level encryption
• result3 =  [encrypt seed=789,again=1, result2]  - third level of encryption
• ------------- at this point, result3 is triple encrypted -------------
• result4 =  [encrypt seed=456,again=1,result3]  - first level of decryption
• result5 =  [encrypt seed=123,again=1,result4]  - second level of decryption
• mystuff =  [decrypt seed=789,result5]  - final level of decryption

Other built-ins used here:  [decrypt] ,  [local]  and  [v]