algorithm |
Returns the algorithm of the receiver.
- (CSSM_ALGORITHMS)algorithm;
See cssmtype.h for algorithms. If you want to know the algorithm used to wrap a key, see the wrapAlgorithm method.
attributes |
Returns a mask representing the attributes of the receiver.
- (CSSM_KEYATTR_FLAGS)attributes;
See cssmtype.h for masks.
blobType |
Returns the 'blob' type of the receiver.
- (CSSM_KEYBLOB_TYPE)blobType;
The 'blob' type of a key is how it is stored in memory - whether as a reference, in raw form, or wrapped form. See cssmtype.h for valid types.
CSPModule |
Returns the CSP module in which the key resides.
- (CSSMModule*)CSPModule;
Returns- the CSP module (if any) the key resides within, or nil if there is no CSP module associated with the key or an error occurs.
It is conceivable that keys can exist outside any particular CSP module, in various raw and wrapped forms. Thus, this method may well return nil. However, for keys which are just references inside a particular module, this method returns the module in which they exist.
CSSMKey |
Returns the CSSM_KEY for the receiver.
- (const CSSM_KEY *)CSSMKey;
This function works whether you created the object with a CSSM_KEY or SecKeyRef. Please make sure to copy the returned CSSM_KEY if you want to change it - don't just cast away the const. Changing the returned CSSM_KEY directly may result in unfavourable behaviour of the owning Key instance.
data |
Returns the key in a reliable raw data form.
- (NSData*)data;
This method encodes both the key data and it's associated attributes into a simple data form. There is no standard form for serially-representing a key like this. Many real-world applications maintain a separation between the key data and it's attributes, preferring to 'remember' the attributes separately from the data, or re-generate them as required. This appears to be counter-intuitive. Thus, this method is suggested as a standard means for serially encoding keys.
Note that at present the data generated by this function is not byte-order independent, meaning it cannot necessarily be taken from one platform to another. It is also, at present, not necessarily compiler independent. These issues will be resolved in the near future. In the mean time, it is still safe to use this method if you are doing single-system testing. Future versions will be able to read any data stored using this version, provided you do so on the same platform and with the same compiler as was used to generate the data.
description |
Returns a user-readable description of the receiver.
- (NSString*)description;
This makes a reasonable attempt to present the key's properties in a human-readable form. Note that it does not contain the key's data. If you want the raw key data, see the rawData method.
endDate |
Returns the time and date after which the receiver should be considered invalid.
- (NSCalendarDate*)endDate;
You should not use a key after it's end date, because there may well be a good reason it expired at that time. This framework does not, at present, verify key validity dates, so you must do so yourself. It may not be necessary to verify a key each time it is used, depending on your application. It is however a good idea to verify the key every now and again, if your application will run for more than half an hour at a time.
format |
Returns the format of the receiver.
- (CSSM_KEYBLOB_FORMAT)format;
See cssmtype.h for known formats.
init((NSString*), (Key*), (Key*), (NSString*), (Key*), (Key*), (Key*)) |
Returns the version of the CDSA used to generate the key.
See Also:
- version
- (Key*)init;
Be wary with this - this framework tries to preserve the version value for keys, but many other libraries do not (e.g. Apple's own Security framework). In fact, many real world applications provide no indication of such information to start with. Plus, this version number only applies to keys generated by the CDSA, not from other libraries. So, in summary, be wary of using this for anything important, as in a significant number of cases it may not be valid.
Generally the fallback is to the version of the CDSA under which this framework was compiled (2.0 at the time of writing). This fallback behaviour, at least, is fairly consistant across libraries (e.g. Apple's Security framework, again).
init((NSString*), (Key*), (Key*), (NSString*), (Key*), (Key*), (Key*)) |
Reject initialiser.
- (Key*)init;
You cannot initialise a Key using "init" - use one of the other initialisation methods.
initWithCSSMKey: |
Initializes the receiver with a CSSM_KEY
See Also:
- initWithCSSMKey:module:
- (Key*)initWithCSSMKey:(const CSSM_KEY *)ke module:(CSSMModule*)CSPModule;
ke- The CSSM_KEY.
CSPModule- The CSP module the given key is a member of. Should not be nil.
The CSSM_KEY provided must not be destroyed while the receiver still exists. Conversely, the receiver will not automatically destroy the key itself.
initWithCSSMKey:module: |
Initializes the receiver with a CSSM_KEY
See Also:
- initWithCSSMKey:
- (Key*)initWithCSSMKey:(const CSSM_KEY *)ke module:(CSSMModule*)CSPModule;
ke- The CSSM_KEY.
CSPModule- The CSP module the given key is a member of. Should not be nil.
The CSSM_KEY provided must not be destroyed while the receiver still exists. Conversely, the receiver will not automatically destroy the key itself.
initWithKeyRef: |
Initiailizes the receiver with a SecKeyRef.
See Also:
- initWithKeyRef:module:
- (Key*)initWithKeyRef:(SecKeyRef)ke module:(CSSMModule*)CSPModule;
ke- The SecKeyRef.
CSPModule- The CSP module the given key is a member of. Should not be nil.
The SecKeyRef is retained by the receiver for the duration of it's lifetime. Changes to the SecKeyRef will reflect on the receiver, and vice versa. Note that this method caches existing Key instances, such that calling this with a SecKeyRef that has already been used will release the receiver and return the existing instance.
initWithKeyRef:module: |
Initiailizes the receiver with a SecKeyRef.
See Also:
- initWithKeyRef:
- (Key*)initWithKeyRef:(SecKeyRef)ke module:(CSSMModule*)CSPModule;
ke- The SecKeyRef.
CSPModule- The CSP module the given key is a member of. Should not be nil.
The SecKeyRef is retained by the receiver for the duration of it's lifetime. Changes to the SecKeyRef will reflect on the receiver, and vice versa. Note that this method caches existing Key instances, such that calling this with a SecKeyRef that has already been used will release the receiver and return the existing instance.
isEqualToKey: |
Compares two keys and returns whether or not they are exactly identical.
- (BOOL)isEqualToKey:(Key*)otherKey;
key- The key to compare with the receiver.
For this method to consider two keys to be identical they must have exactly the same data and exactly the same header information - i.e. usage, attributes, version, validity, etc. If you wish to compare two keys based on whether they have the same key data, use isSimilarToKey:.
Note that this method only works for wrapped/raw keys.
isSimilarToKey: |
Compares two keys and returns whether or not they are similar (have the same key data).
- (BOOL)isSimilarToKey:(Key*)otherKey;
key- The key to compare to the receiver.
Unlike the isEqualToKey: method, this method only compares the keys' raw data. Thus, their header info may differ (i.e. usage, attributes, version, validity, etc). This is useful in many cases because if the raw data is the same, the key is essentially the same - it will produce exactly the same cryptographic outputs. It is entirely plausible that you will have two distinct copies of the same key, but each with different attributes.
Note that this method only works for wrapped/raw keys.
keyClass |
Returns the receiver's key class.
- (CSSM_KEYCLASS)keyClass;
The key class is simply the general type of key - e.g. symmetric, public, private, etc. See cssmtype.h for known classes.
keyHash |
Returns a hash of the key, suitable for uniquely identifying the key (not the object, unlike the NSObject hash method).
- (NSData*)keyHash;
This method returns a hash of the receiver's contents. It does not work the same as the generic NSObject hash function, and should not be treated as such. You may wish to use a public key's hash, for example, when referring to it from the corresponding private key.
keyRef |
Returns a SecKeyRef representing this key, if one exists.
- (SecKeyRef)keyRef;
Keys can be created from SecKeyRef's or from CSSM_KEY's. At present, while you can get the CSSM_KEY from a SecKeyRef-created instance, you cannot get a SecKeyRef from a CSSM_KEY-created instance. This is considered a bug, but may not be fixed in the immediate future.
Note that the returned object is linked to the receiver, and changes to the object will reflect in the receiver (and vice versa).
keyWithCSSMKey: |
Creates and returns a Key instance based on a CSSM_KEY.
See Also:
- keyWithCSSMKey:module:
+ (Key*)keyWithCSSMKey:(const CSSM_KEY *)ke module:(CSSMModule*)CSPModule;
ke- The CSSM_KEY.
CSPModule- The CSP module the given key is a member of. Should not be nil.
The CSSM_KEY provided must not be destroyed while the returned object still exists. Conversely, the returned object will never destroy the CSSM_KEY itself.
keyWithCSSMKey:module: |
Creates and returns a Key instance based on a CSSM_KEY.
See Also:
- keyWithCSSMKey:
+ (Key*)keyWithCSSMKey:(const CSSM_KEY *)ke module:(CSSMModule*)CSPModule;
ke- The CSSM_KEY.
CSPModule- The CSP module the given key is a member of. Should not be nil.
The CSSM_KEY provided must not be destroyed while the returned object still exists. Conversely, the returned object will never destroy the CSSM_KEY itself.
keyWithKeyRef: |
Creates and returns a Key instance based on a SecKeyRef.
See Also:
- keyWithKeyRef:module:
+ (Key*)keyWithKeyRef:(SecKeyRef)ke module:(CSSMModule*)CSPModule;
ke- The SecKeyRef.
CSPModule- The CSP module the given key is a member of. Should not be nil.
The SecKeyRef is retained by the new Key instance for the duration of it's life. This method caches existing Key instances, such that multiple calls with the same SecKeyRef will return the same unique Key instance.
keyWithKeyRef:module: |
Creates and returns a Key instance based on a SecKeyRef.
See Also:
- keyWithKeyRef:
+ (Key*)keyWithKeyRef:(SecKeyRef)ke module:(CSSMModule*)CSPModule;
ke- The SecKeyRef.
CSPModule- The CSP module the given key is a member of. Should not be nil.
The SecKeyRef is retained by the new Key instance for the duration of it's life. This method caches existing Key instances, such that multiple calls with the same SecKeyRef will return the same unique Key instance.
lastError |
Returns the last error that occured for the receiver.
- (int)lastError;
The set of error codes encompasses those returned by Sec* functions - refer to the Security framework documentation for a list. At present there are no other error codes defined for Access instances.
Please note that this error code is local to the receiver only, and not any sort of shared global value.
logicalSize |
Returns the logical size of the receiver in bits.
- (int)logicalSize;
Different algorithms use keys in different ways, such that a key which has a certain number of physical bits may 'expand out to', or 'derive', or 'represent', more bits. The logical size is what is usually quoted in most applications, e.g. "1024-bit RSA" or "128-bit AES" etc. For some algorithms, the physical key size may not even be constant, for the same logical key size.
rawData |
Returns the key data itself, free of any of it's attributes.
- (NSData*)rawData;
No encoding is performed - only the actual key data itself is returned, without any extra encoding [.as with the data method]
startDate |
Returns the time and date before which the receiver should be considered invalid.
- (NSCalendarDate*)startDate;
You should not use a key prior to it's start date, because there may well be a good reason it is not valid until then. This framework does not, at present, verify key validity dates, so you must do so yourself. You should verify the start date at least once, when you first use it. If the start date is in the past, you shouldn't, in normal use, need to verify it again. If not, you should fail in whatever operation you were planning to perform, and remember to test the start date again next time you try to use the key.
unwrappedKeyUnsafe |
Returns the unwrapped version of the receiver.
- (Key*)unwrappedKeyUnsafe;
This method unwraps 'raw' or 'null-wrapped' or 'clear' keys. It is labeled unsafe because in many cases, such an operation is unsafe. Public keys are the exception to this of course, because they are obviously designed to be shared freely. But symmetric and private keys should very rarely be exported from an application without being protected in some way, such as with another key. They certainly should never be stored or transmitted in such a form. The following rant deals only with symmetric and private keys:
There is almost no excuse for why you cannot use another key to wrap a key. If nothing else, you can derive a suitable key from a user-supplied passphrase, which at least provides some level of protection. Further excuses like "the user might forget the passphrase" are not acceptable. How about, "some criminal might get your key and steal your identity"? Or a little more light-sidedly "your friends may get your keys and send doctored photo's of you to that girl you've got a crush on. Photo's of you doing unspeakable things to innocent barn yard animals. Photo's signed by your private key, and thus 'unforgeable'.". Whether criminal or comical, the outcome of poor key security is not fun for those who own the key.
The fundamental point is that no matter how good a security framework is technically, it means exactly jack all if the implementors do stupid things, like permit symmetric or private keys to be transmitted or stored in the clear. Don't do it. If you do, elves will sneak into your computer at night and put playdoh in your power supply.
unwrappedKeyUsingKey: |
Returns the unwrapped version of the receiver.
- (Key*)unwrappedKeyUsingKey:(Key*)wrappingKey;
wrappingKey- The key to be used to unwrap the receiver. This may be a symmetric or public key, as appropriate for the type of wrapping used on the receiver. This cannot be NULL.
This method only works for receivers containing wrapped key data. It's returns a new Key instance containing the unwrapped key.
usage |
Returns a mask representing the valid uses for the receiver.
- (CSSM_KEYUSE)usage;
See cssmtype.h for masks.
version |
Returns the version of the CDSA used to generate the key.
See Also:
- init
- (Key*)init;
Be wary with this - this framework tries to preserve the version value for keys, but many other libraries do not (e.g. Apple's own Security framework). In fact, many real world applications provide no indication of such information to start with. Plus, this version number only applies to keys generated by the CDSA, not from other libraries. So, in summary, be wary of using this for anything important, as in a significant number of cases it may not be valid.
Generally the fallback is to the version of the CDSA under which this framework was compiled (2.0 at the time of writing). This fallback behaviour, at least, is fairly consistant across libraries (e.g. Apple's Security framework, again).
wrapAlgorithm |
Returns the algorithm used to wrap the receiver.
- (CSSM_ALGORITHMS)wrapAlgorithm;
See cssmtype.h for algorithms.
wrapMode |
Returns the wrapping mode, if any, of the receiver.
- (CSSM_ENCRYPT_MODE)wrapMode;
You can view a list of known wrapping modes in cssmtype.h.
wrappedKeyUnsafe |
Returns a clear (raw) version of the receiver.
- (Key*)wrappedKeyUnsafe;
You really shouldn't use this function on symmetric or private keys, only public ones. Null wrapping symmetric or private keys is a bad idea, unless you absolutely have to for some amazingly estoric scenario. Try to use wrappedKeyUsingKey: instead.
Note that you cannot wrap a wrapped key.
wrappedKeyUnsafeWithDescription: |
Returns a clear (raw) version of the receiver.
- (Key*)wrappedKeyUnsafeWithDescription:(NSString*)description;
description- A textual description to be attached to the wrapped key. This may or may not come out in the unwrapping. Best not to use it until it's behaviour is properly determined.
You really shouldn't use this function on symmetric or private keys, only public ones. Null wrapping symmetric or private keys is a bad idea, unless you absolutely have to for some amazingly estoric scenario. Try to use wrappedKeyUsingKey: instead.
Note that you cannot wrap a wrapped key.
wrappedKeyUsingKey: |
Returns the receiver wrapped using a symmetric or public key.
See Also:
- wrappedKeyUsingKey:description:
- (Key*)wrappedKeyUsingKey:(Key*)wrappingKey;
wrappingKey- The key to be used to wrap the receiver. This may be a symmetric or a public key.
This method returns a Key that is the receiver wrapped with the key provided. Wrapped keys can be serialized for storage and transmission. If you are storing a key, you should wrap it with a symmetric key you derive from a user provided passphrase, or some other such mechanism. If you are transmitting a key to another location, you can adopt the same approach, although a better one is to wrap the key using a public key.
Note that you cannot wrap a wrapped key.
wrappedKeyUsingKey:description:((Key*), (Key*), (NSString*), (Key*), (Key*), (Key*)) |
Returns the receiver wrapped using a symmetric or public key.
See Also:
- wrappedKeyUsingKey:
- (Key*)wrappedKeyUsingKey:(Key*)wrappingKey;
wrappingKey- The key to be used to wrap the receiver. This may be a symmetric or a public key.
This method returns a Key that is the receiver wrapped with the key provided. Wrapped keys can be serialized for storage and transmission. If you are storing a key, you should wrap it with a symmetric key you derive from a user provided passphrase, or some other such mechanism. If you are transmitting a key to another location, you can adopt the same approach, although a better one is to wrap the key using a public key.
Note that you cannot wrap a wrapped key.
wrappedKeyUsingKey:description:((Key*), (NSString*), (Key*), (Key*), (Key*)) |
Returns the receiver wrapped using a symmetric or public key, with the provided description attached.
- (Key*)wrappedKeyUsingKey:(Key*)wrappingKey description:(NSString*)description;
wrappingKey- The key to be used to wrap the receiver. This may be a symmetric or a public key.
description- A textual description to be associated with the wrapped key. This may or may not have any use, and may not come out in the unwrapping. Until this is tested, it's generally best to stick to the wrappedKeyUsingKey: method.
This method returns a Key that is the receiver wrapped with the key provided. Wrapped keys can be serialized for storage and transmission. If you are storing a key, you should wrap it with a symmetric key you derive from a user provided passphrase, or some other such mechanism. If you are transmitting a key to another location, you can adopt the same approach, although a better one is to wrap the key using a public key.
Note that you cannot wrap a wrapped key.
(Last Updated September 23, 2007)