Table of Contents
Before we begin with the access control itself some introductorily notes about the module ID. Every module in OpenCA has a module-ID. This ID you can find in the configurationfile of a module. The ID is used to create unique serial numbers for the requests. The moduleshift defines how many bits at the beginning of a serial number (the least significant bits) are reserved for the module's ID. The advantage is that you can issue a request at any module of OpenCA without synchronizing the databases at every time you issue a request because the module's ID is part of every request serial. The parameter in the configurationfiles are ModuleID and ModuleShift. You can configure both parameters via ./configure. The options are --with-module-shift, --with-ra-module-id and --with-pub-module-id. The ID of the CA is at every time zero.
<openca> <access_control> The complete configuration should be here. </access_control> </openca>
channel verification
login
session management
ACLs
The channel configuration checks the parameters of the incoming connection to detect misconfigured apaches and obsolete clients. The values in the configuration are regular expressions except of the type. The type defines the type of the environmentvariables which should be tested. Today we support only mod_ssl.
Example 4.1. channel configuration
<channel> <type>mod_ssl</type> <protocol>ssl</protocol> <source>192.168.0.1</source> <asymmetric_cipher>.*</asymmetric_cipher> <asymmetric_keylength>0</asymmetric_keylength> <symmetric_cipher>.*</symmetric_cipher> <symmetric_keylength>128</symmetric_keylength> </channel>
none
passwd
x509
The first possibility means that there is no login and everybody who pass the channel verification can use the interface. This possibility is nothing else than the deactivation of the access control.
This is not only an option for debugging and testing. You can also use this option if you want to use a RA interface on a server which allows only RA access from the local machine but not over a remote computer.
<login> <type>none</type> </login>
Example 4.2. Login and Passphrase configuration
<login> <type>passwd</type> <database>internal</database> <passwd> <user> <name>root</name> <algorithm>sha1</algorithm> <digest>3Hbp8MAAbo+RngxRXGbbujmC94U</digest> <role>CA Operator</role> </user> <user>...</user> ... </passwd> </login>
We prepared a script to generate the digests. The name of the script is openca-digest and it will be installed during make install*. The program is used like "openca-digest (help|sha1|crypt|md5) string".
External authentication can be used to integrate authentication methods that are not natively supported by OpenCA. Essentially this method is a variant of the username/passwort authentiation.
External authentication requires an external program that receives the login credentials that were passed on the login screen via the environment. The external program then must verify if the username/password combination represents a valid login and return an appropriate exit code (0 for success).
The external program should take care of handling the username/password information properly, i. e. it should NOT write this information to files or pass these values to other programs on the command line. The latter is particularly important, as this might open security problems when processing untrusted user input (i. e. the login name or the password). If you must call external programs with this information, please take extra care to tidy the login information of illegal characters (such as quoting special characters). Specification of username or password as command arguments is not directory supported for exactly this reason. Use shell script wrappers that read environment variables instead.
Example 4.3. External program authentication configuration
In this example configuration two environment variables USERNAME and PASSWORD are set for the external program /usr/local/bin/authdummy. The special strings '__USER__' and '__PASSWORD__' are replaced with the actual user login information within environment value definitions. An arbitrary number of environment variables may be defined in the configuration file.<login> <type>passwd</type> <database>externalcommand</database> <setenv> <option> <name>USERNAME</name> <value>__USER__</value> </option> <option> <name>PASSWORD</name> <value>__PASSWD__</value> </option> </setenv> <command>/usr/local/bin/authdummy</command> </login>
#!/bin/bash if [ "$USERNAME" = "openca" -a "$PASSWORD" = "rocks" ] ; then exit 0 fi exit 1
Example 4.4. Authentication with certificates
<login <type>x509</type> <chain>OPENCADIR/var/crypto/chain</chain> </login>
The filtering of the users is not the job of the login because the login has only to identify the user. The filtering has to be implemented in the ACLs. Therefore we cannot recommend the x509 (smartcard) authentication until now.
Example 4.5. Session configuration
<session> <type>cookie</type> <directory>@var_prefix@/session/cookie</directory> <lifetime>1000</lifetime> <session>
Example 4.6. Basic ACL configuration
<acl_config> <acl>yes</acl> <list>@etc_prefix@/rbac/acl.xml</list> <command_dir>@etc_prefix@/rbac/cmds</command_dir> <module_id>0</module_id> <ca_cert>@var_prefix@/crypto/cacerts/cacert.pem</ca_cert> <map_role>no</map_role> <map_operation>no</map_operation> </acl_config>
enable (yes) or disable (no) the access control list - please notice that a deactivated ACL means that every user has full access to ALL OpenCA functions
defines the place of the ACL
specify the directory which contains the configuration files of the scripts
This is the id of the interface. This id is unique for every interface.
The CA certificate in PEM format is used to verify signatures. You can use here another certificate than of the CA which you control with this access control. This is useful if you have a user CA and a server CA. You can login into the interface of the server CA with a certificate from the user CA.
enable (yes) or disable (no) the mapping from certificates to roles if the certificate of the user is known. If the role is defined during passphrase based login then this option causes the use of the specified role and not the login name.
enable (yes) or disable (no) the mapping from the names of the scripts to the supplied operation
Example 4.7. Permission for serverInfo
<acl> <permission> <module>0<</module> <role>root<</root> <operation>serverInfo</operation> <owner></owner> </permission> <permission>...</permission> ... </acl>
every access right is defined in a permission element
this is the module id of the used web interface. Every installed gateway of OpenCA is a module in the terms of RBAC. If you install the RA then there is a new module with the id 1.
is the name of the user if map_role is no and the role of the certificate if map_role is yes. The roles are part of every role based system. OpenCA defines a set of default roles which you can simply extend by other roles which you need.
Every certificate will be assigned a role if it is issued on the CA. The role of a certificate service request is the role which the requests asks for. The role of a certificate revocation request is the role of the certificate to which the CRR belongs. The CA-certificate(s) and the CRLs have no explicit role because they have automatically the “superrole”. If there is an action where the user is not identified by a certificate then the role which is used is automatically the empty role. This is sometimes necessary for example if you want to control your public gateway by RBAC.
is the name of the script if map_operation is no and the operation of the script if map_role is yes.
is the role of the object which will be automatically detected by the configuration of the script
Example 4.8. Allow all
<acl> <permission> <module>.*</module> <role>.*</role> <operation>.*</operation> <owner>.*</owner> </permission> </acl>
This method is used if an operation affects a certificate and the role should be detected by the serial of the certificate.
This method is used if an operation affects a CSR and the role should be detected by the serial of the CSR.
This method is used if an operation affects a CRR and the role should be detected by the serial of the CRR. The CRR will be loaded and the certificate which should be revoked will be loaded and the role of the certificate is used.
The use of this method is not recommended because the role is not protected by any cryptographic mechanisms.
The operator must have the right to perform this operation for every role.
This method is used to signal that an object is handled which affects the CA directly (e.g. CA-certificate, CRL). The operator needs access to the “superrole”.