aboutsummaryrefslogtreecommitdiffstats
path: root/lib/crypto/doc/src
diff options
context:
space:
mode:
authorAndreas Schultz <[email protected]>2013-03-28 16:19:40 +0100
committerIngela Anderton Andin <[email protected]>2013-05-08 10:39:16 +0200
commitc6c2e82f8b94010e78bfa5fedce7629e7fd32d58 (patch)
tree5bfe63388a215b4f4e11b38fcee552779ebb797b /lib/crypto/doc/src
parent8e00f4ce7a49b2fd1da7e481dc0985703e4131a5 (diff)
downloadotp-c6c2e82f8b94010e78bfa5fedce7629e7fd32d58.tar.gz
otp-c6c2e82f8b94010e78bfa5fedce7629e7fd32d58.tar.bz2
otp-c6c2e82f8b94010e78bfa5fedce7629e7fd32d58.zip
CRYPTO: add support for Elliptic Curves to crypto app
Conflicts: lib/crypto/src/crypto.erl
Diffstat (limited to 'lib/crypto/doc/src')
-rw-r--r--[-rwxr-xr-x]lib/crypto/doc/src/crypto.xml149
1 files changed, 147 insertions, 2 deletions
diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index 7eca4557d9..9201d649d7 100755..100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -66,8 +66,20 @@
<item>
<p>srp: Secure Remote Password Protocol (RFC 2945)</p>
</item>
-
-
+ <item>
+ <p>ecdsa: "Public Key Cryptography for the Financial
+ Services Industry: The Elliptic Curve Digital
+ Signature Standard (ECDSA)", November, 2005.</p>
+ </item>
+ <item>
+ <p>ec: Standards for Efficient Cryptography Group (SECG), "SEC 1:
+ Elliptic Curve Cryptography", Version 1.0, September 2000.</p>
+ </item>
+ <item>
+ <p>ecdsa: American National Standards Institute (ANSI),
+ ANS X9.62-2005: The Elliptic Curve Digital Signature
+ Algorithm (ECDSA), 2005.</p>
+ </item>
</list>
<p>The above publications can be found at <url href="http://csrc.nist.gov/publications">NIST publications</url>, at <url href="http://www.ietf.org">IETF</url>.
</p>
@@ -1360,6 +1372,116 @@ Mpint() = <![CDATA[<<ByteLen:32/integer-big, Bytes:ByteLen/binary>>]]>
</func>
<func>
+ <name>ec_key_new(NamedCurve) -> ECKey</name>
+ <type>
+ <v>NamedCurve = atom()</v>
+ <v>ECKey = EC key resource()</v>
+ </type>
+ <desc>
+ <p>Generate an new EC key from the named curve. The private key
+ will be initialized with random data.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>ec_key_generate(ECKey) -> ok | error</name>
+ <type>
+ <v>ECKey = EC key resource()</v>
+ </type>
+ <desc>
+ <p>Fills in the public key if only the private key is known or generates
+ a new private/public key pair if only the curve parameters are known.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>ec_key_to_term(ECKey) -> ECKeyTerm.</name>
+ <type>
+ <v>ECKey = EC key resource()</v>
+ <v>ECKeyTerm = EC key as Erlang term</v>
+ </type>
+ <desc>
+ <p>Convert a EC key from a NIF resource into an Erlang term.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>term_to_ec_key(ECKeyTerm) -> ECKey</name>
+ <type>
+ <v>ECKeyTerm = EC key as Erlang term</v>
+ <v>ECKey = EC key resource()</v>
+ </type>
+ <desc>
+ <p>Convert a EC key an Erlang term into a NIF resource.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>ecdsa_sign(DataOrDigest, ECKey) -> Signature</name>
+ <name>ecdsa_sign(DigestType, DataOrDigest, ECKey) -> Signature</name>
+ <fsummary>Sign the data using ecdsa with the given key.</fsummary>
+ <type>
+ <v>DataOrDigest = Data | {digest,Digest}</v>
+ <v>Data = Mpint</v>
+ <v>Digest = binary()</v>
+ <v>ECKey = EC key resource()</v>
+ <v>DigestType = md5 | sha | sha256 | sha384 | sha512</v>
+ <d>The default <c>DigestType</c> is sha.</d>
+ <v>Mpint = binary()</v>
+ <v>Signature = binary()</v>
+ </type>
+ <desc>
+ <p>Creates a ESDSA signature with the private key <c>Key</c>
+ of a digest. The digest is either calculated as a
+ <c>DigestType</c> digest of <c>Data</c> or a precalculated
+ binary <c>Digest</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>ecdsa_verify(DataOrDigest, Signature, ECKey) -> Verified</name>
+ <name>ecdsa_verify(DigestType, DataOrDigest, Signature, ECKey) -> Verified </name>
+ <fsummary>Verify the digest and signature using ecdsa with given public key.</fsummary>
+ <type>
+ <v>Verified = boolean()</v>
+ <v>DataOrDigest = Data | {digest|Digest}</v>
+ <v>Data, Signature = Mpint</v>
+ <v>Digest = binary()</v>
+ <v>ECKey = EC key resource()</v>
+ <v>DigestType = md5 | sha | sha256 | sha384 | sha512</v>
+ <d>The default <c>DigestType</c> is sha.</d>
+ <v>Mpint = binary()</v>
+ </type>
+ <desc>
+ <p>Verifies that a digest matches the ECDSA signature using the
+ signer's public key <c>Key</c>.
+ The digest is either calculated as a <c>DigestType</c>
+ digest of <c>Data</c> or a precalculated binary <c>Digest</c>.</p>
+ <p>May throw exception <c>notsup</c> in case the chosen <c>DigestType</c>
+ is not supported by the underlying OpenSSL implementation.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>ecdh_compute_key(OthersPublicKey, MyPrivateKey) -> SharedSecret</name>
+ <name>ecdh_compute_key(OthersPublicKey, MyECPoint) -> SharedSecret</name>
+ <fsummary>Computes the shared secret</fsummary>
+ <type>
+ <v>OthersPublicKey, MyPrivateKey = ECKey()</v>
+ <v>MyPrivatePoint = binary()</v>
+ <v>SharedSecret = binary()</v>
+ </type>
+ <desc>
+ <p>Computes the shared secret from the private key and the other party's public key.
+ </p>
+ </desc>
+ </func>
+
+ <func>
<name>exor(Data1, Data2) -> Result</name>
<fsummary>XOR data</fsummary>
<type>
@@ -1373,6 +1495,29 @@ Mpint() = <![CDATA[<<ByteLen:32/integer-big, Bytes:ByteLen/binary>>]]>
</funcs>
<section>
+ <title>Elliptic Curve Key</title>
+ <p>Elliptic Curve keys consist of the curve paramters and a the
+ private and public keys (points on the curve). Translating the
+ raw curve paraters into something usable for the underlying
+ OpenSSL implementation is a complicated process. The main cryptografic
+ functions therefore expect a NIF resource as input that contains the
+ key in an internal format. Two functions <b>ec_key_to_term/1</b>
+ and <b>term_to_ec_key</b> are provided to convert between Erlang
+ terms and the resource format</p>
+ <p><em>Key in term form</em></p>
+ <pre>
+ec_named_curve() = atom()
+ec_point() = binary()
+ec_basis() = {tpbasis, K :: non_neg_integer()} | {ppbasis, K1 :: non_neg_integer(), K2 :: non_neg_integer(), K3 :: non_neg_integer()} | onbasis
+ec_field() = {prime_field, Prime :: Mpint()} | {characteristic_two_field, M :: integer(), Basis :: ec_basis()}
+ec_prime() = {A :: Mpint(), B :: Mpint(), Seed :: binary()}
+ec_curve_spec() = {Field :: ec_field(), Prime :: ec_prime(), Point :: ec_point(), Order :: Mpint(), CoFactor :: none | Mpint()}
+ec_curve() = ec_named_curve() | ec_curve_spec()
+ec_key() = {Curve :: ec_curve(), PrivKey :: Mpint() | undefined, PubKey :: ec_point() | undefined}
+ </pre>
+ </section>
+
+ <section>
<title>DES in CBC mode</title>
<p>The Data Encryption Standard (DES) defines an algorithm for
encrypting and decrypting an 8 byte quantity using an 8 byte key