1.2 release

- Documentation
- Private signing interface for ECKeyPair

.gitignore

@@ -6,3 +6,5 @@
 #
 # Pods/
 
+
+*.xcuserstate

25519.podspec

@@ -1,12 +1,17 @@
 Pod::Spec.new do |spec|
   spec.name         = '25519'
-  spec.version      = '1.1'
+  spec.version      = '1.2'
   spec.license      = { :type => 'GPLv3' }
   spec.homepage     = 'https://github.com/FredericJacobs/25519'
   spec.preserve_path = 'Sources/ed25519/**/*.{c,h}'
   spec.authors      = { 'Frederic Jacobs' => 'github@fredericjacobs.com' }
-  spec.summary      = 'Objective-C wrapper over Curve25519 & Ed25519 that does signing, verification, key generation, and key agreement with Curve25519 keys.'
-  spec.source       = { :git => 'https://github.com/FredericJacobs/25519.git', :tag => '1.1' }
+  spec.summary      = 'Key agreement (curve25519) and signing (ed25519), all with curve25519 keys.'
+  
+  spec.description  =  <<-DESC
+    Curve25519 is a fast and secure curve used for key agreement. Unfortunately, it does not support signing out of the box. This pod translates the point curves to do ed25519 signing with curve25519 keys.
+  DESC
+
+  spec.source       = { :git => 'https://github.com/FredericJacobs/25519.git', :tag => '1.2' }
   spec.source_files = 'Classes/*.{h,m}', 'Sources/ed25519/*.{c,h}''Sources/Curve25519/curve25519-donna.c', 'Sources/ed25519/*.{c,h}', 'Sources/ed25519/additions/*.{c,h}', 'Sources/ed25519/sha512/sha2big.{c,h}', 'Sources/ed25519/sha512/sph_sha2.h', 'Sources/ed25519/nacl_includes/*.{c,h}'
   spec.private_header_files = 'Sources/ed25519/*.h', 'Sources/ed25519/nacl_includes/*.h','Sources/ed25519/additions/*.h', 'Sources/ed25519/sha512/*.h'
   spec.framework    = 'Security'

Classes/Curve25519.h

@@ -1,6 +1,5 @@
 //
 //  Curve25519.h
-//  BuildTests
 //
 //  Created by Frederic Jacobs on 22/07/14.
 //  Copyright (c) 2014 Open Whisper Systems. All rights reserved.
@@ -16,20 +15,29 @@
     uint8_t privateKey[ECCKeyLength];
 }
 
-/**
- * Export the key pair's public key.
- *
- * @return The key pair's public key.
- */
--(NSData*) sign:(NSData*)data;
 -(NSData*) publicKey;
 
 @end
 
 @interface Curve25519 : NSObject
 
+/**
+ *  Generate a shared secret from a public key and a key pair using curve25519.
+ *
+ *  @param theirPublicKey public curve25519 key
+ *  @param keyPair        curve25519 key pair
+ *
+ *  @return Shared secret derived from ECDH with curve25519 public key and key pair.
+ */
+
 +(NSData*) generateSharedSecretFromPublicKey:(NSData*)theirPublicKey andKeyPair:(ECKeyPair*)keyPair;
 
+/**
+ *  Generate a curve25519 key pair
+ *
+ *  @return curve25519 key pair.
+ */
+
 +(ECKeyPair*)generateKeyPair;
 
 @end

Classes/Curve25519.m

@@ -19,7 +19,6 @@ extern void curve25519_sign(unsigned char* signature_out,
                             unsigned char* curve25519_privkey,
                             unsigned char* msg, unsigned long msg_len);
 
-
 @implementation ECKeyPair
 
 -(void)encodeWithCoder:(NSCoder *)coder {
@@ -27,7 +26,6 @@ extern void curve25519_sign(unsigned char* signature_out,
     [coder encodeBytes:self->privateKey length:ECCKeyLength forKey:TSECKeyPairPrivateKey];
 }
 
-
 -(id)initWithCoder:(NSCoder *)coder {
     self = [super init];
     if (self) {
@@ -100,7 +98,6 @@ extern void curve25519_sign(unsigned char* signature_out,
     return [NSData dataWithBytes:sharedSecret length:32];
 }
 
-
 @end
 
 @implementation Curve25519
@@ -109,7 +106,6 @@ extern void curve25519_sign(unsigned char* signature_out,
     return [ECKeyPair generateKeyPair];
 }
 
-
 +(NSData*)generateSharedSecretFromPublicKey:(NSData *)theirPublicKey andKeyPair:(ECKeyPair *)keyPair{
     return [keyPair generateSharedSecretFromPublicKey:theirPublicKey];
 }

Classes/Ed25519.h

@@ -1,6 +1,5 @@
 //
 //  Ed25519.h
-//  BuildTests
 //
 //  Created by Frederic Jacobs on 22/07/14.
 //  Copyright (c) 2014 Open Whisper Systems. All rights reserved.
@@ -12,7 +11,27 @@
 
 @interface Ed25519 : NSObject
 
+/**
+ *  ed25519 signature of a message with a curve25519 key pair.
+ *
+ *  @param msg     message to be signed.
+ *  @param keyPair curve25519 32-byte key pair.
+ *
+ *  @return The ed25519 64-bytes signature.
+ */
+
 +(NSData*)sign:(NSData*)msg withKeyPair:(ECKeyPair*)keyPair;
+
+/**
+ *  Verify ed25519 signature with 32-bytes Curve25519 key pair. Throws an NSInvalid
+ *
+ *  @param signature ed25519 64-byte signature.
+ *  @param pubKey    public key of the signer.
+ *  @param msg       message to be checked against the signature.
+ *
+ *  @return Returns TRUE if the signature is valid, false if it's not.
+ */
+
 +(BOOL)verifySignature:(NSData*)signature publicKey:(NSData*)pubKey msg:(NSData*)msg;
 
 @end

Classes/Ed25519.m

@@ -9,18 +9,20 @@
 #import "Ed25519.h"
 #import "Curve25519.h"
 
+@interface ECKeyPair ()
+-(NSData*) sign:(NSData*)data;
+@end
+
 extern int curve25519_verify(unsigned char* signature,
                       unsigned char* curve25519_pubkey,
                       unsigned char* msg, unsigned long msg_len);
 
-
 @implementation Ed25519
 
 +(NSData*)sign:(NSData*)msg withKeyPair:(ECKeyPair*)keyPair{
     return [keyPair sign:msg];
 }
 
-
 +(BOOL)verifySignature:(NSData*)signature publicKey:(NSData*)pubKey msg:(NSData*)msg{
     
     if ([msg length]<1) {
@@ -51,6 +53,4 @@ extern int curve25519_verify(unsigned char* signature,
     return success;
 }
 
-
-
 @end

Classes/Randomness.h

@@ -10,6 +10,14 @@
 
 @interface Randomness : NSObject
 
+/**
+ *  Generates a given number of cryptographically secure bytes using SecRandomCopyBytes.
+ *
+ *  @param numberBytes The number of bytes to be generated.
+ *
+ *  @return Random Bytes.
+ */
+
 +(NSMutableData*) generateRandomBytes:(int)numberBytes;
 
 @end

README.md

@@ -1,4 +1,54 @@
 25519
 =====
 
-Objective-C wrapper over Curve25519 & Ed25519 that does signing, verification, key generation, and key agreement with Curve25519 keys.
+Curve25519 is a fast and secure curve used for key agreement. Unfortunately, it does not support signing out of the box. This pod translates the point curves to do ed25519 signing with curve25519 keys.
+
+## Usage
+
+Generating a curve25519 key:
+
+```objective-c
+ECKeyPair *curve25519Key = [Curve25519 generateKeyPair];
+```
+
+`ECKeyPair` conforms to `NSCoding` to make storage of it more convenient. 
+
+- - -
+
+Generating a curve25519 shared secret:
+
+```objective-c
+NSData *sharedSecret = [Curve25519 generateSharedSecretFromPublicKey:aPublicKey andKeyPair:anECKeyPair];
+```
+
+- - -
+
+ed25519-sign message with curve25519 key pair:
+
+```objective-c
+NSData *signature = [Ed25519 sign:message withKeyPair:ecKeyPair]
+```
+
+- - -
+
+ed25519-verify message with curve25519 key pair:
+
+```objective-c
+BOOL validSignature = [Ed25519 verifySignature:signature publicKey:ecPublicKey msg:message;
+```
+
+## Documentation
+
+API reference is available on [CocoaDocs](http://cocoadocs.org/docsets/25519).
+ 
+## Installation
+
+Add this line to your `Podfile`
+
+```
+pod '25519', '~> 1.1'
+```
+
+## License
+
+Licensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html