Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
OpenXPKI::Server::API:UserrContributed PerlOpenXPKI::Server::API::Smartcard(3)


       This API	handles	Smartcard specific calls.

Public functions
       This function accepts a list of certificates and	passes them to
       "sc_analyze_certificate". The result is an array	ref of the result hash
       of this funtion.

       Named function parameters

       o       CERTS (mandatory)

	       This parameter is a list	of certificates	as read	from the card.

       o       CERTFORMAT (mandatory)

	       see sc_analyze_certificate

       This API	function can be	called by an OpenXPKI client in	order to get
       information on a	certificate.  FIXME: Contains no SC specific info -
       can be moved to Object API

       Named function parameters

       o       DATA (mandatory)

	       The raw data of the certificate

       o       CERTFORMAT (mandatory)

	       Supported formats for the CERTS parameter are
	       DER|PEM|BASE64|IDENTIFIER.  BASE64 will accept degraded formats
	       (i. e. data without whitespace or padding).  If IDENTIFIER is
	       selected, the function will retrieve the	specified certificate
	       from the	database and analyze it.

       o       DONTPARSE: 1 (optional)

	       Only acceptable for cert	format 'IDENTIFIER'. If	set, the
	       certificate fetched from	the database will not be parsed, but
	       only the	cert information from the database (CSR	and
	       CERTIFICATE table entries) will be propagated.

       Function	results

       The function will return	a hash reference containing the	detailed
       information about the passed certificate	with following structure (not
       all entries may be set):


       o       IDENTIFIER

       o       PKI_REALM

       o       SUBJECT

       o       ISSUER_DN

       o       ISSUER_IDENTIFIER

       o       EMAIL

       o       PUBKEY



       o       NOTBEFORE

	       Seconds since Epoch

       o       NOTBEFORE_ISO

	       NotBefore date in ISO format

       o       NOTAFTER

	       Seconds since Epoch

       o       NOTAFTER_ISO

	       NotAfter	date in	ISO format

       o       STATUS

       o       PROFILE

       This API	function can be	called by an OpenXPKI client in	order to
       analyze the state of a given Smartcard.

       Named function parameters

       o       SMARTCARDID (mandatory)

	       This parameter shall be set to the Smartcard serial number as
	       read from the card. The API function will query this serial
	       number from the associated directory or repository and
	       determine the designated	owner of the card.

	       The parameter format is defined in the Smartcard	Interfaces

       o       SMARTCHIPID (optional)

	       The hardware chip id of the card. Should	be set if available by
	       the card	driver as it can prevent card forgery.

       o       USERID (optional)

	       If available, the user id of the	currently logged in user
	       should be supplied by the caller. This may be different from
	       the actual Smartcard holder.

       o       CERTS (optional)

	       see sc_parse_certificates

       o       CERTFORMAT (mandatory if	CERTS is given)

	       see sc_parse_certificates

       o       WORKFLOW_TYPES (optional)

	       This parameter is a list	of workflow type names to be queried.
	       If specified, the analyze function will search for existing
	       workflows of the	specified types	that are owned by the holder
	       of the Smartcard	of SMARTCARDID.

	       This is merely a	convenience function that simply wraps the
	       search_workflow_instances API function.

       Function	results

       The function will return	a complex data structure containing the
       results of the Smartcard	analysis.

       These results are directly influenced by

       o       internal	status of the PKI database (e. g. existing
	       certificates for	the user)

       o       external	resources (such	as LDAP	directory contents)

       o       the passed parameters and

       o       the configured policy

       The results of the function can be directly used	for decisions on how
       the actual personalization should happen.

       Return structure:

       o       OVERALL_STATUS (scalar)

	       This is the global status of the	Smartcard which	can be
	       directly	displayed by the frontend.

	       Possible	values:	'green'	(default), 'amber', 'red'

       o       SMARTCARD (hashref)

       The referenced structure	contains the details of	the Smartcard:

       o       serialnumber (scalar)

	       Canonical serial	number of the Smartcard

       o       status (scalar)

	       Smartcard status	(initial|activated|deactivated)

       o       assigned_to (hashref)

	       Designated holder of the	Smartcard. Items in the	hash are
	       determined by the configuration at smartcard.employee.

       o       user_data_source	(scalar)

	       Origin of assigned_to (name of the resolver)

       o       keyalg (scalar)

	       Asymmetric algorith supported (preferred) by this Smartcard

       o       keysize (scalar)

	       Key size	supported (preferred) by this Smartcard

       o       token_chipid_match (scalar)

	       If SMARTCHIPID was given, inicates if the chip id matches the
	       card serialnumber recorded in earlier personalizations.
	       Possible	values are valid|new|mismatch.

       o   CERT_TYPES (array)

	   Lists all certificate types configured for this Smartcard. This is
	   identical to	the keys of CERT_TYPE in the return structure.

       o   WORKFLOWS (hashref)

	   Returned data is identical to the result of the
	   search_workflow_instances() API function.

       o   PROCESS_FLAGS (hash of scalars, interpreted as booleans)

	   These flags can be used for decisions in the	personalization

       o       allow_personalization

	       User is allowed to start	a personalization workflow. This is an
	       alias for the OVERALL_STATUS not	being green.

       o       will_need_pin

	       Smartcard PIN is	required for following operations (either the
	       user's pin or an	autogenerated random pin)

       o       allow_user_pin

	       Policy setting: Allow user to enter pin (otherwise autogenerate
	       random pin -> pin unblock needed	after completion).

       o       puk_is_writable

	       Smartcard puk can be modified

       o       puk_found_in_datapool

	       Smartcard puk is	available in datapool

       o       need_approval

	       Policy setting: if set 0/false no approval is required for user
	       cert issuance

       o       purge_token_before_unblock

	       Policy setting: if true the token must be completely purged
	       before an unblock operation may happen

       o       purge_token_before_personalisation

	       Policy setting: if true the token must be completely purged
	       before a	new personalization is made

       The flags marked	as policy setting are taken from the policy config.
       The purge_token_before* flags are set per card-type at, others are defined
       at smartcard.policy.flag_name.

       o       VALIDITY	(hashref)

	       Store information about forced notafter/validity	setting

       o       set_to_value

	       Epoch timestamp which should be used as notafter	date

       o       set_by_type

	       Certificate type	which was used to determine the	value

       o       TASKS (hashref)

	       Holds the information what should actually be done.

       o       CREATE (array ref)

	       Names of	the certificate	types that should be created.

       o       INSTALL (array ref)

	       List of certificates (descriptive hash) to install.

       o       PURGE (array ref)

	       List of certificates (descriptive hash) to purge.

       o       REVOKE (array ref)

	       List of certificates (descriptive hash) to revoke.

       o       PARSED_CERTS (array ref)

	       List of certificates found on the card. Each entry is a hash
	       ref with	the merged results of sc_parse_certificate and the
	       __check*	methods.

perl v5.24.1			  2017-07-0OpenXPKI::Server::API::Smartcard(3)

Name | Description | Public functions

Want to link to this manual page? Use this URL:

home | help