← Back to branch summary

~clint-fewbar/ubuntu/precise/erlang/merge-15b

« back to all changes in this revision

Viewing changes to lib/crypto/doc/src/crypto.xml

  • Committer: Package Import Robot
  • Author(s): Sergei Golovan
  • Date: 2011-12-15 19:20:10 UTC
  • mfrom: (1.1.18) (3.5.15 sid)
  • mto: (3.5.16 sid)
  • mto: This revision was merged to the branch mainline in revision 33.
  • Revision ID: package-import@ubuntu.com-20111215192010-jnxcfe3tbrpp0big
Tags: 1:15.b-dfsg-1
* New upstream release.
* Upload to experimental because this release breaks external drivers
  API along with ABI, so several applications are to be fixed.
* Removed SSL patch because the old SSL implementation is removed from
  the upstream distribution.
* Removed never used patch which added native code to erlang beam files.
* Removed the erlang-docbuilder binary package because the docbuilder
  application was dropped by upstream.
* Documented dropping ${erlang-docbuilder:Depends} substvar in
  erlang-depends(1) manpage.
* Made erlang-base and erlang-base-hipe provide virtual package
  erlang-abi-15.b (the number means the first erlang version, which
  provides current ABI).

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/crypto/doc/src/crypto.xml
1
 
<?xml version="1.0" encoding="latin1" ?>
 
1
<?xml version="1.0" encoding="iso-8859-1" ?>
2
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
3
3
 
4
4
<erlref>
5
5
  <header>
6
6
    <copyright>
7
 
      <year>1999</year><year>2010</year>
 
7
      <year>1999</year><year>2011</year>
8
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
9
9
    </copyright>
10
10
    <legalnotice>
282
282
      </desc>
283
283
    </func>
284
284
    <func>
 
285
      <name>hmac_init(Type, Key) -> Context</name>
 
286
      <fsummary></fsummary>
 
287
      <type>
 
288
        <v>Type = sha | md5 | ripemd160</v>
 
289
        <v>Key = iolist() | binary()</v>
 
290
        <v>Context = binary()</v>
 
291
      </type>
 
292
      <desc>
 
293
        <p>Initializes the context for streaming HMAC operations. <c>Type</c> determines
 
294
        which hash function to use in the HMAC operation. <c>Key</c> is the authentication
 
295
        key. The key can be any length.</p>
 
296
      </desc>
 
297
    </func>
 
298
    <func>
 
299
      <name>hmac_update(Context, Data) -> NewContext</name>
 
300
      <fsummary></fsummary>
 
301
      <type>
 
302
        <v>Context = NewContext = binary()</v>
 
303
        <v>Data = iolist() | binary()</v>
 
304
      </type>
 
305
      <desc>
 
306
        <p>Updates the HMAC represented by <c>Context</c> using the given <c>Data</c>. <c>Context</c>
 
307
        must have been generated using an HMAC init function (such as 
 
308
        <seealso marker="#hmac_init/2">hmac_init</seealso>). <c>Data</c> can be any length. <c>NewContext</c>
 
309
        must be passed into the next call to <c>hmac_update</c>.</p>
 
310
      </desc>
 
311
    </func>
 
312
    <func>
 
313
      <name>hmac_final(Context) -> Mac</name>
 
314
      <fsummary></fsummary>
 
315
      <type>
 
316
        <v>Context = Mac = binary()</v>
 
317
      </type>
 
318
      <desc>
 
319
        <p>Finalizes the HMAC operation referenced by <c>Context</c>. The size of the resultant MAC is
 
320
        determined by the type of hash function used to generate it.</p>
 
321
      </desc>
 
322
    </func>
 
323
    <func>
 
324
      <name>hmac_final_n(Context, HashLen) -> Mac</name>
 
325
      <fsummary></fsummary>
 
326
      <type>
 
327
        <v>Context = Mac = binary()</v>
 
328
        <v>HashLen = non_neg_integer()</v>
 
329
      </type>
 
330
      <desc>
 
331
        <p>Finalizes the HMAC operation referenced by <c>Context</c>. <c>HashLen</c> must be greater than
 
332
        zero. <c>Mac</c> will be a binary with at most <c>HashLen</c> bytes. Note that if HashLen is greater than the actual number of bytes returned from the underlying hash, the returned hash will have fewer than <c>HashLen</c> bytes.</p>
 
333
      </desc>
 
334
    </func>
 
335
    <func>
285
336
      <name>sha_mac(Key, Data) -> Mac</name>
 
337
      <name>sha_mac(Key, Data, MacLength) -> Mac</name>
286
338
      <fsummary>Compute an <c>MD5 MAC</c>message authentification code</fsummary>
287
339
      <type>
288
340
        <v>Key = Data = iolist() | binary()</v>
289
341
        <v>Mac = binary()</v>
 
342
        <v>MacLenength = integer() =&lt; 20 </v>
290
343
      </type>
291
344
      <desc>
292
345
        <p>Computes an <c>SHA MAC</c> message authentification code
293
 
          from <c>Key</c> and <c>Data</c>, where the length of the Mac
 
346
          from <c>Key</c> and <c>Data</c>, where the default length of the Mac
294
347
          is 160 bits (20 bytes).</p>
295
348
      </desc>
296
349
    </func>
297
350
    <func>
298
351
      <name>sha_mac_96(Key, Data) -> Mac</name>
299
 
      <fsummary>Compute an <c>MD5 MAC</c>message authentification code</fsummary>
 
352
      <fsummary>Compute an <c>SHA MAC</c>message authentification code</fsummary>
300
353
      <type>
301
354
        <v>Key = Data = iolist() | binary()</v>
302
355
        <v>Mac = binary()</v>
353
406
      </desc>
354
407
    </func>
355
408
    <func>
 
409
      <name>des_cfb_encrypt(Key, IVec, Text) -> Cipher</name>
 
410
      <fsummary>Encrypt <c>Text</c>according to DES in CFB mode</fsummary>
 
411
      <type>
 
412
        <v>Key = Text = iolist() | binary()</v>
 
413
        <v>IVec = Cipher = binary()</v>
 
414
      </type>
 
415
      <desc>
 
416
        <p>Encrypts <c>Text</c> according to DES in 8-bit CFB
 
417
          mode. <c>Key</c> is the DES key, and <c>IVec</c> is an
 
418
          arbitrary initializing vector. The lengths of <c>Key</c> and
 
419
          <c>IVec</c> must be 64 bits (8 bytes).</p>
 
420
      </desc>
 
421
    </func>
 
422
    <func>
 
423
      <name>des_cfb_decrypt(Key, IVec, Cipher) -> Text</name>
 
424
      <fsummary>Decrypt <c>Cipher</c>according to DES in CFB mode</fsummary>
 
425
      <type>
 
426
        <v>Key = Cipher = iolist() | binary()</v>
 
427
        <v>IVec = Text = binary()</v>
 
428
      </type>
 
429
      <desc>
 
430
        <p>Decrypts <c>Cipher</c> according to DES in 8-bit CFB mode.
 
431
          <c>Key</c> is the DES key, and <c>IVec</c> is an arbitrary
 
432
          initializing vector.  <c>Key</c> and <c>IVec</c> must have
 
433
          the same values as those used when encrypting.  The lengths of
 
434
          <c>Key</c> and <c>IVec</c> must be 64 bits (8 bytes).</p>
 
435
      </desc>
 
436
    </func>
 
437
    <func>
 
438
      <name>des_cfb_ivec(IVec, Data) -> NextIVec</name>
 
439
      <fsummary>Get <c>IVec</c> to be used in next iteration of
 
440
                <c>des_cfb_[ecrypt|decrypt]</c></fsummary>
 
441
      <type>
 
442
        <v>IVec = iolist() | binary()</v>
 
443
        <v>Data = iolist() | binary()</v>
 
444
        <v>NextIVec = binary()</v>
 
445
      </type>
 
446
      <desc>
 
447
        <p>Returns the <c>IVec</c> to be used in a next iteration of
 
448
          <c>des_cfb_[encrypt|decrypt]</c>. <c>IVec</c> is the vector
 
449
          used in the previous iteration step. <c>Data</c> is the encrypted
 
450
          data from the previous iteration step.</p>
 
451
      </desc>
 
452
    </func>
 
453
    <func>
356
454
      <name>des3_cbc_encrypt(Key1, Key2, Key3, IVec, Text) -> Cipher</name>
357
455
      <fsummary>Encrypt <c>Text</c>according to DES3 in CBC mode</fsummary>
358
456
      <type>
370
468
    </func>
371
469
    <func>
372
470
      <name>des3_cbc_decrypt(Key1, Key2, Key3, IVec, Cipher) -> Text</name>
373
 
      <fsummary>Decrypt <c>Cipher</c>according to DES in CBC mode</fsummary>
 
471
      <fsummary>Decrypt <c>Cipher</c>according to DES3 in CBC mode</fsummary>
374
472
      <type>
375
473
        <v>Key1 = Key2 = Key3 = Cipher = iolist() | binary()</v>
376
474
        <v>IVec = Text = binary()</v>
386
484
          <c>Key3</c>, and <c>IVec</c> must be 64 bits (8 bytes).</p>
387
485
      </desc>
388
486
    </func>
 
487
    <func>
 
488
      <name>des3_cfb_encrypt(Key1, Key2, Key3, IVec, Text) -> Cipher</name>
 
489
      <fsummary>Encrypt <c>Text</c>according to DES3 in CFB mode</fsummary>
 
490
      <type>
 
491
        <v>Key1 =Key2 = Key3 Text = iolist() | binary()</v>
 
492
        <v>IVec = Cipher = binary()</v>
 
493
      </type>
 
494
      <desc>
 
495
        <p>Encrypts <c>Text</c> according to DES3 in 8-bit CFB
 
496
          mode. <c>Key1</c>, <c>Key2</c>, <c>Key3</c>, are the DES
 
497
          keys, and <c>IVec</c> is an arbitrary initializing
 
498
          vector. The lengths of each of <c>Key1</c>, <c>Key2</c>,
 
499
          <c>Key3</c> and <c>IVec</c> must be 64 bits (8 bytes).</p>
 
500
      </desc>
 
501
    </func>
 
502
    <func>
 
503
      <name>des3_cfb_decrypt(Key1, Key2, Key3, IVec, Cipher) -> Text</name>
 
504
      <fsummary>Decrypt <c>Cipher</c>according to DES3 in CFB mode</fsummary>
 
505
      <type>
 
506
        <v>Key1 = Key2 = Key3 = Cipher = iolist() | binary()</v>
 
507
        <v>IVec = Text = binary()</v>
 
508
      </type>
 
509
      <desc>
 
510
        <p>Decrypts <c>Cipher</c> according to DES3 in 8-bit CFB mode.
 
511
          <c>Key1</c>, <c>Key2</c>, <c>Key3</c> are the DES key, and
 
512
          <c>IVec</c> is an arbitrary initializing vector.
 
513
          <c>Key1</c>, <c>Key2</c>, <c>Key3</c> and <c>IVec</c> must
 
514
          and <c>IVec</c> must have the same values as those used when
 
515
          encrypting.  The lengths of <c>Key1</c>, <c>Key2</c>,
 
516
          <c>Key3</c>, and <c>IVec</c> must be 64 bits (8 bytes).</p>
 
517
      </desc>
 
518
    </func>
389
519
 
390
520
    <func>
391
521
      <name>des_ecb_encrypt(Key, Text) -> Cipher</name>
419
549
      <fsummary>Encrypt the first 64 bits of <c>Text</c> using Blowfish in ECB mode</fsummary>
420
550
      <type>
421
551
        <v>Key = Text = iolist() | binary()</v>
422
 
        <v>IVec = Cipher = binary()</v>
 
552
        <v>Cipher = binary()</v>
423
553
      </type>
424
554
      <desc>
425
555
        <p>Encrypts the first 64 bits of <c>Text</c> using Blowfish in ECB mode. <c>Key</c> is the Blowfish key. The length of <c>Text</c> must be at least 64 bits (8 bytes).</p>
426
556
      </desc>
 
557
    </func>
 
558
    <func>
427
559
      <name>blowfish_ecb_decrypt(Key, Text) -> Cipher</name>
428
560
      <fsummary>Decrypt the first 64 bits of <c>Text</c> using Blowfish in ECB mode</fsummary>
429
561
      <type>
430
562
        <v>Key = Text = iolist() | binary()</v>
431
 
        <v>IVec = Cipher = binary()</v>
 
563
        <v>Cipher = binary()</v>
432
564
      </type>
433
565
      <desc>
434
566
        <p>Decrypts the first 64 bits of <c>Text</c> using Blowfish in ECB mode. <c>Key</c> is the Blowfish key. The length of <c>Text</c> must be at least 64 bits (8 bytes).</p>
436
568
    </func>
437
569
 
438
570
    <func>
439
 
      <name>blowfish_cbc_encrypt(Key, Text) -> Cipher</name>
 
571
      <name>blowfish_cbc_encrypt(Key, IVec, Text) -> Cipher</name>
440
572
      <fsummary>Encrypt <c>Text</c> using Blowfish in CBC mode</fsummary>
441
573
      <type>
442
574
        <v>Key = Text = iolist() | binary()</v>
447
579
          arbitrary initializing vector. The length of <c>IVec</c>
448
580
          must be 64 bits (8 bytes). The length of <c>Text</c> must be a multiple of 64 bits (8 bytes).</p>
449
581
      </desc>
450
 
      <name>blowfish_cbc_decrypt(Key, Text) -> Cipher</name>
 
582
    </func>
 
583
    <func>
 
584
      <name>blowfish_cbc_decrypt(Key, IVec, Text) -> Cipher</name>
451
585
      <fsummary>Decrypt <c>Text</c> using Blowfish in CBC mode</fsummary>
452
586
      <type>
453
587
        <v>Key = Text = iolist() | binary()</v>
585
719
    </desc>
586
720
    </func>
587
721
    <func>
 
722
      <name>aes_ctr_stream_init(Key, IVec) -> State</name>
 
723
      <fsummary></fsummary>
 
724
      <type>
 
725
        <v>State = { K, I, E, C }</v>
 
726
        <v>Key = K = iolist()</v>
 
727
        <v>IVec = I = E = binary()</v>
 
728
        <v>C = integer()</v>
 
729
      </type>
 
730
      <desc>
 
731
        <p>Initializes the state for use in streaming AES encryption using Counter mode (CTR).
 
732
        <c>Key</c> is the AES key and must be either 128, 192, or 256 bts long. <c>IVec</c> is
 
733
        an arbitrary initializing vector of 128 bits (16 bytes). This state is for use with
 
734
        <seealso marker="#aes_ctr_stream_encrypt/2">aes_ctr_stream_encrypt</seealso> and 
 
735
        <seealso marker="#aes_ctr_stream_decrypt/2">aes_ctr_stream_decrypt</seealso>.</p>
 
736
      </desc>
 
737
    </func>
 
738
    <func>
 
739
      <name>aes_ctr_stream_encrypt(State, Text) -> { NewState, Cipher}</name>
 
740
      <fsummary></fsummary>
 
741
      <type>
 
742
        <v>Text = iolist() | binary()</v>
 
743
        <v>Cipher = binary()</v>
 
744
      </type>
 
745
      <desc>
 
746
      <p>Encrypts <c>Text</c> according to AES in Counter mode (CTR).  This function can be
 
747
        used to encrypt a stream of text using a series of calls instead of requiring all
 
748
        text to be in memory. <c>Text</c> can be any number of bytes. State is initialized using 
 
749
        <seealso marker="#aes_ctr_stream_init/2">aes_ctr_stream_init</seealso>. <c>NewState</c> is the new streaming
 
750
        encryption state that must be passed to the next call to <c>aes_ctr_stream_encrypt</c>.
 
751
        <c>Cipher</c> is the encrypted cipher text.</p>
 
752
      </desc>
 
753
    </func>
 
754
    <func>
 
755
      <name>aes_ctr_stream_decrypt(State, Cipher) -> { NewState, Text }</name>
 
756
      <fsummary></fsummary>
 
757
      <type>
 
758
        <v>Cipher = iolist() | binary()</v>
 
759
        <v>Text = binary()</v>
 
760
      </type>
 
761
      <desc>
 
762
      <p>Decrypts <c>Cipher</c> according to AES in Counter mode (CTR). This function can be
 
763
        used to decrypt a stream of ciphertext using a series of calls instead of requiring all
 
764
        ciphertext to be in memory.  <c>Cipher</c> can be any number of bytes. State is initialized using 
 
765
        <seealso marker="#aes_ctr_stream_init/2">aes_ctr_stream_init</seealso>. <c>NewState</c> is the new streaming
 
766
        encryption state that must be passed to the next call to <c>aes_ctr_stream_encrypt</c>.
 
767
        <c>Text</c> is the decrypted data.</p>
 
768
      </desc>
 
769
    </func>
 
770
    <func>
588
771
      <name>erlint(Mpint) -> N</name>
589
772
      <name>mpint(N) -> Mpint</name>
590
773
      <fsummary>Convert between binary multi-precision integer and erlang big integer</fsummary>
615
798
      </desc>
616
799
    </func>
617
800
    <func>
 
801
      <name>strong_rand_bytes(N) -> binary()</name>
 
802
      <fsummary>Generate a binary of random bytes</fsummary>
 
803
      <type>
 
804
        <v>N = integer()</v>
 
805
      </type>
 
806
      <desc>
 
807
        <p>Generates N bytes randomly uniform 0..255, and returns the
 
808
        result in a binary. Uses a cryptographically secure prng seeded and
 
809
        periodically mixed with operating system provided entropy. By default
 
810
        this is the <c>RAND_bytes</c> method from OpenSSL.</p>
 
811
        <p>May throw exception <c>low_entropy</c> in case the random generator
 
812
        failed due to lack of secure "randomness".</p>
 
813
      </desc>
 
814
    </func>
 
815
    <func>
618
816
      <name>rand_uniform(Lo, Hi) -> N</name>
619
817
      <fsummary>Generate a random number</fsummary>
620
818
      <type>
625
823
        <p>Generate a random number <c><![CDATA[N, Lo =< N < Hi.]]></c> Uses the
626
824
          <c>crypto</c> library pseudo-random number generator. The
627
825
          arguments (and result) can be either erlang integers or binary
628
 
          multi-precision integers.</p>
 
826
          multi-precision integers. <c>Hi</c> must be larger than <c>Lo</c>.</p>
 
827
      </desc>
 
828
    </func>
 
829
    <func>
 
830
      <name>strong_rand_mpint(N, Top, Bottom) -> Mpint</name>
 
831
      <fsummary>Generate an N bit random number</fsummary>
 
832
      <type>
 
833
        <v>N = non_neg_integer()</v>
 
834
        <v>Top = -1 | 0 | 1</v>
 
835
        <v>Bottom = 0 | 1</v>
 
836
        <v>Mpint = binary()</v>
 
837
      </type>
 
838
      <desc>
 
839
        <p>Generate an N bit random number using OpenSSL's
 
840
        cryptographically strong pseudo random number generator
 
841
        <c>BN_rand</c>.</p>
 
842
        <p>The parameter <c>Top</c> places constraints on the most
 
843
        significant bits of the generated number. If <c>Top</c> is 1, then the
 
844
        two most significant bits will be set to 1, if <c>Top</c> is 0, the
 
845
        most significant bit will be 1, and if <c>Top</c> is -1 then no
 
846
        constraints are applied and thus the generated number may be less than
 
847
        N bits long.</p>
 
848
        <p>If <c>Bottom</c> is 1, then the generated number is
 
849
        constrained to be odd.</p>
 
850
        <p>May throw exception <c>low_entropy</c> in case the random generator
 
851
        failed due to lack of secure "randomness".</p>
629
852
      </desc>
630
853
    </func>
631
854
    <func>
673
896
        <v>Key = [E, N]</v>
674
897
        <v>E, N = Mpint</v>
675
898
        <d>Where <c>E</c> is the public exponent and <c>N</c> is public modulus.</d>
676
 
        <v>DigestType = md5 | sha</v>
 
899
        <v>DigestType = md5 | sha | sha256 | sha384 | sha512</v>
677
900
        <d> The default <c>DigestType</c> is sha.</d>
678
901
        <v>Mpint = binary()</v>
679
902
      </type>
682
905
          and verifies that the digest matches the RSA signature using the
683
906
          signer's public key <c>Key</c>.
684
907
        </p>
 
908
        <p>May throw exception <c>notsup</c> in case the chosen <c>DigestType</c>
 
909
        is not supported by the underlying OpenSSL implementation.</p>
685
910
      </desc>
686
911
    </func>
687
912
    
825
1050
    </func>
826
1051
 
827
1052
    <func>
 
1053
      <name>rc2_cbc_encrypt(Key, IVec, Text) -> Cipher</name>
 
1054
      <fsummary>Encrypt <c>Text</c>according to RC2 in CBC mode</fsummary>
 
1055
      <type>
 
1056
        <v>Key = Text = iolist() | binary()</v>
 
1057
        <v>Ivec = Cipher = binary()</v>
 
1058
      </type>
 
1059
      <desc>
 
1060
        <p>Encrypts <c>Text</c> according to RC2 in CBC mode.</p>
 
1061
      </desc>
 
1062
    </func>
 
1063
 
 
1064
    <func>
 
1065
      <name>rc2_cbc_decrypt(Key, IVec, Cipher) -> Text</name>
 
1066
      <fsummary>Decrypts <c>Cipher</c>according to RC2 in CBC mode</fsummary>
 
1067
      <type>
 
1068
        <v>Key = Text = iolist() | binary()</v>
 
1069
        <v>Ivec = Cipher = binary()</v>
 
1070
      </type>
 
1071
      <desc>
 
1072
        <p>Decrypts <c>Cipher</c> according to RC2 in CBC mode.</p>
 
1073
      </desc>
 
1074
    </func>
 
1075
    
 
1076
    <func>
828
1077
      <name>rc4_encrypt(Key, Data) -> Result</name>
829
1078
      <fsummary>Encrypt data using RC4</fsummary>
830
1079
      <type>