snej@0: //
snej@0: //  MYPublicKey.h
snej@0: //  MYCrypto
snej@0: //
snej@0: //  Created by Jens Alfke on 3/25/09.
snej@0: //  Copyright 2009 Jens Alfke. All rights reserved.
snej@0: //
snej@0: 
snej@0: #import "MYKey.h"
jens@26: @class MYSHA1Digest, MYSymmetricKey, MYCertificate;
snej@0: 
snej@0: #if !TARGET_OS_IPHONE
snej@0: #import <Security/SecKey.h>
snej@0: #endif
snej@0: 
snej@0: 
snej@1: /** A public key, which can be used for encrypting data and verifying signatures.
snej@3:     MYPublicKeys are created as part of generating a key-pair, 
snej@3:     or by being imported from data into a MYKeychain. */
snej@13: @interface MYPublicKey : MYKey
snej@0: {
snej@1:     @private
jens@26:     MYSHA1Digest *_digest;              // The key's SHA-1 digest (null if not determined yet)
jens@26:     MYCertificate *_certificate;        // The cert this key came from (if any)
snej@0: }
snej@0: 
snej@0: /** The public key's SHA-1 digest. This is a convenient short (20-byte) identifier for the key. */
snej@0: @property (readonly) MYSHA1Digest *publicKeyDigest;
snej@0: 
snej@0: /** Encrypts a short piece of data using this key, returning the raw encrypted result.
snej@1:     An RSA key can encrypt only blocks smaller than its own key size; this
snej@0:     method will fail and return nil if the data is too long.
snej@0:     RSA encryption is also much slower than regular symmetric-key encryption, so the correct
snej@0:     way to encrypt a large block of data using a public key is to first generate a random
snej@0:     symmetric key, called the "session key" (using a Cryptor), encrypt that session key with the 
snej@0:     public key, and then encrypt your data with the session key. Send the encrypted session key
snej@0:     and the encrypted data. */
snej@13: - (NSData*) rawEncryptData: (NSData*)data;
snej@0: 
snej@0: /** Verifies the signature of a block of data. If the result is YES, you can be assured that
snej@1:     the signature was generated from the data by using this key's matching private key.
snej@0:     If the result is NO, something is wrong: either the data or the signature was modified,
snej@1:     or the signature was generated by a different private key.
snej@1:     (What's actually verified using RSA is the SHA-256 digest of the data.) */
snej@0: - (BOOL) verifySignature: (NSData*)signature ofData: (NSData*)data;
snej@13: 
snej@14: 
snej@14: /** @name Expert
snej@14:  *  Advanced methods. 
snej@14:  */
snej@14: //@{
jens@21: 
jens@21: /** Initializes a public key directly from its raw RSA modulus and exponent.
jens@21:     These numbers must come from an existing key-pair generated by the RSA algorithm; 
jens@21:     you CANNOT just pass in random data and create a working key! (To create a new key pair,
jens@21:     call -[MYKeychain generateRSAKeyPairOfSize:].)
jens@21:     @param modulus  RSA modulus, a very large integer represented as a blob of big-endian data.
jens@21:     @param exponent  RSA exponent, a prime number, commonly 17 or 65537.
jens@21: */
jens@21: - (id) initWithModulus: (NSData*)modulus exponent: (unsigned)exponent;
jens@21: 
jens@21: /** Retrieves the raw RSA modulus and exponent, which together uniquely specify the key.
jens@21:     The length of the modulus is the size, in bits, of the key: for example, a 2048-bit key
jens@21:     has 256 bytes of modulus data.
jens@21:     @param outModulus  On return, will contain the modulus: a very large positive integer represented
jens@21:                        as a blob of unsigned big-endian data.
jens@21:     @param outExponent  On return, will contain the exponent: a prime number, often 17 or 65537. */
jens@21: - (BOOL) getModulus: (NSData**)outModulus exponent: (unsigned*)outExponent;
jens@21: 
snej@14: #if !TARGET_OS_IPHONE
snej@14: 
snej@13: /** Encrypts a session key using this public key. 
snej@13:     The holder of the private key can then unwrap the session key from this data.
snej@13:     @param sessionKey  The symmetric session key to wrap/encrypt
snej@13:     @return  The encrypted data representing the session key */
snej@13: - (NSData*) wrapSessionKey: (MYSymmetricKey*)sessionKey;
snej@13: 
snej@14: #endif
snej@14: //@}
snej@14: 
snej@0: @end