Functions specific to Scality backends. More...

Functions
void	dpl_scal_gc_gen_key (BIGNUM *id, int cl)
	Generate a GC key. More...

dpl_status_t	dpl_scal_gc_index_init (dpl_dbuf_t **indexp)
	Creates and initialises a new dbuf which can be used to create a GC index. More...

dpl_status_t	dpl_scal_gc_index_serialize (BIGNUM chunkkey, uint64_t offset, uint64_t size, dpl_dbuf_t buffer)
	Add an object ID to a GC index. More...

dpl_status_t	dpl_uks_gen_key_raw (BIGNUM *id, uint32_t hash, uint64_t oid, uint32_t volid, uint8_t serviceid, uint32_t specific)
	Generate a UKS key from raw data. More...

dpl_status_t	dpl_uks_gen_key_ext (BIGNUM *id, dpl_uks_mask_t mask, uint64_t oid, uint32_t volid, uint8_t serviceid, uint32_t specific)
	Set some fields in a binary UKS key. More...

dpl_status_t	dpl_uks_gen_key (BIGNUM *id, uint64_t oid, uint32_t volid, uint8_t serviceid, uint32_t specific)
	Generate a binary UKS key. More...

dpl_status_t	dpl_uks_set_class (BIGNUM *k, int cl)
	Set the class field in a UKS key. More...

dpl_status_t	dpl_uks_set_replica (BIGNUM *k, int replica)
	Set the replica field in a UKS key. More...

dpl_status_t	dpl_uks_bn2hex (const BIGNUM id, char id_str)
	Convert a binary UKS key to string form. More...

Detailed Description

This module contains utility functions for dealing with the Scality backend cloud provider.

Several of these functions deal with Scality's UKS (Universal Key Scheme) which is the binary object ID format used in Scality's RING software. UKS keys are 160 bits long and are divided into several fixed-length fields which encode specific information. Fields include:

hashing/dispersion (24b) used to help distribute objects around multiple servers in a ring, normally an MD5 hash of the payload field.

payload (128b) Further information, broken out below.

class (4b). Classes from 0-5 specify the number of additional copies to be stored, i.e. class 2 means 3 copies will be stored. Some of the class numbers 6-15 are used for other purposes.

replica (4b). The replica number for classes 0-5, i.e. 0 for the first copy, 1 for the second copy.

You can store anything you like in the payload field, but a recommended format is to use the following bit fields.

Object ID (64b). Identifies an object, e.g. an inode number.

Volume ID (32b). Identifies a virtual volume, e.g. a filesystem.

Application ID (8b). Also known as Service ID. A fixed field identifying your application, to allow multiple applications to use the same RING storage. To avoid clashing with future Scality software, use a number greater than 0xc0.

Application Specific (24b), e.g. block offset within the file.

Function Documentation

void dpl_scal_gc_gen_key	(	BIGNUM *	id,
		int	cl
	)

Generates into id a special UKS key which does not refer to an actual object but which can be used to invoke the Scality GC service. The object ID is stored in a BIGNUM structure, which you should create with BN_new() and free with BN_free().

To delete multiple objects in a single protocol call, use this GC key as the id parameter of a dpl_put_id() call, and pass the contents of a GC index as the PUT data. See dpl_scal_gc_index_init() for details on how to create a GC index.

Parameters

[out]	id	the UKS key is returned here
	cl	the UKS class (e.g. 2)

dpl_status_t dpl_scal_gc_index_init ( dpl_dbuf_t ** indexp )

GC indexes are effectively a list of object IDs and can be used to delete multiple objects in a single API call. Individual object IDs can be added to the GC index by calling dpl_scal_gc_index_serialize().

You should free the dbuf using dpl_dbuf_free() when you have finished using it.

Parameters

[out] indexp on success, a new dbuf is returned here

Return values

DPL_SUCCESS	on success, or
DPL_*	a Droplet error code on failure

dpl_status_t dpl_scal_gc_index_serialize	(	BIGNUM *	chunkkey,
		uint64_t	offset,
		uint64_t	size,
		dpl_dbuf_t *	buffer
	)

Adds an object ID to a GC index. The GC index buffer should have been created using dpl_scal_gc_index_init(), the object ID chunkkey using dpl_uks_gen_key().

If this function returns failure, the GC index cannot be used and you should free it immediately using dpl_dbuf_free().

If the object is a part of a logical file at some higher level of abstraction, you may pass the byte range of the object within that logical file as offset and size, but this is not necessary.

Parameters

chunkkey	the binary UKS key to add, may not be NULL
offset	byte offset in some logical file (optional)
size	byte size in some logical file (optional)
buffer	the dbuf in which the GC index is being built, may not be NULL

Return values

DPL_SUCCESS	on success, or
DPL_*	a Droplet error code on failure

dpl_status_t dpl_uks_bn2hex	(	const BIGNUM *	id,
		char *	id_str
	)

Converts the binary UKS key in id to a string form in id_str. The string form is suitable for use as the id parameter of the RESTful functions such as dpl_put_id(). The binary key id is stored in a BIGNUM structure, which you should create with BN_new() and free with BN_free().

Parameters

	id	the binary UKS key
[out]	id_str	on success the string form is written here, must be at least `DPL_UKS_BCH_LEN+1` bytes long

Return values

DPL_SUCCESS	on success, or
DPL_*	a Droplet error code on failure

dpl_status_t dpl_uks_gen_key	(	BIGNUM *	id,
		uint64_t	oid,
		uint32_t	volid,
		uint8_t	serviceid,
		uint32_t	specific
	)

Sets all the fields in a binary UKS key and automatically calculates the hashing/dispersion field. You should also call dpl_uks_set_class() to set the class field. The binary key id is stored in a BIGNUM structure, which you should create with BN_new() and free with BN_free().

Parameters

id	the binary UKS key
oid	will be used as the Object ID field
volid	will be used as the Volume ID field
serviceid	will be used as the Service ID field
specific	will be used as the Application Specific field

Return values

DPL_SUCCESS	on success, or
DPL_*	a Droplet error code on failure

dpl_status_t dpl_uks_gen_key_ext	(	BIGNUM *	id,
		dpl_uks_mask_t	mask,
		uint64_t	oid,
		uint32_t	volid,
		uint8_t	serviceid,
		uint32_t	specific
	)

Sets some fields in a binary UKS key, according to a mask of which fields to set. Fields not specified in the mask are preserved. Automatically recalculates the hashing/dispersion field. You should also call dpl_uks_set_class() to set the class field. The binary key id is stored in a BIGNUM structure, which you should create with BN_new() and free with BN_free().

Parameters

id	the binary UKS key
mask	a bitmask of the following values indicating which fields to set `DPL_UKS_MASK_OID` use the oid parameter as the Object ID field `DPL_UKS_MASK_VOLID` use the volid parameter as the Volume ID field `DPL_UKS_MASK_SERVICEID` use the parameter as the Service ID field `DPL_UKS_MASK_SPECIFIC` use the parameter as the Application Specific field.
oid	will be used as the Object ID field if `DPL_UKS_MASK_OID` is present in mask
volid	will be used as the Volume ID field if `DPL_UKS_MASK_VOLID` is present in mask
serviceid	will be used as the Service ID field if `DPL_UKS_MASK_SERVICEID` is present in mask
specific	will be used as the Application Specific field if `DPL_UKS_MASK_SPECIFIC` is present in mask

Return values

DPL_SUCCESS	on success, or
DPL_*	a Droplet error code on failure

dpl_status_t dpl_uks_gen_key_raw	(	BIGNUM *	id,
		uint32_t	hash,
		uint64_t	oid,
		uint32_t	volid,
		uint8_t	serviceid,
		uint32_t	specific
	)

Generates a binary UKS key in id using raw data for each of the bitfields in the generic format. Note the class and replica fields should be set separately using dpl_uks_set_class() and dpl_uks_set_replica(). The binary key id is stored in a BIGNUM structure, which you should create with BN_new() and free with BN_free().

Only use this function if you know what you are doing. Note particularly that this function requires you to calculate and set the hashing/dispersion field yourself. For most applications you should use either dpl_uks_gen_key_ext() or dpl_uks_gen_key() which will calculate the hashing/dispersion field for you.

Parameters

id	the binary UKS key will be generated here
hash	will be used as the hashing/dispersion field
oid	will be used as the Object ID field
volid	will be used as the Volume ID field
serviceid	will be used as the Service ID field
specific	will be used as the Application Specific field

Return values

DPL_SUCCESS this function currently cannot fail

dpl_status_t dpl_uks_set_class	(	BIGNUM *	k,
		int	cl
	)

Set the class field in a UKS key. The binary key id is stored in a BIGNUM structure, which you should create with BN_new() and free with BN_free().

Parameters

k	the binary UKS key
cl	will be used as the class field

Return values

DPL_SUCCESS	on success, or
DPL_*	a Droplet error code on failure

dpl_status_t dpl_uks_set_replica	(	BIGNUM *	k,
		int	replica
	)

Set the replica field in a UKS key. The binary key id is stored in a BIGNUM structure, which you should create with BN_new() and free with BN_free().

Parameters

k	the binary UKS key
replica	will be used as the replica field

Return values

DPL_SUCCESS	on success, or
DPL_*	a Droplet error code on failure