This parameter is a list of certificates as read from the card.
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.
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 CERTIFICATE_SERIAL o IDENTIFIER o PKI_REALM o SUBJECT o ISSUER_DN o ISSUER_IDENTIFIER o o PUBKEY o SUBJECT_KEY_IDENTIFIER o AUTHORITY_KEY_IDENTIFIER o NOTBEFORE
Seconds since Epoch
NotBefore date in ISO format
Seconds since Epoch
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 document.
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)
o CERTFORMAT (mandatory if CERTS is given)
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.
The function will return a complex data structure containing the results of the Smartcard analysis.
These results are directly influenced by
The results of the function can be directly used for decisions on how the actual personalization should happen.
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 referenced structure contains the details of the Smartcard:
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)
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 workflow.
The flags marked as policy setting are taken from the policy config. The purge_token_before* flags are set per card-type at smartcard.cardinfo.properties.card_type.flag_name, others are defined at smartcard.policy.flag_name.
User is allowed to start a personalization workflow. This is an alias for the OVERALL_STATUS not being green.
Smartcard PIN is required for following operations (either the users pin or an autogenerated random pin)
Policy setting: Allow user to enter pin (otherwise autogenerate random pin -> pin unblock needed after completion).
Smartcard puk can be modified
Smartcard puk is available in datapool
Policy setting: if set 0/false no approval is required for user cert issuance
o purge_token_before_unblock o purge_token_before_personalisation
o VALIDITY (hashref)
Store information about forced notafter/validity setting
Epoch timestamp which should be used as notafter date
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.20.3||OPENXPKI::SERVER::API::SMARTCARD (3)||2016-04-03|