readme.api

linux for amd development lx8

----------------------------
USING THE GEODEAES INTERFACE
----------------------------
User applications can communicate with the AES engine through a series of 
ioctl() calls as detailed below:


* ALLOCATING A SESSION
All AES operations happen against a set session. 


struct geode_crypt_session {
	unsigned int  flags;
	unsigned int  blocksize;
	unsigned char key[CRYPTO_KEY_LEN];
	int id;
};

* Flags is a bitmask of the following options:

CRYPTO_SESSION_HWKEY      
Specify that the session should use the hardware key from the EEPROM.
Default is off

CRYPTO_SESSION_ECB
Indicates that this session should use the ECB mode of encryption

CRYPTO_SESSION_CBC
Indicates that this session should use the CBC mode of encryption.  These
two modes cannot be defined at the same time.

CRYPTO_SESSION_NOCOHERENCY
Indicates that you should not use cache coherency when doing this operation.
Default is to turn caching off on the pages being operated on.

* Blocksize is the size of the block (from 16 to 3MB allowed)
* key is an array of 16 bytes that should hold the hex equivelent of the
key (if HWKEY is set, this field is ignored).

* id should be zero going in.

Specify a new session by calling the ioctl:

ioctl(fd, SIOCGSESSION, &session);

The session id is returned in the id member.

* PERFORMING AN OPERATION

To perform a particular encryption/decryption operation, the following 
structure is used:

struct geode_crypt_op {
	int id;
	unsigned int  flags;
	unsigned int  len;

	void *src;
	void *dst;
	void *iv;
};

* id - the session id as allocated above
* flags - either CRYPTO_FLAG_DECRYPT or CRYPTO_FLAG_ENCRYPT
* len - the length of the operation (not nessesarly the blocksize indicated 
in the session).

* src,dst - the sorce and destination pointers of the data.  These must be
non null and big enough to hold the block size.

* iv - an optional initalization vector used in CBC mode.  If it is null,
* then it is ignored.

Call an operation with the following:

ioctl(fd, SIOCCRYPT, &op);

Any number of operations can be called on a single session.

* SETTING A NEW KEY ON THE SESSION
to change the key of a session, use the following:

struct geode_crypt_key {
        int id;
	unsigned char key[CRYPTO_KEY_LEN];
};

ioctl(fd, CIOSKEY, &key);

* FREEING A SESSION
When you are done with a session, free it with following
ioctl(fd, CIOFSESSION, session.id);