Added cipher acceleration to SILC Accelerator. Added cipher softacc.

[crypto.git] / lib / silcacc / silcacc.h

diff --git a/lib/silcacc/silcacc.h b/lib/silcacc/silcacc.h
index ea97437ae8ea3150a7ce0caa089ea543cd069303..040f1c692a8999ffde8e73679d9c92fc32ea1863 100644 (file)
--- a/lib/silcacc/silcacc.h
+++ b/lib/silcacc/silcacc.h
@@ -4,7 +4,7 @@
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 2007 Pekka Riikonen
+  Copyright (C) 2007 - 2008 Pekka Riikonen
 
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
@@ -17,16 +17,28 @@
 
 */
 
-/****h* silcskr/SILC Accelerator Interface
+/****h* silcacc/Crypto Accelerator Interface
  *
  * DESCRIPTION
  *
+ * SILC Crypto Accelerator Interface provides a generic interface for
+ * cryptographic accelerators.  The interface can access different kind of
+ * accelerators, such as hardware accelerators.  Using an accelerator can
+ * significantly improve encryption, decryption, signature and verification
+ * performance.
+ *
+ * Third-party accelerators can be registered into the accelerator interface
+ * and used through the same generic interface.
+ *
+ * The interface can be used to accelerate public and private keys, and
+ * ciphers.
+ *
  ***/
 
 #ifndef SILCACC_H
 #define SILCACC_H
 
-/****s* silcacc/SilcAccAPI/SilcAccelerator
+/****s* silcacc/SilcAccelerator
  *
  * NAME
  *
@@ -47,16 +59,16 @@ typedef struct SilcAcceleratorObject {
                   va_list va);             /* Initialize accelerator */
   SilcBool (*uninit)(void);                /* Uninitialize accelerator */
   const SilcPKCSAlgorithm *pkcs;            /* Accelerated PKCS algorithms */
+  const SilcCipherObject *cipher;          /* Accelerated ciphers */
 #if 0
   const SilcDHObject *dh;                   /* Accelerated Diffie-Hellmans */
-  const SilcCipherObject *cipher;          /* Accelerated ciphers */
   const SilcHashObject *hash;              /* Accelerated hashes */
   const SilcHmacObject *hmac;              /* Accelerated HMACs */
   const SilcRngObject *rng;                /* Accelerated RNG's */
 #endif /* 0 */
 } *SilcAccelerator, SilcAcceleratorStruct;
 
-/****f* silcacc/SilcAccAPI/silc_acc_register
+/****f* silcacc/silc_acc_register
  *
  * SYNOPSIS
  *
@@ -76,7 +88,7 @@ typedef struct SilcAcceleratorObject {
  ***/
 SilcBool silc_acc_register(const SilcAccelerator acc);
 
-/****f* silcacc/SilcAccAPI/silc_acc_unregister
+/****f* silcacc/silc_acc_unregister
  *
  * SYNOPSIS
  *
@@ -90,7 +102,7 @@ SilcBool silc_acc_register(const SilcAccelerator acc);
  ***/
 void silc_acc_unregister(SilcAccelerator acc);
 
-/****f* silcacc/SilcAccAPI/silc_acc_find
+/****f* silcacc/silc_acc_find
  *
  * SYNOPSIS
  *
@@ -104,7 +116,7 @@ void silc_acc_unregister(SilcAccelerator acc);
  ***/
 SilcAccelerator silc_acc_find(const char *name);
 
-/****f* silcacc/SilcAccAPI/silc_acc_init
+/****f* silcacc/silc_acc_init
  *
  * SYNOPSIS
  *
@@ -126,7 +138,7 @@ SilcAccelerator silc_acc_find(const char *name);
  ***/
 SilcBool silc_acc_init(SilcAccelerator acc, SilcSchedule schedule, ...);
 
-/****f* silcacc/SilcAccAPI/silc_acc_uninit
+/****f* silcacc/silc_acc_uninit
  *
  * SYNOPSIS
  *
@@ -142,7 +154,7 @@ SilcBool silc_acc_init(SilcAccelerator acc, SilcSchedule schedule, ...);
  ***/
 SilcBool silc_acc_uninit(SilcAccelerator acc);
 
-/****f* silcacc/SilcAccAPI/silc_acc_get_supported
+/****f* silcacc/silc_acc_get_supported
  *
  * SYNOPSIS
  *
@@ -156,7 +168,7 @@ SilcBool silc_acc_uninit(SilcAccelerator acc);
  ***/
 SilcDList silc_acc_get_supported(void);
 
-/****f* silcacc/SilcAccAPI/silc_acc_get_name
+/****f* silcacc/silc_acc_get_name
  *
  * SYNOPSIS
  *
@@ -169,7 +181,7 @@ SilcDList silc_acc_get_supported(void);
  ***/
 const char *silc_acc_get_name(SilcAccelerator acc);
 
-/****f* silcacc/SilcAccAPI/silc_acc_public_key
+/****f* silcacc/silc_acc_public_key
  *
  * SYNOPSIS
  *
@@ -188,11 +200,15 @@ const char *silc_acc_get_name(SilcAccelerator acc);
  *    The associated `public_key' can be retrieved from the returned
  *    public key by calling silc_acc_get_public_key.
  *
+ *    If this returns NULL the public key could not be accelerated.  This
+ *    usually should not be considered serious error.  Instead, the public
+ *    key should be used without acceleration.
+ *
  ***/
 SilcPublicKey silc_acc_public_key(SilcAccelerator acc,
                                  SilcPublicKey public_key);
 
-/****f* silcacc/SilcAccAPI/silc_acc_private_key
+/****f* silcacc/silc_acc_private_key
  *
  * SYNOPSIS
  *
@@ -211,11 +227,15 @@ SilcPublicKey silc_acc_public_key(SilcAccelerator acc,
  *    The associated `private_key' can be retrieved from the returned
  *    private key by calling silc_acc_get_private_key.
  *
+ *    If this returns NULL the private key could not be accelerated.  This
+ *    usually should not be considered serious error.  Instead, the private
+ *    key should be used without acceleration.
+ *
  ***/
 SilcPrivateKey silc_acc_private_key(SilcAccelerator acc,
                                    SilcPrivateKey private_key);
 
-/****f* silcacc/SilcAccAPI/silc_acc_get_public_key
+/****f* silcacc/silc_acc_get_public_key
  *
  * SYNOPSIS
  *
@@ -232,7 +252,7 @@ SilcPrivateKey silc_acc_private_key(SilcAccelerator acc,
 SilcPublicKey silc_acc_get_public_key(SilcAccelerator acc,
                                      SilcPublicKey public_key);
 
-/****f* silcacc/SilcAccAPI/silc_acc_get_private_key
+/****f* silcacc/silc_acc_get_private_key
  *
  * SYNOPSIS
  *
@@ -249,4 +269,45 @@ SilcPublicKey silc_acc_get_public_key(SilcAccelerator acc,
 SilcPrivateKey silc_acc_get_private_key(SilcAccelerator acc,
                                        SilcPrivateKey private_key);
 
+/****f* silcacc/silc_acc_cipher
+ *
+ * SYNOPSIS
+ *
+ *    SilcCipher silc_acc_cipher(SilcAccelerator acc, SilcCipher cipher);
+ *
+ * DESCRIPTION
+ *
+ *    Accelerate the cipher indicated by `cipher'.  Returns new accelerated
+ *    SilcCipher context.  It can be used just as normal cipher and must be
+ *    freed by calilng silc_cipher_free.  The associated `cipher' is not
+ *    freed when the accelerated cipher is freed.  The `cipher' must not be
+ *    freed as long as it is accelerated.
+ *
+ *    When key and IV is set for the accelerated cipher, it is also set to
+ *    the associated cipher.
+ *
+ *    The associated `cipher' can be retrieved from the accelerated cipher
+ *    by calling silc_acc_get_cipher.
+ *
+ *    If this returns NULL the cipher could not be accelerated.  This
+ *    usually should not be considered serious error.  Instead, the cipher
+ *    should be used without acceleration.
+ *
+ ***/
+SilcCipher silc_acc_cipher(SilcAccelerator acc, SilcCipher cipher);
+
+/****f* silcacc/silc_acc_get_cipher
+ *
+ * SYNOPSIS
+ *
+ *    SilcCipher silc_acc_get_cipher(SilcAccelerator acc, SilcCipher cipher);
+ *
+ * DESCRIPTION
+ *
+ *    Returns the underlaying cipher from the accelerated cipher indicated
+ *    by `cipher'.  Returns NULL if `cipher' is not accelerated cipher.
+ *
+ ***/
+SilcCipher silc_acc_get_cipher(SilcAccelerator acc, SilcCipher cipher);
+
 #endif /* SILCACC_H */