diff options
author | lloyd <[email protected]> | 2006-05-18 18:33:19 +0000 |
---|---|---|
committer | lloyd <[email protected]> | 2006-05-18 18:33:19 +0000 |
commit | a2c99d3270eb73ef2db5704fc54356c6b75096f8 (patch) | |
tree | ad3d6c4fcc8dd0f403f8105598943616246fe172 /doc/porting.txt |
Initial checkin1.5.6
Diffstat (limited to 'doc/porting.txt')
-rw-r--r-- | doc/porting.txt | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/doc/porting.txt b/doc/porting.txt new file mode 100644 index 000000000..48c095837 --- /dev/null +++ b/doc/porting.txt @@ -0,0 +1,144 @@ +* Botan Porting Guide, 1.2.x -> 1.4.x + +This is a guide for how to port your code from 1.2.x to 1.4.x. For the most +part, they are compatible, but there are a few cases that might cause +problems. The externally visible changes are much smaller than 1.0->1.2 changes +were. If you run into something that used to work that doesn't now and isn't +mentioned here, let me know so I can either fix it, or document it here. + +If you can provide a solid reason for 1.4.x to supply backwards-compatible +behavior with something that's mentioned here, I'll consider it, but no +promises. + +* Memory Containers + +The memory containers (SecureBuffer, SecureVector) have been changed to +subclass another object, MemoryRegion (a third subclass, MemoryVector, is just +like SecureVector, except it never locks memory - though it will clear it when +freeing). On it's own, this shouldn't cause any problems, but there are some +cases to be aware of. + +The ptr() function was renamed begin() to match the STL. This is probably the +change most likely to cause problems. + +Various other functions (such as compare) were removed or renamed. The ones +that were removed can be replaced with STL algorithms (for example, compare -> +lexicographical_compare) and the renamed ones were typically renamed to match +the STL. + +SecureBuffer can now be resized, so the second template parameter shouldn't be +considered to be the same as the actual size; it is instead the *initial* size +of the buffer. You can get the current size by calling the size() member +function. While it's possible to modify the size of a SecureBuffer now, don't +do it: it's really confusing, and you should just use a SecureVector instead. + +Second (optional, but a good idea): convert any functions taking a "const +SecureVector<T>&" to "const MemoryRegion<T>&"; this will let them work with +arbitrary memory types; in particular, it will work with a MemoryVector, which +doesn't lock. In fact, the compiler will convert it for you, but this will slow +things down quite a bit (since copying it requires an allocation and a memcpy), +so it's a good idea to do the change. + +* OctetString / SymmetricKey / InitializationVector + +This probably wins the 'most likely to cause compile errors' award. There are +two changes: + +1) copy() was renamed bits_of() + +2) The implicit conversion to byte* was removed. If you were passing it to + another library function as a byte*/u32bit pair, there is probably a version + taking the object directly; use that instead. + + If you were using it for something else, do the following: 1) call bits_of() + and use the returned SecureVector<byte> to get the byte* value, and 2) email + me so I can figure out if what you're doing it worth supporting in the + library (obviously strike this last part if what you're doing is so totally + one-off that nobody would ever need it elsewhere). + +* BigInt::zero() / BigInt::one() + +They were removed. Just use integer constants (0/1) instead; the performance +gain was extremely questionable, and there was lots of special glue to make +sure they worked correctly. + +* ASN.1 decoding + +If something took an X509_Encoding flag before, it probably doesn't +anymore. Some magical heuristics (BER::maybe_BER and PEM_Code::matches) have +been added which can successfully tell if something is PEM or BER/DER encoded +by looking at the data. The heuristics are not perfect (that's why I'm calling +them heuristics), but they work pretty well, and for the most part you would +have to go quite out of your way to fool them (you will be rewarded for your +hard work with an exception, when the decoding fails). + +The places that took it for encoding still do, as the library has no way to +guess which format you want it in. + +* General PK + +PK_Key::check_params() was renamed check_key() to better reflect what +operations are performed. + +* X.509 + +The first two arguments of X509_CA::update_crl (the list of new entries and the +CRL) have been swapped. Now the CRL is the first argument, and the list of +entires is the second. This just seemed a lot more natural. + +CRL_Usage was moved from being a global enumeration to a member of X509_Store, +which makes more sense as that is the only class that uses it. Just replace +CRL_Usage with X509_Store::CRL_Usage, and similarly for any elements of +CRL_Usage (ie, instead of TLS_SERVER, use X509_Store::TLS_SERVER). + +* PKCS #8 + +The PKCS #8 key loading interface has changed significantly in 1.4.0. First, +the versions taking memory objects have been completely removed. While it is, +in fact, quite useful to do this, it's not so useful that it's worth supporting +it in the library (IMO). Just create a DataSource_Memory and pass that to +load_key instead. In fact, here's the code: + +PKCS8_PrivateKey* load_key(const SecureVector<byte>& buffer, + const std::string& pass) + { + DataSource_Memory source(buffer); + return PKCS8::load_key(source, pass); + } + +See, that was easy. :) + +Second, instead of passing a std::string, representing the passphrase, you pass +a User_Interface& object, which a) will not be used if the key isn't encrypted, +and b) will be called as many times as needed until the correct passphrase it +entered (or until the number of tries exceeds the config option +"base/pkcs8_tries", which defaults to 3 (or until the ui object returns +CANCEL_ACTION)). + +The base User_Interface class is pretty brain-dead. The constructor takes an +(optional) passphrase, which it spits back out the first time it's called. The +second time it gets called, it will return CANCEL_ACTION. This behavior is for +compatibility with the old std::string interface (the functions still exist as +forwarding functions, which just create the base UI object and pass it to the +real decoding functions). + +Updating your code to use the new PKCS #8 functions could make things much +nicer in your interface (for example, popping up a dialog box that asks for the +passphrase, but only if the key really is encrypted). There is a GTK+ example +that shows how to do this, check the web page. + +* Public/Private Keys + +This is a pretty big change. Almost all of the PK objects used to have a +constructor taking a DataSource&, from which it would read the key. However, +this was a poor design, because if you guess incorrectly as to what kind of key +was in use, bad stuff would happen. So basically it was impossible to use +safely. In addition, it was rather complex to support. + +Use {X509,PKCS8}::load_key and dynamic_cast<> instead. It's a bit more code, +but it's worth it for the flexibility and better error handling. If you really +want something like the constructors, you can look at the try_load functions in +1.2.x's pkcs8.cpp and x509_key.cpp to see how they did it (you won't get the +same exact effect, since you can't add a constructor, but you can do something +that looks fairly similar). + |