Importing the library - ivan-zaera/cipher GitHub Wiki

The library consists of two parts: the API and the implementation. Although the imports may be tuned to suit your application needs, there is a canonical way to do it which has three flavours depending on whether you want to use cipher in the server side, in the client side, or independent of server and client (runnable in both environments).

This is because some algorithms use server or client specific APIs and, thus, may not be run in both environments. It is, for instance, the case of the entropy source that reads from /dev/random which, of course, cannot be run in a browser.

To overcome this problem, cipher's implementation is divided in three libraries: one that is environment independent, and two more for the client and server environments. Both the client and server implementations take care of initialization of the independent library, so there's no need to bother with that one.

Regarding the API, all of it is platform independent. There's one more piece to the puzzle: the initialization parameter classes for the out-of-the-box provided algorithms. This classes are part of the implementation (because they are tied to the available algorithms), but are usually included with the API to make them easier to use.

In reality the parameter classes are somewhere between the API and the implementations. Cipher's API is just an abstract specification but to make it usable we provide a set of implementations included in cipher. You could, for instance, use another implementation if you wish or even make your own that still uses cipher's spec but resorts to, for example, native implementations. Thus, you need the parameter classes to make use of the out-of-the-box implementations but, if you decided to use other spec implementation, it could be the case that the parameter classes provided with cipher don't need to be used. That's why parameter classes are not part of the spec API, but the API of the out-of-the-box implementations provided with cipher. I hope this makes sense (if not, ask for clarification ;-)).

So, to sum up: how would you go including cipher in your project? Let's see it:

• Using cipher client side

  • You must include cipher's API and parameter classes in all your project's libraries where you use cipher:

    ```import "package:cipher/cipher.dart";```
    

  • You must include the implementation in all your entry points so you are able to load the implementations:

    ```import "package:cipher/impl/client.dart";```
    

  • Before you use any of the classes, you must initialize the library in all your entry points. You do that calling the initCipher() method:

    initCipher();
    

• Using cipher server side

  • You must include cipher's API and parameter classes in all your project's libraries where you use cipher:

    ```import "package:cipher/cipher.dart";```
    

  • You must include the implementation in your entry point so you are able to load the implementations:

    ```import "package:cipher/impl/server.dart";```
    

  • Before you use any of the classes, you must initialize the library in your entry point. You do that calling initCipher() method:

    initCipher();
    

That's it :-).

NOTE: In versions prior to 0.5.1 you could import each one separately (API and implementation) or both at the same time but it is not the case any more.