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