Ticket #6139: sbox_call_and_rest.patch
File sbox_call_and_rest.patch, 20.7 KB (added by , 10 years ago) 


doc/en/reference/cryptography.rst
# HG changeset patch # User Martin Albrecht <malb@informatik.unibremen.de> # Date 1243428493 3600 # Node ID cecc283f3ecd027b767257222cf3c995997c20a9 # Parent 16d22ab7b4abea2a1cae69fea26f9da684ad610c fixed calling an Sbox with m != n and ReSTified SBox docs diff r 16d22ab7b4ab r cecc283f3ecd doc/en/reference/cryptography.rst
a b 17 17 sage/crypto/lfsr 18 18 19 19 sage/crypto/mq/sr 20 sage/crypto/mq/mpolynomialsystem 21 No newline at end of file 20 sage/crypto/mq/mpolynomialsystem 21 sage/crypto/mq/sbox 22 No newline at end of file 
sage/crypto/mq/sbox.py
diff r 16d22ab7b4ab r cecc283f3ecd sage/crypto/mq/sbox.py
a b 1 1 r""" 2 SBoxes 3 4 A substitution box or Sbox is one of the basic components of 5 symmetric key cryptography. In general, an Sbox takes $m$ input bits 6 and transforms them into some $n$ output bits. This is then called an 7 $mxn$ Sbox and is often implemented as a lookup table. These Sboxes 8 are carefully chosen to resist linear and differential cryptanalysis. 9 10 This module implements an Sbox class which allows an algebraic 11 treatment. 12 13 EXAMPLE: 14 15 We consider the Sbox of the block cipher PRESENT: 16 17 sage: S = mq.SBox(12,5,6,11,9,0,10,13,3,14,15,8,4,7,1,2); S 18 (12, 5, 6, 11, 9, 0, 10, 13, 3, 14, 15, 8, 4, 7, 1, 2) 19 sage: S(1) 20 5 21 22 Note that by default bits are interpreted in big endian order. This is 23 not consistent with the rest of \SAGE, which has a strong bias towards 24 little endian, but is consistent with most cryptographic literature. 25 26 sage: S([0,0,0,1]) 27 [0, 1, 0, 1] 28 29 sage: S = mq.SBox(12,5,6,11,9,0,10,13,3,14,15,8,4,7,1,2, big_endian=False) 30 sage: S(1) 31 5 32 sage: S([0,0,0,1]) 33 [1, 1, 0, 0] 2 SBoxes and Their Algebraic Representations. 34 3 """ 35 4 36 5 from sage.combinat.integer_vector import IntegerVectors … … 46 15 from sage.structure.sage_object import SageObject 47 16 48 17 class SBox(SageObject): 18 r""" 19 A substitution box or Sbox is one of the basic components of 20 symmetric key cryptography. In general, an Sbox takes ``m`` input 21 bits and transforms them into ``n`` output bits. This is called an 22 ``mxn`` Sbox and is often implemented as a lookup table. These 23 Sboxes are carefully chosen to resist linear and differential 24 cryptanalysis [Heys02]_. 25 26 This module implements an Sbox class which allows an algebraic 27 treatment. 28 29 EXAMPLE: 30 31 We consider the Sbox of the block cipher PRESENT [PRESENT07]_:: 32 33 sage: S = mq.SBox(12,5,6,11,9,0,10,13,3,14,15,8,4,7,1,2); S 34 (12, 5, 6, 11, 9, 0, 10, 13, 3, 14, 15, 8, 4, 7, 1, 2) 35 sage: S(1) 36 5 37 38 Note that by default bits are interpreted in big endian 39 order. This is not consistent with the rest of Sage, which has a 40 strong bias towards little endian, but is consistent with most 41 cryptographic literature.:: 42 43 sage: S([0,0,0,1]) 44 [0, 1, 0, 1] 45 46 sage: S = mq.SBox(12,5,6,11,9,0,10,13,3,14,15,8,4,7,1,2, big_endian=False) 47 sage: S(1) 48 5 49 sage: S([0,0,0,1]) 50 [1, 1, 0, 0] 51 52 53 Now we construct an ``SBox`` object for the 4bit small scale AES 54 SBox (cf. :mod:`sage.crypto.mq.sr`):: 55 56 sage: sr = mq.SR(1,1,1,4, allow_zero_inversions=True) 57 sage: S = mq.SBox([sr.sub_byte(e) for e in list(sr.k)]) 58 sage: S 59 (6, 5, 2, 9, 4, 7, 3, 12, 14, 15, 10, 0, 8, 1, 13, 11) 60 61 REFERENCES: 62 63 .. [Heys02] H. Heys *A Tutorial on Linear and Differential 64 Cryptanalysis* ; 2002' available at 65 http://www.engr.mun.ca/~howard/PAPERS/ldc_tutorial.pdf 66 67 .. [PRESENT07] A. Bogdanov, L. Knudsen, G. Leander, C. Paar, 68 A. Poschmann, M. Robshaw, Y. Seurin, C. Vikkelsoe *PRESENT: An 69 UltraLightweight Block Cipher*; in Proceedings of CHES 2007; 70 LNCS 7427; pp. 450466; Springer Verlag 2007; available at 71 http://www.crypto.rub.de/imperia/md/content/texte/publications/conferences/present_ches2007.pdf 72 """ 73 49 74 def __init__(self, *args, **kwargs): 50 75 """ 51 76 Construct a substitution box (Sbox) for a given lookup table 52 $S$.77 `S`. 53 78 54 79 INPUT: 55 S  a finite iterable defining the Sbox with integer or 56 finite field elements 57 big_endian  controls whether bits shall be ordered in 58 big endian order (default: True) 80 81  ``S``  a finite iterable defining the Sbox with integer or 82 finite field elements 83 84  ``big_endian``  controls whether bits shall be ordered in 85 big endian order (default: ``True``) 59 86 60 87 EXAMPLE: 61 88 62 89 We construct a 3bit Sbox where e.g. the bits (0,0,1) are 63 mapped to (1,1,1). 90 mapped to (1,1,1).:: 64 91 65 92 sage: S = mq.SBox(7,6,0,4,2,5,1,3); S 66 93 (7, 6, 0, 4, 2, 5, 1, 3) 67 94 68 95 sage: S(0) 69 96 7 70 71 Now we construct an SBox object for the 4bit small scale AES72 SBox.73 74 sage: sr = mq.SR(1,1,1,4, allow_zero_inversions=True)75 sage: S = mq.SBox([sr.sub_byte(e) for e in list(sr.k)])76 sage: S77 (6, 5, 2, 9, 4, 7, 3, 12, 14, 15, 10, 0, 8, 1, 13, 11)78 79 97 """ 80 98 if "S" in kwargs: 81 99 S = kwargs["S"] … … 106 124 107 125 def _repr_(self): 108 126 """ 109 EXAMPLE: 127 EXAMPLE:: 128 110 129 sage: mq.SBox(7,6,0,4,2,5,1,3) #indirect doctest 111 130 (7, 6, 0, 4, 2, 5, 1, 3) 112 131 """ … … 116 135 """ 117 136 Return the length of input bit strings. 118 137 119 EXAMPLE: 138 EXAMPLE:: 139 120 140 sage: len(mq.SBox(7,6,0,4,2,5,1,3)) 121 141 3 122 142 """ … … 127 147 Sboxes are considered to be equal if all construction 128 148 parameters match. 129 149 130 EXAMPLE: 150 EXAMPLE:: 151 131 152 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 132 153 sage: loads(dumps(S)) == S 133 154 True … … 135 156 return cmp((self._S,self._big_endian), (other._S,self._big_endian)) 136 157 137 158 def to_bits(self, x, n=None): 138 r"""139 Return bitstring of length $n$ for integer $x$. The returned140 bitstring is guaranteed to have length \code{n}.159 """ 160 Return bitstring of length ``n`` for integer ``x``. The 161 returned bitstring is guaranteed to have length ``n``. 141 162 142 163 INPUT: 143 x  an integer144 n  bit length (optional)145 164 146 EXAMPLE: 165  ``x``  an integer 166 167  ``n``  bit length (optional) 168 169 EXAMPLE:: 170 147 171 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 148 172 sage: S.to_bits(6) 149 173 [1, 1, 0] … … 164 188 return swp(self._rpad( map(self._F,ZZ(x).digits(2)), n )) 165 189 166 190 def from_bits(self, x, n=None): 167 r"""168 Return integer for bitstring $x$ of length $n$.191 """ 192 Return integer for bitstring ``x`` of length ``n``. 169 193 170 194 INPUT: 171 x  a bitstring172 n  bit length (optional)173 195 174 EXAMPLE: 196  ``x``  a bitstring 197 198  ``n``  bit length (optional) 199 200 EXAMPLE:: 201 175 202 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 176 203 sage: S.from_bits( [1,1,0]) 177 204 6 … … 192 219 return ZZ( map(ZZ, self._rpad(swp(x), n)), 2) 193 220 194 221 def _rpad(self,x, n=None): 195 r"""196 Right pads x such that \code{len(x)} is $n$.222 """ 223 Right pads ``x`` such that ``len(x) == n``. 197 224 198 EXAMPLE: 225 EXAMPLE:: 226 199 227 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 200 228 sage: S._rpad([1,1]) 201 229 [1, 1, 0] … … 205 233 return x + [self._F(0)]*(nlen(x)) 206 234 207 235 def __call__(self, X): 208 r"""209 Apply substitution to X.236 """ 237 Apply substitution to ``X``. 210 238 211 If X is a list, it is interpreted as a sequence of bits depending212 on the bit order of this Sbox.239 If X is a list, it is interpreted as a sequence of bits 240 depending on the bit order of this Sbox. 213 241 214 INPUT: 215 X  either an integer, a tuple of GF(2) elements of 216 length \code{len(self)} or a finite field element in 217 GF($2^n$). As a last resort this function tries to 218 convert X to an integer. 242 INPUT:: 219 243 220 EXAMPLE: 244  ``X``  either an integer, a tuple of `\GF{2}` elements of 245 length ``len(self)`` or a finite field element in 246 `\GF{2^n}`. As a last resort this function tries to convert 247 ``X`` to an integer. 248 249 EXAMPLE:: 250 221 251 sage: S = mq.SBox([7,6,0,4,2,5,1,3]) 222 252 sage: S(7) 223 253 3 … … 247 277 Traceback (most recent call last): 248 278 ... 249 279 TypeError: Cannot apply SBox to 1/2. 280 281 sage: S = mq.SBox(3, 0, 1, 3, 1, 0, 2, 2) 282 sage: S(0) 283 3 284 sage: S([0,0,0]) 285 [1, 1] 250 286 """ 251 287 if isinstance(X, (int, long, Integer)): 252 288 return self._S[ZZ(X)] … … 263 299 else: 264 300 X = list(X) 265 301 X = ZZ(map(ZZ,X),2) 266 out = self.to_bits(self._S[X] )302 out = self.to_bits(self._S[X], self.n) 267 303 if self._big_endian: 268 304 out = list(reversed(out)) 269 305 return K(vector(GF(2),out)) … … 271 307 pass 272 308 273 309 try: 274 if len(X) == self. n:310 if len(X) == self.m: 275 311 if self._big_endian: 276 312 X = list(reversed(X)) 277 313 X = ZZ(map(ZZ,X),2) 278 314 out = self._S[X] 279 return self.to_bits(out )315 return self.to_bits(out,self.n) 280 316 except TypeError: 281 317 pass 282 318 … … 288 324 if len(str(X)) > 50: 289 325 raise TypeError, "Cannot apply SBox to provided element." 290 326 else: 291 raise TypeError, "Cannot apply SBox to %s."% X327 raise TypeError, "Cannot apply SBox to %s."%(X,) 292 328 293 329 def __getitem__(self, X): 294 r"""295 See as \code{self.__call__}.330 """ 331 See :meth:`SBox.__call__`. 296 332 297 EXAMPLE: 333 EXAMPLE:: 334 298 335 sage: S = mq.SBox([7,6,0,4,2,5,1,3]) 299 336 sage: S[7] 300 337 3 … … 302 339 return self(X) 303 340 304 341 def is_permutation(self): 305 r"""306 Return \code{True}if this SBox is a permutation.342 """ 343 Return ``True`` if this SBox is a permutation. 307 344 308 EXAMPLE: 345 EXAMPLE:: 346 309 347 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 310 348 sage: S.is_permutation() 311 349 True … … 320 358 321 359 def __iter__(self): 322 360 """ 323 EXAMPLE: 361 EXAMPLE:: 362 324 363 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 325 364 sage: [e for e in S] 326 365 [7, 6, 0, 4, 2, 5, 1, 3] … … 330 369 331 370 def difference_distribution_matrix(self): 332 371 """ 333 Return difference distribution matrix $A$for this Sbox.372 Return difference distribution matrix ``A`` for this Sbox. 334 373 335 The rows of $A$ encode the differences $\Delta I$ of the input336 and the columns encode the difference $\Delta O$ for the337 output. The bits are ordered according to the endianess of338 this Sbox. The value at $A[\Delta I,\Delta O]$encoded how339 often $\Delta O$ is the actual output difference given $\Delta340 I$as input difference.374 The rows of ``A`` encode the differences ``Delta I`` of the 375 input and the columns encode the difference ``Delta O`` for 376 the output. The bits are ordered according to the endianess of 377 this Sbox. The value at ``A[Delta I,Delta O]`` encoded how 378 often ``Delta O`` is the actual output difference given 379 ``Delta I`` as input difference. 341 380 342 EXAMPLE: 381 See [Heys02]_ for an introduction to differential 382 cryptanalysis. 383 384 EXAMPLE:: 385 343 386 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 344 387 sage: S.difference_distribution_matrix() 345 388 [8 0 0 0 0 0 0 0] … … 350 393 [0 0 2 2 2 2 0 0] 351 394 [0 2 2 0 0 2 2 0] 352 395 [0 0 0 0 2 2 2 2] 353 354 REFERENCES: Howard M. Heys, A Tutorial on Linear and355 Differential Cryptanalysis, Cryptologia, v.XXVI n.3,356 p.189221, July 2002357 396 """ 358 397 m = self.m 359 398 n = self.n … … 376 415 highest probability in absolute terms, i.e. how often it 377 416 occurs in total. 378 417 379 EXAMPLE: 418 EXAMPLE:: 419 380 420 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 381 421 sage: S.maximal_difference_probability_absolute() 382 422 2 383 423 384 NOTE: This code is called internally. 424 .. note:: 425 426 This code is mainly called internally. 385 427 """ 386 428 A = self.difference_distribution_matrix().copy() 387 429 A[0,0] = 0 … … 393 435 highest probability in the range between 0.0 and 1.0 394 436 indicating 0\% or 100\% respectively. 395 437 396 EXAMPLE: 438 EXAMPLE:: 439 397 440 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 398 441 sage: S.maximal_difference_probability() 399 442 0.25 … … 402 445 403 446 def linear_approximation_matrix(self): 404 447 """ 405 Return linear approximation matrix $A$for this Sbox.448 Return linear approximation matrix ``A`` for this Sbox. 406 449 407 Let $i_b$ be the $b$th bit of $i$ and $o_b$ the $b$th bit of 408 $o$. Then $v = A[i,o]$ encodes the bias of the equation 409 #\Sigma i_b * x_i == \Sigma o_b * y_i$ if $x_i$ and $y_i$ 410 represent the input and output variables of the Sbox. 450 Let ``i_b`` be the ``b``th bit of ``i`` and ``o_b`` the 451 ``b``th bit of ``o``. Then ``v = A[i,o]`` encodes the bias of 452 the equation ``sum( i_b * x_i ) = sum( o_b * y_i )`` if 453 ``x_i`` and ``y_i`` represent the input and output variables 454 of the Sbox. 411 455 412 EXAMPLE: 456 See [Heys02]_ for an introduction to linear cryptanalysis. 457 458 EXAMPLE:: 459 413 460 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 414 461 sage: S.linear_approximation_matrix() 415 462 [ 4 0 0 0 0 0 0 0] … … 421 468 [ 0 2 2 0 0 2 2 0] 422 469 [ 0 2 2 0 2 0 0 2] 423 470 424 According to this matrix the first bit of the input is425 equal to the third bit of the output 6 out of 8 times.471 According to this matrix the first bit of the input is equal 472 to the third bit of the output 6 out of 8 times.:: 426 473 427 474 sage: for i in srange(8): print S.to_bits(i)[0] == S.to_bits(S(i))[2] 428 475 False … … 433 480 True 434 481 True 435 482 True 436 437 REFERENCES: Howard M. Heys, A Tutorial on Linear and438 Differential Cryptanalysis, Cryptologia, v.XXVI n.3,439 p.189221, July 2002440 483 """ 441 484 try: 442 485 return self._linear_approximation_matrix … … 469 512 return A 470 513 471 514 def maximal_linear_bias_absolute(self): 472 r"""515 """ 473 516 Return maximal linear bias, i.e. how often the linear 474 517 approximation with the highest bias is true or false minus 475 $2^{n1}$.518 `2^{n1}`. 476 519 477 EXAMPLE: 520 EXAMPLE:: 521 478 522 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 479 523 sage: S.maximal_linear_bias_absolute() 480 524 2 … … 488 532 Return maximal bias of all linear approximations of this 489 533 Sbox. 490 534 491 EXAMPLE: 535 EXAMPLE:: 536 492 537 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 493 538 sage: S.maximal_linear_bias_relative() 494 539 0.25 … … 500 545 Create, return and cache a polynomial ring for Sbox 501 546 polynomials. 502 547 503 EXAMPLE: 548 EXAMPLE:: 549 504 550 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 505 551 sage: S.ring() 506 552 Multivariate Polynomial Ring in x0, x1, x2, y0, y1, y2 over Finite Field of size 2 … … 523 569 Return a dictionary of solutions to this Sbox. 524 570 525 571 INPUT: 526 X  input variables (default: None)527 Y  output variables (default: None)528 572 529 EXAMPLE: 573  ``X``  input variables (default: ``None``) 574 575  ``Y``  output variables (default: ``None``) 576 577 EXAMPLE:: 578 530 579 sage: S = mq.SBox([7,6,0,4,2,5,1,3]) 531 580 sage: F = S.polynomials() 532 581 sage: s = S.solutions() … … 551 600 return solutions 552 601 553 602 def polynomials(self, X=None, Y=None, degree=2, groebner=False): 554 r"""603 """ 555 604 Return a list of polynomials satisfying this Sbox. 556 605 557 If \code{groebner=False} these polynomials are at most of 558 degree \code{degree}. Otherwise the highest degree equals the 559 highest degree of the reduced Groebner basis. 606 First, a simple linear fitting is performed for the given 607 ``degree`` (cf. for example [BC03]_). If ``groebner=True`` a 608 Groebner basis is also computed for the result of that 609 process. 560 610 561 611 INPUT: 562 X  input variables563 Y  output variables564 degree  integer > 0 (default: 2)565 groebner  calculate a reduced Groebner basis of the566 spanning polynomials to obtain more567 polynomials (default: False)568 612 569 EXAMPLES: 613  ``X``  input variables 614 615  ``Y``  output variables 616 617  ``degree``  integer > 0 (default: ``2``) 618 619  ``groebner``  calculate a reduced Groebner basis of the 620 spanning polynomials to obtain more polynomials (default: 621 ``False``) 622 623 EXAMPLES:: 624 570 625 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 571 626 sage: P = S.ring() 572 627 573 By default, this method returns an indirect representation .628 By default, this method returns an indirect representation:: 574 629 575 630 sage: S.polynomials() 576 631 [x0*x2 + x1 + y1 + 1, … … 591 646 We can get a direct representation by computing a 592 647 lexicographical Groebner basis with respect to the right 593 648 variable ordering, i.e. a variable orderings where the output 594 bits are greater than the input bits .649 bits are greater than the input bits:: 595 650 596 651 sage: P.<y0,y1,y2,x0,x1,x2> = PolynomialRing(GF(2),6,order='lex') 597 652 sage: S.polynomials([x0,x1,x2],[y0,y1,y2], groebner=True) … … 599 654 y1 + x0*x2 + x1 + 1, 600 655 y2 + x0 + x1*x2 + x1 + x2 + 1] 601 656 602 REFERENCES: A. Biryukov and C. D. Canniere, Block Ciphers and 603 Systems of Quadratic Equations, Fast Software Encryption 2003, LNCS 604 2887, pp. 274289, SpringerVerlag, 2003. 657 REFERENCES: 658 659 .. [BC03] A. Biryukov and C. D. Canniere *Block Ciphers and 660 Systems of Quadratic Equations*; in Proceedings of Fast 661 Software Encryption 2003; LNCS 2887; pp. 274289, 662 SpringerVerlag 2003. 605 663 """ 606 664 def nterms(nvars, deg): 607 665 """ 608 Return the number of monomials possible up to a given degree. 666 Return the number of monomials possible up to a given 667 degree. 609 668 610 669 INPUT: 611 nvars  number of variables612 deg  degree670 671  ``nvars``  number of variables 613 672 614 TESTS: 673  ``deg``  degree 674 675 TESTS:: 676 615 677 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 616 678 sage: F = S.polynomials(degree=3) # indirect doctest 617 679 """ … … 683 745 Return a univariate polynomial over an extension field 684 746 representing this Sbox. 685 747 686 If $m$is the input length of this Sbox then the extension687 field is of degree $m$.748 If ``m`` is the input length of this Sbox then the extension 749 field is of degree ``m``. 688 750 689 751 If the output length does not match the input length then a 690 \code{TypeError}is raised.752 ``TypeError`` is raised. 691 753 692 754 INPUT: 693 k  an instance of GF($2^m$) (default: None)694 755 695 EXAMPLE: 756  ``k``  an instance of `\GF{2^m}` (default: ``None``) 757 758 EXAMPLE:: 759 696 760 sage: S = mq.SBox(7,6,0,4,2,5,1,3) 697 761 sage: f = S.interpolation_polynomial() 698 762 sage: f … … 714 778 k = GF(2**self.m,'a') 715 779 l = [] 716 780 for i in xrange(2**self.m): 717 i = self.to_bits(i )781 i = self.to_bits(i, self.m) 718 782 o = self(i) 719 783 if self._big_endian: 720 784 i = reversed(i)