1## Cipher 2 3The `Cipher` class handles all encryption and decryption including AEAD 4as well as provides various information about selecte cipher algorithm. 5 6### Constants 7 8#### `Cipher::MODE_CBC` 9 10The CBC (Cipher Block Chaining) mode XOR's the previous block with the 11currently en/decrypted one. It requires random IV to be set. 12 13#### `Cipher::MODE_CCM` 14 15The CCM (Counter with CBC-MAC) is an authenticated mode. It requires 16a length pre-initialization which means that a plain resp. cipher 17text must be known before encryption resp. decryption. That makes 18it unsituable for streams or continuous cipher update. 19 20Encryption is done using CTR (Counter) mode which means that 21a supplied nonce and counter is used. The nonce is passed as an IV. 22The default tag size is 16 bytes. 23 24#### `Cipher::MODE_CFB` 25 26The CFB (Cipher FeedBack) mode makes a block ciphper into 27a self-synchronizing stream cipher. 28 29#### `Cipher::MODE_CTR` 30 31The CTR (CounTeR) mode uses counter and a random nonce. 32 33#### `Cipher::MODE_ECB` 34 35The ECB (Electronic Codebook) mode is an insecure mode susceptible 36on replay attack if a message length is greater than a block length. 37 38#### `Cipher::MODE_GCM` 39 40The GCM (Golias Counter Mode) is an authenticated mode. 41 42#### `Cipher::MODE_OFB` 43 44The OFB (Output FeedBack) mode makes a block cipher into 45a synchronous stream cipher 46 47#### `Cipher::MODE_XTS` 48 49The XTS (XEX-based tweaked codebook mode with ciphertext stealing) 50mode is a mode designed for hard disk storage. 51 52 53### Static Methods 54 55#### `Cipher::__callStatic($name, $arguments)` 56 57_**Description**_: Creates a cipher using a static call syntax. 58 59The usage of `__callStatic` magic method allows simplified syntax 60for creating a `Cipher` object 61(e.g. `Cipher::aes(Crypto\Cipher::MODE_CBC, 128)`). The `$name` 62depicts the algorithm which is checked if it's found. If not 63then `CipherException` is thrown. Otherwise the new `Cipher` 64instance is returned. 65 66##### *Parameters* 67 68*name* : `string` - the algorithm name (e.g. `aes`) 69 70*arguments* : `array` - there should be an algorithm mode 71and key size (if supported by algorithm) 72 73##### *Return value* 74 75`Cipher`: New instances of the class. 76 77##### *Throws* 78 79It can throw `CipherException` with code 80 81- `CipherException::ALGORITHM_NOT_FOUND` - the algorithm (name) is 82not found 83 84##### *Examples* 85 86```php 87$cipher = \Crypto\Cipher::aes(\Crypto\Cipher::MODE_CBC, 128); 88``` 89 90#### `Cipher::getAlgorithms($aliases = false, $prefix = null)` 91 92_**Description**_: Returns all cipher algorithms. 93 94This static method returns all cipher algorithms. Their parameters 95allow filtering of the result. Some algorithms have aliases that 96can be returned if the `$aliases` parameter is `true`. The `$prefix` 97allows filtering by the supplied prefix string. 98 99##### *Parameters* 100 101*aliases* : `bool` - whether to show aliases 102*prefix* : `string` - prefix that is used for filtering of the result 103 104##### *Throws* 105 106This method does not throw any exception. 107 108##### *Return value* 109 110`array`: list of supported cipher alorithms 111 112##### *Examples* 113 114```php 115print_r(\Crypto\Cipher::getAlgorithms()); 116``` 117 118#### `Cipher::hasAlgorithm($algorithm)` 119 120_**Description**_: Finds out wheter the supplied algorithm is supported 121 122This static method checks if the supplied cipher algorithm is supported. 123 124##### *Parameters* 125 126*algorithm* : `string` - algorithm name 127 128##### *Throws* 129 130This method does not throw any exception. 131 132##### *Return value* 133 134`bool`: if the algorithm is supperted, returns `true`, otherwise `false` 135 136##### *Examples* 137 138```php 139if (\Crypto\Cipher::hasAlgorithm('aes-128-ccm')) { 140 // use AES wiht CCM mode 141} 142``` 143 144#### `Cipher::hasMode($mode)` 145 146_**Description**_: Finds out wheter the supplied mode is supported 147 148This static method checks if the supplied cipher mode is supported. 149The `$mode` parameter must be one of the mode cipher constant 150defined in `Cipher` class. 151 152##### *Parameters* 153 154*mode* : `int` - mode constant 155 156##### *Throws* 157 158This method does not throw any exception. 159 160##### *Return value* 161 162`bool`: if the mode is supperted, returns `true`, otherwise `false` 163 164##### *Examples* 165 166```php 167if (\Crypto\Cipher::hasMode(\Crypto\Cipher::MODE_CCM)) { 168 // use CCM mode 169} 170``` 171 172### Instance Methods 173 174#### `Cipher::__construct($algorithm, $mode = NULL, $key_size = NULL)` 175 176_**Description**_: Creates a new cipher object 177 178The constructor allows creating an object using two ways. Either 179algorithm name is a string containing all details (algorithm, mode, 180key size) or it is just a name of the block algorithm (e.g. AES) 181followed by mode `Cipher` class constant and, if algorithm allows 182that, then key size. Internally the name is concatened to the first 183form so the result is the same. The final algorithm name is then 184checked if it is supported. If not, then the `CipherException` 185is thrown. 186 187##### *Parameters* 188 189*algorithm* : `string` - algorithm name 190 191*mode* : `int` - mode constant 192 193*key_size* : `int` - algorithm key size 194 195##### *Throws* 196 197It can throw `CipherException` with code 198 199- `CipherException::ALGORITHM_NOT_FOUND` - the algorithm (name) is 200not found 201 202##### *Return value* 203 204`Cipher`: new cipher object 205 206##### *Examples* 207 208Creating cipher using just algorithm parameter 209```php 210$cipher = new \Crypto\Cipher('AES-128-GCM'); 211``` 212 213Creating cipher using composed parameters 214```php 215use Crypto\Cipher; 216 217$cipher = new Cipher('AES', Cipher::MODE_GCM, 128); 218``` 219 220#### `Cipher::decrypt($data, $key, $iv = null)` 221 222_**Description**_: Decrypts encrypted data using key and IV 223 224This method decrypts encrypted data (cipher text) on the `Cipher` 225object. It uses a supplied key `$key` and an initial vector `$iv` 226for decryption. Internally it calls init, update and finish 227operations on cipher context. If any of them fails, a `CipherException` 228with an appropriate code is thrown. 229 230The key resp. IV parameters has to contain an exact number of bytes 231that is returned by `Cipher::getKeyLength` resp. `Cipher::getIVLength()`. 232If it's not the case, then a `CipherException` is thrown. 233 234##### *Parameters* 235 236*data* : `string` - cipher text 237 238*key* : `string` - key 239 240*iv* : `string` - initial vector 241 242##### *Throws* 243 244It can throw `CipherException` with code 245 246- `CipherException::INIT_ALG_FAILED` - initialization of cipher algorithm 247failed 248- `CipherException::INIT_CTX_FAILED` - initialization of cipher context 249failed 250- `CipherException::UPDATE_FAILED` - updating of decryption failed 251- `CipherException::FINISH_FAILED` - finalizing of decryption failed 252- `CipherException::INPUT_DATA_LENGTH_HIGH` - if the data length exceeds 253C INT_MAX 254- `CipherException::KEY_LENGTH_INVALID` - the key length is invalid 255- `CipherException::IV_LENGTH_INVALID` - the IV length is invalid 256- `CipherException::TAG_VERIFY_FAILED` - tag verification failed 257(only for GCM or CCM mode) 258 259##### *Return value* 260 261`string`: The decrypted plain text. 262 263##### *Examples* 264 265```php 266$cipher = new \Crypto\Cipher('AES-128-GCM'); 267echo $cipher->decrypt($msg, $key, $iv); 268``` 269 270#### `Cipher::decryptFinish()` 271 272_**Description**_: Finalizes a decryption 273 274This method decrypts an outstanding incomplete block if there is 275any such block in cipher context. It also closes the context so 276the update cannot be called again unless the object is again 277initialized. In addition it finishes the authentication for GCM mode. 278 279If the operation fails (e.g. verification fails), then 280`CipherException` is thrown. The same exception with different code 281is thrown if the context has not been initialized for decryption 282before. 283 284##### *Parameters* 285 286This method has no parameters. 287 288##### *Throws* 289 290It can throw `CipherException` with code 291 292- `CipherException::FINISH_FAILED` - finalizing of decryption failed 293- `CipherException::FINISH_DECRYPT_FORBIDDEN` - cipher has not been 294initialized for decryption 295- `CipherException::TAG_VERIFY_FAILED` - tag verification failed 296(only for GCM or CCM mode) 297 298##### *Return value* 299 300`string`: The decrypted data (plain text) from the last incomplets 301block or empty string. 302 303##### *Examples* 304 305```php 306$cipher = new \Crypto\Cipher('AES-128-CTR'); 307$cipher->decryptInit($key, $iv); 308$ct = $cipher->decryptUpdate($msg); 309$ct .= $cipher->decryptFinish(); 310``` 311 312#### `Cipher::decryptInit($key, $iv = null)` 313 314_**Description**_: Initializes cipher decryption 315 316This method initializes decryption on the `Cipher` object. 317It uses a supplied key `$key` and an initial vector `$iv`. If 318the initialization fails, a `CipherException` with an appropriate 319code is thrown. 320 321The key resp. IV parameters has to contain an exact number of bytes 322that is returned by `Cipher::getKeyLength` resp. `Cipher::getIVLength()`. 323If it's not the case, then a `CipherException` is thrown. 324 325##### *Parameters* 326 327*key* : `string` - key 328 329*iv* : `string` - initial vector 330 331##### *Throws* 332 333It can throw `CipherException` with code 334 335- `CipherException::INIT_ALG_FAILED` - initialization of cipher 336algorithm failed 337- `CipherException::INIT_CTX_FAILED` - initialization of cipher 338context failed 339- `CipherException::KEY_LENGTH_INVALID` - the key length is invalid 340- `CipherException::IV_LENGTH_INVALID` - the IV length is invalid 341 342##### *Return value* 343 344`null`: Nothing is returned. 345 346##### *Examples* 347 348```php 349$cipher = new \Crypto\Cipher('AES-128-CBC'); 350try { 351 $cipher->decryptInit($key, $iv); 352} catch (\Crypto\CipherException $ex) { 353 switch ($ex->getCode()) { 354 case \Crypto\CipherException::KEY_LENGTH_INVALID: 355 echo "You need to set a correct key length"; 356 break; 357 case \Crypto\CipherException::IV_LENGTH_INVALID: 358 echo "You need to set a correct IV length"; 359 break; 360 default: 361 echo $ex->getMessage(); 362 break; 363 } 364} 365``` 366 367#### `Cipher::decryptUpdate($data) ` 368 369_**Description**_: Updates decryption context with data and returns 370encrypted blocks. 371 372This method decrypts encrypted data (cipher text) on the `Cipher` object. 373It updates an initialized context and all encrypted blocks are returned. 374If the context is not initialized using `Cipher::decryptInit`, then 375a `CipherException` is thrown. 376 377If the decryption fails, a `CipherException` is thrown. 378 379##### *Parameters* 380 381*data* : `string` - cipher text 382 383##### *Throws* 384 385It can throw `CipherException` with code 386 387- `CipherException::UPDATE_FAILED` - updating of decryption failed 388- `CipherException::INPUT_DATA_LENGTH_HIGH` - if the data length exceeds 389C INT_MAX 390- `CipherException::UPDATE_DECRYPT_FORBIDDEN` - cipher has not been 391initialized for decryption 392- `CipherException::TAG_VERIFY_FAILED` - tag verification failed 393(only for GCM or CCM mode) 394 395##### *Return value* 396 397`string`: The decrypted plain text. 398 399##### *Examples* 400 401```php 402$cipher = new \Crypto\Cipher('AES-128-CTR'); 403$cipher->decryptInit($key, $iv); 404$plain_text = ""; 405while (($data = read_data_from_somewhere()) !== false) { 406 $plain_text .= $cipher->decryptUpdate($msg); 407} 408$plain_text .= $cipher->decryptFinish(); 409``` 410 411#### `Cipher::encrypt($data, $key, $iv = null)` 412 413_**Description**_: Encrypts data using key and IV 414 415This method encrypts data (plain text) on the `Cipher` 416object. It uses a supplied key `$key` and an initial vector `$iv` 417for encryption. Internally it calls init, update and finish 418operations on cipher context. If any of them fails, a `CipherException` 419with an appropriate code is thrown. 420 421The key resp. IV parameters has to contain an exact number of bytes 422that is returned by `Cipher::getKeyLength` resp. `Cipher::getIVLength()`. 423If it's not the case, then a `CipherException` is thrown. 424 425##### *Parameters* 426 427*data* : `string` - plain text 428 429*key* : `string` - key 430 431*iv* : `string` - initial vector 432 433##### *Throws* 434 435It can throw `CipherException` with code 436 437- `CipherException::INIT_ALG_FAILED` - initialization of cipher 438algorithm failed 439- `CipherException::INIT_CTX_FAILED` - initialization of cipher context 440failed 441- `CipherException::UPDATE_FAILED` - updating of encryption failed 442- `CipherException::FINISH_FAILED` - finalizing of encryption failed 443- `CipherException::INPUT_DATA_LENGTH_HIGH` - if the data length exceeds 444C INT_MAX 445- `CipherException::KEY_LENGTH_INVALID` - the key length is invalid 446- `CipherException::IV_LENGTH_INVALID` - the IV length is invalid 447 448##### *Return value* 449 450`string`: The encrypted cipher text. 451 452##### *Examples* 453 454```php 455$cipher = new \Crypto\Cipher('AES-128-CTR'); 456echo $cipher->encrypt($cipher_text, $key, $iv); 457``` 458 459 460#### `Cipher::encryptFinish()` 461 462_**Description**_: Finalizes encryption 463 464This method encrypts an outstanding incomplete block including padding 465if there is any such block in cipher context and/or padding is required. 466It also closes the context so the update cannot be called again unless 467the object is again initialized. 468 469If the operation fails (e.g. verification fails), then 470`CipherException` is thrown. The same exception with different code 471is thrown if the context has not been initialized for decryption 472before. 473 474##### *Parameters* 475 476This method has no parameters. 477 478##### *Throws* 479 480It can throw `CipherException` with code 481 482- `CipherException::FINISH_FAILED` - finalizing of encryption failed 483- `CipherException::FINISH_ENCRYPT_FORBIDDEN` - cipher has not been 484initialized for encryption 485 486##### *Return value* 487 488`string`: The encrypted data (cipher text) from the last incomplete block 489with padding or empty string. 490 491##### *Examples* 492 493```php 494$cipher = new \Crypto\Cipher('AES-128-CTR'); 495$cipher->encryptInit($key, $iv); 496$plain_text = $cipher->encryptUpdate($cipher_text); 497$plain_text .= $cipher->encryptFinish(); 498``` 499 500#### `Cipher::encryptInit($key, $iv = null)` 501 502_**Description**_: Initializes cipher encryption 503 504This method initializes encryption on the `Cipher` object. 505It uses a supplied key `$key` and an initial vector `$iv`. If 506the initialization fails, a `CipherException` with an appropriate 507code is thrown. 508 509The key resp. IV parameters has to contain an exact number of bytes 510that is returned by `Cipher::getKeyLength` resp. `Cipher::getIVLength()`. 511If it's not the case, then a `CipherException` is thrown. 512 513##### *Parameters* 514 515*key* : `string` - key 516 517*iv* : `string` - initial vector 518 519##### *Throws* 520 521It can throw `CipherException` with code 522 523- `CipherException::INIT_ALG_FAILED` - initialization of cipher 524algorithm failed 525- `CipherException::INIT_CTX_FAILED` - initialization of cipher 526context failed 527- `CipherException::KEY_LENGTH_INVALID` - the key length is invalid 528- `CipherException::IV_LENGTH_INVALID` - the IV length is invalid 529 530##### *Return value* 531 532`null`: Nothing is returned. 533 534##### *Examples* 535 536```php 537$cipher = new \Crypto\Cipher('AES-128-CBC'); 538try { 539 $cipher->encryptInit($key, $iv); 540} catch (\Crypto\CipherException $ex) { 541 switch ($ex->getCode()) { 542 case \Crypto\CipherException::KEY_LENGTH_INVALID: 543 echo "You need to set a correct key length"; 544 break; 545 case \Crypto\CipherException::IV_LENGTH_INVALID: 546 echo "You need to set a correct IV length"; 547 break; 548 default: 549 echo $ex->getMessage(); 550 break; 551 } 552} 553``` 554 555#### `Cipher::encryptUpdate($data)` 556 557_**Description**_: Updates encryption context with data and returns 558encrypted blocks. 559 560This method encrypts data (plain text) on the `Cipher` object. It updates 561an initialized context and all encrypted blocks are returned (if any). If 562the context is not initialized using `Cipher::encryptInit`, then 563a `CipherException` is thrown. 564 565If the decryption fails, a `CipherException` is thrown. 566 567##### *Parameters* 568 569*data* : `string` - plain text 570 571##### *Throws* 572 573It can throw `CipherException` with code 574 575- `CipherException::UPDATE_FAILED` - updating of encryption failed 576- `CipherException::INPUT_DATA_LENGTH_HIGH` - if the data length exceeds 577C INT_MAX 578- `CipherException::UPDATE_DECRYPT_FORBIDDEN` - cipher has not been 579initialized for encryption 580 581##### *Return value* 582 583`string`: The encrypted cipher text. 584 585##### *Examples* 586 587```php 588$cipher = new \Crypto\Cipher('AES-128-CTR'); 589$cipher->decryptInit($key, $iv); 590$cipher_text = ""; 591while (($data = read_data_from_somewhere()) !== false) { 592 $cipher_text .= $cipher->encryptUpdate($msg); 593} 594$cipher_text .= $cipher->encryptFinish(); 595``` 596 597#### `Cipher::getAlgorithmName()` 598 599_**Description**_: Returns a cipher algorithm name. 600 601It is a getter for internal `Cipher::$algorithm` read only property 602which is set during the object creation. 603 604##### *Parameters* 605 606This method has no parameters. 607 608##### *Throws* 609 610This method does not throw any exception. 611 612##### *Return value* 613 614`string`: The name of the cipher algorithm and additional info 615like a mode (e.g. `AES-128-CTR`) 616 617##### *Examples* 618 619```php 620$cipher = new \Crypto\Cipher('aes-128-ctr'); 621// this will output AES-128-CTR 622echo $cipher->getAlgorithmName(); 623``` 624 625#### `Cipher::getBlockSize()` 626 627_**Description**_: Returns a cipher block size in bytes. 628 629This method returns a block size of the cipher algorithm. 630 631##### *Parameters* 632 633This method has no parameters. 634 635##### *Throws* 636 637This method does not throw any exception. 638 639##### *Return value* 640 641`int`: The cipher block size in bytes. 642 643##### *Examples* 644 645```php 646$cipher = new \Crypto\Cipher('aes-128-ctr'); 647// this will output 16 648echo $cipher->getBlockSize(); 649``` 650 651#### `Cipher::getIVLength()` 652 653_**Description**_: Returns a cipher IV length in bytes. 654 655This method returns an initial vector length of the cipher algorithm. 656The IV length depends on the selected mode. This is also applicable 657on modes that are based on CTR mode which requires a nonce. The nonce 658length is returned in this case. 659 660##### *Parameters* 661 662This method has no parameters. 663 664##### *Throws* 665 666This method does not throw any exception. 667 668##### *Return value* 669 670`int`: The cipher IV length in bytes. 671 672##### *Examples* 673 674```php 675$cipher = new \Crypto\Cipher('aes-128-ctr'); 676// this will output 16 677echo $cipher->getIVLength(); 678``` 679 680#### `Cipher::getKeyLength()` 681 682_**Description**_: Returns a cipher key length in bytes. 683 684This method returns a key length of the cipher algorithm. The key length 685depends on the cipher where some ciphers support more key lengths (e.g. 686AES) that can be specified in the algorithm name or as a parameter of 687the cipher constructor. 688 689##### *Parameters* 690 691This method has no parameters. 692 693##### *Throws* 694 695This method does not throw any exception. 696 697##### *Return value* 698 699`int`: The cipher key length in bytes. 700 701##### *Examples* 702 703```php 704$cipher = new \Crypto\Cipher('aes-192-ctr'); 705// this will output 24 706echo $cipher->getKeyLength(); 707``` 708 709#### `Cipher::getMode()` 710 711_**Description**_: Returns a cipher mode constant value. 712 713This method returns a `Cipher` class constant value for the used mode. 714It's identified from the algorithm name passed to the constructor. 715 716##### *Parameters* 717 718This method has no parameters. 719 720##### *Throws* 721 722This method does not throw any exception. 723 724##### *Return value* 725 726`int`: The cipher mode constant value. 727 728##### *Examples* 729 730```php 731$cipher = new \Crypto\Cipher('aes-128-ctr'); 732$mode = $cipher->getMode(); 733// this will be true 734if ($mode === \Crypto\Cipher::MODE_CTR) { 735 echo "Mode is CTR"; 736} 737``` 738 739#### `Cipher::getTag()` 740 741_**Description**_: Returns an authentication tag. 742 743This method returns a message authentication tag. It can be used 744only for modes that supports that (GCM and CCM) and only after 745encryption is finished. In any other case, `CipherException` 746is thrown. 747 748The returned tag length can be set by `Cipher::setTagLength` before 749encryption. If it's not set, then the defualt length is 16. 750 751##### *Parameters* 752 753This method has no parameters. 754 755##### *Throws* 756 757It can throw `CipherException` with code 758 759- `CipherException::AUTHENTICATION_NOT_SUPPORTED` - mode is not 760an authenticated mode 761- `CipherException::TAG_GETTER_FORBIDDEN` - method is not called after 762finishing encryption 763- `CipherException::TAG_GETTER_FAILED` - getting tag failed 764 765##### *Return value* 766 767`string`: The authenticated tag. 768 769##### *Examples* 770 771```php 772$cipher = new \Crypto\Cipher('aes-128-gcm'); 773$cipher_text = $cipher->encrypt($plain_text, $key, $iv); 774$tag = $cipher->getTag(); 775``` 776 777#### `Cipher::setAAD($aad)` 778 779_**Description**_: Sets an additional application data. 780 781This method sets an additional application data (AAD). It can be used 782only for authenticated modes (GCM and CCM) and only before encryption 783or decryption is updated (any data are encrypted or decrypted). In any 784other case, a `CipherException` is thrown. 785 786##### *Parameters* 787 788*aad* : `string` - additional application data 789 790##### *Throws* 791 792It can throw `CipherException` with code 793 794- `CipherException::AUTHENTICATION_NOT_SUPPORTED` - mode is not 795an authenticated mode 796- `CipherException::AAD_SETTER_FORBIDDEN` - method is not called before 797encryption or decryption 798- `CipherException::AAD_LENGTH_HIGH` - if the AAD length exceeds 799C INT_MAX 800 801##### *Return value* 802 803`bool`: true if the AAD was set succesfully 804 805##### *Examples* 806 807```php 808// encrypt 809$cipher = new \Crypto\Cipher('aes-128-gcm'); 810$cipher->setAAD($aad); 811$cipher_text = $cipher->encrypt($plain_text, $key, $iv); 812$tag = $cipher->getTag(); 813 814// later you have to decrypt with the same AAD 815$cipher = new \Crypto\Cipher('aes-128-gcm'); 816$cipher->setAAD($aad); 817$cipher->setTag($tag); 818$plain_text = $cipher->decrypt($cipher_text, $key, $iv); 819``` 820 821#### `Cipher::setTag($tag)` 822 823_**Description**_: Sets a message authentication tag. 824 825This method sets a message authentication tag. It can be used 826only for authenticated modes (GCM and CCM) and only before 827decryption is updated (any data are decrypted). In any other 828case, a `CipherException` is thrown. 829 830The tag length has to be between 4 and 16 bytes, otherwise 831a `CipherException` is thrown. 832 833##### *Parameters* 834 835*tag* : `string` - message authentication tag 836 837##### *Throws* 838 839It can throw `CipherException` with code 840 841- `CipherException::AUTHENTICATION_NOT_SUPPORTED` - mode is not 842an authenticated mode 843- `CipherException::TAG_SETTER_FORBIDDEN` - method is not called before 844decryption 845- `CipherException::TAG_LENGTH_LOW` - if tag length is less than 8464 bytes 847- `CipherException::TAG_LENGTH_HIGH` - if tag length is more than 84816 bytes 849 850##### *Return value* 851 852`bool`: true if the tag was set succesfully 853 854##### *Examples* 855 856```php 857$cipher = new \Crypto\Cipher('aes-128-gcm'); 858$cipher->setTag($tag); 859$plain_text = $cipher->decrypt($cipher_text, $key, $iv); 860``` 861 862#### `Cipher::setTagLength($tag_length)` 863 864_**Description**_: Sets a message authentication tag length. 865 866This method sets a length for an authentication tag that is 867later returned using `Cipher::getTag`. It can be used 868only for authenticated modes (GCM and CCM) and only before 869encryption is updated (any data are encrypted). In any other 870case, a `CipherException` is thrown. 871 872The tag length has to be between 4 and 16 bytes, otherwise 873a `CipherException` is thrown. 874 875The method is useful only if there is a requirement of 876different tag length than the default which is 16 bytes. The tag 877is just trimmed for GCM mode. However it's a completely different 878tag if it's used with CCM mode. 879 880##### *Parameters* 881 882*length* : `int` - message authentication tag length 883 884##### *Throws* 885 886It can throw `CipherException` with code 887 888- `CipherException::AUTHENTICATION_NOT_SUPPORTED` - mode is not 889an authenticated mode 890- `CipherException::TAG_SETTER_FORBIDDEN` - method is not called before 891encryption 892- `CipherException::TAG_LENGTH_LOW` - if tag length is less than 8934 bytes 894- `CipherException::TAG_LENGTH_HIGH` - if tag length is more than 89516 bytes 896 897##### *Return value* 898 899`bool`: true if the tag length was set succesfully 900 901##### *Examples* 902 903```php 904$cipher = new \Crypto\Cipher('aes-128-ccm'); 905$cipher->setTagLength(12); 906$cipher_text = $cipher->encrypt($plain_text, $key, $nonce); 907// tag with lenth 12 bytes (characters) 908$tag = $cipher->getTag(); 909``` 910