diff options
Diffstat (limited to 'base/tps/man/man5')
-rw-r--r-- | base/tps/man/man5/pki-tps-connector.5 | 217 | ||||
-rw-r--r-- | base/tps/man/man5/pki-tps-profile.5 | 204 |
2 files changed, 421 insertions, 0 deletions
diff --git a/base/tps/man/man5/pki-tps-connector.5 b/base/tps/man/man5/pki-tps-connector.5 new file mode 100644 index 000000000..85b6792d6 --- /dev/null +++ b/base/tps/man/man5/pki-tps-connector.5 @@ -0,0 +1,217 @@ +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH pki-tps-connector 5 "April 22, 2014" "version 10.2" "PKI TPS Connector Configuration" Dogtag Team +.\" Please adjust this date whenever revising the man page. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp <n> insert n+1 empty lines +.\" for man page specific macros, see man(7) +.SH NAME +PKI TPS Connector Configuration + +.SH LOCATION +/var/lib/pki/<instance>/conf/tps/CS.cfg + +.SH DESCRIPTION + +TPS connector provides a mechanism for TPS to communicate with other PKI subsystems. +There are three supported connector types: CA, KRA, and TKS. The connectors are +defined using properties in the TPS configuration file. + +.SH CA CONNECTOR + +A CA connector is defined using properties that begin with tps.connector.ca<n> where +n is a positive integer indicating the ID of the CA connector. + +.SS tps.connector.ca<n>.enable + +This property contains a boolean value indicating whether the connector is enabled. + +.SS tps.connector.ca<n>.host + +In no-failover configuration, the property contains the hostname of the CA. + +In failover configuration, the property contains a list of hostnames and port numbers +of the CA subsystems. The format is hostname:port separated by spaces. + +.SS tps.connector.ca<n>.port + +In no-failover configuration, the property contains the port number of the CA. + +.SS tps.connector.ca<n>.nickName + +This property contains the nickname of the TPS subsystem certificate for SSL client +authentication to the CA. + +.SS tps.connector.ca<n>.minHttpConns + +This property contains the minimum number of HTTP connections. + +.SS tps.connector.ca<n>.maxHttpConns + +This property contains the maximum number of HTTP connections. + +.SS tps.connector.ca<n>.uri.<op> + +This property contains the URI to contact CA for the operation <op>. +Example ops: enrollment, renewal, revoke, unrevoke. + +.SS tps.connector.ca<n>.timeout + +This property contains the connection timeout. + +.SH KRA CONNECTOR + +A KRA connector is defined using properties that begin with tps.connector.kra<n> where +n is a positive integer indicating the ID of the KRA connector. + +.SS tps.connector.kra<n>.enable + +This property contains a boolean value indicating whether the connector is enabled. + +.SS tps.connector.kra<n>.host + +In no-failover configuration, the property contains the hostname of the KRA. + +In failover configuration, the property contains a list of hostnames and port numbers +of the KRA subsystems. The format is hostname:port separated by spaces. + +.SS tps.connector.kra<n>.port + +In no-failover configuration, the property contains the port number of the KRA. + +.SS tps.connector.kra<n>.nickName + +This property contains the nickname of the TPS subsystem certificate for SSL client +authentication to the KRA. + +.SS tps.connector.kra<n>.minHttpConns + +This property contains the minimum number of HTTP connections. + +.SS tps.connector.kra<n>.maxHttpConns + +This property contains the maximum number of HTTP connections. + +.SS tps.connector.kra<n>.uri.<op> + +This property contains the URI to contact KRA for the operation <op>. +Example ops: GenerateKeyPair, TokenKeyRecovery. + +.SS tps.connector.kra<n>.timeout + +This property contains the connection timeout. + +.SH TKS CONNECTOR + +A TKS connector is defined using properties that begin with tps.connector.tks<n> where +n is a positive integer indicating the ID of the TKS connector. + +.SS tps.connector.tks<n>.enable + +This property contains a boolean value indicating whether the connector is enabled. + +.SS tps.connector.tks<n>.host + +In no-failover configuration, the property contains the hostname of the TKS. + +In failover configuration, the property contains a list of hostnames and port numbers +of the TKS subsystems. The format is hostname:port separated by spaces. + +.SS tps.connector.tks<n>.port + +In no-failover configuration, the property contains the port number of the TKS. + +.SS tps.connector.tks<n>.nickName + +This property contains the nickname of the TPS subsystem certificate for SSL client +authentication to the TKS. + +.SS tps.connector.tks<n>.minHttpConns + +This property contains the minimum number of HTTP connections. + +.SS tps.connector.tks<n>.maxHttpConns + +This property contains the maximum number of HTTP connections. + +.SS tps.connector.tks<n>.uri.<op> + +This property contains the URI to contact TKS for the operation <op>. +Example ops: computeRandomData, computeSessionKey, createKeySetData, encryptData. + +.SS tps.connector.tks<n>.timeout + +This property contains the connection timeout. + +.SS tps.connector.tks<n>.generateHostChallenge + +This property contains a boolean value indicating whether to generate host challenge. + +.SS tps.connector.tks<n>.serverKeygen + +This property contains a boolean value indicating whether to generate keys on server side. + +.SS tps.connector.tks<n>.keySet + +This property contains the key set to be used on TKS. + +.SS tps.connector.tks<n>.tksSharedSymKeyName + +This property contains the shared secret key name. + +.SH EXAMPLE + +.nf +tps.connector.ca1.enable=true +tps.connector.ca1.host=server.example.com +tps.connector.ca1.port=8443 +tps.connector.ca1.minHttpConns=1 +tps.connector.ca1.maxHttpConns=15 +tps.connector.ca1.nickName=subsystemCert cert-pki-tomcat TPS +tps.connector.ca1.timeout=30 +tps.connector.ca1.uri.enrollment=/ca/ee/ca/profileSubmitSSLClient +tps.connector.ca1.uri.renewal=/ca/ee/ca/profileSubmitSSLClient +tps.connector.ca1.uri.revoke=/ca/ee/subsystem/ca/doRevoke +tps.connector.ca1.uri.unrevoke=/ca/ee/subsystem/ca/doUnrevoke + +tps.connector.kra1.enable=true +tps.connector.kra1.host=server.example.com +tps.connector.kra1.port=8443 +tps.connector.kra1.minHttpConns=1 +tps.connector.kra1.maxHttpConns=15 +tps.connector.kra1.nickName=subsystemCert cert-pki-tomcat TPS +tps.connector.kra1.timeout=30 +tps.connector.kra1.uri.GenerateKeyPair=/kra/agent/kra/GenerateKeyPair +tps.connector.kra1.uri.TokenKeyRecovery=/kra/agent/kra/TokenKeyRecovery + +tps.connector.tks1.enable=true +tps.connector.tks1.host=server.example.com +tps.connector.tks1.port=8443 +tps.connector.tks1.minHttpConns=1 +tps.connector.tks1.maxHttpConns=15 +tps.connector.tks1.nickName=subsystemCert cert-pki-tomcat TPS +tps.connector.tks1.timeout=30 +tps.connector.tks1.generateHostChallenge=true +tps.connector.tks1.serverKeygen=false +tps.connector.tks1.keySet=defKeySet +tps.connector.tks1.tksSharedSymKeyName=sharedSecret +tps.connector.tks1.uri.computeRandomData=/tks/agent/tks/computeRandomData +tps.connector.tks1.uri.computeSessionKey=/tks/agent/tks/computeSessionKey +tps.connector.tks1.uri.createKeySetData=/tks/agent/tks/createKeySetData +tps.connector.tks1.uri.encryptData=/tks/agent/tks/encryptData +.fi + +.SH AUTHORS +Dogtag Team <pki-devel@redhat.com>. + +.SH COPYRIGHT +Copyright (c) 2014 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. diff --git a/base/tps/man/man5/pki-tps-profile.5 b/base/tps/man/man5/pki-tps-profile.5 new file mode 100644 index 000000000..2b864a05f --- /dev/null +++ b/base/tps/man/man5/pki-tps-profile.5 @@ -0,0 +1,204 @@ +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH pki-tps-connector 5 "May 6, 2014" "version 10.2" "PKI TPS Profile Configuration" Dogtag Team +.\" Please adjust this date whenever revising the man page. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp <n> insert n+1 empty lines +.\" for man page specific macros, see man(7) +.SH NAME +PKI TPS Profile Configuration + +.SH LOCATION +/var/lib/pki/<instance>/conf/tps/CS.cfg + +.SH DESCRIPTION + +Token profiles are defined using properties in the TPS configuration file. + +.SS Enrollment Operation For CoolKey + +The following property sets the size of the key the token should generate: + +.B op.enroll.<tokenType>.keyGen.<keyType>.keySize=1024 + +The maximum value is 1024. + +The following properties specify the PKCS11 attributes to set on the token: + +.nf +.B op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.encrypt=false +.B op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.sign=true +.B op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.signRecover=true +.B op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.decrypt=false +.B op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.derive=false +.B op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.unwrap=false +.B op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.wrap=false +.B op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.verifyRecover=true +.B op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.verify=true +.B op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.sensitive=true +.B op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.private=true +.B op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.token=true +.fi + +The following property specifies the CUID shown in the certificate: + +.B op.enroll.<tokenType>.keyGen.<keyType>.cuid_label + +The following property specifies the token name: + +.B op.enroll.<tokenType>.keyGen.<keyType>.label + +The following variables can be used in the token name: + \fB$pretty_cuid$\fR - Pretty Print CUID (i.e. 4090-0062-FF02-0000-0B9C) + \fB$cuid$\fR - CUID (i.e. 40900062FF0200000B9C) + \fB$msn$\fR - MSN + \fB$userid$\fR - User ID + \fB$profileId$\fR - Profile ID + +All resulting labels for co-existing keys on the same token must be unique. + +The following property determines whether TPS will overwrite key and certificate if they already exist: + +.B op.enroll.<tokenType>.keyGen.<keyType>.overwrite=true|false + +The following properties specify name PKCS11 object IDs: + +.nf +.B op.enroll.<tokenType>.keyGen.<keyType>.certId=C1 +.B op.enroll.<tokenType>.keyGen.<keyType>.certAttrId=c1 +.B op.enroll.<tokenType>.keyGen.<keyType>.privateKeyAttrId=k2 +.B op.enroll.<tokenType>.keyGen.<keyType>.publicKeyAttrId=k3 +.B op.enroll.<tokenType>.keyGen.<keyType>.privateKeyNumber=2 +.B op.enroll.<tokenType>.keyGen.<keyType>.publicKeyNumber=3 +.fi + +Lower case letters signify objects containing PKCS11 object attributes +in the format described below: + \fBc\fR - An object containing PKCS11 attributes for a certificate. + \fBk\fR - An object containing PKCS11 attributes for a public or private key + \fBr\fR - An object containing PKCS11 attributes for an "reader". + +Upper case letters signify objects containing raw data corresponding to +the lower case letters described above. For example, object \fBC0\fR +contains raw data corresponding to object \fBc0\fR. + \fBC\fR - This object contains an entire DER cert, and nothing else. + \fBK\fR - This object contains a MUSCLE "key blob". TPS does not use this. + +The following properties specify the algorithm, the key size, the key usage, +and which PIN user should be granted: + +.nf +.B op.enroll.<tokenType>.keyGen.<keyType>.alg=2 +.B op.enroll.<tokenType>.keyGen.<keyType>.keySize=1024 +.B op.enroll.<tokenType>.keyGen.<keyType>.keyUsage=0 +.B op.enroll.<tokenType>.keyGen.<keyType>.keyUser=0 +.fi + +The valid algorithms are: + \fB2\fR - RSA + \fB5\fR - ECC + +For ECC, the valid key sizes are 256 and 384. + +Use privilege of the generated private key, or 15 if all users have use privilege for the private key. +Valid usages: (only specifies the usage for the private key) + \fB0\fR - default usage (Signing only for this APDU) + \fB1\fR - signing only + \fB2\fR - decryption only + \fB3\fR - signing and decryption + +The following property determines whether to enable writing of PKCS11 cache object to the token: + +.B op.enroll.<tokenType>.pkcs11obj.enable=true|false + +The following property determines whether to enable compression for writing of PKCS11 cache object to the token: + +.B op.enroll.<tokenType>.pkcs11obj.compress.enable=true|false + +The following property determines the maximum number of retries before blocking the token: + +.B op.enroll.<tokenType>.pinReset.pin.maxRetries=127 + +The maximum value is 127. + +There is a special case of tokenType userKeyTemporary. +Make sure the profile specified by the profileId to have +short validity period (e.g. 7 days) for the certificate. + +.nf +.B op.enroll.userKey.keyGen.<keyType>.publisherId=fileBasedPublisher +.B op.enroll.userKeyTemporary.keyGen.<keyType>.publisherId=fileBasedPublisher +.fi + +The folowing property describes the scheme used for recovery: + +.nf +.B op.enroll.<tokenType>.keyGen.<keyType>.recovery.<tokenState>.scheme=GenerateNewKey +.fi + +The three recovery schemes supported are: + \fBGenerateNewKey\fR - Generate a new cert for the encryption cert. + \fBRecoverLast\fR - Recover the most recent cert for the encryption cert. + \fBGenerateNewKeyandRecoverLast\fR - Generate new cert AND recover last for encryption cert. + +.SS Token Renewal + +The following properties are used to define token renewal: + +.B op.enroll.<tokenType>.renewal.* + +For each token in TPS UI, set the following to trigger renewal operations: + +.B RENEW=YES + +Optional grace period enforcement must coincide exactly with what the CA enforces. + +In case of renewal, encryption certId values are for completeness only, +server code calculates actual values used. + +.SS Format Operation For tokenKey + +The following property determines whether to update applet if the token is empty: + +.B op.format.<tokenType>.update.applet.emptyToken.enable=false + +The property is applicable to: + - CoolKey + - HouseKey + - HouseKey with Legacy Applet + +.SS Certificate Chain Imports + +.nf +.B op.enroll.certificates.num=1 +.B op.enroll.certificates.value.0=caCert +.B op.enroll.certificates.caCert.nickName=caCert0 pki-tps +.B op.enroll.certificates.caCert.certId=C5 +.B op.enroll.certificates.caCert.certAttrId=c5 +.B op.enroll.certificates.caCert.label=caCert Label +.fi + +.SS Pin Reset Operation For CoolKey + +The following property determines whether to update applet if the token is empty: + +.B op.pinReset.<tokenType>.update.applet.emptyToken.enable=false + +The property is not applicable to: + - HouseKey + - HouseKey with Legacy Applet + +.SH AUTHORS +Dogtag Team <pki-devel@redhat.com>. + +.SH COPYRIGHT +Copyright (c) 2014 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. |