Package org.cyclos.security.access

Class TokenServiceSecurity

java.lang.Object

org.cyclos.impl.AbstractServerComponent

org.cyclos.impl.AbstractNetworkedServerComponent

org.cyclos.security.BaseServiceSecurity

org.cyclos.security.CRUDServiceSecurity<TokenDTO,Token,TokenData,TokenDataParams>

org.cyclos.security.access.TokenServiceSecurity

All Implemented Interfaces:

TokenService, CRUDService<TokenDTO,TokenData,TokenDataParams>, CRUDWithConfirmationPasswordService<TokenDTO,TokenData,TokenDataParams>, Service

@Security
public class TokenServiceSecurity
extends CRUDServiceSecurity<TokenDTO,Token,TokenData,TokenDataParams>
implements TokenService

Security for TokenService

Field Summary

Fields inherited from class org.cyclos.security.CRUDServiceSecurity

entityClass

Fields inherited from class org.cyclos.impl.AbstractNetworkedServerComponent

authHandler, conversionHandler, customFieldValueHandler, entityManagerHandler, groupsHandler, productsHandler, restBeanPropertyMapping, userLocatorHandler

Fields inherited from class org.cyclos.impl.AbstractServerComponent

accountHandler, configurationHandler, dataTranslationHandler, notificationHandler, profileFieldHandler, transactionHandler, translationHandler

Constructor Summary

Constructors

Constructor	Description
TokenServiceSecurity()

Method Summary

Modifier and Type	Method	Description
Long	activate(TokenActionDTO dto, UserLocatorVO locator)	Searches for a token with the given type and value specified in the TokenActionDTO parameter. The token's status must be TokenStatus.UNASSIGNED orTokenStatus.PENDING_ACTIVATION but assigned to the logged user or one of its operators. If the token is unassigned then this method assigns it to the user specified by the UserLocatorVO parameter and change its status to TokenStatus.ACTIVE. Otherwise (the token is already assigned and is pending by activation) it activates only. This method can be used only by members (i.e.
void	activatePending(Long tokenId)	Activates an already assigned token with status TokenStatus.PENDING_ACTIVATION. This operation can only be done by admins/brokers over tokens of managed users or member over tokens of its operators with permission to activate the corresponding TokenPrincipalTypeVO.
void	assign(@NotNull Long tokenId, @NotNull UserLocatorVO user)	Assigns a pending token to a user, leaving it in pending status The token status must be TokenStatus.UNASSIGNED.
SerializableInputStream	barcode(TokenBarcodeParams params)	Returns a barcode image of the token
void	block(Long tokenId)	Blocks the given token
void	cancel(Long tokenId)	Cancels the given token
void	cancelNFCToken(TokenActionDTO dto)	Cancels the given NFC token.
protected void	checkCreateNew(TokenDataParams params)	Checks whether creating new entities with the given context parameters is allowed, throwing PermissionDeniedException if not
DeviceConfirmationVO	createDeviceConfirmationForPersonalizeNFCTag(@NotNull UserLocatorVO locator, @NotNull TokenPrincipalTypeVO tokenTypeVO)	Creates a new pending device confirmation for the specified user.
protected void	customizeData(TokenData data)	Can be overridden in order to process the returned data object for the given entity
SerializableInputStream	deviceConfirmationBarcodeForPersonalizeNFCTag(UserLocatorVO locator, @NotNull TokenPrincipalTypeVO tokenTypeVO, DeviceConfirmationBarcodeParams params)	Generates a two-dimensional barcode (QR code), only if the confirmation was not already approved nor rejected for the given payer.
protected boolean	doHasManageAccess(Token entity)	Should be implemented in order to return whether the caller is allowed to manage the given entity, for the given operation
boolean	doHasViewAccess(Token token)	Should be implemented in order to return whether the caller is allowed to view the given entity.
FileInfo	exportTokens(@NotNull ExportFormatVO format, @NotNull TokenQuery query)	Exports the token search results to file
protected CRUDServiceLocal<Token,TokenDTO,TokenData,TokenDataParams>	getImplementation()	Should be implemented in order to return the actual implementation of the service
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 locator)	Returns data for listing tokens of a given type and user
PersonalizeNFCTagData	getPersonalizeNFCTagData(TokenPrincipalTypeVO tokenTypeVO, 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
boolean	hasPermissionToPersonalizeAtRegistration(UserGroup group, NFCTokenPrincipalType type, boolean asMember)	Returns true if the logged user can personalize a token for the given type and also checks the user can register new users for the specified group.
InitializeNFCTagResult	initializeNFCTag(NFCTagInitializeDTO dto)	Initializes and optionally personalize a NFC tag with the given data.
boolean	isAccessible(SessionData sessionData, Token entity)	Must be implemented in order to determine whether the given entity is accessible for the given session data.
protected void	onBeforeSave(TokenDTO dto, Token entity)
void	personalizeNFCTag(NFCTagPersonalizeDTO dto)	Personalizes a NFC tag for the given user.
void	removeDeviceConfirmationForPersonalizeNFCTag(@NotNull UserLocatorVO locator, @NotNull TokenPrincipalTypeVO tokenTypeVO, String deviceConfirmationId)	Removes a device confirmation 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, SendMedium 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 TokenService.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	setActivationDeadline(@NotNull Long tokenId, DateTime date)	Changes the token activation deadline date.
void	setExpiryDate(@NotNull Long tokenId, DateTime date)	Changes the token expiry date.
void	unblock(Long tokenId)	Unblocks the given token
DeviceConfirmationVO	viewDeviceConfirmationForPersonalizeNFCTag(@NotNull UserLocatorVO locator, @NotNull TokenPrincipalTypeVO tokenTypeVO, String deviceConfirmationId)	Loads the details of a confirmation belonging to the given user.

Methods inherited from class org.cyclos.security.CRUDServiceSecurity

canPerformOperation, canViewData, checkManageAccess, checkOperation, checkSave, checkViewAccess, find, getConfirmationPasswordInputForRemove, getData, getDataForNew, getEntityClass, hasManageAccess, hasViewAccess, load, remove, removeAll, removeAllWithConfirmationPassword, removeWithConfirmationPassword, resolveEntityCheck, save, saveWithConfirmationPassword

Methods inherited from class org.cyclos.security.BaseServiceSecurity

checkGuest, checkId, checkIds, checkInternalName, checkLoggedIn, checkManagesUser, checkRelatesToUser, checkScope, checkVO, checkVOs, doInitialize, getEntityCheckRegistry, getUser, initialize

Methods inherited from class org.cyclos.impl.AbstractNetworkedServerComponent

canManage, checkManagesUser, checkPermission, checkRelatesToUser, checkValue, clearAlreadyValidated, getBaseEntityManagerHandler, getConfiguration, getLoggedBasicUser, getLoggedUser, getProducts, getTranslatedName, getTranslatedValue, hasPermission, hasValue, inSameNetwork, inSameNetworkOrGlobal, isAdmin, isAlreadyValidated, isBroker, isGlobalAdmin, isGlobalAdminInNetwork, isGuest, isLoggedIn, isMember, isMemberOnly, isNetworkAdmin, isOperator, isRelatedToUser, isSystem, isUserManager, isUserManagerOf, message, message, permission, permission, permissionOptionalValue, permissionOptionalValue, setAlreadyValidated, toDate, toDateTime, validate

Methods inherited from class org.cyclos.impl.AbstractServerComponent

dataTranslationProxy, dataTranslationProxy, delete, detach, doDataTranslationProxy, find, flush, from, getApplicationContext, getFormatter, getFormatter, getFormatter, getLogger, getRemoteAddress, getSessionData, mailContentBuilder, message, message, persist, processBatch, processBatch, refresh, remove, selectFrom, subQuery, update

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.cyclos.services.CRUDService

getData, getDataForNew, load, remove, removeAll, save

Constructor Detail

TokenServiceSecurity

public TokenServiceSecurity()

Method Detail

activate

public Long activate(TokenActionDTO dto,
                     UserLocatorVO locator)

Description copied from interface: TokenService

Searches for a token with the given type and value specified in the TokenActionDTO parameter.
The token's status must be TokenStatus.UNASSIGNED orTokenStatus.PENDING_ACTIVATION but assigned to the logged user or one of its operators.
If the token is unassigned then this method assigns it to the user specified by the UserLocatorVO parameter and change its status to TokenStatus.ACTIVE.
Otherwise (the token is already assigned and is pending by activation) it activates only.
This method can be used only by members (i.e. not administrators) with permission to activate the corresponding TokenPrincipalTypeVO. For administrators / brokers, see TokenService.activatePending(Long)

Specified by:

activate in interface TokenService

activatePending

public void activatePending(Long tokenId)

Description copied from interface: TokenService

Activates an already assigned token with status TokenStatus.PENDING_ACTIVATION.
This operation can only be done by admins/brokers over tokens of managed users or member over tokens of its operators with permission to activate the corresponding TokenPrincipalTypeVO.

Specified by:

activatePending in interface TokenService

assign

public void assign(@NotNull
                   @NotNull Long tokenId,
                   @NotNull
                   @NotNull UserLocatorVO user)
            throws FrameworkException

Description copied from interface: TokenService

Assigns a pending token to a user, leaving it in pending status The token status must be TokenStatus.UNASSIGNED.

Specified by:

assign in interface TokenService

Throws:

FrameworkException

barcode

public SerializableInputStream barcode(TokenBarcodeParams params)
                                throws FrameworkException

Description copied from interface: TokenService

Returns a barcode image of the token

Specified by:

barcode in interface TokenService

Throws:

FrameworkException

block

public void block(Long tokenId)

Description copied from interface: TokenService

Blocks the given token

Specified by:

block in interface TokenService

cancel

public void cancel(Long tokenId)

Description copied from interface: TokenService

Cancels the given token

Specified by:

cancel in interface TokenService

cancelNFCToken

public void cancelNFCToken(TokenActionDTO dto)

Description copied from interface: TokenService

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.

Specified by:

cancelNFCToken in interface TokenService

createDeviceConfirmationForPersonalizeNFCTag

public DeviceConfirmationVO createDeviceConfirmationForPersonalizeNFCTag(@NotNull
                                                                         @NotNull UserLocatorVO locator,
                                                                         @NotNull
                                                                         @NotNull TokenPrincipalTypeVO tokenTypeVO)
                                                                  throws FrameworkException

Description copied from interface: TokenService

Creates a new pending device confirmation for the specified user. The logged user will be notified after the confirmation was processed. It has the same security controls as for TokenService.personalizeNFCTag(NFCTagPersonalizeDTO), that is the logged user must be allowed to personalize a NFC Tag for the specified user.

Specified by:

createDeviceConfirmationForPersonalizeNFCTag in interface TokenService

tokenTypeVO - the principal type used to personalize the card

Throws:

FrameworkException

deviceConfirmationBarcodeForPersonalizeNFCTag

public SerializableInputStream deviceConfirmationBarcodeForPersonalizeNFCTag(UserLocatorVO locator,
                                                                             @NotNull
                                                                             @NotNull TokenPrincipalTypeVO tokenTypeVO,
                                                                             DeviceConfirmationBarcodeParams params)
                                                                      throws FrameworkException

Description copied from interface: TokenService

Generates a two-dimensional barcode (QR code), only if the confirmation was not already approved nor rejected for the given payer. It has the same security controls as for TokenService.personalizeNFCTag(NFCTagPersonalizeDTO), that is the logged user must be allowed to personalize a NFC Tag for the specified user.

Specified by:

deviceConfirmationBarcodeForPersonalizeNFCTag in interface TokenService

tokenTypeVO - the principal type used to personalize the card

Throws:

FrameworkException

doHasViewAccess

public boolean doHasViewAccess(Token token)

Description copied from class: CRUDServiceSecurity

Should be implemented in order to return whether the caller is allowed to view the given entity.

Specified by:

doHasViewAccess in class CRUDServiceSecurity<TokenDTO,Token,TokenData,TokenDataParams>

exportTokens

public FileInfo exportTokens(@NotNull
                             @NotNull ExportFormatVO format,
                             @NotNull
                             @NotNull TokenQuery query)
                      throws FrameworkException

Description copied from interface: TokenService

Exports the token search results to file

Specified by:

exportTokens in interface TokenService

Throws:

FrameworkException

getInitializeNFCTagData

public InitializeNFCTagData getInitializeNFCTagData()
                                             throws FrameworkException

Description copied from interface: TokenService

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

Specified by:

getInitializeNFCTagData in interface TokenService

Throws:

FrameworkException

See Also:

TokenService.initializeNFCTag(NFCTagInitializeDTO)

getListData

public TokensListData getListData(TokenPrincipalTypeVO tokenType,
                                  UserLocatorVO locator)
                           throws FrameworkException

Description copied from interface: TokenService

Returns data for listing tokens of a given type and user

Specified by:

getListData in interface TokenService

Throws:

FrameworkException

getPersonalizeNFCTagData

public PersonalizeNFCTagData getPersonalizeNFCTagData(TokenPrincipalTypeVO tokenTypeVO,
                                                      UserLocatorVO locator)
                                               throws FrameworkException

Description copied from interface: TokenService

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.

Specified by:

getPersonalizeNFCTagData in interface TokenService

Throws:

FrameworkException

getSearchData

public TokenSearchData getSearchData(TokenPrincipalTypeVO tokenType)
                              throws FrameworkException

Description copied from interface: TokenService

Returns data for searching tokens

Specified by:

getSearchData in interface TokenService

Throws:

FrameworkException

hasPermissionToPersonalizeAtRegistration

public boolean hasPermissionToPersonalizeAtRegistration(UserGroup group,
                                                        NFCTokenPrincipalType type,
                                                        boolean asMember)

Returns true if the logged user can personalize a token for the given type and also checks the user can register new users for the specified group.

Parameters:

asMember - Only used if the logged user is a broker.

Returns:

initializeNFCTag

public InitializeNFCTagResult initializeNFCTag(NFCTagInitializeDTO dto)
                                        throws FrameworkException

Description copied from interface: TokenService

Initializes and optionally personalize a NFC tag with the given data. If the TokenActionWithUserDTO.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).

Specified by:

initializeNFCTag in interface TokenService

Throws:

FrameworkException

isAccessible

public boolean isAccessible(SessionData sessionData,
                            Token entity)

Description copied from class: CRUDServiceSecurity

Must be implemented in order to determine whether the given entity is accessible for the given session data. This method shouldn't check the same condition as CRUDServiceSecurity.hasViewAccess(BaseEntity). If the only condition for an entity is CRUDServiceSecurity.hasViewAccess(BaseEntity), this method should return false.

Specified by:

isAccessible in class CRUDServiceSecurity<TokenDTO,Token,TokenData,TokenDataParams>

personalizeNFCTag

public void personalizeNFCTag(NFCTagPersonalizeDTO dto)
                       throws FrameworkException

Description copied from interface: TokenService

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 ( TokenService.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)

Specified by:

personalizeNFCTag in interface TokenService

Throws:

FrameworkException

See Also:

TokenService.requestForExternalAuthenticate(ExternalNFCTagAuthenticateDTO)

removeDeviceConfirmationForPersonalizeNFCTag

public void removeDeviceConfirmationForPersonalizeNFCTag(@NotNull
                                                         @NotNull UserLocatorVO locator,
                                                         @NotNull
                                                         @NotNull TokenPrincipalTypeVO tokenTypeVO,
                                                         String deviceConfirmationId)
                                                  throws FrameworkException

Description copied from interface: TokenService

Removes a device confirmation for the given user. It has the same security controls as for TokenService.personalizeNFCTag(NFCTagPersonalizeDTO), that is the logged user must be allowed to personalize a NFC Tag for the specified user.

Specified by:

removeDeviceConfirmationForPersonalizeNFCTag in interface TokenService

tokenTypeVO - the principal type used to personalize the card

Throws:

FrameworkException

requestForExternalAuthenticate

public ExternalNFCTagAuthenticateData requestForExternalAuthenticate(ExternalNFCTagAuthenticateDTO dto)
                                                              throws FrameworkException

Description copied from interface: TokenService

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

Specified by:

requestForExternalAuthenticate in interface TokenService

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

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

Description copied from interface: TokenService

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 TokenService.personalizeNFCTag(NFCTagPersonalizeDTO), that is the logged user must be allowed to personalize a NFC Tag for the specified user.

Specified by:

requestNewOTPForPersonalizeNFCTag in interface TokenService

tokenTypeVO - the principal type used to personalize the card

medium - the medium used to send the OTP.

Throws:

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

FrameworkException

search

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

Description copied from interface: TokenService

Searches for tokens. This method can only be user by administrators or brokers.

Specified by:

search in interface TokenService

Throws:

FrameworkException

QueryParseException

setActivationDeadline

public void setActivationDeadline(@NotNull
                                  @NotNull Long tokenId,
                                  DateTime date)
                           throws FrameworkException

Description copied from interface: TokenService

Changes the token activation deadline date. The token status must be either TokenStatus.PENDING_ACTIVATION or TokenStatus.ACTIVATION_EXPIRED.

Specified by:

setActivationDeadline in interface TokenService

Throws:

FrameworkException

setExpiryDate

public void setExpiryDate(@NotNull
                          @NotNull Long tokenId,
                          DateTime date)
                   throws FrameworkException

Description copied from interface: TokenService

Changes the token expiry date. The token status must be either TokenStatus.ACTIVE, TokenStatus.BLOCKED or TokenStatus.EXPIRED.

Specified by:

setExpiryDate in interface TokenService

Throws:

FrameworkException

unblock

public void unblock(Long tokenId)

Description copied from interface: TokenService

Unblocks the given token

Specified by:

unblock in interface TokenService

viewDeviceConfirmationForPersonalizeNFCTag

public DeviceConfirmationVO viewDeviceConfirmationForPersonalizeNFCTag(@NotNull
                                                                       @NotNull UserLocatorVO locator,
                                                                       @NotNull
                                                                       @NotNull TokenPrincipalTypeVO tokenTypeVO,
                                                                       String deviceConfirmationId)
                                                                throws FrameworkException

Description copied from interface: TokenService

Loads the details of a confirmation belonging to the given user. It has the same security controls as for TokenService.personalizeNFCTag(NFCTagPersonalizeDTO), that is the logged user must be allowed to personalize a NFC Tag for the specified user.

Specified by:

viewDeviceConfirmationForPersonalizeNFCTag in interface TokenService

tokenTypeVO - the principal type used to personalize the card

Throws:

FrameworkException

checkCreateNew

protected void checkCreateNew(TokenDataParams params)

Description copied from class: CRUDServiceSecurity

Checks whether creating new entities with the given context parameters is allowed, throwing PermissionDeniedException if not

Specified by:

checkCreateNew in class CRUDServiceSecurity<TokenDTO,Token,TokenData,TokenDataParams>

customizeData

protected void customizeData(TokenData data)

Description copied from class: CRUDServiceSecurity

Can be overridden in order to process the returned data object for the given entity

Overrides:

customizeData in class CRUDServiceSecurity<TokenDTO,Token,TokenData,TokenDataParams>

doHasManageAccess

protected boolean doHasManageAccess(Token entity)

Description copied from class: CRUDServiceSecurity

Should be implemented in order to return whether the caller is allowed to manage the given entity, for the given operation

Specified by:

doHasManageAccess in class CRUDServiceSecurity<TokenDTO,Token,TokenData,TokenDataParams>

getImplementation

protected CRUDServiceLocal<Token,TokenDTO,TokenData,TokenDataParams> getImplementation()

Description copied from class: CRUDServiceSecurity

Should be implemented in order to return the actual implementation of the service

Specified by:

getImplementation in class CRUDServiceSecurity<TokenDTO,Token,TokenData,TokenDataParams>

onBeforeSave

protected void onBeforeSave(TokenDTO dto,
                            Token entity)

Overrides:

onBeforeSave in class CRUDServiceSecurity<TokenDTO,Token,TokenData,TokenDataParams>