git.iko.soy/urbit.org
on cb112e8 help sign in
urbit.org/content/docs/hoon/reference/stdlib/3f.md
722 lines 14 kB history raw
1+++
2title = "3f: Scrambling"
3weight = 26
4template = "doc.html"
5+++
6### `++un`
8Reversible scrambling
10A core that contains arms that perform reversible scrambling operations.
11Used in the `@p` phonetic base.
13#### Source
15```hoon
16 ++ un
17 |%
18```
20---
21### `++wren:un`
23Conceal structure
25Scrambles a byte-string `pyn` by adding the current position to each
26byte, looking it up in an s-box, and then performing the XOR operation
27on the result, pushing it forward. The inverse of `wred`.
29#### Accepts
31`pyn` is an atom.
33#### Produces
35An atom.
37#### Source
39```hoon
40 ++ wren
41 |= pyn=@ ^- @
42 =+ len=(met 3 pyn)
43 ?: =(0 len)
44 0
45 => .(len (dec len))
46 =+ mig=(zaft (xafo len (cut 3 [len 1] pyn)))
47 %+ can 3
48 %- flop ^- (list [@ @])
49 :- [1 mig]
50 |- ^- (list [@ @])
51 ?: =(0 len)
52 ~
53 => .(len (dec len))
54 =+ mog=(zyft :(mix mig (end 3 1 len) (cut 3 [len 1] pyn)))
55 [[1 mog] $(mig mog)]
56 ::
57```
59#### Examples
61```
62 > `@ux`(wren:un 'testing')
63 0x30.bf6a.b9fe.7d8f
65 > `@ux`'testing'
66 0x67.6e69.7473.6574
68 > `@da`(wred:un (wren:un ~2001.2.5))
69 ~2001.2.5
70```
72---
73### `++wred:un`
75Restore structure
77Unscrambles a byte-string `cry` by subtracting the current position from
78each byte, looking it up in an s-box, and performing the XOR operation
79on the result, pushing it forward. The inverse of `wren`.
81#### Accepts
83`cry` is an atom.
85#### Produces
87An atom.
89#### Source
91```hoon
92 ++ wred
93 |= cry=@ ^- @
94 =+ len=(met 3 cry)
95 ?: =(0 len)
96 0
97 => .(len (dec len))
98 =+ mig=(cut 3 [len 1] cry)
99 %+ can 3
100 %- flop ^- (list [@ @])
101 :- [1 (xaro len (zart mig))]
102 |- ^- (list [@ @])
103 ?: =(0 len)
104 ~
105 => .(len (dec len))
106 =+ mog=(cut 3 [len 1] cry)
107 [[1 :(mix mig (end 3 1 len) (zyrt mog))] $(mig mog)]
108 ::
109```
111#### Examples
113```
114 > (wred:un 0x30.bf6a.b9fe.7d8f)
115 29.113.321.805.538.676
117 > `@t`(wred:un 0x30.bf6a.b9fe.7d8f)
118 'testing'
120 > (wred:un (wren:un 200.038.426))
121 200.038.426
122```
124---
125### `++xafo:un`
127Add modulo 255
129Produces the sum of two atoms modulo 255, encoded as a nonzero byte. The inverse
130of `xaro`.
132#### Accepts
134`a` is an atom.
136`b` is an atom.
138#### Produces
140An atom.
142#### Source
144```hoon
145 ++ xafo |=([a=@ b=@] +((mod (add (dec b) a) 255)))
146```
148#### Examples
150```
151 > (xafo:un 5 6)
152 11
154 > (xafo:un 256 20)
155 21
157 > (xafo:un 256 (xaro:un 256 20))
158 20
159```
161---
162### `++xaro:un`
164Subtract modulo 255
166Produces the sum of two atoms modulo 255, encoded as a nonzero byte. The inverse
167of `xafo`.
169#### Accepts
171`a` is an atom.
173`b` is an atom.
175#### Produces
177An atom.
179#### Source
181```hoon
182 ++ xaro |=([a=@ b=@] +((mod (add (dec b) (sub 255 (mod a 255))) 255)))
183```
185#### Examples
187```
188 > (xaro:un 17 57)
189 40
191 > (xaro:un 265 12)
192 2
194 > (xaro:un 256 (xafo:un 256 20))
195 20
196```
198---
199### `++zaft:un`
201Look up in 255 sub box
203Looks up a nonzero byte `a` in a substitution box with 255 values, producing a
204unique nonzero byte. The inverse of `zart`.
206#### Accepts
208`a` is an atom of one byte in length.
210#### Produces
212An atom.
214#### Source
216```hoon
217 ++ zaft
218 |= a=@D
219 =+ ^= b
220 0xcc.75bc.86c8.2fb1.9a42.f0b3.79a0.92ca.21f6.1e41.cde5.fcc0.
221 7e85.51ae.1005.c72d.1246.07e8.7c64.a914.8d69.d9f4.59c2.8038.
222 1f4a.dca2.6fdf.66f9.f561.a12e.5a16.f7b0.a39f.364e.cb70.7318.
223 1de1.ad31.63d1.abd4.db68.6a33.134d.a760.edee.5434.493a.e323.
224 930d.8f3d.3562.bb81.0b24.43cf.bea5.a6eb.52b4.0229.06b2.6704.
225 78c9.45ec.d75e.58af.c577.b7b9.c40e.017d.90c3.87f8.96fa.1153.
226 0372.7f30.1c32.ac83.ff17.c6e4.d36d.6b55.e2ce.8c71.8a5b.b6f3.
227 9d4b.eab5.8b3c.e7f2.a8fe.9574.5de0.bf20.3f15.9784.9939.5f9c.
228 e609.564f.d8a4.b825.9819.94aa.2c08.8e4c.9b22.477a.2840.3ed6.
229 3750.6ef1.44dd.89ef.6576.d00a.fbda.9ed2.3b6c.7b0c.bde9.2ade.
230 5c88.c182.481a.1b0f.2bfd.d591.2726.57ba
231 (cut 3 [(dec a) 1] b)
232```
234#### Examples
236```
237 > (zaft:un 0x12)
238 42
240 > (zaft:un 0xff)
241 204
242 > `@ux`(zart:un 204)
243 0xff
245 > (zaft:un 0x0)
246 ! decrement-underflow
247 ! exit
248```
250---
251### `++zart:un`
253Reverse look up in 255 sub box
255Looks up the index of a nonzero byte `a` in the substitution box with 255
256values, producing a unique nonzero byte. The inverse of `zaft`.
258#### Accepts
260`a` is an atom of one byte in length.
262#### Produces
264An atom.
266#### Source
268```hoon
269 ++ zart :: reverse 255-sbox
270 |= a=@D
271 =+ ^= b
272 0x68.4f07.ea1c.73c9.75c2.efc8.d559.5125.f621.a7a8.8591.5613.
273 dd52.40eb.65a2.60b7.4bcb.1123.ceb0.1bd6.3c84.2906.b164.19b3.
274 1e95.5fec.ffbc.f187.fbe2.6680.7c77.d30e.e94a.9414.fd9a.017d.
275 3a7e.5a55.8ff5.8bf9.c181.e5b6.6ab2.35da.50aa.9293.3bc0.cdc6.
276 f3bf.1a58.4130.f844.3846.744e.36a0.f205.789e.32d8.5e54.5c22.
277 0f76.fce7.4569.0d99.d26e.e879.dc16.2df4.887f.1ffe.4dba.6f5d.
278 bbcc.2663.1762.aed7.af8a.ca20.dbb4.9bc7.a942.834c.105b.c4d4.
279 8202.3e61.a671.90e6.273d.bdab.3157.cfa4.0c2e.df86.2496.f7ed.
280 2b48.2a9d.5318.a343.d128.be9c.a5ad.6bb5.6dfa.c5e1.3408.128d.
281 2c04.0339.97a1.2ff0.49d0.eeb8.6c0a.0b37.b967.c347.d9ac.e072.
282 e409.7b9f.1598.1d3f.33de.8ce3.8970.8e7a
283 (cut 3 [(dec a) 1] b)
284 ::
285```
287#### Examples
289```
290 > `@ux`(zart:un 204)
291 0xff
293 > `@ux`(zart:un 42)
294 0x12
296 > (zaft:un 0x12)
297 42
298```
300---
301### `++zyft:un`
303Lookup byte in 256 sub box
305Looks up a byte `a` in a substitution box with 256 values, producing a byte. The
306inverse of `zyrt`.
308#### Accepts
310`a` is an atom of one byte in length.
312#### Produces
314An atom.
316#### Source
318```hoon
319 ++ zyft :: forward 256-sbox
320 |= a=@D
321 =+ ^= b
322 0xbb49.b71f.b881.b402.17e4.6b86.69b5.1647.115f.dddb.7ca5.
323 8371.4bd5.19a9.b092.605d.0d9b.e030.a0cc.78ba.5706.4d2d.
324 986a.768c.f8e8.c4c7.2f1c.effe.3cae.01c0.253e.65d3.3872.
325 ce0e.7a74.8ac6.daac.7e5c.6479.44ec.4143.3d20.4af0.ee6c.
326 c828.deca.0377.249f.ffcd.7b4f.eb7d.66f2.8951.042e.595a.
327 8e13.f9c3.a79a.f788.6199.9391.7fab.6200.4ce5.0758.e2f1.
328 7594.c945.d218.4248.afa1.e61a.54fb.1482.bea4.96a2.3473.
329 63c2.e7cb.155b.120a.4ed7.bfd8.b31b.4008.f329.fca3.5380.
330 9556.0cb2.8722.2bea.e96e.3ac5.d1bc.10e3.2c52.a62a.b1d6.
331 35aa.d05e.f6a8.0f3b.31ed.559d.09ad.f585.6d21.fd1d.8d67.
332 370b.26f4.70c1.b923.4684.6fbd.cf8b.5036.0539.9cdc.d93f.
333 9068.1edf.8f33.b632.d427.97fa.9ee1
334 (cut 3 [a 1] b)
335 ::
336```
338#### Examples
340```
341 > (zyft:un 0x12)
342 57
344 > (zyft:un 0x0)
345 225
347 > (zyft:un 0xff)
348 187
349 > `@ux`(zyrt:un 187)
350 0xff
351```
353---
354### `++zyrt:un`
356Reverse lookup byte in 256 sub box
358Looks up a byte `a` in a substitution box with 256 values, producing a byte.
359The inverse of `zyft`.
361#### Accepts
363`a` is an atom of one byte in length.
365#### Produces
367An atom.
369#### Source
371```hoon
372 ++ zyrt :: reverse 256-sbox
373 |= a=@D
374 =+ ^= b
375 0x9fc8.2753.6e02.8fcf.8b35.2b20.5598.7caa.c9a9.30b0.9b48.
376 47ce.6371.80f6.407d.00dd.0aa5.ed10.ecb7.0f5a.5c3a.e605.
377 c077.4337.17bd.9eda.62a4.79a7.ccb8.44cd.8e64.1ec4.5b6b.
378 1842.ffd8.1dfb.fd07.f2f9.594c.3be3.73c6.2cb6.8438.e434.
379 8d3d.ea6a.5268.72db.a001.2e11.de8c.88d3.0369.4f7a.87e2.
380 860d.0991.25d0.16b9.978a.4bf4.2a1a.e96c.fa50.85b5.9aeb.
381 9dbb.b2d9.a2d1.7bba.66be.e81f.1946.29a8.f5d2.f30c.2499.
382 c1b3.6583.89e1.ee36.e0b4.6092.937e.d74e.2f6f.513e.9615.
383 9c5d.d581.e7ab.fe74.f01b.78b1.ae75.af57.0ec2.adc7.3245.
384 12bf.2314.3967.0806.31dc.cb94.d43f.493c.54a6.0421.c3a1.
385 1c4a.28ac.fc0b.26ca.5870.e576.f7f1.616d.905f.ef41.33bc.
386 df4d.225e.2d56.7fd6.1395.a3f8.c582
387 (cut 3 [a 1] b)
388```
390#### Examples
392```
393 > `@ux`(zyrt:un 57)
394 0x12
396 > `@ux`(zyrt:un 225)
397 0x0
399 > `@ux`(zyrt:un 187)
400 0xff
401 > (zyft:un 0xff)
402 187
403```
405---
406### `++ob`
408Reversible scrambling, v2
410```hoon
411 ++ ob
412 |%
413```
415A core for performing reversible scrambling operations for the `@p` phonetic
416base.
418---
419### `++feen:ob`
421Conceal structure, v2
423Randomly permutes atoms that fit into 17 to 32 bits into one another. If the
424atom fits into 33 to 64 bits, does the same permutation on the low 32 bits
425only. Otherwise, passes the atom through unchanged.
427#### Accepts
429An atom.
431#### Produces
433An atom.
435#### Source
437```hoon
438 ++ feen
439 |= pyn=@ ^- @
440 ?: &((gte pyn 0x1.0000) (lte pyn 0xffff.ffff))
441 (add 0x1.0000 (fice (sub pyn 0x1.0000)))
442 ?: &((gte pyn 0x1.0000.0000) (lte pyn 0xffff.ffff.ffff.ffff))
443 =+ lo=(dis pyn 0xffff.ffff)
444 =+ hi=(dis pyn 0xffff.ffff.0000.0000)
445 %+ con hi
446 (add 0x1.0000 (fice (sub lo 0x1.0000)))
447 pyn
448 ::
449```
451#### Examples
453```
454 > `@p`(feen:ob 111.103)
455 ~mophul-pagwyx
457 > `@p`(feen:ob ~mophul-pagwyx)
458 ~wisfed-lonwes
460 > `@p`(feen:ob (fend:ob ~mophul-pagwyx))
461 ~mophul-pagwyx
463 > `@p`(feen:ob ~wex)
464 ~wex
465```
467---
468### `++fend:ob`
470Restore structure, v2
472Randomly permutes atoms that fit into 17 to 32 bits into one another, and
473randomly permutes the low 32 bits of atoms that fit into 33 to 64 bits;
474otherwise, passes the atom through unchanged. The inverse of the one applied
475by `feen`.
477#### Accepts
479An atom.
481#### Produces
483An atom.
485#### Source
487```hoon
488 ++ fend
489 |= cry=@ ^- @
490 ?: &((gte cry 0x1.0000) (lte cry 0xffff.ffff))
491 (add 0x1.0000 (teil (sub cry 0x1.0000)))
492 ?: &((gte cry 0x1.0000.0000) (lte cry 0xffff.ffff.ffff.ffff))
493 =+ lo=(dis cry 0xffff.ffff)
494 =+ hi=(dis cry 0xffff.ffff.0000.0000)
495 %+ con hi
496 (add 0x1.0000 (teil (sub lo 0x1.0000)))
497 cry
498 ::
499```
501#### Examples
503```
504 > `@p`(fend:ob 111.103)
505 ~doznec-sapfes
507 > `@p`(fend:ob ~doznec-sapfes)
508 ~hanrud-widwyc
510 > `@p`(fend:ob ~wisfed-lonwes)
511 ~mophul-pagwyx
513 > `@p`(fend:ob (feen:ob ~wisfed-lonwes))
514 ~wisfed-lonwes
516 > `@p`(fend:ob ~tarmed)
517 ~tarmed
518```
520---
521### `++fice:ob`
523Feistel-like cipher
525Produces an atom by applying a variant of the Feistel cipher. Unlike
526a conventional Feistel cipher that is its own inverse if keys are used in
527reverse order, this Feistel-like cipher uses two moduli that must be swapped
528when applying the reverse transformation. The inverse of `teil`.
530#### Accepts
532`nor` is an atom.
534#### Produces
536An atom.
538#### Source
540```hoon
541 ++ fice :: adapted from
542 |= nor=@ :: black and rogaway
543 ^- @ :: "ciphers with
544 =+ ^= sel :: arbitrary finite
545 %+ rynd 2 :: domains", 2002
546 %+ rynd 1
547 %+ rynd 0
548 [(mod nor 65.535) (div nor 65.535)]
549 (add (mul 65.535 -.sel) +.sel)
550 ::
551```
553#### Examples
555```
556 > (fice:ob 11)
557 776.343.932
559 > (fice:ob (teil:ob 11))
560 11
561```
563---
564### `++teil:ob`
566Reverse Feistel-like cipher
568Applies the reverse of the Feistel-like cipher applied by `fice`. Unlike
569a conventional Feistel cipher that is its own inverse if keys are used in
570reverse order, this Feistel-like cipher uses two moduli that must be swapped
571when applying the reverse transformation.
573#### Accepts
575`vip` is an atom.
577#### Produces
579An atom.
581#### Source
583```hoon
584 ++ teil :: reverse ++fice
585 |= vip=@
586 ^- @
587 =+ ^= sel
588 %+ rund 0
589 %+ rund 1
590 %+ rund 2
591 [(mod vip 65.535) (div vip 65.535)]
592 (add (mul 65.535 -.sel) +.sel)
593 ::
594```
597#### Examples
599```
600 > (teil:ob 11)
601 514.230.493
603 > (teil:ob (fice:ob 11))
604 11
605```
607---
608### `++rynd:ob`
610Reverse Feistel-like cipher
612A single round of the Feistel-like cipher `fice`. AES ([`aesc`](/docs/hoon/reference/stdlib/3f)) is
613used as the round function. The inverse of `rund`.
615#### Accepts
617`n` is an atom.
619`l` is an atom.
621`r` is an atom.
623#### Produces
625A cell of two atoms.
627#### Source
629```hoon
630 ++ rynd
631 |= [n=@ l=@ r=@]
632 ^- [@ @]
633 :- r
634 ?~ (mod n 2)
635 (~(sum fo 65.535) l (en:aesc (snag n raku) r))
636 (~(sum fo 65.536) l (en:aesc (snag n raku) r))
637```
639#### Examples
641```
642 > (rynd:ob 2 261 9)
643 [9 37.422]
645 > (rynd:ob 2 (rund:ob 2 37.422 9))
646 [261 32.902]
647```
649---
650### `++rund:ob`
652Reverse single Feistel-like
654A single round of the Feistel-like reverse cipher `teil`. AES ([`aesc`](/docs/hoon/reference/stdlib/3f))
655is used as the round function. The inverse of `rynd`.
657#### Accepts
659`n` is an atom.
661`l` is an atom.
663`r` is an atom.
665#### Produces
667A cell of two atoms.
669#### Source
671```hoon
672 ++ rund
673 |= [n=@ l=@ r=@]
674 ^- [@ @]
675 :- r
676 ?~ (mod n 2)
677 (~(dif fo 65.535) l (muk (snag n raku) 2 r))
678 (~(dif fo 65.536) l (muk (snag n raku) 2 r))
679```
681#### Examples
683```
684 > (rund:ob 2 261 9)
685 [9 28.635]
687 > (rund:ob 2 (rynd:ob 2 28.635 9))
688 [261 32.651]
689```
691---
692### `++raku:ob`
694Key list
696Produces a list of arbitrary hexademical keys for use with [`aesc`](/docs/hoon/reference/stdlib/3f).
698#### Produces
700A list of atoms of aura `@ux` (hexadecimal).
702#### Source
704```hoon
705 ++ raku
706 ^- (list @ux)
707 :~ 0xb76d.5eed
708 0xee28.1300
709 0x85bc.ae01
710 0x4b38.7af7
711 ==
712 --
713```
715#### Examples
717```
718 > raku:ob
719 ~[0xb76d.5eed 0xee28.1300 0x85bc.ae01 0x4b38.7af7]
720```
722---