Red Hat CERTIFICATE SYSTEM 7.3 - COMMAND-LINE Informations techniques

Red Hat Certificate System 7.3Command-Line ToolsGuide7.3ISBN: N/APublication date:

• Certificate System Enterprise Security Client Guide explains how to install, configure, and usethe Enterprise Security Client, the user client appli

This utility requires an input file which includes the URI to the CA's bulk issuanceinterface and the certificate request.Chapter 24. Bulk Issuan

Revocation Automation UtilityThe revoker utility sends revocation requests to the CA agent interface to revoke certificates.To access the interface, r

Option Description• 0 - Unspecified (default).• 1 - The key was compromised.• 2 - The CA key was compromised.• 3 - The affiliation of the user has cha

IndexAASCII to Binary tool , 31example , 31syntax , 31BBinary to ASCII tool , 33example , 33syntax , 33Ccommand-line utilitiesASCII to Binary , 31Bina

92

Formatting Style Purposeemphasize a new term or other phrase.Bolded text Most phrases which are in bold are application names, such asCygwin, or are f

• Select the Red Hat Certificate System product.• Set the component to Doc - cli-tools-guide.• Set the version number to 7.3.• For errors, give the pa

Create and Remove Instance ToolsThe Certificate System includes two tools to create and remove subsystem instances,pkicreate and pkiremove.NOTEThe pki

Parameter Descriptionpki_instance_root Gives the full path to the new instanceconfiguration directory.subsystem_typeGives the type of subsystem being

1.2. UsageIn the following example, the pkicreate is used to create a new DRM instance running on ports10543 and 10180, named rhpki-drm2, in the /var/

4

Silent InstallationThe Certificate System includes a tool, pkisilent, which can completely create and configurean instance in a single step. Normally,

-token_name HSM_name-token_pwd HSM_password-save_p12 export-p12-file-backup_pwd passwordThis tool has the following syntax for the RA subsystem:perl p

-admin_user adminUID-admin_email admin@email-admin_password password-agent_name agentName-ldap_host hostname-ldap_port port-bind_dn bindDN-bind_passwo

This book covers important, Certificate System-specific, command-line tools that you can use tocreate, remove, and manage subsystem instances and to c

Java™ Class Name SubsystemConfigureDRM For the DRM.ConfigureOCSP For the OCSP.ConfigureTKS For the TKS.ConfigureTPS For the TPS.Table 2.1. Subsystem J

Parameter Descriptionagent_name The new agent for the new subsystem.agent_key_size The key size to use for generating the agentcertificate and key pai

Parameter Descriptiondatabase to use for the TPS subsystem tokendatabase. Only for the TPS subsystem.ldap_auth_base_dn Gives the base DN in the LDAP d

perl pkisilent ConfigureTPS -cs_hostname localhost -cs_port 7988-ca_hostname server.example.com -ca_port 9080 -ca_ssl_port 9443-ca_agent_name agent -c

12

TokenInfoThis tool is used to determine which external hardware tokens are visible to the CertificateSystem subsystem. This can be used to diagnose wh

14

SSLGetThis tool is similar to the the wget command, which downloads files over HTTP. sslgetsupports client authentication using NSS libraries. The con

For example, to submit a certificate request through a certificate profile enrollment for to a CA,the command is as follows:sslget -e"profileId=c

AuditVerify1. About the AuditVerify ToolThe AuditVerify tool is used to verify that signed audit logs were signed with the privatesigning key and that

Red Hat Certificate System 7.3: Command-Line Tools GuideCopyright © 2008 Red Hat, Inc.Copyright © 2008 Red Hat. This material may only be distributed

certutil -d /var/lib/instance_ID/logs/signedAudit/dbdir -A -n "CACertificate" -t \"CT,CT,CT" -a -i /var/lib/instance_ID/alias/cace

Option Descriptionshould be prepended to the new audit securitydatabase files.v Optional. Specifies verbose output.Table 5.1.4. Return ValuesWhen Audi

20

PIN GeneratorFor the Certificate System to use the UidPwdPinDirAuth authentication plug-in module, theauthentication directory must contain unique PIN

## This line switches setpin into setup mode.## Please do not change it.setup=yes3. Run setpin, and set the option file to setpin.conf.setpin optfile=

Option Descriptionfilter searches from the root.length Specifies the exact number a PIN mustcontain; the default is 6. Do not use withminlength or max

Option Descriptionand generates PINs for only those DNs .output Specifies the absolute path to the file to writethe PINs as setpin generates them. If

Table 6.1.1.3. UsageThe following command generates PINs for all entries that have the CN attribute in theirdistinguished name in an LDAP directory na

unless that option is used. This allows the PINs to be verified before any entriesare modified.The information can be written to a different output fi

The output file contains the entry and PIN information from running setpin, as shown in thefollowing example:Processing: cn=QA Managers,ou=employees,o

Red Hat Certificate System 7.3

The PIN Generator can receive a list of DNs to modify in a text file specified by the inputargument. If an input file is specified, then the tool comp

NOTEHashed PINs cannot be provided to the tool.2.2. Output FileThe PIN Generator can capture the output to a text file specified by the output option.

X Hash Algorithm0 SHA-11 MD545 noneTable 6.3.The PIN is stored in the directory as a binary value, not as a base-64 encoded value.2.4. Exit CodesWhen

ASCII to BinaryThe Certificate System ASCII to binary tool converts ASCII base-64 encoded data to binarybase-64 encoded data.1. SyntaxThe ASCII to bin

32

Binary to ASCIIThe Certificate System binary to ASCII tool, BtoA converts binary base-64 encoded data toASCII base-64 encoded data.1. SyntaxThe BtoA t

34

Pretty Print CertificateThe Pretty Print Certificate utility, PrettyPrintCert, prints the contents of a certificate storedas ASCII base-64 encoded dat

-----END CERTIFICATE-----The certificate in pretty-print format in the ascii_cert.out file looks like the following:Certificate:Data:Version: v3Serial

format output file cert.simple.PrettyPrintCert -simpleinfo /usr/home/smith/test/ascii_cert.in/usr/home/smith/test/cert.simpleThe base-64 encoded certi

About This Guide ... vii1. Who Should Read This Gui

38

Pretty Print CRLThe Pretty Print CRL tool, PrettyPrintCrl, prints the contents of a certificate revocation list(CRL) in an ASCII base-64 encoded file

The CRL in pretty-print format in the ascii_crl.out output file looks like the following:Certificate Revocation List:Data:Version: v2Signature Algorit

TKS ToolThe TKS utility, tksTool, manages keys, including keys stored on tokens, the TKS master key,and related keys and databases.1. SyntaxThe tksToo

tksTool -P -d dbdir [-p dbprefix] [-f pwfile]• Renaming a symmetric key.tksTool -R -n keyname -r new_keyname -d dbdir [-h token_name][-p dbprefix] [-f

The tksTool options are as follows:Option DescriptionD Deletes a key from the token.d Required. Gives the security moduledatabase (HSM, if allowed for

Option Descriptionz Gives the path and filename of the noise fileto generate the key.Table 11.1.There are two additional options which can be used wit

NOTEA hardware HSM can be used instead of the software database if the modutilutility is first used to insert the HSM slot and token into the secmod.d

Successfully generated, stored, and named the transport key!8. List the contents of the key database again.tksTool -L -d .slot: NSS User Private Key a

NOTEThe order of the keys is not important, and some systems may display the keysin a different order.11.Use the transport key to generate and unwrap

9. Pretty Print Certificate ...351. Syntax ...

tksTool -D -d . -n wrapped_masterEnter Password or Pin for "NSS Certificate DB":tksTool: 1 key(s) called "wrapped_master" were del

CMC RequestThe CMC Request utility, CMCRequest, creates a CMC request from one or more PKCS #10 orCRMF requests. The utility can also be used to revok

Parameters DescriptionRequired. The full path to the directory wherethe cert8.db, key3.db, and secmod.dbdatabases are located.For example, dbdir=/u/sm

Parameters DescriptionFor example, getCert.enable=false.getCert.serialThe serial number for the getCert control.For example, getCert.serial=300.getCer

Parameters Descriptionis assumed to be false.For example, revRequest.enable=true.revRequest.nicknameThe nickname for the certificate beingrevoked.For

Parameters DescriptionFor example,revRequest.invalidityDatePresent=false.identityProof.enableIf set to true, then the request contains thiscontrol. If

By default, the URI of the servlet that processes a simple CMC request is/ca/ee/ca/profileSubmitCMCSimple; this must be specified in the HttpClientcon

CMC EnrollmentThe CMC Enrollment utility, CMCEnroll, is used to sign a certificate request with an agent'scertificate. This can be used in conjun

requests, change the configuration so that this field is available.To enable the CMC Enrollment form for the CA end-entity interface, do the following

form.e. The certificate is immediately processed and returned since a signed request was sentand the CMCAuth plug-in was enabled.f. Use the agent page

About This GuideThe Certificate System Command-Line Tools Guide describes the command-line tools andutilities bundled with Red Hat Certificate System

58

CMC ResponseThe CMC Response utility, CMCResponse, parses a CMC response received by the utility.1. SyntaxThe CMC Response utility uses the following

60

CMC RevocationThe CMC Revocation utility, CMCRevoke, signs a revocation request with an agent's certificate.1. SyntaxThis utility has the followi

NOTESurround values that include spaces in quotation marks.2. Testing CMC RevocationTest that CMC revocation is working properly by doing the followin

CRMF Pop RequestThe CRMFPopClient utility is a tool to send a Certificate Request Message Format (CRMF)request to a Certificate System CA with the req

Option DescriptionpasswordThe password of the Certificate System user.pop_optionOptional. Sets the type of POP request togenerate; since this can gene

certificate must be in the same directory from which the utility is launched; the tool picks up thisfile automatically.CRMFPopClient password123 POP_S

66

Extension JoinerThe Certificate System provides policy plug-in modules that allow standard and custom X.509certificate extensions to be added to end-e

Chapter 3, TokenInfo Describes the utility which can be used toidentify tokens on a machine, which showswhether the Certificate System can detectthose

This creates a base-64 encoded blob of the joined extensions, similar to this example:MEwwLgYDVR0lAQHBCQwIgYFKoNFBAMGClGC5EKDM5PeXzUGBi2CVyLNCQYFUiBak

0 warnings, 0 errors.If the output data do not appeat to be correct, check that the original Java™ extension filesare correct, and repeat converting t

70

Key Usage ExtensionThe GenExtKeyUsage tool creates a base-64 encoded blob that adds ExtendedKeyUsage (OID2.5.29.37) to the certificate. This blob is p

72

Issuer Alternative Name ExtensionThe GenIssuerAltNameExt creates a base-64 encoded blob that adds the issuer nameextensions, IssuerAltNameExt (OID 2.5

Parameter Descriptiono=Example Corporation, c=US.• For DNSName, the value must be a validfully-qualified domain name. For example,testCA.example.com.•

Parameter Descriptionrealm1|0|userID1,userID2.Table 19.1.2. UsageThe following example sets the issuer name in the RFC822Name and DirectoryName format

76

Subject Alternative Name ExtensionThe GenSubjectAltNameExt creates a base-64 encoded blob to add the alternate subject nameextension, SubjectAltNameEx

encoding rules (DER)-encoded Extended KeyUsage extension.Chapter 19, Issuer Alternative NameExtensionDescribes how to generate an IssuerAlternative Na

Parameter Descriptioncn=SubCA, ou=Research Dept,o=Example Corporation, c=US.• For DNSName, the value must be a validfully-qualified domain name. For e

Parameter DescriptionRealm|NameType|NameStrings, such asrealm1|0|userID1,userID2.Table 20.1.2. UsageIn the following example, the subject alternate na

80

HTTP ClientThe HTTP Client utility, HttpClient, sends a CMC request (created with the CMC Requestutility) or a PKCS #10 request to a CA.1. SyntaxThis

Parameters Descriptionservlet The URI of the servlet that processes fullCMC requests. The default value is/ca/profileSubmitCMCFull. For example:servle

OCSP RequestThe OCSP request utility, OCSPClient, creates an OCSP request conforming to RFC 2560,submits it to the OCSP server, and saves the OCSP res

84

PKCS #10 ClientThe PKCS #10 utility, PKCS10Client, generates a 1024-bit RSA key pair in the securitydatabase, constructs a PKCS#10 certificate request

86

Bulk Issuance ToolThe bulkissuance utility sends a KEYGEN or a CRMF enrollment request to the bulk issuanceinterface of a CA to create certificates au