NAME

xslm_install_certificate

SYNOPSIS

#include <libxslm.h>

xslm_uint32 xslm_install_certificate(
    xslm_uuid       server_id,
    xslm_uint32     certificate_length,
    xslm_cert_t     * certificate,
    xslm_uint32     * annotation_length,
    xslm_string     * annotation,
    xslm_uint32     data_element_error_offset,
    xslm_uint32     value_error_offset,
    xslm_uint32     * status,
    xslm_uint32     auth_token,
    xslm_bin_string * auth_signature,
    xslm_uuid       * auth_lic_sys_id
);

DESCRIPTION

xslm_install_certificate() installs a certificate into a license server. The certificate is installed only when all of the following are true: the certificate structure is valid; all the certificate values are valid; this specific certificate is not already installed; except for publisher-specific data elements, all other certificate functions are supported by the server; the certificate has a valid digital signature.

INPUT PARAMETERS

server_id

Identification of server to which this request is being directed.

certificate_length

Length of the certificate structure to be installed.

certificate

The certificate structure to be installed.

annotation

Arbitrary textual data to be maintained together with the certificate.

auth_token

A 32-bit arbitrary value created by the application and used as part of the licensing system authentication process. See Process Description for more information.

INPUT/OUTPUT PARAMETERS

annotation_length

Length in bytes of the annotation data. Specify a value of 0 to indicate that no annotation data should be saved. A licensing server must support a length of at least 4,096 bytes, but may support any length longer than this. If the actual value passed in this parameter exceeds the maximum value the licensing server will reject the certificate installation request, and will place in this field the maximum value it can accept.

OUTPUT PARAMETERS

data_element_error_offset

Offset from the start of the certificate structure to the certificate data element where the license server detected the error reported with the status value.

value_error_offset

Offset from the start of the certificate data element to the value where the license server detected the error value reported with the status value. Note that a null value indicates that the data element itself is in error rather than the values which follow the data element.

status

Completion status. Detailed error code directly addressable by the caller. This value is set of XSLM_OK if no error occurred. For other messages, see ERRORS.

auth_signature

An area large enough to contain a 16-byte digital signature created by the licensing system from the input parameters and auth_token. Used as part of the licensing system authentication process.

auth_lic_sys_id

A unique identifier for the particular type of licensing system handling the current license instance. Used as part of the licensing system authentication process.

RETURN VALUE

XSLM_OK

Query completed successfully

XSLM_COMM_ERR

Communications problem

XSLM_CERT_ERR

Problems with the license and/or certificate

XSLM_RESRC_UNAVL

Resources unavailable

XSLM_PARM_ERR

Bad parameters passed

XLSM_AUTH_ERROR

Requester is not authorized

PROGRAMMING NOTE

The xslm_install_certificate() call requests the license server to install the license certificate being passed on the call. For a select set of XSLM_CERT_ERR errors, the license server will return the value of the offset from the beginning of the certificate to the first data element whose associated value represents an invalid value, a certificate structure problem, or a function that is not supported by this license server.

ERRORS

The function return value gives an overall indication of the success or failure of the call. In addition, the status parameter will be set to one of the following values, to further help point to the reason for a failed request.

Note:

In the future, additional values may be defined for the status variable. An application must not rely upon these being the only possible values.

Return Value	Status Value	Explanation
XSLM_OK	XSLM_STATUS_OK	No errors occurred. Certificate installed
XSLM_COMM_ERR	XSLM_COMM_UNAVAIL	Communications problem
XSLM_CERT_ERR	XSLM_INVALID_STRUCTURE	Invalid certificate structure encountered
	XSLM_INVALID_VALUES	Invalid certificate value encountered
	XSLM_CERT_VALIDITY_FAILURE	Certificate validity check failed. Certificate content is different to that provided by the license certificate issuer.
	XSLM_DUPLICATE_CERT	License certificate already installed on license server
	XSLM_CERT_NOT_SUPPORTED	License certificate not supported by license server
XSM_RESRC_UNAVAIL	XSLM_NO_RES	Local platform specific environmental problems
	XSLM_SERVER_ERROR	Unrecoverable environmental error was encountered by the license server
XSLM_PARM_ERR	XSLM_BAD_PARM	One or more parameters were not correct
	XSLM_BAD_BUFFER_LENGTH	The value specified for annotation_length exceeds the maximum value the server can support
	XSLM_BAD_SERVER_ID	The server_id specified does not correspond to a known server
XSLM_AUTH_ERROR	XSLM_NOT_AUTHORIZED	The requester is not authorized to perform the requested action

SEE ALSO

xslm_get_certificate(), xslm_remove_certificate().