GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  OPENXPKI::SERVER::API::SMARTCARD (3)

.ds Aq ’

Name

OpenXPKI::Server::API::Smartcard

CONTENTS

Description

This API handles Smartcard specific calls.

Public functions

    sc_parse_certificates

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

    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 CERTIFICATE_SERIAL
o IDENTIFIER
o PKI_REALM
o SUBJECT
o ISSUER_DN
o ISSUER_IDENTIFIER
o EMAIL
o PUBKEY
o SUBJECT_KEY_IDENTIFIER
o AUTHORITY_KEY_IDENTIFIER
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

    sc_analyze_smartcard

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)

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 workflow.

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 smartcard.cardinfo.properties.card_type.flag_name, 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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 OPENXPKI::SERVER::API::SMARTCARD (3) 2016-04-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.