we're up to ecc now

cryptx.h

@@ -417,8 +417,6 @@ typedef enum {
  * @param oaep_hash_alg	The numeric ID of the hashing algorithm to use within OAEP encoding.
  *      See @b cryptx_hash_algorithms.
  * @returns  An @b rsa_error_t indicating the status of the RSA operation.
- * @note @b ciphertext should be at least @b msglen bytes large.
- * @note OAEP encoding is applied to the message as part of the encryption.
  */
 rsa_error_t cryptx_rsa_encrypt(const void* msg,
 							   size_t msglen,
@@ -431,12 +429,14 @@ rsa_error_t cryptx_rsa_encrypt(const void* msg,
 /// ### ELLIPTIC CURVE DIFFIE-HELLMAN ###
 /// Using curve SECT233k1
 
-/** Defines the byte length of an ECDH private key supported by this library. */
-#define CRYPTX_EC_PRIVKEY_LEN		30
+/** Defines the byte length of a private key used by this module. */
+#define CRYPTX_KEYLEN_EC_PRIVKEY  30
 
-/** Defines the byte length of an ECDH public key supported by this library.  */
-#define CRYPTX_EC_PUBKEY_LEN		(CRYPTX_ECDH_PRIVKEY_LEN<<1)
-#define CRYPTX_EC_SECRET_LEN		CRYPTX_ECDH_PUBKEY_LEN
+/** Defines the byte length of a public key used by this module.  */
+#define CRYPTX_KEYLEN_EC_PUBKEY		(CRYPTX_KEYLEN_EC_PRIVKEY<<1)
+
+/** Defines the byte length of a secret generated by this module.  */
+#define CRYPTX_KEYLEN_EC_SECRET		CRYPTX_KEYLEN_EC_PUBKEY
 
 /// Defines possible response codes from calls to the ECDH API.
 typedef enum _ec_error {
@@ -447,31 +447,18 @@ typedef enum _ec_error {
 } ec_error_t;
 
 /**
- * @brief Generates a pair of public/private keys for ECC over SECT233k1
+ * @brief Generates a pair of public/private keys over SECT233k1
  * @param privkey	Pointer to EC private key buffer.
  * @param pubkey	Pointer to EC public key buffer.
  * @returns A random 29-byte EC private key and associated public key.
- * @note Output public key is a point on the curve expressed as two 30-byte coordinates
- * encoded in little endian byte order and padded with zeros (if needed). You may have to
- * deserialize the key and then serialize it into a different format to use it with
- * some encryption libraries.
- * @note
  */
 ec_error_t cryptx_ec_keygen(uint8_t *privkey, uint8_t *pubkey);
 
 /**
- * @brief Computes a secret from the private key and the remote public key.
+ * @brief Computes a secret given a private key and remote public key using the elliptic curve variant of the @b diffie-hellman algorithm..
  * @param privkey	Pointer to local private key.
  * @param rpubkey	Pointer to remote public key.
  * @param secret	Pointer to buffer to write shared secret to.
- * @note @b secret must be at least @b CRYPTX_ECDH_SECRET_LEN bytes large.
- * @note Output secret is a point on the curve expressed as two 30-byte coordinates
- * encoded in little endian byte order and padded with zeros if needed. You may have to
- * deserialize the secret and then serialize it into a different format for compatibility with
- * other encryption libraries.
- * @note It is generally not recommended to use the computed secret as an encryption key as is.
- * It is preferred to pass the secret to a KDF or a cryptographic primitive such as a hash function and use
- * that output as your symmetric key.
  */
 ec_error_t cryptx_ec_secret(const uint8_t *privkey, const uint8_t *rpubkey, uint8_t *secret);
 

docs/doxygen/xml/index.xml

@@ -90,9 +90,9 @@
     <member refid="cryptx_8h_1a7bffe1d673fd05c8e538d6169b12509f" kind="define"><name>cryptx_aes_gcm_flagset</name></member>
     <member refid="cryptx_8h_1adf4062c77f37927bc0178872056602ff" kind="define"><name>cryptx_aes_get_ciphertext_len</name></member>
     <member refid="cryptx_8h_1a265dcd336b31e2b95870d864c85cee2a" kind="define"><name>CRYPTX_RSA_MODULUS_MAX</name></member>
-    <member refid="cryptx_8h_1a26e233163ef752cc08d3f3499007369a" kind="define"><name>CRYPTX_EC_PRIVKEY_LEN</name></member>
-    <member refid="cryptx_8h_1a9fb63bb764b8654fc273535be6c4e3a3" kind="define"><name>CRYPTX_EC_PUBKEY_LEN</name></member>
-    <member refid="cryptx_8h_1a3afc412d9c56cd1f46407fe280b92156" kind="define"><name>CRYPTX_EC_SECRET_LEN</name></member>
+    <member refid="cryptx_8h_1aba6c506b34f4d5e1ab991512f4368b8e" kind="define"><name>CRYPTX_KEYLEN_EC_PRIVKEY</name></member>
+    <member refid="cryptx_8h_1a46079c346c2ba0f2145e084a78c2cdab" kind="define"><name>CRYPTX_KEYLEN_EC_PUBKEY</name></member>
+    <member refid="cryptx_8h_1afdb20067c07b76dac6331ed30d6cd1d6" kind="define"><name>CRYPTX_KEYLEN_EC_SECRET</name></member>
     <member refid="cryptx_8h_1a13585a6206e220218a8f379327b04433" kind="define"><name>cryptx_asn1_get_tag</name></member>
     <member refid="cryptx_8h_1a5af192045bb48e03f788962f259a2a7e" kind="define"><name>cryptx_asn1_get_class</name></member>
     <member refid="cryptx_8h_1a3c8b39f5fb3ad1d8d138b9791b18f01e" kind="define"><name>cryptx_asn1_get_form</name></member>

docs/doxygen/xml/structcryptx__ecc__point.xml

@@ -16,7 +16,7 @@
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="/Users/acagliano/Library/Mobile Documents/com~apple~CloudDocs/Repositories/toolchain/src/cryptx/cryptx.h" line="665" column="9" bodyfile="/Users/acagliano/Library/Mobile Documents/com~apple~CloudDocs/Repositories/toolchain/src/cryptx/cryptx.h" bodystart="665" bodyend="-1"/>
+        <location file="/Users/acagliano/Library/Mobile Documents/com~apple~CloudDocs/Repositories/toolchain/src/cryptx/cryptx.h" line="652" column="9" bodyfile="/Users/acagliano/Library/Mobile Documents/com~apple~CloudDocs/Repositories/toolchain/src/cryptx/cryptx.h" bodystart="652" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structcryptx__ecc__point_1ada79cb09d73636479cf469e6de935973" prot="public" static="no" mutable="no">
         <type>uint8_t</type>
@@ -30,15 +30,15 @@
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="/Users/acagliano/Library/Mobile Documents/com~apple~CloudDocs/Repositories/toolchain/src/cryptx/cryptx.h" line="666" column="9" bodyfile="/Users/acagliano/Library/Mobile Documents/com~apple~CloudDocs/Repositories/toolchain/src/cryptx/cryptx.h" bodystart="666" bodyend="-1"/>
+        <location file="/Users/acagliano/Library/Mobile Documents/com~apple~CloudDocs/Repositories/toolchain/src/cryptx/cryptx.h" line="653" column="9" bodyfile="/Users/acagliano/Library/Mobile Documents/com~apple~CloudDocs/Repositories/toolchain/src/cryptx/cryptx.h" bodystart="653" bodyend="-1"/>
       </memberdef>
       </sectiondef>
     <briefdescription>
 <para>Defines a point for use with elliptic curve arithmetic. </para>
     </briefdescription>
     <detaileddescription>
     </detaileddescription>
-    <location file="/Users/acagliano/Library/Mobile Documents/com~apple~CloudDocs/Repositories/toolchain/src/cryptx/cryptx.h" line="664" column="1" bodyfile="/Users/acagliano/Library/Mobile Documents/com~apple~CloudDocs/Repositories/toolchain/src/cryptx/cryptx.h" bodystart="664" bodyend="667"/>
+    <location file="/Users/acagliano/Library/Mobile Documents/com~apple~CloudDocs/Repositories/toolchain/src/cryptx/cryptx.h" line="651" column="1" bodyfile="/Users/acagliano/Library/Mobile Documents/com~apple~CloudDocs/Repositories/toolchain/src/cryptx/cryptx.h" bodystart="651" bodyend="654"/>
     <listofallmembers>
       <member refid="structcryptx__ecc__point_1a7a6b80237baf8237385a5827601d1337" prot="public" virt="non-virtual"><scope>cryptx_ecc_point</scope><name>x</name></member>
       <member refid="structcryptx__ecc__point_1ada79cb09d73636479cf469e6de935973" prot="public" virt="non-virtual"><scope>cryptx_ecc_point</scope><name>y</name></member>

docs/index.rst

@@ -99,6 +99,8 @@ Check out the :ref:`analysis` for more technical implementation details includin
   modules/hash
   modules/hmac
   modules/aes
+  modules/rsa
+  modules/ec
 
   static/analysis
   static/references

docs/modules/ec.rst

@@ -0,0 +1,35 @@
+.. _ec:
+
+Elliptic Curves
+================
+
+.. raw:: html
+
+  <p style="background:rgba(176,196,222,.5); padding:10px; font-family:Arial; margin:20px 0;"><span style="font-weight:bold;">Module Functionality</span><br />Provides elliptic curve cryptography&mdash;generation of public/private keypairs, the diffie-hellman key exchange protocol, and digital signature algorithm.</p>
+
+Macros
+_______
+
+.. doxygendefine:: CRYPTX_KEYLEN_EC_PRIVKEY
+	:project: CryptX
+
+.. doxygendefine:: CRYPTX_KEYLEN_EC_PUBKEY
+	:project: CryptX
+
+.. doxygendefine:: CRYPTX_KEYLEN_EC_SECRET
+	:project: CryptX
+
+Response Codes
+_______________
+
+.. doxygenenum:: ec_error_t
+	:project: CryptX
+
+Functions
+___________
+
+.. doxygenfunction:: cryptx_ec_keygen
+	:project: CryptX
+
+.. doxygenfunction:: cryptx_ec_secret
+	:project: CryptX

docs/modules/rsa.rst

@@ -1,13 +1,33 @@
 .. _rsa:
 
-function documentation: RSA
-===============================
+RSA
+====
+
+.. raw:: html
+
+  <p style="background:rgba(176,196,222,.5); padding:10px; font-family:Arial; margin:20px 0;"><span style="font-weight:bold;">Module Functionality</span><br />Provides an encryption-only implemention of the Rivest-Shamir Adleman (RSA) public key encrytion system. RSA is still widely used at the start of an encrypted connection to negotiate a secret for a faster encryption algorithm like AES.</p>
+
+Macros
+_________
 
 .. doxygendefine:: CRYPTX_RSA_MODULUS_MAX
 	:project: CryptX
+
+Response Codes
+_______________
 
 .. doxygenenum:: rsa_error_t
 	:project: CryptX
-
+
+Functions
+____________
+
 .. doxygenfunction:: cryptx_rsa_encrypt
 	:project: CryptX
+
+Notes
+______
+
+(1) This implementation automatically applies Optimal Asymmetric Encryption Padding (OAEP) v2.2 encoding to the message. The length of the plaintext message to encrypt cannot exceed :code:`len(public_modulus) - (2 * chosen_hash_digestlen) - 2`.
+
+(2) The length of the ciphertext returned is the same length as the public modulus used for encryption. This means you can allocate/reserve a buffer of that size, or just use the macro defined above for the maximum length.

docs/www/_sources/index.rst.txt

@@ -99,6 +99,8 @@ Check out the :ref:`analysis` for more technical implementation details includin
   modules/hash
   modules/hmac
   modules/aes
+  modules/rsa
+  modules/ec
 
   static/analysis
   static/references

docs/www/_sources/modules/ec.rst.txt

@@ -0,0 +1,35 @@
+.. _ec:
+
+Elliptic Curves
+================
+
+.. raw:: html
+
+  <p style="background:rgba(176,196,222,.5); padding:10px; font-family:Arial; margin:20px 0;"><span style="font-weight:bold;">Module Functionality</span><br />Provides elliptic curve cryptography&mdash;generation of public/private keypairs, the diffie-hellman key exchange protocol, and digital signature algorithm.</p>
+
+Macros
+_______
+
+.. doxygendefine:: CRYPTX_KEYLEN_EC_PRIVKEY
+	:project: CryptX
+
+.. doxygendefine:: CRYPTX_KEYLEN_EC_PUBKEY
+	:project: CryptX
+
+.. doxygendefine:: CRYPTX_KEYLEN_EC_SECRET
+	:project: CryptX
+
+Response Codes
+_______________
+
+.. doxygenenum:: ec_error_t
+	:project: CryptX
+
+Functions
+___________
+
+.. doxygenfunction:: cryptx_ec_keygen
+	:project: CryptX
+
+.. doxygenfunction:: cryptx_ec_secret
+	:project: CryptX

docs/www/_sources/modules/rsa.rst.txt

@@ -1,13 +1,33 @@
 .. _rsa:
 
-function documentation: RSA
-===============================
+RSA
+====
+
+.. raw:: html
+
+  <p style="background:rgba(176,196,222,.5); padding:10px; font-family:Arial; margin:20px 0;"><span style="font-weight:bold;">Module Functionality</span><br />Provides an encryption-only implemention of the Rivest-Shamir Adleman (RSA) public key encrytion system. RSA is still widely used at the start of an encrypted connection to negotiate a secret for a faster encryption algorithm like AES.</p>
+
+Macros
+_________
 
 .. doxygendefine:: CRYPTX_RSA_MODULUS_MAX
 	:project: CryptX
+
+Response Codes
+_______________
 
 .. doxygenenum:: rsa_error_t
 	:project: CryptX
-
+
+Functions
+____________
+
 .. doxygenfunction:: cryptx_rsa_encrypt
 	:project: CryptX
+
+Notes
+______
+
+(1) This implementation automatically applies Optimal Asymmetric Encryption Padding (OAEP) v2.2 encoding to the message. The length of the plaintext message to encrypt cannot exceed :code:`len(public_modulus) - (2 * chosen_hash_digestlen) - 2`.
+
+(2) The length of the ciphertext returned is the same length as the public modulus used for encryption. This means you can allocate/reserve a buffer of that size, or just use the macro defined above for the maximum length.

docs/www/genindex.html

@@ -41,6 +41,8 @@
 <li class="toctree-l1"><a class="reference internal" href="modules/hash.html">Secure Hashing</a></li>
 <li class="toctree-l1"><a class="reference internal" href="modules/hmac.html">Hash-Based MAC</a></li>
 <li class="toctree-l1"><a class="reference internal" href="modules/aes.html">Advanced Encryption Standard</a></li>
+<li class="toctree-l1"><a class="reference internal" href="modules/rsa.html">RSA</a></li>
+<li class="toctree-l1"><a class="reference internal" href="modules/ec.html">Elliptic Curves</a></li>
 <li class="toctree-l1"><a class="reference internal" href="static/analysis.html">Analysis &amp; Overview</a></li>
 </ul>
 
@@ -73,6 +75,7 @@ <h1 id="index">Index</h1>
 <div class="genindex-jumpbox">
  <a href="#A"><strong>A</strong></a>
  | <a href="#C"><strong>C</strong></a>
+ | <a href="#E"><strong>E</strong></a>
  | <a href="#R"><strong>R</strong></a>
 
 </div>
@@ -215,12 +218,12 @@ <h2 id="C">C</h2>
 </li>
       <li><a href="modules/encoding.html#_CPPv4N16CRYPTX_ASN1_TAGS13ASN1_OBJECTIDE">CRYPTX_ASN1_TAGS::ASN1_OBJECTID (C++ enumerator)</a>
 </li>
-  </ul></td>
-  <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="modules/encoding.html#_CPPv4N16CRYPTX_ASN1_TAGS16ASN1_OCTETSTRINGE">CRYPTX_ASN1_TAGS::ASN1_OCTETSTRING (C++ enumerator)</a>
 </li>
       <li><a href="modules/encoding.html#_CPPv4N16CRYPTX_ASN1_TAGS20ASN1_PRINTABLESTRINGE">CRYPTX_ASN1_TAGS::ASN1_PRINTABLESTRING (C++ enumerator)</a>
 </li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="modules/encoding.html#_CPPv4N16CRYPTX_ASN1_TAGS9ASN1_REALE">CRYPTX_ASN1_TAGS::ASN1_REAL (C++ enumerator)</a>
 </li>
       <li><a href="modules/encoding.html#_CPPv4N16CRYPTX_ASN1_TAGS16ASN1_RELATIVEOIDE">CRYPTX_ASN1_TAGS::ASN1_RELATIVEOID (C++ enumerator)</a>
@@ -269,7 +272,9 @@ <h2 id="C">C</h2>
 </li>
       <li><a href="modules/hash.html#c.CRYPTX_DIGESTLEN_SHA256">CRYPTX_DIGESTLEN_SHA256 (C macro)</a>, <a href="modules/hmac.html#c.CRYPTX_DIGESTLEN_SHA256">[1]</a>
 </li>
-      <li><a href="modules/ecc.html#_CPPv416cryptx_ec_keygenP7uint8_tP7uint8_t">cryptx_ec_keygen (C++ function)</a>
+      <li><a href="modules/ec.html#_CPPv416cryptx_ec_keygenP7uint8_tP7uint8_t">cryptx_ec_keygen (C++ function)</a>
+</li>
+      <li><a href="modules/ec.html#_CPPv416cryptx_ec_secretPK7uint8_tPK7uint8_tP7uint8_t">cryptx_ec_secret (C++ function)</a>
 </li>
       <li><a href="modules/hazardous.html#_CPPv416cryptx_ecc_point">cryptx_ecc_point (C++ struct)</a>
 </li>
@@ -316,6 +321,12 @@ <h2 id="C">C</h2>
       <li><a href="modules/aes.html#c.CRYPTX_KEYLEN_AES192">CRYPTX_KEYLEN_AES192 (C macro)</a>
 </li>
       <li><a href="modules/aes.html#c.CRYPTX_KEYLEN_AES256">CRYPTX_KEYLEN_AES256 (C macro)</a>
+</li>
+      <li><a href="modules/ec.html#c.CRYPTX_KEYLEN_EC_PRIVKEY">CRYPTX_KEYLEN_EC_PRIVKEY (C macro)</a>
+</li>
+      <li><a href="modules/ec.html#c.CRYPTX_KEYLEN_EC_PUBKEY">CRYPTX_KEYLEN_EC_PUBKEY (C macro)</a>
+</li>
+      <li><a href="modules/ec.html#c.CRYPTX_KEYLEN_EC_SECRET">CRYPTX_KEYLEN_EC_SECRET (C macro)</a>
 </li>
       <li><a href="modules/rsa.html#_CPPv418cryptx_rsa_encryptPKv6size_tPKv6size_tPv7uint8_t">cryptx_rsa_encrypt (C++ function)</a>
 </li>
@@ -324,6 +335,24 @@ <h2 id="C">C</h2>
   </ul></td>
 </tr></table>
 
+<h2 id="E">E</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="modules/ec.html#_CPPv410ec_error_t">ec_error_t (C++ enum)</a>
+</li>
+      <li><a href="modules/ec.html#_CPPv4N10ec_error_t14EC_INVALID_ARGE">ec_error_t::EC_INVALID_ARG (C++ enumerator)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="modules/ec.html#_CPPv4N10ec_error_t5EC_OKE">ec_error_t::EC_OK (C++ enumerator)</a>
+</li>
+      <li><a href="modules/ec.html#_CPPv4N10ec_error_t18EC_PRIVKEY_INVALIDE">ec_error_t::EC_PRIVKEY_INVALID (C++ enumerator)</a>
+</li>
+      <li><a href="modules/ec.html#_CPPv4N10ec_error_t18EC_RPUBKEY_INVALIDE">ec_error_t::EC_RPUBKEY_INVALID (C++ enumerator)</a>
+</li>
+  </ul></td>
+</tr></table>
+
 <h2 id="R">R</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>

docs/www/index.html

@@ -42,6 +42,8 @@
 <li class="toctree-l1"><a class="reference internal" href="modules/hash.html">Secure Hashing</a></li>
 <li class="toctree-l1"><a class="reference internal" href="modules/hmac.html">Hash-Based MAC</a></li>
 <li class="toctree-l1"><a class="reference internal" href="modules/aes.html">Advanced Encryption Standard</a></li>
+<li class="toctree-l1"><a class="reference internal" href="modules/rsa.html">RSA</a></li>
+<li class="toctree-l1"><a class="reference internal" href="modules/ec.html">Elliptic Curves</a></li>
 <li class="toctree-l1"><a class="reference internal" href="static/analysis.html">Analysis &amp; Overview</a></li>
 </ul>
 
@@ -144,7 +146,7 @@ <h2>API Documentation<a class="headerlink" href="#api-documentation" title="Perm
 <tr class="row-odd"><td><p><a class="reference internal" href="modules/rsa.html#rsa"><span class="std std-ref">rsa</span></a></p></td>
 <td><p>rivest-shamir-adleman (RSA) public key encryption</p></td>
 </tr>
-<tr class="row-even"><td><p><a class="reference internal" href="modules/ecc.html#ec"><span class="std std-ref">ec</span></a></p></td>
+<tr class="row-even"><td><p><a class="reference internal" href="modules/ec.html#ec"><span class="std std-ref">ec</span></a></p></td>
 <td><p>elliptic curves: Diffie-Helman kex, Digitial Signing Algorithm</p></td>
 </tr>
 <tr class="row-odd"><td><p><span class="xref std std-ref">asn1</span></p></td>