-
Notifications
You must be signed in to change notification settings - Fork 22
The Low Level Interface
Botan has two different interfaces. The one documented in this section is meant more for implementing higher-level types (see the section on filters, earlier in this manual) than for use by applications. Using it safely requires a solid knowledge of encryption techniques and best practices, so unless you know, for example, what CBC mode and nonces are, and why PKCS #1 padding is important, you should avoid this interface in favor of something working at a higher level.
There are a small handful of functions implemented by most of Botan's algorithm objects. Among these are:
@property string name()
Returns a human-readable string of the name of this
algorithm. Examples of names returned are "AES-128" and
"HMAC(SHA-512)". You can turn names back into algorithm objects using
the functions in botan.libstate.lookup
.
void clear()
Clear out the algorithm's internal state. A block cipher object will "forget" its key, a hash function will "forget" any data put into it, etc. The object will look and behave as it did when you initially allocated it.
T clone()
This function is central to Botan's name-based interface. The
clone
has many different return types, such as BlockCipher
and HashFunction
, depending on what kind of object it is called
on. Note that unlike Java's clone, this returns a new object in a
"pristine" state; that is, operations done on the initial object
before calling clone
do not affect the initial state of the new
clone.
Cloned objects should be stored in a Unique!
or a scoped!
object
to minimize GC collection cycles.
Both symmetric keys and initialization values can be considered byte
(or octet) strings. These are represented by class OctetString
, also
known as SymmetricKey
and InitializationVector
, when you want to
express intent.
this(RandomNumberGenerator rng, size_t length);
This constructor creates a new random key length bytes long using the random number generator.
this(string str);
The argument str is assumed to be a hex string; it is converted to binary and stored. Whitespace is ignored.
this(in byte* input, size_t length);
This constructor copies its input.
string toString() const
Returns the hex representation of the key or IV
Block ciphers, stream ciphers, and MACs are all keyed operations; to be useful, they have to be set to use a particular key, which is a randomly chosen string of bits of a specified length. The length required by any particular algorithm may vary, depending on both the algorithm specification and the implementation. You can query any botan object to find out what key length(s) it supports.
To make this similarity in terms of keying explicit, all algorithms of
those types are derived from the SymmetricAlgorithm
base class.
This type provides functions for setting the key, and querying
restrictions on the size of the key.
void setKey(in ubyte* key, size_t length);
void setKey(in SymmetricKey key);
This sets the key to the value specified. Most algorithms only
accept keys of certain lengths. If you attempt to call
setKey
with a key length that is not supported, the
exception InvalidKeyLength
will be thrown.
In all cases, setKey
must be called on an object before any
data processing (encryption, decryption, etc) is done by that
object. If this is not done, the results are undefined.
bool validKeylength(size_t length) const
This function returns true if and only if length
is a valid
keylength for the algorithm.
size_t minimumKeylength() const
Return the smallest key length (in bytes) that is acceptable for the algorithm.
size_t maximumKeylength() const
Return the largest key length (in bytes) that is acceptable for the algorithm
All block ciphers classes in botan are subclasses of BlockCipher
,
which subclasses the SymmetricAlgorithm
interface.
@property size_t blockSize() const
Returns the block size of the cipher in bytes
void encryptN(in ubyte* input, ubyte* output, size_t n) const
Encrypt n
blocks of data, taking the input from the array input
and placing the ciphertext into output
. The two pointers may be
identical, but should not overlap ranges.
void encrypt(in ubyte* input, ubyte* output) const
Encrypt a single block, taking the input from input
and placing
it in output
. Acts like a call to encryptN(input, output, 1)
.
void encrypt(ubyte* block) const
Identical to encrypt
(block, block)
void decryptN(in ubyte* input, ubyte output, size_t n) const
Decrypt n blocks of data, taking the input from in and placing the plaintext in out. The two pointers may be identical, but should not overlap ranges.
void decrypt(in ubyte* input, ubyte* output) const
Decrypt a single block, taking the input from input
and placing it
in output
. Acts like a call to decryptN(input, output, 1)
.
void decrypt(ubyte* block) const
Identical to decrypt
(block, block)
@property size_t parallelism() const
Returns the native parallelism of this implementation, ie how
many blocks can be processed in parallel if sufficient data is
passed to encryptN
or decryptN
.
Stream ciphers are somewhat different from block ciphers, in that encrypting data results in changing the internal state of the cipher. Also, you may encrypt any length of data in one go (in byte amounts).
void encrypt(const ubyte* input, ubyte* output, size_t length);
void encrypt(ubyte* data, size_t length);
Stream ciphers implement the SymmetricAlgorithm
interface.
Hash functions take their input without producing any output, only
producing anything when all input has already taken place. MACs are
very similar, but are additionally keyed. Both of these are derived
from the base class BufferedComputation
, which has the following
functions.
size_t outputLength()
Return the size of the output of this function.
void update(in ubyte* input, size_t length);
void update(ubyte input);
void update(in string input);
Updates the hash/mac calculation with input
.
void flush(ubyte* output);
SecureVector!ubyte flush();
Complete the hash/MAC calculation and place the result into output
.
For the argument taking an array, exactly outputLength
bytes will
be written. After you call flush
, the hash function is reset to
its initial state, so it may be reused immediately.
The second method of using final is to call it with no arguments at all, as shown in the second prototype. It will return the hash/mac value in a memory buffer.
There is also a pair of functions called process
. They are a
combination of a single update
, and flush
. Both versions
return the final value, rather than placing it an array. Calling
process
with a single byte value isn't available, mostly because
it would rarely be useful.
A MAC can be viewed (in most cases) as a keyed hash function, so
classes that are derived from MessageAuthenticationCode
have
update
and flush
classes just like a HashFunction
(and
like a HashFunction
, after flush
is called, it can be used to
make a new MAC right away; the key is kept around).
A MAC has the SymmetricAlgorithm
interface in addition to the
BufferedComputation
interface.
Checksums are very similar to hash functions, and in fact share the same interface. But there are some significant differences, the major ones being that the output size is very small (usually in the range of 2 to 4 bytes), and is not cryptographically secure. But for their intended purpose (error checking), they perform very well. Some examples of checksums included in Botan are the Adler32 and CRC32 checksums.