classes

Class PivApiWrapper

java.lang.Object

classes.PivApiWrapper

All Implemented Interfaces:

PIVReturnCodes

public class PivApiWrapper
extends java.lang.Object
implements PIVReturnCodes

The PivApiWrapper class provides a Java wrapper around the ActivIdentity PIV API.

ASN.1 OID Identifiers

The following identifiers are used to identify the PIV objects in the pivPutData() and the pivGetData() methods.

ASN.1 OID		Description
2.16.840.1.101.3.7.1.219.0		Card Capability Container
2.16.840.1.101.3.7.2.48.0		Card Holder Unique Identifier
2.16.840.1.101.3.7.2.1.1		X.509 Certificate for PIV Authentication
2.16.840.1.101.3.7.2.96.16		Card Holder Fingerprints
2.16.840.1.101.3.7.2.48.1		Printed Information
2.16.840.1.101.3.7.2.96.48		Card Holder Facial Image
2.16.840.1.101.3.7.2.1.0		X.509 Certificate for Digital Signature
2.16.840.1.101.3.7.2.1.2		X.509 Certificate for Key Management
2.16.840.1.101.3.7.2.5.0		X.509 Certificate for Card Authentication
2.16.840.1.101.3.7.2.144.0		Security Object

NIST [SP 800-73] cryptographic mechanism identifiers

The following identifiers are used to identify the types of key pairs to be generated by the pivGenerateKeyPair() method. The table below corresponds to Table 20 of NIST [SP 800-73].

Cryptographic mechanism identifier		Description
05		RSA 3072
06		RSA 1024
07		RSA 2048

Field Summary

Fields inherited from interface interfaces.PIVReturnCodes

PIV_AUTHENTICATION_FAILURE, PIV_AUTHENTICATOR_MALFORMED, PIV_CARD_APPLICATION_NOT_FOUND, PIV_CARD_READER_ERROR, PIV_CONNECTION_DESCRIPTION_MALFORMED, PIV_CONNECTION_FAILURE, PIV_CONNECTION_LOCKED, PIV_DATA_OBJECT_NOT_FOUND, PIV_INPUT_BYTES_MALFORMED, PIV_INSUFFICIENT_BUFFER, PIV_INSUFFICIENT_CARD_RESOURCE, PIV_INVALID_CARD_HANDLE, PIV_INVALID_KEY_OR_KEYALG_COMBINATION, PIV_INVALID_KEYREF_OR_ALGORITHM, PIV_INVALID_OID, PIV_OK, PIV_SECURITY_CONDITIONS_NOT_SATISFIED, PIV_UNABLE_TO_LOAD_WRAPPER, PIV_UNSUPPORTED_CRYPTOGRAPHIC_MECHANISM

Constructor Summary

Constructors

Constructor and Description
PivApiWrapper()

Method Summary

Modifier and Type	Method and Description
java.lang.String	getStringErrorCode(int error)
long	pivConnect(boolean bSharedConnection, byte[] connectionDescription) Connects the client application to the PIV card application on a specific ICC.
byte[]	pivCrypt(long cardHandle, byte algorithmID, byte keyReference, byte[] algorithmInput) Performs a cryptographic operation such as encryption or signing on a sequence of bytes.
void	pivDisconnect(long cardHandle) Disconnects the PIV programming interface from the PIV card application and the ICC containing the PIV card application.
byte[]	pivGenerateKeyPair(long cardHandle, byte keyReference, byte cryptographicMechanism) Generates an asymmetric key pair in the currently selected application.
byte[]	pivGetData(long cardHandle, java.lang.String OID) Returns the entire data content of the named data object.
void	pivLogIntoCardApplication(long cardHandle, byte[] Authenticators) Establishes the application security status within the PIV card application, either by verifying the card holder.
void	pivLogoutOfCardApplication(long cardHandle) Resets the application security status of the PIV card application.
java.lang.String	pivMiddlewareVersion() Returns the PIV Middleware version string.
void	pivPutData(long cardHandle, java.lang.String OID, byte[] data) Replaces the entire data content of the named data object with the provided data.
byte[]	pivSelectCardApplication(long cardHandle, byte[] ApplicationAID) Sets the currently selected card application.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PivApiWrapper

public PivApiWrapper()
              throws PIVAPIException

Throws:

PIVAPIException

Method Detail

getStringErrorCode

public java.lang.String getStringErrorCode(int error)

pivConnect

public long pivConnect(boolean bSharedConnection,
                       byte[] connectionDescription)
                throws PIVAPIException

Connects the client application to the PIV card application on a specific ICC. If the card that is inserted in the reader and to which the method is attempting to connect does not contain a PIV card application, then this method fails with an error code. Otherwise, the method succeeds and the PIV card application (AID = [A0 00 00 03 08 00 00 10 00]) is selected.

Parameters:

bSharedConnection - Boolean value that indicates whether other applications can establish concurrent connections with the PIV card application.

• If this parameter is true then the connection is shared.
• If false and the connection is established, the calling client-application has exclusive access to the ICC.

connectionDescription - A connection description BER-TLV data object. This parameter, defined in [SP800-73-1] section 5.4 Table 11, represents a BER-TLV buffer containing the connection description template to be used to connect to the PIV API card application.

Returns:

A cardhandle (an opaque identifier that identifies the communication channel to a particular ICC and hence the card itself). The cardHandle is used in all other entry points on the PIV client-application programming interface to identify which card the functionality of the entry point is to be applied.

Throws:

PIVAPIException - if an error occured

See Also:

Interfaces for Personnal Identity Verification documentation (NIST Special Publication 800-73-3)

pivDisconnect

public void pivDisconnect(long cardHandle)
                   throws PIVAPIException

Disconnects the PIV programming interface from the PIV card application and the ICC containing the PIV card application.

Parameters:

cardHandle - Communication handle returned by a successful call to the pivConnect() function. After the call to pivDisconnect, this handle is undefined and should not be used in subsequent calls.

Throws:

PIVAPIException - if an error occured

See Also:

Interfaces for Personnal Identity Verification documentation (NIST Special Publication 800-73-3)

pivLogIntoCardApplication

public void pivLogIntoCardApplication(long cardHandle,
                                      byte[] Authenticators)
                               throws PIVAPIException

Establishes the application security status within the PIV card application, either by verifying the card holder. PIV card application PIN or by performing an external authentication using the PIV card application administration key.

Parameters:

cardHandle - Communication handle returned by a successful call to the pivConnect() function.

Authenticators - A sequence of zero or more BER-TLV encoded authenticators to be used to authenticate the client application to the card application and hence in establishing the initial security status in the card application context.

Throws:

PIVAPIException - if an error occured

See Also:

Interfaces for Personnal Identity Verification documentation (NIST Special Publication 800-73-3)

pivSelectCardApplication

public byte[] pivSelectCardApplication(long cardHandle,
                                       byte[] ApplicationAID)
                                throws PIVAPIException

Sets the currently selected card application. The call is successful if the given PIV card application is found; otherwise, an error code is returned.

Note: The ActivIdentity optimizes the implementation of this method so that if it is called multiple times once the application has been selected, it does not go to the card to select the application again. This means that invoking this method multiple times does not impact performance.

Parameters:

cardHandle - Communication handle returned by a successful call to the pivConnect() function.

ApplicationAID - The AID of the card application that is to become the currently selected card application.

Returns:

The application properties of the selected card application (sequence of bytes).

Throws:

PIVAPIException - if an error occured

See Also:

Interfaces for Personnal Identity Verification documentation (NIST Special Publication 800-73-3)

pivLogoutOfCardApplication

public void pivLogoutOfCardApplication(long cardHandle)
                                throws PIVAPIException

Resets the application security status of the PIV card application. The currently selected application after successful return from this entry point is card-dependent. The application may have to reselect the PIV card application using pivSelectCardApplication() after this call. When this method succeeds, access rights acquired by a previous call to the pivLogIntoCardApplication() are lost.

Parameters:

cardHandle - Communication handle returned by a successful call to the pivConnect() function. The cardHandle remains valid after execution of this function.

Throws:

PIVAPIException - if an error occured

See Also:

Interfaces for Personnal Identity Verification documentation (NIST Special Publication 800-73-3)

pivGetData

public byte[] pivGetData(long cardHandle,
                         java.lang.String OID)
                  throws PIVAPIException

Returns the entire data content of the named data object.

Parameters:

cardHandle - Communication handle returned by a successful call to the pivConnect() function.

OID - Object identifier of the object whose data content is to be retrieved coded as a string that contains the ASN.1 identifier of the object whose data content is to be retrieved. For example,

"2.16.840.1.101.3.7.2.48.0"

.

Returns:

data Retrieved data content (sequence of bytes)

Throws:

PIVAPIException - if an error occured

See Also:

Interfaces for Personnal Identity Verification documentation (NIST Special Publication 800-73-3)

pivCrypt

public byte[] pivCrypt(long cardHandle,
                       byte algorithmID,
                       byte keyReference,
                       byte[] algorithmInput)
                throws PIVAPIException

Performs a cryptographic operation such as encryption or signing on a sequence of bytes.

Parameters:

cardHandle - Communication handle returned by a successful call to the pivConnect() function.

algorithmID - Identifier of the cryptographic algorithm to be used for the cryptographic operation. The ActivIdentity implementation supports all the algorithms listed in Table 7 of NIST [SP800-73-1] publication:

• 05, 06, 07 for asymmetric algorithms
• 01, 02, 03, 04, 08, 09, 0A, 0B, 0C, 0D, 0E, 0F, 10, 11, 12, 13 for symmetric algorithms.
• 00 for symmetric or asymmetric algorithm depending on the keyReference.

Other values are rejected and the function returns an error.

keyReference - Identifier of the on-card key to be used for the cryptographic operation. The ActivIdentity implementation supports all the key reference values listed in Table 12 of the NIST [SP 800-73] publication other than 9A, 9B, 9C, and 9D. The ActivIdentity implementation does support the value 9E, even though it is not listed in Table 12 of NIST [SP 800-73]. (See PIV Project Questions and Answers Web site.) Other key reference values are rejected and the function returns an error.

algorithmInput - Sequence of bytes used as the input to the cryptographic operation. For more information, see the Dynamic Authentication Template Format definition in Table 17 of [SP-800-73-1].

Returns:

Sequence of bytes output by the cryptographic operation.

Throws:

PIVAPIException - if an error occured

See Also:

Interfaces for Personnal Identity Verification documentation (NIST Special Publication 800-73-3)

pivPutData

public void pivPutData(long cardHandle,
                       java.lang.String OID,
                       byte[] data)
                throws PIVAPIException

Replaces the entire data content of the named data object with the provided data.

Parameters:

cardHandle - Communication handle returned by a successful call to the pivConnect() function.

OID - Object identifier of the object whose data content is to be replaced, coded as a string that contains the ASN.1 identifier. For example,

"2.16.840.1.101.3.7.2.48.0"

.

data - Data to be used to replace in its entirety the data content of the named data object.

Throws:

PIVAPIException - if an error occured

See Also:

Interfaces for Personnal Identity Verification documentation (NIST Special Publication 800-73-3)

pivGenerateKeyPair

public byte[] pivGenerateKeyPair(long cardHandle,
                                 byte keyReference,
                                 byte cryptographicMechanism)
                          throws PIVAPIException

Generates an asymmetric key pair in the currently selected application.

Parameters:

cardHandle - Communication handle returned by a successful call to the pivConnect() function.

keyReference - Key reference value of the key to be generated.

cryptographicMechanism - The type of the key pair to be generated. See NIST [SP 800-73] cryptographic mechanism identifiers for the supported cryptographic mechanism identifiers.

Returns:

BER-TLV data objects defining the public key of the generated key pair (Sequence of bytes). See the ActivClient SDK PIV API Reference Guide for an example of a public key value.

Throws:

PIVAPIException - if an error occured

See Also:

Interfaces for Personnal Identity Verification documentation (NIST Special Publication 800-73-3)

pivMiddlewareVersion

public java.lang.String pivMiddlewareVersion()
                                      throws PIVAPIException

Returns the PIV Middleware version string.

Returns:

PIV Middleware version string

Throws:

PIVAPIException - if an error occured

See Also:

Interfaces for Personnal Identity Verification documentation (NIST Special Publication 800-73-3)