diff options
| -rw-r--r-- | doc/porting.txt | 144 |
1 files changed, 0 insertions, 144 deletions
diff --git a/doc/porting.txt b/doc/porting.txt deleted file mode 100644 index 48c095837..000000000 --- a/doc/porting.txt +++ /dev/null @@ -1,144 +0,0 @@ -* 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). - |