org.cyclos.services.access

Interface TokenService

All Superinterfaces:

CRUDService<TokenDTO,TokenData,TokenDataParams>, Service

public interface TokenService
extends CRUDService<TokenDTO,TokenData,TokenDataParams>

Service for managing tokens, NFC tokens and NFC devices

Author:

jcomas, ameyer

Method Summary

Modifier and Type	Method and Description
void	activatePending(java.lang.Long tokenId) Activates the given token.
void	assign(TokenActionDTO dto) Assigns and activates an unassigned token with the given type and value for the logged user.
void	block(java.lang.Long tokenId) Blocks the given token
void	cancel(java.lang.Long tokenId) Cancels the given token
void	cancelNFCToken(TokenActionDTO dto) Cancels the given NFC token.
SerializableInputStream	exportToCSV(TokenQuery query) Returns a CSV version of all returned tokens
InitializeNFCTagData	getInitializeNFCTagData() Returns data with the token types available to initialize a blank NFC tag. The available tokens to personalize the tag are returned too to allow initialization and personalization at the same time.
TokensListData	getListData(TokenPrincipalTypeVO tokenType, UserLocatorVO user) Returns data for listing tokens of a given type and user
PersonalizeNFCTagData	getPersonalizeNFCTagData(TokenPrincipalTypeVO tokenType, UserLocatorVO locator) Returns data needed to personalize a NFC tag for the specified type and user. The PersonalizeNFCTagData.CONFIRMATION_PASSWORD_INPUT will be null if the logged user manages the given user.
TokenSearchData	getSearchData(TokenPrincipalTypeVO tokenType) Returns data for searching tokens
InitializeNFCTagResult	initializeNFCTag(NFCTagInitializeDTO dto) Initializes and optionally personalize a NFC tag with the given data.
void	personalizeNFCTag(NFCTagPersonalizeDTO dto) Personalizes a NFC tag for the given user.
ExternalNFCTagAuthenticateData	requestForExternalAuthenticate(ExternalNFCTagAuthenticateDTO dto) This method must be invoked to start a mutual authentication process between the server and the NFC tag (e.g.
void	requestNewOTPForPersonalizeNFCTag(UserLocatorVO locator, TokenPrincipalTypeVO tokenTypeVO, OTPSendMedium medium) Generates a new OTP (removing any previous password, if any) and sends it to the user by the specified medium using the confirmation password type set for the BuiltInChannel.POS channel for the specified user. It has the same security controls as for personalizeNFCTag(NFCTagPersonalizeDTO), that is the logged user must be allowed to personalize a NFC Tag for the specified user.
Page<TokenVO>	search(TokenQuery query) Searches for tokens
void	unblock(java.lang.Long tokenId) Unblocks the given token

Methods inherited from interface org.cyclos.services.CRUDService

getData, getDataForNew, load, remove, removeAll, save

Method Detail

activatePending

void activatePending(java.lang.Long tokenId)
              throws FrameworkException

Activates the given token. This operation can only be done by admins or brokers over tokens of managed users.

Throws:

FrameworkException

assign

void assign(TokenActionDTO dto)
     throws FrameworkException,
            MaxTokenActivationAttemptsException,
            InvalidTokenException

Assigns and activates an unassigned token with the given type and value for the logged user.

Throws:

FrameworkException

MaxTokenActivationAttemptsException

InvalidTokenException

block

void block(java.lang.Long tokenId)
    throws FrameworkException

Blocks the given token

Throws:

FrameworkException

cancel

void cancel(java.lang.Long tokenId)
     throws FrameworkException

Cancels the given token

Throws:

FrameworkException

cancelNFCToken

void cancelNFCToken(TokenActionDTO dto)
             throws FrameworkException

Cancels the given NFC token. Admins and brokers with permissions can cancel a NFC token of type TokenType.NFC_TAG.
In case of a NFC token of type TokenType.NFC_DEVICE only the logged user can cancel its own token.

Throws:

FrameworkException

exportToCSV

SerializableInputStream exportToCSV(TokenQuery query)
                             throws FrameworkException

Returns a CSV version of all returned tokens

Throws:

FrameworkException

getInitializeNFCTagData

InitializeNFCTagData getInitializeNFCTagData()
                                      throws FrameworkException

Returns data with the token types available to initialize a blank NFC tag.
The available tokens to personalize the tag are returned too to allow initialization and personalization at the same time. Only allowed for managers (Brokers & Administrators).

Throws:

FrameworkException

See Also:

initializeNFCTag(NFCTagInitializeDTO)

getListData

TokensListData getListData(TokenPrincipalTypeVO tokenType,
                           UserLocatorVO user)
                    throws FrameworkException

Returns data for listing tokens of a given type and user

Throws:

FrameworkException

getPersonalizeNFCTagData

PersonalizeNFCTagData getPersonalizeNFCTagData(TokenPrincipalTypeVO tokenType,
                                               UserLocatorVO locator)
                                        throws FrameworkException

Returns data needed to personalize a NFC tag for the specified type and user.
The PersonalizeNFCTagData.CONFIRMATION_PASSWORD_INPUT will be null if the logged user manages the given user. The PersonalizeNFCTagData.TOKEN_TYPE is the token principal type the tag was initialized for.

Throws:

FrameworkException

getSearchData

TokenSearchData getSearchData(TokenPrincipalTypeVO tokenType)
                       throws FrameworkException

Returns data for searching tokens

Throws:

FrameworkException

initializeNFCTag

InitializeNFCTagResult initializeNFCTag(NFCTagInitializeDTO dto)
                                 throws FrameworkException,
                                        TokenAlreadyInUseException

Initializes and optionally personalize a NFC tag with the given data. If the NFCTagInitializeDTO.getUser() is not null then the token will be personalized for that user too. Returns the private keys (PICC Master Key (i.e. PMK), Application Master Key (i.e. AMK) and Operational key) to be stored into the tag.
Only allowed for managers (Brokers & Administrators).

Throws:

FrameworkException

TokenAlreadyInUseException

personalizeNFCTag

void personalizeNFCTag(NFCTagPersonalizeDTO dto)
                throws FrameworkException,
                       TokenAlreadyInUseException

Personalizes a NFC tag for the given user. If the logged user doesn't manages the user then the confirmation password of that user is required. This method requires a successful previous external authentication ( requestForExternalAuthenticate(ExternalNFCTagAuthenticateDTO))
The required NFCTagPersonalizeDTO.CYCLOS_CHALLENGE is the encrypted (hexadecimal string) challenge generated by the server (returned in the previous external authenticate) used to ensure the tag presence (internal authenticate)

Throws:

FrameworkException

TokenAlreadyInUseException

See Also:

requestForExternalAuthenticate(ExternalNFCTagAuthenticateDTO)

requestForExternalAuthenticate

ExternalNFCTagAuthenticateData requestForExternalAuthenticate(ExternalNFCTagAuthenticateDTO dto)
                                                       throws FrameworkException

This method must be invoked to start a mutual authentication process between the server and the NFC tag (e.g. a card) to prove that both share the same secret key.
The authentication process is carried out in the following order:

• Validate the identity of the server: external authenticate
• Validate the identity of the NFc tag: internal authenticate

Parameters:

dto - contains the token type id (required), the token value (optional) and an encrypted challenge (required) generated by the tag in hexadecimal notation. If the token value is null then means the authentication process will be using the PICC Master Key (PMK).

Returns:

data containing the following:

• ExternalNFCTagAuthenticateData.CYCLOS_CHALLENGE: encrypted data (hexadecimal string) containing both: a new challenge generated by the server (used to validate the identity of the NFC tag, internal authenticate) and the original challenge generated by the tag processed according to the tag's authentication process. The (processed) original tag challenge will be used by the NFC tag to complete the server identity validation (external authenticate).
• ExternalNFCTagAuthenticateData.SESSION_KEY: A session key needed by the tag to allow send enciphered data to be written into the NFC tag

Throws:

FrameworkException

requestNewOTPForPersonalizeNFCTag

void requestNewOTPForPersonalizeNFCTag(UserLocatorVO locator,
                                       TokenPrincipalTypeVO tokenTypeVO,
                                       OTPSendMedium medium)
                                throws FrameworkException,
                                       SmsSendingException

Generates a new OTP (removing any previous password, if any) and sends it to the user by the specified medium using the confirmation password type set for the BuiltInChannel.POS channel for the specified user.
It has the same security controls as for personalizeNFCTag(NFCTagPersonalizeDTO), that is the logged user must be allowed to personalize a NFC Tag for the specified user.

Parameters:

tokenTypeVO - the principal type used to personalize the card

medium - the medium used to send the OTP.

Throws:

SmsSendingException - only if medium is OTPSendMedium.BY_SMS and the OTP could not be sent to any enabled for sms phone.

FrameworkException

search

Page<TokenVO> search(TokenQuery query)
              throws FrameworkException,
                     QueryParseException

Searches for tokens

Throws:

FrameworkException

QueryParseException

unblock

void unblock(java.lang.Long tokenId)
      throws FrameworkException

Unblocks the given token

Throws:

FrameworkException