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