public interface PasswordService extends ResourceService
Provides password management services.
check(..)
method verifies the provided password.update(..)
method changes the password after successful verification.resetAndUnblock(..)
method resets the retry counter and unblocks the password.
The password resources must be configured by the CSP Admin.
The resource identifiers for passwords, assigned during creation, must be used in the methods provided by the PasswordService
.
For details on admin commands of the CSP-Protocol, see Chapter 7 of GlobalPlatform Amendment N [GPC_SPE_230].
Below are pseudo admin command examples using CSP-Protocol ASN.1 types.
// Create PIN with 3 invalid attempts allowed and initial one-time-password value. CSPCreateResource(PIN_ID, PWD_NUMERIC, minSize=5, maxSize=5, tryLimit=3, transportLimit=1) CSPSetValue(PIN_ID, inTransport=true) // Create PUK with 10 usages allowed. CSPCreateResource(PUK_ID, PWD_NUMERIC, minSize=6, maxSize=6, tryLimit=10, successUsageLimit=10) CSPSetValue(PUK_ID, data) // Set access control and PUK-based PIN unblock policy. CSPConfigureResource(PIN_ID, ACR_USE & ACR_SETUP, POLICY_UNBLOCK_PASSWORD=PUK_ID) CSPConfigureResource(PUK_ID, ACR_USE) // Configure simple password verification usage. CSPConfigureResource(PIN_ID, USAGE_PASSWORD, SEC_PACE) // Alternatively, configure as PACE PIN. // CSPConfigureResource(PIN_ID, USAGE_SECCHANNEL, SEC_PACE)
Note: Success and transport counters are managed by CounterService
, while the try limit is handled by PasswordService
.
Sample code for using the PasswordService
:
// Retrieve CSP Shareable Instance. AID cspAID = JCSystem.lookupAID(CSP_AID_DATA, (short) 0, (byte) CSP_AID_DATA.length); GlobalService cspGlobalService = GPSystem.getService(cspAID, CSP.GLOBAL_SERVICE_ID); AID clientAID = JCSystem.getAID(); GPRegistryEntry clientRegistryEntry = GPSystem.getRegistryEntry(clientAID); CSP csp = (CSP) cspGlobalService.getServiceInterface(clientRegistryEntry, CSP.DEFAULT_SERVICE_ID, null, (short) 0, (short) 0); // Init service. PasswordService pwdService = csp.getPasswordService(); switch (ins) { // Login: Verify a PIN. case LOGIN: short validated = pwdService.check(PIN_ID, pinBuffer, pinOffset, pinLength); pwdService.assertSensitiveResult(validated); if (validated == CSP.RESULT_TRUE) { // do something } if (pwdService.isAuthenticated(PIN_ID) == CSP.RESULT_TRUE) { // do something } break; // Logout: reset validation. case LOGOUT: pwdService.reset(PIN_ID); break; // Change a password. case CHANGE_PIN: pwdService.check(PIN_ID, pinBuffer, pinOffset, pinLength); try { pwdService.update(PIN_ID, newPwdBuffer, newPwdOffset, newPwdLength); SensitiveArrays.assertIntegrity(newPwdBuffer); } catch (CSPException e) { // Handle PIN is not authenticated or SETUP privileges are not granted. } break; // Block a PIN: use invalid password attempts until PIN is blocked. case BLOCK_TEST: short tries = pwdService.getTryCounter(PIN_ID); for (short i = 0; i <= tries; i++) { pwdService.check(PIN_ID, wrongPinBuffer, wrongPinOffset, wrongPinLength); } if (pwdService.getState(PIN_ID) == PasswordService.STATE_BLOCKED) { // do something } break; // Unblock a PIN. case UNBLOCK: if (pwdService.getState(PIN_ID) == PasswordService.STATE_BLOCKED) { // Verify PUK. pwdService.check(PUK_ID, pukBuffer, pukOffset, pukLength); try { // Unblock the PIN. pwdService.resetAndUnblock(PIN_ID, PUK_ID); } catch (CSPException e) { // Handle PUK is not authenticated. } } break; }
KeyService
,
CertificateService
Modifier and Type | Field and Description |
---|---|
static byte |
PWD_ALPHAMERIC
Alphanumeric (0-9, a-z, A-Z).
|
static byte |
PWD_ANY
Flexible format.
|
static byte |
PWD_NUMERIC
Numeric (0-9), typically used for PINs/PUKs.
|
static byte |
PWD_STRONG
UTF-8 encoded password with rules: at least 1 uppercase, 1 lowercase, 1 number, and 1 special character.
|
static byte |
PWD_UTF8
UTF-8 encoded password.
|
RESOURCE_CERTIFICATE, RESOURCE_COUNTER, RESOURCE_KEY, RESOURCE_PASSWORD, RESOURCE_TIMER, STATE_BLOCKED, STATE_EXHAUSTED, STATE_EXPIRED, STATE_OPERATIONAL, STATE_UNINITIALIZED
RESULT_FALSE, RESULT_TRUE
Modifier and Type | Method and Description |
---|---|
short |
check(short pwdResourceId,
byte[] pwdBuffer,
short pwdOffset,
byte pwdSize)
Verify a password and set the
authenticated flag upon successful verification. |
short |
getMaxSize(short pwdResourceId)
Retrieve the maximum allowed character size for a password update.
|
short |
getMinSize(short pwdResourceId)
Retrieve the minimum allowed character size for a password update.
|
byte |
getTryCounter(short pwdResourceId)
Retrieve the current value of the (re)try counter, indicating the remaining limit for incorrect password verification attempts.
|
byte |
getTryLimit(short pwdResourceId)
Retrieve the maximum (re)try limit for incorrect password verification attempts.
|
byte |
getType(short pwdResourceId)
Retrieve the password type.
|
short |
isAuthenticated(short pwdResourceId)
Retrieve whether the password is authenticated.
|
short |
isBlocked(short pwdResourceId)
Retrieve whether the password is blocked.
|
short |
isInTransport(short pwdResourceId)
Retrieve whether the password is marked with in-transport.
|
void |
reset(short pwdResourceId)
Resets the
authenticated flag of a password. |
void |
resetAndUnblock(short pwdResourceId,
short pwdPukResourceId)
Convenience method that invokes
resetAndUnblock(pwdResourceId, pwdPukResourceId, null, (short) 0, (short) 0)
without providing a new password value. |
void |
resetAndUnblock(short pwdResourceId,
short pukResourceId,
byte[] newPwdBuffer,
short newPwdOffset,
short newPwdLength)
Unblock a password resource and reset the try counter.
|
void |
update(short pwdResourceId,
byte[] newPwdBuffer,
short newPwdOffset,
short newPwdLength)
Sets or updates a password value.
|
clear, clearTransient, getResourceType, getState
assertSensitiveResult
static final byte PWD_ANY
Password is a byte array with an undefined format, used for custom types.
static final byte PWD_NUMERIC
Encoded in ASCII format.
static final byte PWD_ALPHAMERIC
Encoded in ASCII format, suitable for simple passwords.
static final byte PWD_UTF8
Allows international and special characters, ideal for complex passwords.
static final byte PWD_STRONG
Used for strong passwords with a minimum charset of N = 90, ensuring uniform random selection.
short isInTransport(short pwdResourceId)
Transport passwords indicate initial values that require a mandatory change.
This flag is cleared when the password is updated using the update(..)
method.
Usage Guidelines:
assertSensitiveResult(..)
.pwdResourceId
- Password resource.TRUE
if the password is in transport, otherwise FALSE
.CSPException
- for:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or is not a PASSWORD
[2090].ILLEGAL_CONFIG
: CSP not activated [3001] or password not initialized [3003].NOT_ALLOWED
: Client not authenticated [5006].getState(..)
,
isAuthenticated(..)
short isAuthenticated(short pwdResourceId)
Method Behavior:
Passwords are considered authenticated after successful verification through check(..)
or successful PACE authentication through SecureChannelService#processSecurity(..)
.
The authenticated flag is stored in transient memory with CLEAR_ON_RESET and is invalidated via:
reset(..)
SecureChannelService#resetSecurity(..)
clear(..)
clearTransient(..)
The method handles access control, counters, timers and events according to Section 6.9.3 of GlobalPlatform Amendment N.
Usage Guidelines:
assertSensitiveResult(..)
.POLICY_PASSWORD
when possible instead of this method.pwdResourceId
- Password resource.TRUE
if password is authenticated, otherwise FALSE
.CSPException
- for:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or is not a PASSWORD
[2090].ILLEGAL_CONFIG
: CSP not activated [3001], password not initialized [3003] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007], blocked [5092], exhausted [50A0], expired [50B1], not configured for USAGE_PASSWORD
[5090] or a policy failed [500B].getState(..)
,
isInTransport(..)
short isBlocked(short pwdResourceId)
Method Behavior:
Passwords are considered blocked after too many failed password verification attempts or PACE failures, and the remaining try counter reached zero.
The method handles access control, counters, timers and events according to Section 6.9.3 of GlobalPlatform Amendment N.
pwdResourceId
- Password resource.TRUE
if password is blocked, otherwise FALSE
.CSPException
- for:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or is not a PASSWORD
[2090].ILLEGAL_CONFIG
: CSP not activated [3001] or password not initialized [3003].NOT_ALLOWED
: Client not authenticated [5006].getState(..)
,
isInTransport(..)
short check(short pwdResourceId, byte[] pwdBuffer, short pwdOffset, byte pwdSize)
authenticated
flag upon successful verification.
Method Behavior:
This method compares the input buffer against the value of the password resource.
On successful verification:
CSPService.RESULT_TRUE
.On failed verification:
STATE_BLOCKED
.CSPService.RESULT_FALSE
.The method handles access control, counters, timers and events according to Section 6.9.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the input buffer.assertSensitiveResult(..)
.pwdResourceId
- Password resource.pwdBuffer
- The input buffer containing password value.pwdOffset
- Offset in the input buffer to start reading.pwdSize
- Length of the input buffer in bytes.TRUE
on successful verification; FALSE
otherwise.CSPException
- for:
ILLEGAL_BUFFER
: Illegal input buffer [1002], [1004], [1005], [1006], [1007].ILLEGAL_VALUE
: Resource ID does not exist [2001] or is not a PASSWORD
[2090].ILLEGAL_CONFIG
: CSP not activated [3001], password not initialized [3003] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007], blocked [5092], exhausted [50A0], expired [50B1], not configured for USAGE_PASSWORD
[5090] or a policy failed [500B].getState(..)
,
update(pwdId, newPwd, ..)
,
reset(..)
,
resetAndUnblock(..)
void update(short pwdResourceId, byte[] newPwdBuffer, short newPwdOffset, short newPwdLength)
Method Behavior:
Sets the password's value and, if initially set, resets the internal transport flag
to CSPService.RESULT_FALSE
.
The method handles access control, counters, timers and events according to Section 6.9.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the new password buffer.STATE_UNINITIALIZED
or authenticated using the check(..)
method.pwdResourceId
- Password resource.newPwdBuffer
- The input buffer containing the new password.newPwdOffset
- Offset in the input buffer to start reading.newPwdLength
- Length of the input buffer in bytes.CSPException
- for:
ILLEGAL_BUFFER
: Illegal input buffer [1002], [1004], [1005], [1006], [1007].ILLEGAL_VALUE
: Resource ID does not exist [2001] or is not a PASSWORD
[2090].ILLEGAL_CONFIG
: CSP not activated [3001], password not initialized [3003] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006], password not authenticated [5091] or resource missing ACCESS_SETUP
[5008], blocked [5092], exhausted [50A0], expired [50B1] or a policy failed [500B].ILLEGAL_USE
: New password is too short [6090] or too long [6091].getState(..)
,
isAuthenticated(..)
,
getTryCounter(..)
,
getMaxSize(..)
,
getMinSize(..)
,
check(..)
void reset(short pwdResourceId)
authenticated
flag of a password.
Method Behavior:
This method sets the internal authenticated
flag to FALSE
.
The method handles access control, counters, timers and events according to Section 6.9.3 of GlobalPlatform Amendment N.
pwdResourceId
- The password to reset.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or is not a PASSWORD
[2090].ILLEGAL_CONFIG
: CSP not activated [3001].NOT_ALLOWED
: Client not authenticated [5006] or not configured for USAGE_PASSWORD
[5090].getState(..)
,
check(..)
,
isAuthenticated(..)
void resetAndUnblock(short pwdResourceId, short pukResourceId, byte[] newPwdBuffer, short newPwdOffset, short newPwdLength)
Method Behavior:
When the provided PUK is authenticated
, this method:
STATE_OPERATIONAL
.The method handles access control, counters, timers and events according to Section 6.9.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the new password buffer.pwdResourceId
- The password to unblock.pukResourceId
- The PUK resource to authorize the unblocking.newPwdBuffer
- An input buffer containing a new password; optional, can be null.newPwdOffset
- Offset in the input buffer to start reading.newPwdLength
- Length of the input buffer in bytes; optional, can be zero.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input buffer [1003], [1004], [1005], [1006], [1007].ILLEGAL_VALUE
: A resource ID does not exist [2001] or is not a PASSWORD
[2090].ILLEGAL_CONFIG
: CSP not activated [3001], a resource not initialized [3003] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006], PUK not authenticated [5091] or password missing ACCESS_SETUP
[5008], exhausted [50A0], expired [50B1] or a policy failed [500B].ILLEGAL_USE
: New password is too short [6090] or too long [6091].getState(..)
,
check(..)
,
getMaxSize(..)
,
getMinSize(..)
void resetAndUnblock(short pwdResourceId, short pwdPukResourceId)
resetAndUnblock(pwdResourceId, pwdPukResourceId, null, (short) 0, (short) 0)
without providing a new password value.pwdResourceId
- The password to unblock.pwdPukResourceId
- The PUK resource to authorize the unblocking.CSPException
- same as resetAndUnblock(..)
byte getType(short pwdResourceId)
Available types:
pwdResourceId
- The password resource.CSPException
- with reason:
ILLEGAL_VALUE
: resource ID does not exist [2001] or is not a PASSWORD
[2090].ILLEGAL_CONFIG
: CSP not activated [3001].NOT_ALLOWED
: Client not authenticated [5006].short getMinSize(short pwdResourceId)
pwdResourceId
- The password resource.CSPException
- with reason:
ILLEGAL_VALUE
: resource ID does not exist [2001] or is not a PASSWORD
[2090].ILLEGAL_CONFIG
: CSP not activated [3001].NOT_ALLOWED
: Client not authenticated [5006].getMaxSize(..)
,
getType(..)
,
update(..)
,
resetAndUnblock(..)
short getMaxSize(short pwdResourceId)
pwdResourceId
- The password resource.CSPException
- with reason:
ILLEGAL_VALUE
: resource ID does not exist [2001] or is not a PASSWORD
[2090].ILLEGAL_CONFIG
: CSP not activated [3001].NOT_ALLOWED
: Client not authenticated [5006].getMinSize(..)
,
getType(..)
,
update(..)
,
resetAndUnblock(..)
byte getTryLimit(short pwdResourceId)
Returns 0xFF if no (re)try limit is configured, permitting unlimited incorrect attempts.
pwdResourceId
- The password resource.CSPException
- with reason:
ILLEGAL_VALUE
: resource ID does not exist [2001] or is not a PASSWORD
[2090].ILLEGAL_CONFIG
: CSP not activated [3001].NOT_ALLOWED
: Client not authenticated [5006].getTryCounter(..)
byte getTryCounter(short pwdResourceId)
Returns 0 if no retry limit is configured, permitting unlimited incorrect attempts.
pwdResourceId
- The password resource.CSPException
- with reason:
ILLEGAL_VALUE
: resource ID does not exist [2001] or is not a PASSWORD
[2090].ILLEGAL_CONFIG
: CSP not activated [3001] or password not initialized [3003].NOT_ALLOWED
: Client not authenticated [5006], resource blocked [5092], exhausted [50A0] or expired [50B1].getTryLimit(..)
Copyright © 2023-2025 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.