org.globalplatform
Interface Authority

All Superinterfaces:
javacard.framework.Shareable

public interface Authority
extends javacard.framework.Shareable

This interface allows performing operations such as recovering a cryptographic key or signing data. The required algorithms and credentials are known implicitly.

It is intended that Security Domains would be able to access an Authority instance through a Global Service by a Controlling Authority Security Domain (CASD) with a service name of (GPSystem.FAMILY_AUTHORITY<<8|0x00).

Since:

Field Summary
static byte MODE_KEY_RECOVERY
          Used with init(byte) method to indicate key recovery mode.
static byte MODE_SIGN
          Used with init(byte) method to indicate signing mode.
 
Method Summary
 void init(byte theMode)
          Initializes the Authority interface with the appropriate mode (MODE_SIGN or MODE_KEY_RECOVERY).
 short recoverKey(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset)
          Recovers a cryptographic key from a set of data structures provided in the input buffer (inBuff).
 short sign(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset)
          Generates the signature of all/last input data.
 void update(byte[] inBuff, short inOffset, short inLength)
          Accumulates input data. for the current operation (MODE_SIGN or MODE_KEY_RECOVERY).
 

Field Detail

MODE_SIGN

static final byte MODE_SIGN
Used with init(byte) method to indicate signing mode.

See Also:
Constant Field Values

MODE_KEY_RECOVERY

static final byte MODE_KEY_RECOVERY
Used with init(byte) method to indicate key recovery mode.

See Also:
Constant Field Values
Method Detail

init

void init(byte theMode)
          throws javacard.security.CryptoException
Initializes the Authority interface with the appropriate mode (MODE_SIGN or MODE_KEY_RECOVERY).

Parameters:
theMode - one of MODE_SIGN or MODE_KEY_RECOVERY.
Throws:
javacard.security.CryptoException - with the following reason code:
  • ILLEGUAL_VALUE if theMode option is an undefined value.

sign

short sign(byte[] inBuff,
           short inOffset,
           short inLength,
           byte[] sigBuff,
           short sigOffset)
           throws javacard.security.CryptoException
Generates the signature of all/last input data. A call to this method resets this Authority interface to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to sign another message. The input and output buffer may overlap and shall be global arrays.

Parameters:
inBuff - the input buffer of data to be signed
inOffset - the offset in input buffer at which the signature starts
inLength - the byte length to sign
sigBuff - the output buffer to store signature data
sigOffset - the offset into sigBuff at which to begin signature generation
Returns:
the number of bytes of signature output in sigBuff
Throws:
javacard.security.CryptoException - with the following reason codes:
  • INVALID_INIT if this Authority interface is not initialized or initialized in MODE_KEY_RECOVERY mode.
  • ILLEGAL_USE if this Authority algorithm does not pad the message and the message is not block aligned.
java.lang.SecurityException - if the inBuff or sigBuff are not global arrays.

update

void update(byte[] inBuff,
            short inOffset,
            short inLength)
            throws javacard.security.CryptoException
Accumulates input data. for the current operation (MODE_SIGN or MODE_KEY_RECOVERY).

When this method is used, temporary storage of intermediate results is required. This method should only be used if all the input data required for the current operation is not available in one byte array. The sign or recoverKey methods are recommended whenever possible. The inBuff shall be global array.

Parameters:
inBuff - buffer containing input data
inOffset - offset of input data
inLength - length of input data
Throws:
javacard.security.CryptoException - with the following reason codes:
  • INVALID_INIT if this Authority interface is not initialized.
java.lang.SecurityException - if the inBuff is not global array.

recoverKey

short recoverKey(byte[] inBuff,
                 short inOffset,
                 short inLength,
                 byte[] outBuff,
                 short outOffset)
                 throws javacard.security.CryptoException
Recovers a cryptographic key from a set of data structures provided in the input buffer (inBuff). As a mandatory step, the recovery mechanism includes the verification of the origin and integrity of the recovered key. This method knows, from the set of data structures present in the input buffer, which recovery mechanism is to be used. The recovered key is written in the ouput buffer (outBuff) at specified offset (outOffset), in the form of a key data structure whose format depends on the type of the key. A call to this method resets this instance of the Authority interface to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to recover another key. The input and output buffers may overlap and shall be global arrays.

Parameters:
inBuff - containing input data.
inOffset - offset of input data.
inLength - length of input data.
outBuff - the buffer where recovered key data structure shall be written
outOffset - offset where recovered key data structure shall be written
Returns:
Length of the recovered key data structure written in outBuff at outOffset,or 0 if the recovery mechanism failed (e.g. recovered key was considered invalid).
Throws:
javacard.security.CryptoException - - with the following reason codes:
  • INVALID_INIT if this Authority interface is not initialized or initialized in MODE_SIGN mode.
java.lang.SecurityException - if the inBuff or outBuff are not global arrays.


Copyright © 2003-2014 GlobalPlatform, Inc. All rights reserved. The technology provided or described in this specification is subject to updates, revisions, and extensions by GlobalPlatform. Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights or other intellectual property rights of which they may be aware which might be necessarily infringed by the implementation of the specification or other work product set forth in this document, and to provide supporting documentation.
THIS SPECIFICATION OR OTHER WORK PRODUCT IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NON-INFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY IMPLEMENTATION OF THIS SPECIFICATION OR OTHER WORK PRODUCT SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE COMPANY, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER DIRECTLY OR INDIRECTLY ARISING FROM THE IMPLEMENTATION OF THIS SPECIFICATION OR OTHER WORK PRODUCT.