From The Linux Foundation

OpenSSL Stability Anaysis

A OpenSSL API list was compiled with several criteria from several sources of imperial data:

1) A detailed analysis was performed against the debian etch repository to determine was OpenSSL exported symbols where being used by applications included in etch. Debian etch was not chosen for any reason other than it was readily available, but should be representative of typical open source applications found on most Linux distributions (this statement is based upon a quick survey of current Linux distributions, most where found to be using some version of OpenSSL 0.9.8). We populated a database table with this information.

2) A list of documented OpenSSL APIs was created. Since documentation is a prerequisite for standardization, APIs that are documented already fulfill this requirement and have a higher probability of being used and stable between releases. This list was merged with the symbols actually exported from libssl and libcrypto for the 0.9.8 OpenSSL release in a database table.

3) We used the LSB’s devchk program to determine what APIs have changed within the 0.9.8(-c) releases using the default configure options.

The purpose of this excersize is to determine if there is a pragmatic solution to inclusion of OpenSSL into LSB before the (as yet theoretical) OpenSSL 1.0.0 release. Pragmatic in this context means, 'can we define a set of APIs that have been stable for a large number of OpenSSL releases AND gives a reasonable range of complete functionality for a typical application'. This does not mean that highly sophisticated OpenSSL applications or packages that attempt to provide exhaustive glues or bindings to OpenSSL functionality are considered. Use cases that are considered are driven by 'in the wild' API usage.

Criteria used

1) The APIs within the 1-sigma cut-off for all OpenSSL APIs used by all applications in Debian Etch would be automatically added to the list.

2) APIs that are documented and appear on the ‘used by debian applications list’ with any prevalence and are from the same API family (SSL_*(), EVP_*() etc.) as an API from the first criteria would be automatically added to the list.

3) APIs that are not documented and appear on the ‘used by debian applications list’ with any prevalence and are from the same API family as an API from the first criteria would be subjectively added to the list if the API is obviously necessary to use an API from the first criteria (such as a new or free routine) would be added to the list.

4) APIs that are not documented and appear on the ‘used by debian applications list’ with any prevalence and are from the same API family as an API from the first criteria would be subjectively added to the list if the API has obvious utility for a typical application using the APIs from criteria 1 and it had remained stable with devchk.

5) Structure definitions needed by APIs from the list from critieria 1-5 would be added as opaque types if possible (i.e. LSB applications would only use pointers to these structures and would be expected to not modify them). If an opaque type is not an option (macros that access members) the type’s full definition would be added. Additionally constant values used in macros that call OpenSSL *_ctrl() interface APIs, error codes etc. will be added.

6) APIs from the list complied in 1-5 would then be checked against devchk and if they where not stable would be subjectively considered for removal on instability grounds.

This list is obviously not inclusive of a lot of OpenSSL’s functionality however while including about a 1/3 of the public OpenSSL exports, it supports about 45% of the applications in the 'debian applisions list'.

Potential LSB OpenSSL API subset from criteria

This API subset includes most of the OpenSSL SSL_, EVP_, ERR_, BIO_, RAND_, RSA_, and MD5_ family of interfaces. Functionally this allows applications to make use of SSL, cryptographically strong random numbers, cryptographic signing, hashing, encryption and decryption.

Total number of APIs in subset: 442 out of 1274 (34%)

Debian Application List

Total number of packages having symbol dependencies on a shared libssl or libcrypto: 311

Debian Packages supportable by API subset

Total supportable packages with API subset: 141 out of 311 (45%)

This list does not consider any potential code changes due to opaque typing discussed below.

OpenSSL APIs used by all Debian Applications

Total number of used APIs by all applications: 1274

All OpenSSL APIs

Total number of exported APIs: 1274

All Documented OpenSSL APIs

Total number of documented APIs: 953 out of 1274 (74%)

Stability of the API subset

OpenSSL 0.9.8

The API subset was confirmed with the LSB devchk tool to be stable within OpenSSL versions 0.9.8-0.9.8c (0.9.8c is most current at this time).

OpenSSL 0.9.7

The API was also confirmed to be stable within OpenSSL versions 0.9.7e-0.9.7k (0.9.7k is most current 0.9.7 at this time).

OpenSSL 0.9.7-0.9.8 and opaque typing

OpenSSL exposes many internal details in it structure types, however it is possible in most situations to do useful things with OpenSSL and treat all OpenSSL structure types as opaque types. If most OpenSSL structures are used as opaque types, this API subset is stable from 0.9.7e-0.9.8c. If we leave these structures public, changes in type and size cause ABI incompatibilities between 0.9.7 and 0.9.8 releases (as expected).

The trade off of forcing types to be opaque for LSB applications is that a fairly large set of applications may require some minor to moderate modifications to ensure that OpenSSL types are always treated as opaque (and not allocated on the stack for instance).

However if we cause types to be opaque, we may be reasonable assured of forward compatibility through to version 1.0.0 without significantly hindering OpenSSL development in the meantime.

List of types that need to be opaque this list is provisional, it may be appropriate to include more types, or fewer types, however this set was sufficient to give ABI compatibility between 0.9.7e and 0.9.8c using devchk.

NOTE: Efforts to port a small set of applications with the 'make everything opaque' strategy have revealled a few practical issues. OpenSSL defines many accessor functions as macros that reach into now opaque types. While these macros produce portable code, they do not guarantee ABI stability. Most situations are trivial to convert into functions in the OpenSSL library, however the number and scope of such changes is large.

Additional effort

The subset includes some APIs that are not presently documented, and some APIs that while documented are not sufficiently documented.

Undocumented APIs in the subset

Total undocumented APIs: 54 (12%)

Total documented APIs (including those that may require additional documentation): 387 (87%)