Version: current

# Class Security

Implements a basic security model

  Object
  ViewableData implements IteratorAggregate
  RequestHandler
  Controller
  Security

Package: sapphire\security
Located at sapphire/security/Security.php

## Methods summary

`public static` | # `get_word_list( )` Get location of word list file Get location of word list file
`public static` | # `set_word_list( string $wordListFile )` Set location of word list file Set location of word list file #### Parameters $wordListFile string $wordListFile Location of word list file
`public static` | # `set_default_message_set( string|array $messageSet )` Set the default message set used in permissions failures. Set the default message set used in permissions failures. #### Parameters $messageSet string|array $messageSet
`public static` | # `permissionFailure( `Controller` $controller = null, string|array $messageSet = null )` Register that we've had a permission failure trying to view the given page Register that we've had a permission failure trying to view the given page This will redirect to a login page. If you don't provide a messageSet, a default will be used. #### Parameters $controller Controller $controller The controller that you were on to cause the permission failure. $messageSet string|array $messageSet The message to show to the user. This can be a string, or a map of different messages for different contexts. If you pass an array, you can use the following keys: - default: The default message - logInAgain: The message to show if the user has just logged out and the - alreadyLoggedIn: The message to show if the user is already logged in and lacks the permission to access the item. The alreadyLoggedIn value can contain a '%s' placeholder that will be replaced with a link to log in.
`protected` | # `LoginForm( )` Get the login form to process according to the submitted data Get the login form to process according to the submitted data
`protected array` | # `GetLoginForms( )` Get the login forms for all available authentication methods Get the login forms for all available authentication methods #### Returns `array` Returns an array of available login forms (array of Form objects).
`public static string` | # `Link( string $action = null )` Get a link to a security action Get a link to a security action #### Parameters $action string $action Name of the action #### Returns `string` Returns the link to the given action
`public` | # `logout( boolean $redirect = true )` Log the currently logged in user out Log the currently logged in user out #### Parameters $redirect bool $redirect Redirect the user back to where they came. - If it's false, the code calling logout() is responsible for sending the user where-ever they should go.
`public string` | # `login( )` Show the "login" page Show the "login" page #### Returns `string` Returns the "login" page as HTML code.
`public` | # `basicauthlogin( )`
`public string` | # `lostpassword( )` Show the "lost password" page Show the "lost password" page #### Returns `string` Returns the "lost password" page as HTML code.
`public `Form`` | # `LostPasswordForm( )` Factory method for the lost password form Factory method for the lost password form #### Returns ``Form`` Returns the lost password form
`public string` | # `passwordsent( `SS_HTTPRequest` $request )` Show the "password sent" page, after a user has requested to reset their password. Show the "password sent" page, after a user has requested to reset their password. #### Parameters $request SS_HTTPRequest $request The SS_HTTPRequest for this action. #### Returns `string` Returns the "password sent" page as HTML code.
`public static` | # `getPasswordResetLink( string $autoLoginHash )` Create a link to the password reset form Create a link to the password reset form #### Parameters $autoLoginHash string $autoLoginHash The auto login hash
`public string` | # `changepassword( )` Show the "change password" page Show the "change password" page #### Returns `string` Returns the "change password" page as HTML code.
`public` | # `ping( )` Security/ping can be visited with ajax to keep a session alive. This is used in the CMS. Security/ping can be visited with ajax to keep a session alive. This is used in the CMS.
`public `Form`` | # `ChangePasswordForm( )` Factory method for the lost password form Factory method for the lost password form #### Returns ``Form`` Returns the lost password form
`public static boolean|`Member`` | # `authenticate( mixed $RAW_email, mixed $RAW_password )` Authenticate using the given email and password, returning the appropriate member object if Authenticate using the given email and password, returning the appropriate member object if #### Returns `boolean|`Member`` Returns FALSE if authentication fails, otherwise the member object #### See ``Security::setDefaultAdmin()``
`public static `Member`` | # `findAnAdministrator( )` Return an existing member with administrator privileges, or create one of necessary. Return an existing member with administrator privileges, or create one of necessary. Will create a default 'Administrators' group if no group is found with an ADMIN permission. Will create a new 'Admin' member with administrative permissions if no existing Member with these permissions is found. Important: Any newly created administrator accounts will NOT have valid login credentials (Email/Password properties), which means they can't be used for login purposes outside of any default credentials set through `Security::setDefaultAdmin()`. #### Returns ``Member`` Member
`public static` | # `setDefaultAdmin( string $username, string $password )` Set a default admin in dev-mode Set a default admin in dev-mode This will set a static default-admin which is not existing as a database-record. By this workaround we can test pages in dev-mode with a unified login. Submitted login-credentials are first checked against this static information in `Security::authenticate()`. #### Parameters $username string $username The user name $password string $password The password (in cleartext)
`public static boolean` | # `check_default_admin( string $username, string $password )` Checks if the passed credentials are matching the default-admin. Compares cleartext-password set through Security::setDefaultAdmin(). Checks if the passed credentials are matching the default-admin. Compares cleartext-password set through Security::setDefaultAdmin(). #### Parameters $username string $username $password string $password #### Returns `boolean` bool
`public static` | # `check_admin_ip( mixed $ip = null )`
`public static` | # `has_default_admin( )` Check that the default admin account has been set. Check that the default admin account has been set.
`public static` | # `setStrictPathChecking( boolean $strictPathChecking )` Set strict path checking Set strict path checking This prevents sharing of the session across several sites in the domain. #### Parameters $strictPathChecking boolean $strictPathChecking To enable or disable strict patch checking.
`public static boolean` | # `getStrictPathChecking( )` Get strict path checking Get strict path checking #### Returns `boolean` Status of strict path checking
`public static` | # `encrypt_passwords( boolean $encrypt )` Set if passwords should be encrypted or not Set if passwords should be encrypted or not #### Deprecated 2.4 Use PasswordEncryptor_None instead. #### Parameters $encrypt bool $encrypt Set to TRUE if you want that all (new) passwords will be stored encrypted, FALSE if you want to store the passwords in clear text.
`public static array` | # `get_encryption_algorithms( )` Get a list of all available encryption algorithms. Note: These are arbitrary codes, and not callable methods. Get a list of all available encryption algorithms. Note: These are arbitrary codes, and not callable methods. #### Deprecated 2.4 Use PasswordEncryptor::get_encryptors() #### Returns `array` Returns an array of strings containing all supported encryption algorithms.
`public static boolean` | # `set_password_encryption_algorithm( string $algorithm )` Set the password encryption algorithm Set the password encryption algorithm #### Parameters $algorithm string $algorithm One of the available password encryption algorithms determined by `Security::get_encryption_algorithms()` #### Returns `boolean` Returns TRUE if the passed algorithm was valid, otherwise FALSE.
`public static String` | # `get_password_encryption_algorithm( )` #### Returns `String` String
`public static mixed` | # `encrypt_password( string $password, string $salt = null, string $algorithm = null, `Member` $member = null )` Encrypt a password according to the current password encryption settings. If the settings are so that passwords shouldn't be encrypted, the result is simple the clear text password with an empty salt except when a custom algorithm ($algorithm parameter) was passed. Encrypt a password according to the current password encryption settings. If the settings are so that passwords shouldn't be encrypted, the result is simple the clear text password with an empty salt except when a custom algorithm ($algorithm parameter) was passed. #### Parameters $password string $password The password to encrypt $salt string $salt Optional: The salt to use. If it is not passed, but needed, the method will automatically create a random salt that will then be returned as return value. $algorithm string $algorithm Optional: Use another algorithm to encrypt the password (so that the encryption algorithm can be changed over the time). $member Member $member Optional #### Returns `mixed` Returns an associative array containing the encrypted password and the used salt in the form: <code> array( 'password' => string, 'salt' => string, 'algorithm' => string, 'encryptor' => PasswordEncryptor instance ) </code> If the passed algorithm is invalid, FALSE will be returned. #### See ``Security::encrypt_passwords()`` ``Security::set_password_encryption_algorithm()``
`public static boolean` | # `database_is_ready( )` Checks the database is in a state to perform security checks. See DatabaseAdmin->init() for more information. Checks the database is in a state to perform security checks. See DatabaseAdmin->init() for more information. #### Returns `boolean` bool
`public static` | # `set_login_recording( boolean $bool )` Enable or disable recording of login attempts through the LoginRecord object. Enable or disable recording of login attempts through the LoginRecord object. #### Parameters $bool boolean $bool
`public static boolean` | # `login_recording( )` #### Returns `boolean` boolean
`public static` | # `set_default_login_dest( mixed $dest )` Set the default login dest This is the URL that users will be redirected to after they log in, if they haven't logged in en route to access a secured page. Set the default login dest This is the URL that users will be redirected to after they log in, if they haven't logged in en route to access a secured page. By default, this is set to the homepage
`public static` | # `default_login_dest( )` Get the default login dest Get the default login dest

### Methods inherited from Controller

`CurrentMember()`, `Now()`, `PastMember()`, `PastVisitor()`, `can()`, `curr()`, `defaultAction()`, `disableBasicAuth()`, `getAction()`, `getFormOwner()`, `getRequest()`, `getResponse()`, `getSession()`, `getURLParams()`, `getViewer()`, `handleAction()`, `handleRequest()`, `hasAction()`, `hasActionTemplate()`, `has_curr()`, `init()`, `isAjax()`, `join_links()`, `popCurrent()`, `pushCurrent()`, `redirect()`, `redirectBack()`, `redirectedTo()`, `render()`, `setSession()`, `setURLParams()`

### Methods inherited from RequestHandler

`__construct()`, `allowedActions()`, `checkAccessAction()`, `httpError()`

### Methods inherited from ViewableData

`ATT_val()`, `BaseHref()`, `CSSClasses()`, `ColumnBreak()`, `ColumnCalc()`, `ColumnNumber()`, `ColumnPad()`, `ColumnPos()`, `CurrentPage()`, `Debug()`, `Even()`, `EvenOdd()`, `First()`, `FirstLast()`, `HasPerm()`, `IsAjax()`, `JS_val()`, `Last()`, `Me()`, `Middle()`, `MiddleString()`, `Modulus()`, `MultipleOf()`, `Odd()`, `Pos()`, `RAW_val()`, `SQL_val()`, `ThemeDir()`, `ThemeName()`, `Top()`, `TotalItems()`, `XML_val()`, `__get()`, `__isset()`, `__set()`, `buildCastingCache()`, `cachedCall()`, `castingClass()`, `castingHelper()`, `castingHelperPair()`, `castingObjectCreator()`, `castingObjectCreatorPair()`, `customise()`, `defineMethods()`, `escapeTypeForField()`, `getField()`, `getIterator()`, `getSecurityID()`, `getXMLValues()`, `hasField()`, `hasValue()`, `i18nLocale()`, `iteratorProperties()`, `obj()`, `renderWith()`, `setCustomisedObj()`, `setField()`

### Methods inherited from Object

`__call()`, `__toString()`, `__wakeup()`, `addMethodsFrom()`, `addStaticVars()`, `addWrapperMethod()`, `add_extension()`, `add_static_var()`, `allMethodNames()`, `cacheToFile()`, `cacheToFileWithArgs()`, `clearCache()`, `combined_static()`, `create()`, `createMethod()`, `create_from_string()`, `exists()`, `extInstance()`, `extend()`, `getCustomClass()`, `getExtensionInstance()`, `getExtensionInstances()`, `get_extensions()`, `get_static()`, `hasExtension()`, `hasMethod()`, `has_extension()`, `invokeWithExtensions()`, `is_a()`, `loadCache()`, `parentClass()`, `parse_class_spec()`, `remove_extension()`, `sanitiseCachename()`, `saveCache()`, `set_stat()`, `set_static()`, `set_uninherited()`, `stat()`, `strong_create()`, `uninherited()`, `uninherited_static()`, `useCustomClass()`

### Magic methods summary

## Properties summary

`protected static string` | $default_username | # Default user name. Only used in dev-mode by `Security::setDefaultAdmin()` Default user name. Only used in dev-mode by `Security::setDefaultAdmin()` #### See ``Security::setDefaultAdmin()``
`protected static string` | $default_password | # Default password. Only used in dev-mode by `Security::setDefaultAdmin()` Default password. Only used in dev-mode by `Security::setDefaultAdmin()` #### See ``Security::setDefaultAdmin()``
`protected static boolean` | $strictPathChecking | # If set to TRUE to prevent sharing of the session across several sites in the domain. If set to TRUE to prevent sharing of the session across several sites in the domain.
`protected static boolean` | $encryptPasswords | # Should passwords be stored encrypted? Should passwords be stored encrypted? #### Deprecated 2.4 Please use 'none' as the default $encryptionAlgorithm instead
`protected static string` | $encryptionAlgorithm | # The password encryption algorithm to use by default. This is an arbitrary code registered through `PasswordEncryptor`. The password encryption algorithm to use by default. This is an arbitrary code registered through `PasswordEncryptor`.
`protected static boolean` | $useSalt | # Should a salt be used for the password encryption? Should a salt be used for the password encryption? #### Deprecated 2.4 Please use a custom `PasswordEncryptor` instead
`public static boolean` | $autologin_enabled | # Showing "Remember me"-checkbox on loginform, and saving encrypted credentials to a cookie. Showing "Remember me"-checkbox on loginform, and saving encrypted credentials to a cookie.
`protected static string` | $wordlist | # Location of word list to use for generating passwords Location of word list to use for generating passwords
`public static string` | $template_main | # Template thats used to render the pages. Template thats used to render the pages.
`protected static array|string` | $default_message_set | # Default message set used in permission failures. Default message set used in permission failures.
`protected static boolean` | $login_recording | # Enable or disable recording of login attempts through the LoginRecord object. Enable or disable recording of login attempts through the LoginRecord object.
`protected static string` | $default_login_dest | #

### Properties inherited from Controller

`$action`, `$allowed_actions`, `$baseInitCalled`, `$basicAuthEnabled`, `$controller_stack`, `$request`, `$requestParams`, `$response`, `$session`, `$urlParams`, `$url_handlers`

### Properties inherited from RequestHandler

`$brokenOnConstruct`

### Properties inherited from ViewableData

`$casting`, `$customisedObject`, `$default_cast`, `$failover`, `$iteratorPos`, `$iteratorTotalItems`

### Properties inherited from Object

`$class`, `$extension_instances`, `$extensions`

[Raise a SilverStripe Framework issue/bug](https://github.com/silverstripe/silverstripe-framework/issues/new)
- [Raise a SilverStripe CMS issue/bug](https://github.com/silverstripe/silverstripe-cms/issues/new)
- Please use the Silverstripe Forums to ask development related questions. -