From 9665655aa38ffa39d7587b16a60fe89f392a9d03 Mon Sep 17 00:00:00 2001 From: Ryan Treat Date: Tue, 12 Dec 2023 16:50:26 -0700 Subject: [PATCH 1/3] Use PBES2 with PBKDF2 and AES-256-CBC for PKCS#12 keystores --- cmd/vcert/commands.go | 16 ++++++++-------- cmd/vcert/flags.go | 2 +- cmd/vcert/passwords.go | 4 +++- cmd/vcert/result_writer.go | 9 ++++++--- cmd/vcert/utils.go | 3 ++- cmd/vcert/validators.go | 10 +++++----- go.mod | 2 +- go.sum | 4 ++-- pkg/playbook/app/installer/pkcs12.go | 3 +-- 9 files changed, 29 insertions(+), 24 deletions(-) diff --git a/cmd/vcert/commands.go b/cmd/vcert/commands.go index 046d0cc1..27f9971c 100644 --- a/cmd/vcert/commands.go +++ b/cmd/vcert/commands.go @@ -372,7 +372,7 @@ func doCommandEnroll1(c *cli.Context) error { req.KeyPassword = flags.keyPassword // Creates a temporary password for service generated csr if following validation is fulfilled. - // Analyzing validation assuming that pkcs12, jks and service flags are true + // Analyzing validation assuming that pkcs12, legacy-pkcs12, jks and service flags are true //+-------------+----------------+----------------------------------------------------------------------+ //| --no-prompt | --key-password | What happens in validation? | //|-------------|----------------|----------------------------------------------------------------------| @@ -385,7 +385,7 @@ func doCommandEnroll1(c *cli.Context) error { //| false | false |VCert will prompt to enter password and process will not be completed | //| | |until password is provided by user | //+-------------+----------------+----------------------------------------------------------------------+ - if flags.noPrompt && flags.keyPassword == "" && flags.format != "pkcs12" && flags.format != "jks" && flags.csrOption == "service" { + if flags.noPrompt && flags.keyPassword == "" && flags.format != P12Format && flags.format != LegacyP12Format && flags.format != JKSFormat && flags.csrOption == "service" { flags.keyPassword = fmt.Sprintf("t%d-%s.tem.pwd", time.Now().Unix(), randRunes(4)) req.KeyPassword = flags.keyPassword passwordAutogenerated = true @@ -408,7 +408,7 @@ func doCommandEnroll1(c *cli.Context) error { } } - if (pcc.PrivateKey != "" && (flags.format == Pkcs12 || flags.format == JKSFormat)) || (flags.format == util.LegacyPem && flags.csrOption == "service") || flags.noPrompt && passwordAutogenerated { + if (pcc.PrivateKey != "" && (flags.format == P12Format || flags.format == LegacyP12Format || flags.format == JKSFormat)) || (flags.format == util.LegacyPem && flags.csrOption == "service") || flags.noPrompt && passwordAutogenerated { privKey, err := util.DecryptPkcs8PrivateKey(pcc.PrivateKey, flags.keyPassword) if err != nil { if err.Error() == "pkcs8: only PBES2 supported" && connector.GetType() == endpoint.ConnectorTypeTPP { @@ -934,7 +934,7 @@ func doCommandPickup1(c *cli.Context) error { isServiceGen := IsCSRServiceVaaSGenerated(c.Command.Name) wasPasswordEmpty := false - if flags.noPrompt && flags.keyPassword == "" && flags.format != "pkcs12" && flags.format != "jks" && (isServiceGen || isTppConnector(c.Command.Name)) { + if flags.noPrompt && flags.keyPassword == "" && flags.format != P12Format && flags.format != LegacyP12Format && flags.format != JKSFormat && (isServiceGen || isTppConnector(c.Command.Name)) { flags.keyPassword = fmt.Sprintf("t%d-%s.tem.pwd", time.Now().Unix(), randRunes(4)) wasPasswordEmpty = true } @@ -998,7 +998,7 @@ func doCommandPickup1(c *cli.Context) error { } logf("Successfully retrieved request for %s", flags.pickupID) - if pcc.PrivateKey != "" && (flags.format == Pkcs12 || flags.format == JKSFormat || flags.format == util.LegacyPem) || (flags.noPrompt && wasPasswordEmpty && pcc.PrivateKey != "") { + if pcc.PrivateKey != "" && (flags.format == P12Format || flags.format == LegacyP12Format || flags.format == JKSFormat || flags.format == util.LegacyPem) || (flags.noPrompt && wasPasswordEmpty && pcc.PrivateKey != "") { privKey, err := util.DecryptPkcs8PrivateKey(pcc.PrivateKey, flags.keyPassword) if err != nil { if err.Error() == "pkcs8: only PBES2 supported" && connector.GetType() == endpoint.ConnectorTypeTPP { @@ -1421,7 +1421,7 @@ func doCommandRenew1(c *cli.Context) error { req.ChainOption = certificate.ChainOptionFromString(flags.chainOption) req.KeyPassword = flags.keyPassword - if flags.noPrompt && flags.keyPassword == "" && flags.format != "pkcs12" && flags.format != "jks" && flags.csrOption == "service" { + if flags.noPrompt && flags.keyPassword == "" && flags.format != P12Format && flags.format != LegacyP12Format && flags.format != JKSFormat && flags.csrOption == "service" { flags.keyPassword = fmt.Sprintf("t%d-%s.tem.pwd", time.Now().Unix(), randRunes(4)) req.KeyPassword = flags.keyPassword passwordAutogenerated = true @@ -1444,7 +1444,7 @@ func doCommandRenew1(c *cli.Context) error { } // Creates a temporary password for service generated csr if following validation is fulfilled. - // Analyzing validation assuming that pkcs12, jks and service flags are true + // Analyzing validation assuming that pkcs12, legacy-pkcs12, jks and service flags are true //+-------------+----------------+----------------------------------------------------------------------+ //| --no-prompt | --key-password | What happens in validation? | //|-------------|----------------|----------------------------------------------------------------------| @@ -1457,7 +1457,7 @@ func doCommandRenew1(c *cli.Context) error { //| false | false |VCert will prompt to enter password and process will not be completed | //| | |until password is provided by user | //+-------------+----------------+----------------------------------------------------------------------+ - if (pcc.PrivateKey != "" && (flags.format == Pkcs12 || flags.format == JKSFormat)) || (flags.format == util.LegacyPem && flags.csrOption == "service") || flags.noPrompt && passwordAutogenerated { + if (pcc.PrivateKey != "" && (flags.format == P12Format || flags.format == LegacyP12Format || flags.format == JKSFormat)) || (flags.format == util.LegacyPem && flags.csrOption == "service") || flags.noPrompt && passwordAutogenerated { privKey, err := util.DecryptPkcs8PrivateKey(pcc.PrivateKey, flags.keyPassword) if err != nil { if err.Error() == "pkcs8: only PBES2 supported" && connector.GetType() == endpoint.ConnectorTypeTPP { diff --git a/cmd/vcert/flags.go b/cmd/vcert/flags.go index 7bbed34a..66a4ac7d 100644 --- a/cmd/vcert/flags.go +++ b/cmd/vcert/flags.go @@ -227,7 +227,7 @@ var ( flagFormat = &cli.StringFlag{ Name: "format", - Usage: "Use to specify the output format. Options include: pem | json | pkcs12 | jks." + + Usage: "Use to specify the output format. Options include: pem | json | pkcs12 | jks | legacy-pem | legacy-pkcs12." + " If PKCS#12 or JKS formats are specified, the --file parameter is required." + " For JKS format, the --jks-alias parameter is required and a password must be provided (see --key-password and --jks-password).", Destination: &flags.format, diff --git a/cmd/vcert/passwords.go b/cmd/vcert/passwords.go index 335b3893..bbee61ef 100644 --- a/cmd/vcert/passwords.go +++ b/cmd/vcert/passwords.go @@ -60,7 +60,9 @@ func readPasswordsFromInputFlags(commandName string, cf *commandFlags) error { cloudSerViceGenerated := IsCSRServiceVaaSGenerated(commandName) - if commandName == commandSshPickupName || commandName == commandSshEnrollName || commandName == commandEnrollName || commandName == commandGenCSRName || commandName == commandRenewName || commandName == commandPickupName && (cf.format == "pkcs12" || cf.format == JKSFormat || cloudSerViceGenerated) { + if commandName == commandSshPickupName || commandName == commandSshEnrollName || commandName == commandEnrollName || + commandName == commandGenCSRName || commandName == commandRenewName || commandName == commandPickupName && + (cf.format == P12Format || cf.format == LegacyP12Format || cf.format == JKSFormat || cloudSerViceGenerated) { var keyPasswordNotNeeded = false keyPasswordNotNeeded = keyPasswordNotNeeded || (cf.csrOption == "service" && cf.noPickup) diff --git a/cmd/vcert/result_writer.go b/cmd/vcert/result_writer.go index a6cc1be6..a0e30e83 100644 --- a/cmd/vcert/result_writer.go +++ b/cmd/vcert/result_writer.go @@ -18,7 +18,6 @@ package main import ( "bytes" - "crypto/rand" "crypto/x509" "encoding/json" "encoding/pem" @@ -122,7 +121,11 @@ func (o *Output) AsPKCS12(c *Config) ([]byte, error) { return nil, fmt.Errorf("private key error(3): %s", err) } - bytes, err := pkcs12.Encode(rand.Reader, privKey, cert, chain_list, c.KeyPassword) + encoder := pkcs12.Modern2023 + if c.Format == LegacyP12Format { + encoder = pkcs12.LegacyRC2 + } + bytes, err := encoder.Encode(privKey, cert, chain_list, c.KeyPassword) if err != nil { return nil, fmt.Errorf("encode error: %s", err) } @@ -313,7 +316,7 @@ func (r *Result) Flush() error { allFileOutput.CSR = r.Pcc.CSR var bytes []byte - if r.Config.Format == "pkcs12" { + if r.Config.Format == P12Format || r.Config.Format == LegacyP12Format { bytes, err = allFileOutput.AsPKCS12(r.Config) if err != nil { return fmt.Errorf("failed to encode pkcs12: %s", err) diff --git a/cmd/vcert/utils.go b/cmd/vcert/utils.go index 06969bfc..61325e25 100644 --- a/cmd/vcert/utils.go +++ b/cmd/vcert/utils.go @@ -43,7 +43,8 @@ import ( const ( JKSFormat = "jks" - Pkcs12 = "pkcs12" + P12Format = "pkcs12" + LegacyP12Format = "legacy-pkcs12" Sha256 = "SHA256" SshCertPubKeyServ = "service" SshCertPubKeyFilePreff = "file:" diff --git a/cmd/vcert/validators.go b/cmd/vcert/validators.go index 9ec2751e..9aa39c90 100644 --- a/cmd/vcert/validators.go +++ b/cmd/vcert/validators.go @@ -75,7 +75,7 @@ func readData(commandName string) error { func validateCommonFlags(commandName string) error { - if flags.format != "" && flags.format != "pem" && flags.format != "json" && flags.format != "pkcs12" && flags.format != JKSFormat && flags.format != util.LegacyPem { + if flags.format != "" && flags.format != "pem" && flags.format != "json" && flags.format != P12Format && flags.format != LegacyP12Format && flags.format != JKSFormat && flags.format != util.LegacyPem { return fmt.Errorf("Unexpected output format: %s", flags.format) } if flags.file != "" && (flags.certFile != "" || flags.chainFile != "" || flags.keyFile != "") { @@ -176,7 +176,7 @@ func validateConnectionFlags(commandName string) error { } func validatePKCS12Flags(commandName string) error { - if flags.format == "pkcs12" { + if flags.format == P12Format || flags.format == LegacyP12Format { if commandName == commandEnrollName { if flags.file == "" && flags.csrOption != "service" { return fmt.Errorf("PKCS#12 format requires certificate, private key, and chain to be written to a single file; specify using --file") @@ -187,13 +187,13 @@ func validatePKCS12Flags(commandName string) error { } } if flags.certFile != "" || flags.chainFile != "" || flags.keyFile != "" { - return fmt.Errorf(`The --file parameter may not be combined with the --cert-file, --key-file, or --chain-file parameters when --format is "pkcs12"`) + return fmt.Errorf(`The --file parameter may not be combined with the --cert-file, --key-file, or --chain-file parameters when --format is %q`, flags.format) } if strings.HasPrefix(flags.csrOption, "file:") { - return fmt.Errorf(`The --csr "file" option may not be used with the enroll or renew actions when --format is "pkcs12"`) + return fmt.Errorf(`The --csr "file" option may not be used with the enroll or renew actions when --format is %q`, flags.format) } if (flags.csrOption == "" || flags.csrOption == "local") && flags.noPickup { - return fmt.Errorf(`The --csr "local" option may not be used with the enroll or renew actions when --format is "pkcs12" and --no-pickup is specified`) + return fmt.Errorf(`The --csr "local" option may not be used with the enroll or renew actions when --format is %q and --no-pickup is specified`, flags.format) } } return nil diff --git a/go.mod b/go.mod index 7a505275..666f0ef0 100644 --- a/go.mod +++ b/go.mod @@ -17,7 +17,7 @@ require ( gopkg.in/ini.v1 v1.51.0 gopkg.in/yaml.v2 v2.4.0 gopkg.in/yaml.v3 v3.0.1 - software.sslmate.com/src/go-pkcs12 v0.2.1 + software.sslmate.com/src/go-pkcs12 v0.4.0 ) require ( diff --git a/go.sum b/go.sum index 33647daf..c52dac76 100644 --- a/go.sum +++ b/go.sum @@ -361,5 +361,5 @@ honnef.co/go/tools v0.0.0-20190106161140-3f1c8253044a/go.mod h1:rf3lG4BRIbNafJWh honnef.co/go/tools v0.0.0-20190418001031-e561f6794a2a/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4= honnef.co/go/tools v0.0.1-2019.2.3/go.mod h1:a3bituU0lyd329TUQxRnasdCoJDkEUEAqEt0JzvZhAg= rsc.io/binaryregexp v0.2.0/go.mod h1:qTv7/COck+e2FymRvadv62gMdZztPaShugOCi3I+8D8= -software.sslmate.com/src/go-pkcs12 v0.2.1 h1:tbT1jjaeFOF230tzOIRJ6U5S1jNqpsSyNjzDd58H3J8= -software.sslmate.com/src/go-pkcs12 v0.2.1/go.mod h1:Qiz0EyvDRJjjxGyUQa2cCNZn/wMyzrRJ/qcDXOQazLI= +software.sslmate.com/src/go-pkcs12 v0.4.0 h1:H2g08FrTvSFKUj+D309j1DPfk5APnIdAQAB8aEykJ5k= +software.sslmate.com/src/go-pkcs12 v0.4.0/go.mod h1:Qiz0EyvDRJjjxGyUQa2cCNZn/wMyzrRJ/qcDXOQazLI= diff --git a/pkg/playbook/app/installer/pkcs12.go b/pkg/playbook/app/installer/pkcs12.go index deb6bdb6..daca9933 100644 --- a/pkg/playbook/app/installer/pkcs12.go +++ b/pkg/playbook/app/installer/pkcs12.go @@ -17,7 +17,6 @@ package installer import ( - "crypto/rand" "crypto/x509" "encoding/pem" "fmt" @@ -186,7 +185,7 @@ func packageAsPKCS12(pcc certificate.PEMCollection, keyPassword string) ([]byte, return nil, err } - bytes, err := pkcs12.Encode(rand.Reader, privateKey, cert, chainList, keyPassword) + bytes, err := pkcs12.Modern2023.Encode(privateKey, cert, chainList, keyPassword) if err != nil { return nil, fmt.Errorf("PKCS12 encode error: %w", err) } From bd7a5420581aaa6ba4e1b222b40d101660a83a68 Mon Sep 17 00:00:00 2001 From: marcos-albornoz Date: Fri, 15 Dec 2023 19:19:56 -0600 Subject: [PATCH 2/3] Feat: Update tests for PKCS12 upgrade --- aruba/features/format/pkcs12.feature | 35 +++ .../playbook/steps_definitions/my_steps.rb | 2 +- .../renew/renew-with-csr-local.feature | 20 ++ .../renew/renew-with-csr-service.feature | 9 + aruba/features/step_definitions/openssl.rb | 13 ++ cmd/vcert/result_writer_test.go | 213 ++++++++++++++++++ 6 files changed, 291 insertions(+), 1 deletion(-) diff --git a/aruba/features/format/pkcs12.feature b/aruba/features/format/pkcs12.feature index b9953842..ac15c43d 100644 --- a/aruba/features/format/pkcs12.feature +++ b/aruba/features/format/pkcs12.feature @@ -66,6 +66,26 @@ Feature: PKCS#12 format output | endpoint | | Cloud | + Scenario Outline: where all objects are written to one PKCS#12 legacy archive with key password + When I enroll random certificate in with -format legacy-pkcs12 -file all.p12 -key-password newPassw0rd! + Then the exit status should be 0 + And "all.p12" should be PKCS#12 archive in legacy mode with password "newPassw0rd!" + + @FAKE + Examples: + | endpoint | + | test-mode | + + @TPP + Examples: + | endpoint | + | TPP | + + @VAAS + Examples: + | endpoint | + | Cloud | + Scenario Outline: where it outputs error when trying to pickup local-generated certificate and output it in PKCS#12 format When I enroll random certificate using with -no-prompt -no-pickup And I retrieve the certificate using using the same Pickup ID with -timeout 180 -no-prompt -file all.p12 -format pkcs12 @@ -159,6 +179,21 @@ Feature: PKCS#12 format output | endpoint | | TPP | + Scenario Outline: where it pickups up service-generated certificate and outputs it in PKCS#12 legacy format + When I enroll random certificate using with -no-prompt -no-pickup -csr service + And I retrieve the certificate using using the same Pickup ID with -timeout 180 -key-password newPassw0rd! -file all.p12 -format legacy-pkcs12 + And "all.p12" should be PKCS#12 archive in legacy mode with password "newPassw0rd!" + + @FAKE + Examples: + | endpoint | + | test-mode | + + @TPP + Examples: + | endpoint | + | TPP | + # TODO: Now VaaS supports CSR, but we need to verify this behavior for this test # @VAAS # Examples: diff --git a/aruba/features/playbook/steps_definitions/my_steps.rb b/aruba/features/playbook/steps_definitions/my_steps.rb index afbf9d03..c7af424b 100644 --- a/aruba/features/playbook/steps_definitions/my_steps.rb +++ b/aruba/features/playbook/steps_definitions/my_steps.rb @@ -291,7 +291,7 @@ cert_path = Dir.pwd + $path_separator + $temp_path + $path_separator + filename steps %{ - Then I try to run `openssl pkcs12 -in "#{cert_path}" -legacy -passin pass:#{password} -noout` + Then I try to run `openssl pkcs12 -in "#{cert_path}" -passin pass:#{password} -noout` And the exit status should be 0 } end diff --git a/aruba/features/renew/renew-with-csr-local.feature b/aruba/features/renew/renew-with-csr-local.feature index 65d76c0c..da5b3c32 100644 --- a/aruba/features/renew/renew-with-csr-local.feature +++ b/aruba/features/renew/renew-with-csr-local.feature @@ -84,5 +84,25 @@ Feature: renew action with -csr local (default) option | endpoint | | Cloud | + Scenario Outline: renew certificate using -id using `-csr local` with PKCS12 legacy flag + Given I enroll random certificate using with -key-password Passcode123! -key-file k.pem -cert-file c.pem -csr local + And it should write private key to the file "k.pem" + And it should write certificate to the file "c.pem" + And it should output Pickup ID + And I decode certificate from file "c.pem" + Then I renew the certificate in using the same Pickup ID with flags -key-password Passcode123! -file all.p12 -format legacy-pkcs12 + And it should retrieve certificate + And "all.p12" should be PKCS#12 archive in legacy mode with password "Passcode123!" + + @TPP + Examples: + | endpoint | + | TPP | + + @VAAS + Examples: + | endpoint | + | Cloud | + Scenario: where renewed certificate may have new -key-size, -san-dns Given I implement that later diff --git a/aruba/features/renew/renew-with-csr-service.feature b/aruba/features/renew/renew-with-csr-service.feature index ef6a4096..d3af071f 100644 --- a/aruba/features/renew/renew-with-csr-service.feature +++ b/aruba/features/renew/renew-with-csr-service.feature @@ -83,3 +83,12 @@ Feature: renew action with `-csr service` option When I renew the certificate in TPP using the same Pickup ID with flags -csr service -key-password Passcode123! -file all.p12 -format pkcs12 Then it should retrieve certificate And "all.p12" should be PKCS#12 archive with password "Passcode123!" + + Scenario: renew service-generated-CSR certificate in TPP with `-csr service` option with PKCS12 legacy flag + Given I enroll random certificate using TPP with -csr service -key-password Passcode123! -key-file k.pem -cert-file c.pem + And it should write private key to the file "k.pem" + And it should write certificate to the file "c.pem" + And it should output Pickup ID + When I renew the certificate in TPP using the same Pickup ID with flags -csr service -key-password Passcode123! -file all.p12 -format legacy-pkcs12 + Then it should retrieve certificate + And "all.p12" should be PKCS#12 archive in legacy mode with password "Passcode123!" diff --git a/aruba/features/step_definitions/openssl.rb b/aruba/features/step_definitions/openssl.rb index 0ba2d932..a2fe5994 100644 --- a/aruba/features/step_definitions/openssl.rb +++ b/aruba/features/step_definitions/openssl.rb @@ -122,6 +122,19 @@ end When(/^"([^"]*)" should be PKCS#12 archive with password "([^"]*)"$/) do |filename, password| + steps %{ + Then I try to run `openssl pkcs12 -in "#{filename}" -passin pass:#{password} -noout` + And the exit status should be 0 + } + # -nokeys Don't output private keys + # -nocerts Don't output certificates + # -clcerts Only output client certificates + # -cacerts Only output CA certificates + # -noout Don't output anything, just verify + # -nodes Don't encrypt private keys +end + +When(/^"([^"]*)" should be PKCS#12 archive in legacy mode with password "([^"]*)"$/) do |filename, password| steps %{ Then I try to run `openssl pkcs12 -in "#{filename}" -legacy -passin pass:#{password} -noout` And the exit status should be 0 diff --git a/cmd/vcert/result_writer_test.go b/cmd/vcert/result_writer_test.go index a53671dd..2589b917 100644 --- a/cmd/vcert/result_writer_test.go +++ b/cmd/vcert/result_writer_test.go @@ -17,9 +17,17 @@ package main import ( + "crypto/x509" + "encoding/pem" + "errors" + "os" "testing" + "github.com/stretchr/testify/assert" + "software.sslmate.com/src/go-pkcs12" + "github.com/Venafi/vcert/v5/pkg/certificate" + "github.com/Venafi/vcert/v5/pkg/util" ) var ( @@ -141,6 +149,9 @@ func TestPKCS12withEncPK(t *testing.T) { if err != nil { t.Fatal("Failed to output the results: ", err) } + + //confirming that the PKCS12 file contains the same PK, Cert and Chain as the original data + validateGeneratedPKCS12IsCorrect(t, result) } func TestPKCS12withPlainPK(t *testing.T) { @@ -171,6 +182,9 @@ func TestPKCS12withPlainPK(t *testing.T) { if err != nil { t.Fatal("Failed to output the results: ", err) } + + //confirming that the PKCS12 file contains the same PK, Cert and Chain as the original data + validateGeneratedPKCS12IsCorrect(t, result) } func TestPKCS12withPlainEcPK(t *testing.T) { @@ -201,6 +215,108 @@ func TestPKCS12withPlainEcPK(t *testing.T) { if err != nil { t.Fatal("Failed to output the results: ", err) } + + //confirming that the PKCS12 file contains the same PK, Cert and Chain as the original data + validateGeneratedPKCS12IsCorrect(t, result) +} + +func TestLegacyPKCS12withEncPK(t *testing.T) { + result := &Result{ + &certificate.PEMCollection{ + Certificate: cert, + PrivateKey: encPK, + Chain: chain, + }, + "==pickup-id==", + &Config{ + "enroll", + "legacy-pkcs12", + "", + "", + certificate.ChainOptionFromString(""), + "/tmp/TestLegacyPKCS12withEncPK", + "", + "", + "", + "", + "", + "asdf", + }, + } + err := result.Flush() + + if err != nil { + t.Fatal("Failed to output the results: ", err) + } + + //confirming that the PKCS12 file contains the same PK, Cert and Chain as the original data + validateGeneratedPKCS12IsCorrect(t, result) +} + +func TestLegacyPKCS12withPlainPK(t *testing.T) { + result := &Result{ + &certificate.PEMCollection{ + Certificate: cert, + PrivateKey: PK, + Chain: chain, + }, + "==pickup-id==", + &Config{ + "enroll", + "legacy-pkcs12", + "", + "", + certificate.ChainOptionFromString(""), + "/tmp/TestLegacyPKCS12withPlainPK", + "", + "", + "", + "", + "", + "", + }, + } + err := result.Flush() + + if err != nil { + t.Fatal("Failed to output the results: ", err) + } + + //confirming that the PKCS12 file contains the same PK, Cert and Chain as the original data + validateGeneratedPKCS12IsCorrect(t, result) +} + +func TestLegacyPKCS12withPlainEcPK(t *testing.T) { + result := &Result{ + &certificate.PEMCollection{ + Certificate: cert, + PrivateKey: ec, + Chain: chain, + }, + "==pickup-id==", + &Config{ + "enroll", + "legacy-pkcs12", + "", + "", + certificate.ChainOptionFromString(""), + "/tmp/TestLegacyPKCS12withPlainEcPK", + "", + "", + "", + "", + "", + "", + }, + } + err := result.Flush() + + if err != nil { + t.Fatal("Failed to output the results: ", err) + } + + //confirming that the PKCS12 file contains the same PK, Cert and Chain as the original data + validateGeneratedPKCS12IsCorrect(t, result) } func TestJKSWithEncPKWithoutJKSPass(t *testing.T) { @@ -262,3 +378,100 @@ func TestJKSWithEncPKAndJKSPass(t *testing.T) { t.Fatal("Failed to output the results: ", err) } } + +func validateGeneratedPKCS12IsCorrect(t *testing.T, result *Result) { + //reading the generated PCKS12 file in order to get the PrivateKey, Cert and ChainCert to validate they are equals + // to the original + bytes, err := os.ReadFile(result.Config.AllFile) + if err != nil { + t.Fatal("Failed to read the output results: ", err) + } + + //decoding the PKCS12 data + privateKeyDecoded, certDecoded, caCertsDecoded, err := pkcs12.DecodeChain(bytes, result.Config.KeyPassword) + + if assert.NoError(t, err) { + assert.NotNil(t, privateKeyDecoded) + assert.NotNil(t, certDecoded) + assert.NotNil(t, caCertsDecoded) + + //getting the original PK + var privKeyOriginal interface{} + privKeyOriginal, err = parsePKInPKCS1ToPrivateKey(result.Pcc.PrivateKey, result.Config.KeyPassword) + if err != nil { + t.Fatal("Failed to parse the original private key: ", err) + } + + //asserting the original PK and the decoded PK from the generated PKCS12 are the same + assert.Equal(t, privKeyOriginal, privateKeyDecoded) + + //getting the original Cert + var certOriginal *x509.Certificate + certOriginal, err = parseCertificate(result.Pcc.Certificate) + if err != nil { + t.Fatal("Failed to parse the original certificate: ", err) + } + + //asserting the original Cert and the decoded Cert from the generated PKCS12 are the same + assert.Equal(t, certOriginal, certDecoded) + + //getting the original CAChain + var chainList []*x509.Certificate + chainList, err = parseChain(result.Pcc.Chain) + if err != nil { + t.Fatal("Failed to parse the original chain of certificates: ", err) + } + + //asserting the original CAChain and the decoded CAChain from the generated PKCS12 are the same + assert.Equal(t, chainList, caCertsDecoded) + } +} + +func parsePKInPKCS1ToPrivateKey(encPK string, keyPassword string) (interface{}, error) { + privateKeyPEM, _ := pem.Decode([]byte(encPK)) + if privateKeyPEM == nil { + return nil, errors.New("it was not possible to decode the private key") + } + var privateBytes []byte + if keyPassword != "" { + var err error + privateBytes, err = util.X509DecryptPEMBlock(privateKeyPEM, []byte(keyPassword)) + if err != nil { + return nil, err + } + } else { + privateBytes = privateKeyPEM.Bytes + } + + if privateKeyPEM.Type == "EC PRIVATE KEY" { + return x509.ParseECPrivateKey(privateBytes) + } else { + // then it's considered as RSA Private Key + return x509.ParsePKCS1PrivateKey(privateBytes) + } +} + +func parseCertificate(certString string) (*x509.Certificate, error) { + certPEMBlock, _ := pem.Decode([]byte(certString)) + if certPEMBlock == nil || certPEMBlock.Type != "CERTIFICATE" { + return nil, errors.New("it was not possible to decode the certificate") + } + return x509.ParseCertificate(certPEMBlock.Bytes) +} + +func parseChain(chain []string) ([]*x509.Certificate, error) { + var chainList []*x509.Certificate + for _, chainCert := range chain { + certPEMBlock, _ := pem.Decode([]byte(chainCert)) + if certPEMBlock == nil { + return nil, errors.New("it was not possible to decode the CA certificate") + } + parsedCert, err := x509.ParseCertificate(certPEMBlock.Bytes) + if err != nil { + return nil, err + } + chainList = append(chainList, parsedCert) + } + + return chainList, nil +} From f7d8d644e90c9a0a9490e9fc66d89ee9847c88a6 Mon Sep 17 00:00:00 2001 From: marcos-albornoz Date: Mon, 18 Dec 2023 11:04:45 -0600 Subject: [PATCH 3/3] Feat: Add doc for legacy flags --- README-CLI-CLOUD.md | 194 ++++++++++++++--------------- README-CLI-FIREFLY.md | 64 +++++----- README-CLI-PLATFORM.md | 276 ++++++++++++++++++++--------------------- 3 files changed, 267 insertions(+), 267 deletions(-) diff --git a/README-CLI-CLOUD.md b/README-CLI-CLOUD.md index c651647d..1e8ab4d1 100644 --- a/README-CLI-CLOUD.md +++ b/README-CLI-CLOUD.md @@ -80,7 +80,7 @@ The following options apply to the `enroll`, `pickup`, and `renew` actions: | `--test-mode-delay` | Use to specify the maximum number of seconds for the random test-mode connection delay. Default is 15 (seconds). | | `--timeout` | Use to specify the maximum amount of time to wait in seconds for a certificate to be processed by VaaS. Default is 120 (seconds). | | `--trust-bundle` | Use to specify a file with PEM formatted certificates to be used as trust anchors when communicating with VaaS. Generally not needed because VaaS is secured by a publicly trusted certificate but it may be needed if your organization requires VCert to traverse a proxy server. VCert uses the trust store of your operating system for this purpose if not specified.
Example: `--trust-bundle /path-to/bundle.pem` | -| `-u` | Use to specify the URL of the Venafi as a Service API server. If it's omitted, then VCert will use [https://api.venafi.cloud](https://api.venafi.cloud/vaas) as API server.
Example: `-u https://api.venafi.eu` | +| `-u` | Use to specify the URL of the Venafi as a Service API server. If it's omitted, then VCert will use [https://api.venafi.cloud](https://api.venafi.cloud/vaas) as API server.
Example: `-u https://api.venafi.eu` | | `--verbose` | Use to increase the level of logging detail, which is helpful when troubleshooting issues. | ### Environment Variables @@ -93,31 +93,31 @@ vcert enroll -k --cn -z Example: `--app-info "Venafi VCert CLI"` | -| `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.
Example: `--cert-file /path-to/example.crt` | -| `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.
Options: `root-last` (default), `root-first`, `ignore` | -| `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | -| `--cn` | Use to specify the common name (CN). This is required for Enrollment. | -| `--csr` | Use to specify the CSR and private key location. Options: `local` (default), `service`, `file`
- local: private key and CSR will be generated locally
- service: private key and CSR will be generated by a VSatellite in Venafi as a Service
- file: CSR will be read from a file by name
Example: `--csr file:/path-to/example.req` | -| `--file` | Use to specify a name and location of an output file that will contain the private key and certificates when they are not written to their own files using `--key-file`, `--cert-file`, and/or `--chain-file`.
Example: `--file /path-to/keycert.pem` | -| `--format` | Use to specify the output format. The `--file` option must be used with the PKCS#12 and JKS formats to specify the keystore file. JKS format also requires `--jks-alias` and at least one password (see `--key-password` and `--jks-password`)
Options: `pem` (default), `json`, `pkcs12`, `jks` | -| `--jks-alias` | Use to specify the alias of the entry in the JKS file when `--format jks` is used | -| `--jks-password` | Use to specify the keystore password of the JKS file when `--format jks` is used. If not specified, the `--key-password` value is used for both the key and store passwords | -| `--key-curve` | Use to specify the elliptic curve for key generation when `--key-type` is ECDSA.
Options: `p256` (default), `p384`, `p521` | -| `--key-file` | Use to specify the name and location of an output file that will contain only the private key.
Example: `--key-file /path-to/example.key` | -| `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, specify `--no-prompt` without specifying this option. You can specify the password using one of three methods: at the command line, when prompted, or by using a password file.
Example: `--key-password file:/path-to/passwd.txt` | -| `--key-size` | Use to specify a key size for RSA keys. Default is 2048. | -| `--key-type` | Use to specify the key algorithm.
Options: `rsa` (default), `ecdsa` | -| `--no-pickup` | Use to disable the feature of VCert that repeatedly tries to retrieve the issued certificate. When this is used you must run VCert again in pickup mode to retrieve the certificate that was requested. | -| `--pickup-id-file` | Use to specify a file name where the unique identifier for the certificate will be stored for subsequent use by pickup, renew, and revoke actions. Default is to write the Pickup ID to STDOUT. | -| `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-dns one.example.com` `--san-dns two.example.com` | -| `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-email me@example.com` `--san-email you@example.com` | -| `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | -| `--san-uri` | Use to specify a Uniform Resource Indicator Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-uri spiffe://workload1.example.com` `--san-uri spiffe://workload2.example.com` | -| `--valid-days` | Use to specify the number of days a certificate needs to be valid.
Example: `--valid-days 30` | -| `-z` | Use to specify the name of the Application to which the certificate will be assigned and the API Alias of the Issuing Template that will handle the certificate request.
Example: `-z "Business App\\Enterprise CIT"` | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--app-info` | Use to identify the application requesting the certificate with details like vendor name and vendor product.
Example: `--app-info "Venafi VCert CLI"` | +| `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.
Example: `--cert-file /path-to/example.crt` | +| `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.
Options: `root-last` (default), `root-first`, `ignore` | +| `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | +| `--cn` | Use to specify the common name (CN). This is required for Enrollment. | +| `--csr` | Use to specify the CSR and private key location. Options: `local` (default), `service`, `file`
- local: private key and CSR will be generated locally
- service: private key and CSR will be generated by a VSatellite in Venafi as a Service
- file: CSR will be read from a file by name
Example: `--csr file:/path-to/example.req` | +| `--file` | Use to specify a name and location of an output file that will contain the private key and certificates when they are not written to their own files using `--key-file`, `--cert-file`, and/or `--chain-file`.
Example: `--file /path-to/keycert.pem` | +| `--format` | Use to specify the output format. The `--file` option must be used with the PKCS#12 and JKS formats to specify the keystore file. JKS format also requires `--jks-alias` and at least one password (see `--key-password` and `--jks-password`)
Options: `pem` (default), `legacy-pem`, `json`, `pkcs12`, `legacy-pkcs12` (analogous to OpenSSL 3.x -legacy flag), `jks` | +| `--jks-alias` | Use to specify the alias of the entry in the JKS file when `--format jks` is used | +| `--jks-password` | Use to specify the keystore password of the JKS file when `--format jks` is used. If not specified, the `--key-password` value is used for both the key and store passwords | +| `--key-curve` | Use to specify the elliptic curve for key generation when `--key-type` is ECDSA.
Options: `p256` (default), `p384`, `p521` | +| `--key-file` | Use to specify the name and location of an output file that will contain only the private key.
Example: `--key-file /path-to/example.key` | +| `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, specify `--no-prompt` without specifying this option. You can specify the password using one of three methods: at the command line, when prompted, or by using a password file.
Example: `--key-password file:/path-to/passwd.txt` | +| `--key-size` | Use to specify a key size for RSA keys. Default is 2048. | +| `--key-type` | Use to specify the key algorithm.
Options: `rsa` (default), `ecdsa` | +| `--no-pickup` | Use to disable the feature of VCert that repeatedly tries to retrieve the issued certificate. When this is used you must run VCert again in pickup mode to retrieve the certificate that was requested. | +| `--pickup-id-file` | Use to specify a file name where the unique identifier for the certificate will be stored for subsequent use by pickup, renew, and revoke actions. Default is to write the Pickup ID to STDOUT. | +| `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-dns one.example.com` `--san-dns two.example.com` | +| `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-email me@example.com` `--san-email you@example.com` | +| `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | +| `--san-uri` | Use to specify a Uniform Resource Indicator Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-uri spiffe://workload1.example.com` `--san-uri spiffe://workload2.example.com` | +| `--valid-days` | Use to specify the number of days a certificate needs to be valid.
Example: `--valid-days 30` | +| `-z` | Use to specify the name of the Application to which the certificate will be assigned and the API Alias of the Issuing Template that will handle the certificate request.
Example: `-z "Business App\\Enterprise CIT"` | ## Certificate Retrieval Parameters ``` @@ -125,15 +125,15 @@ vcert pickup -k [--pickup-id | --pickup-id-file Example: `--cert-file /path-to/example.crt` | -| `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.
Options: `root-last` (default), `root-first`, `ignore` | -| `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | -| `--file` | Use to specify a name and location of an output file that will contain certificates when they are not written to their own files using `--cert-file` and/or `--chain-file`.
Example: `--file /path-to/keycert.pem` | -| `--format` | Use to specify the output format.
Options: `pem` (default), `json` | -| `--pickup-id` | Use to specify the unique identifier of the certificate returned by the enroll or renew actions if `--no-pickup` was used or a timeout occurred. Required when `--pickup-id-file` is not specified. | -| `--pickup-id-file` | Use to specify a file name that contains the unique identifier of the certificate returned by the enroll or renew actions if --no-pickup was used or a timeout occurred. Required when `--pickup-id` is not specified. | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.
Example: `--cert-file /path-to/example.crt` | +| `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.
Options: `root-last` (default), `root-first`, `ignore` | +| `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | +| `--file` | Use to specify a name and location of an output file that will contain certificates when they are not written to their own files using `--cert-file` and/or `--chain-file`.
Example: `--file /path-to/keycert.pem` | +| `--format` | Use to specify the output format.
Options: `pem` (default), `json` | +| `--pickup-id` | Use to specify the unique identifier of the certificate returned by the enroll or renew actions if `--no-pickup` was used or a timeout occurred. Required when `--pickup-id-file` is not specified. | +| `--pickup-id-file` | Use to specify a file name that contains the unique identifier of the certificate returned by the enroll or renew actions if --no-pickup was used or a timeout occurred. Required when `--pickup-id` is not specified. | ## Certificate Renewal Parameters @@ -142,31 +142,31 @@ vcert renew -k [--id | --thumbprint ] ``` Options: -|         Command         | Description | -| ------------------ | ------------------------------------------------------------ | -| `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.
Example: `--cert-file /path-to/example.crt` | -| `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.
Options: `root-last` (default), `root-first`, `ignore` | -| `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | -| `--cn` | Use to specify the common name (CN). This is required for Enrollment. | -| `--csr` | Use to specify the CSR and private key location. Options: `local` (default), `service`, `file`
- local: private key and CSR will be generated locally
- service: private key and CSR will be generated by a VSatellite in Venafi as a Service
- file: CSR will be read from a file by name
Example: `--csr file:/path-to/example.req` | -| `--file` | Use to specify a name and location of an output file that will contain the private key and certificates when they are not written to their own files using `--key-file`, `--cert-file`, and/or `--chain-file`.
Example: `--file /path-to/keycert.pem` | -| `--format` | Use to specify the output format. The `--file` option must be used with the PKCS#12 and JKS formats to specify the keystore file. JKS format also requires `--jks-alias` and at least one password (see `--key-password` and `--jks-password`)
Options: `pem` (default), `json`, `pkcs12`, `jks` | -| `--id` | Use to specify the unique identifier of the certificate returned by the enroll or renew actions. Value may be specified as a string or read from a file by using the file: prefix.
Example: `--id file:cert_id.txt` | -| `--jks-alias` | Use to specify the alias of the entry in the JKS file when `--format jks` is used | -| `--jks-password` | Use to specify the keystore password of the JKS file when `--format jks` is used. If not specified, the `--key-password` value is used for both the key and store passwords | -| `--key-curve` | Use to specify the elliptic curve for key generation when `--key-type` is ECDSA.
Options: `p256` (default), `p384`, `p521` | -| `--key-file` | Use to specify the name and location of an output file that will contain only the private key.
Example: `--key-file /path-to/example.key` | -| `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, specify `--no-prompt` without specifying this option. You can specify the password using one of three methods: at the command line, when prompted, or by using a password file. | -| `--key-size` | Use to specify a key size for RSA keys. Default is 2048. | -| `--key-type` | Use to specify the key algorithm.
Options: `rsa` (default), `ecdsa` | -| `--no-pickup` | Use to disable the feature of VCert that repeatedly tries to retrieve the issued certificate. When this is used you must run VCert again in pickup mode to retrieve the certificate that was requested. | -| `--omit-sans` | Ignore SANs in the previous certificate when preparing the renewal request. Workaround for CAs that forbid any SANs even when the SANs match those the CA automatically adds to the issued certificate. | -| `--pickup-id-file` | Use to specify a file name where the unique identifier for the certificate will be stored for subsequent use by `pickup`, `renew`, and `revoke` actions. By default it is written to STDOUT. | -| `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-dns one.example.com` `--san-dns two.example.com` | -| `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-email me@example.com` `--san-email you@example.com` | -| `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | -| `--san-uri` | Use to specify a Uniform Resource Indicator Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-uri spiffe://workload1.example.com` `--san-uri spiffe://workload2.example.com` | -| `--thumbprint` | Use to specify the SHA1 thumbprint of the certificate to renew. Value may be specified as a string or read from the certificate file using the `file:` prefix. | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.
Example: `--cert-file /path-to/example.crt` | +| `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.
Options: `root-last` (default), `root-first`, `ignore` | +| `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | +| `--cn` | Use to specify the common name (CN). This is required for Enrollment. | +| `--csr` | Use to specify the CSR and private key location. Options: `local` (default), `service`, `file`
- local: private key and CSR will be generated locally
- service: private key and CSR will be generated by a VSatellite in Venafi as a Service
- file: CSR will be read from a file by name
Example: `--csr file:/path-to/example.req` | +| `--file` | Use to specify a name and location of an output file that will contain the private key and certificates when they are not written to their own files using `--key-file`, `--cert-file`, and/or `--chain-file`.
Example: `--file /path-to/keycert.pem` | +| `--format` | Use to specify the output format. The `--file` option must be used with the PKCS#12 and JKS formats to specify the keystore file. JKS format also requires `--jks-alias` and at least one password (see `--key-password` and `--jks-password`)
Options: `pem` (default), `legacy-pem`, `json`, `pkcs12`, `legacy-pkcs12` (analogous to OpenSSL 3.x -legacy flag), `jks` | +| `--id` | Use to specify the unique identifier of the certificate returned by the enroll or renew actions. Value may be specified as a string or read from a file by using the file: prefix.
Example: `--id file:cert_id.txt` | +| `--jks-alias` | Use to specify the alias of the entry in the JKS file when `--format jks` is used | +| `--jks-password` | Use to specify the keystore password of the JKS file when `--format jks` is used. If not specified, the `--key-password` value is used for both the key and store passwords | +| `--key-curve` | Use to specify the elliptic curve for key generation when `--key-type` is ECDSA.
Options: `p256` (default), `p384`, `p521` | +| `--key-file` | Use to specify the name and location of an output file that will contain only the private key.
Example: `--key-file /path-to/example.key` | +| `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, specify `--no-prompt` without specifying this option. You can specify the password using one of three methods: at the command line, when prompted, or by using a password file. | +| `--key-size` | Use to specify a key size for RSA keys. Default is 2048. | +| `--key-type` | Use to specify the key algorithm.
Options: `rsa` (default), `ecdsa` | +| `--no-pickup` | Use to disable the feature of VCert that repeatedly tries to retrieve the issued certificate. When this is used you must run VCert again in pickup mode to retrieve the certificate that was requested. | +| `--omit-sans` | Ignore SANs in the previous certificate when preparing the renewal request. Workaround for CAs that forbid any SANs even when the SANs match those the CA automatically adds to the issued certificate. | +| `--pickup-id-file` | Use to specify a file name where the unique identifier for the certificate will be stored for subsequent use by `pickup`, `renew`, and `revoke` actions. By default it is written to STDOUT. | +| `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-dns one.example.com` `--san-dns two.example.com` | +| `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-email me@example.com` `--san-email you@example.com` | +| `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | +| `--san-uri` | Use to specify a Uniform Resource Indicator Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-uri spiffe://workload1.example.com` `--san-uri spiffe://workload2.example.com` | +| `--thumbprint` | Use to specify the SHA1 thumbprint of the certificate to renew. Value may be specified as a string or read from the certificate file using the `file:` prefix. | @@ -176,10 +176,10 @@ vcert retire -k [--id | --thumbprint ] ``` Options: -|         Command         | Description | -| -------------- | ------------------------------------------------------------ | -| `--id` | Use to specify the unique identifier of the certificate to retire. Value may be specified as a string or read from a file using the `file:` prefix. | -| `--thumbprint` | Use to specify the SHA1 thumbprint of the certificate to retire. Value may be specified as a string or read from the certificate file using the `file:` prefix. | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--id` | Use to specify the unique identifier of the certificate to retire. Value may be specified as a string or read from a file using the `file:` prefix. | +| `--thumbprint` | Use to specify the SHA1 thumbprint of the certificate to retire. Value may be specified as a string or read from the certificate file using the `file:` prefix. | ## Parameters for Applying Certificate Policy ``` @@ -187,10 +187,10 @@ vcert setpolicy -k -z --file ``` Options: -|         Command         | Description | -| ------------------ | ------------------------------------------------------------ | -| `--file` | Use to specify the location of the required file that contains a JSON or YAML certificate policy specification. | -| `--verify` | Use to verify that a policy specification is valid. `-k` and `-z` are ignored with this option. | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------| +| `--file` | Use to specify the location of the required file that contains a JSON or YAML certificate policy specification. | +| `--verify` | Use to verify that a policy specification is valid. `-k` and `-z` are ignored with this option. | Notes: - The Venafi certificate policy specification is documented in detail [here](README-POLICY-SPEC.md). @@ -213,10 +213,10 @@ vcert getpolicy -k -z [--fil ``` Options: -|         Command         | Description | -| ------------------ | ------------------------------------------------------------ | -| `--file` | Use to write the retrieved certificate policy to a file in JSON format. If not specified, policy is written to STDOUT. | -| `--starter` | Use to generate a template policy specification to help with getting started. `-k` and `-z` are ignored with this option. | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| +| `--file` | Use to write the retrieved certificate policy to a file in JSON format. If not specified, policy is written to STDOUT. | +| `--starter` | Use to generate a template policy specification to help with getting started. `-k` and `-z` are ignored with this option. | ## Examples @@ -289,11 +289,11 @@ vcert getcred --email ``` Options: -|         Command         | Description | -| ---------------- | ------------------------------------------------------------ | -| `--email` | Use to specify a user's business email address. An email will be sent to this address with a link to activate the API key that is output by this action. This is required for (re)registerting with Venafi as a Service. | -| `--format` | Specify "json" to get more verbose JSON formatted output instead of the plain text default. | -| `--password` | Use to specify the user's password if it is expected the user will need to login to the [Venafi as a Service web UI](https://ui.venafi.cloud/). | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--email` | Use to specify a user's business email address. An email will be sent to this address with a link to activate the API key that is output by this action. This is required for (re)registerting with Venafi as a Service. | +| `--format` | Specify "json" to get more verbose JSON formatted output instead of the plain text default. | +| `--password` | Use to specify the user's password if it is expected the user will need to login to the [Venafi as a Service web UI](https://ui.venafi.cloud/). | ### Generating a new key pair and CSR @@ -303,23 +303,23 @@ vcert gencsr --cn -o --ou --ou -l Example: `--csr-file /path-to/example.req` | -| `--format` | Generates the Certificate Signing Request in the specified format. Options: `pem` (default), `json`
- pem: Generates the CSR in classic PEM format to be used as a file.
- json: Generates the CSR in JSON format, suitable for REST API operations. | -| `--key-curve` | Use to specify the ECDSA key curve. Options: `p256` (default), `p384`, `p521` | -| `--key-file` | Use to specify a file name and a location where the resulting private key file should be written. Do not use in combination with `--csr` file.
Example: `--key-file /path-to/example.key` | -| `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, omit this option and instead specify `--no-prompt`.
Example: `--key-password file:/path-to/passwd.txt` | -| `--key-size` | Use to specify a key size. Default is 2048. | -| `--key-type` | Use to specify a key type. Options: `rsa` (default), `ecdsa` | -| `-l` | Use to specify the city or locality (L) for the Subject DN. | -| `--no-prompt` | Use to suppress the private key password prompt and not encrypt the private key. | -| `-o` | Use to specify the organization (O) for the Subject DN. | -| `--ou` | Use to specify an organizational unit (OU) for the Subject DN. To specify more than one, simply repeat this parameter for each value.
Example: `--ou "Engineering"` `--ou "Quality Assurance"` ... | -| `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-dns one.example.com` `--san-dns two.example.com` | -| `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-email me@example.com` `--san-email you@example.com` | -| `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | -| `--san-uri` | Use to specify a Uniform Resource Indicator Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-uri spiffe://workload1.example.com` `--san-uri spiffe://workload2.example.com` | -| `--st` | Use to specify the state or province (ST) for the Subject DN. | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `-c` | Use to specify the country (C) for the Subject DN. | +| `--cn` | Use to specify the common name (CN). This is required for enrollment except when providing a CSR file. | +| `--csr-file` | Use to specify a file name and a location where the resulting CSR file should be written.
Example: `--csr-file /path-to/example.req` | +| `--format` | Generates the Certificate Signing Request in the specified format. Options: `pem` (default), `json`
- pem: Generates the CSR in classic PEM format to be used as a file.
- json: Generates the CSR in JSON format, suitable for REST API operations. | +| `--key-curve` | Use to specify the ECDSA key curve. Options: `p256` (default), `p384`, `p521` | +| `--key-file` | Use to specify a file name and a location where the resulting private key file should be written. Do not use in combination with `--csr` file.
Example: `--key-file /path-to/example.key` | +| `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, omit this option and instead specify `--no-prompt`.
Example: `--key-password file:/path-to/passwd.txt` | +| `--key-size` | Use to specify a key size. Default is 2048. | +| `--key-type` | Use to specify a key type. Options: `rsa` (default), `ecdsa` | +| `-l` | Use to specify the city or locality (L) for the Subject DN. | +| `--no-prompt` | Use to suppress the private key password prompt and not encrypt the private key. | +| `-o` | Use to specify the organization (O) for the Subject DN. | +| `--ou` | Use to specify an organizational unit (OU) for the Subject DN. To specify more than one, simply repeat this parameter for each value.
Example: `--ou "Engineering"` `--ou "Quality Assurance"` ... | +| `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-dns one.example.com` `--san-dns two.example.com` | +| `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-email me@example.com` `--san-email you@example.com` | +| `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | +| `--san-uri` | Use to specify a Uniform Resource Indicator Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-uri spiffe://workload1.example.com` `--san-uri spiffe://workload2.example.com` | +| `--st` | Use to specify the state or province (ST) for the Subject DN. | diff --git a/README-CLI-FIREFLY.md b/README-CLI-FIREFLY.md index 4e4ed7a1..502445db 100644 --- a/README-CLI-FIREFLY.md +++ b/README-CLI-FIREFLY.md @@ -71,38 +71,38 @@ vcert enroll -u -t --cn -z Example: `--app-info "Venafi VCert CLI"` | -| `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.
Example: `--cert-file /path-to/example.crt` | -| `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.
Options: `root-last` (default), `root-first`, `ignore` | -| `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | -| `--cn` | Use to specify the common name (CN). This is required for Enrollment. | -| `--csr` | Use to specify the CSR and private key location. Options: `local` (default), `service`, `file`
- local: private key and CSR will be generated locally
- service: private key and CSR will be generated within Venafi Platform
- file: CSR will be read from a file by name
Example: `--csr file:/path-to/example.req` | -| `--field` | Use to specify Custom Fields in 'key=value' format. If many values are required for the same Custom Field (key), use the following syntax: `--field key1=value1` `--field key1=value2` ... | -| `--file` | Use to specify a name and location of an output file that will contain the private key and certificates when they are not written to their own files using `--key-file`, `--cert-file`, and/or `--chain-file`.
Example: `--file /path-to/keycert.pem` | -| `--format` | Use to specify the output format. The `--file` option must be used with the PKCS#12 and JKS formats to specify the keystore file. JKS format also requires `--jks-alias` and at least one password (see `--key-password` and `--jks-password`)
Options: `pem` (default), `json`, `pkcs12`, `jks` | -| `--instance` | Use to provide the name/address of the compute instance and an identifier for the workload using the certificate. This results in a device (node) and application (workload) being associated with the certificate in the Venafi Platform.
Example: `--instance node:workload` | -| `--jks-alias` | Use to specify the alias of the entry in the JKS file when `--format jks` is used | -| `--jks-password` | Use to specify the keystore password of the JKS file when `--format jks` is used. If not specified, the `--key-password` value is used for both the key and store passwords | -| `--key-curve` | Use to specify the elliptic curve for key generation when `--key-type` is ECDSA.
Options: `p256` (default), `p384`, `p521` | -| `--key-file` | Use to specify the name and location of an output file that will contain only the private key.
Example: `--key-file /path-to/example.key` | -| `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, specify `--no-prompt` without specifying this option. You can specify the password using one of three methods: at the command line, when prompted, or by using a password file.
Example: `--key-password file:/path-to/passwd.txt` | -| `--key-size` | Use to specify a key size for RSA keys. Default is 2048. | -| `--key-type` | Use to specify the key algorithm.
Options: `rsa` (default), `ecdsa` | -| `--nickname` | Use to specify a name for the new certificate object that will be created and placed in a folder (which you specify using the `-z` option). | -| `--no-pickup` | Use to disable the feature of VCert that repeatedly tries to retrieve the issued certificate. When this is used you must run VCert again in pickup mode to retrieve the certificate that was requested. | -| `--pickup-id-file` | Use to specify a file name where the unique identifier for the certificate will be stored for subsequent use by pickup, renew, and revoke actions. Default is to write the Pickup ID to STDOUT. | -| `--platform` | (REQUIRED) Use to specify the Venafi Firefly platform.
Example: `--platform firefly` | -| `--replace-instance` | Force the specified instance to be recreated if it already exists and is associated with the requested certificate. Default is for the request to fail if the instance already exists. | -| `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-dns one.example.com` `--san-dns two.example.com` | -| `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-email me@example.com` `--san-email you@example.com` | -| `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | -| `--tls-address` | Use to specify the hostname, FQDN or IP address and TCP port where the certificate can be validated after issuance and installation. Only allowed when `--instance` is also specified.
Example: `--tls-address 10.20.30.40:443` | -| `-u` | Use to specify the URL of the Venafi Firefly API server.
Example: `-u https://firefly.venafi.example` | -| `--valid-days` | Use to specify the number of days a certificate needs to be valid if supported/allowed by the CA template. Indicate the target issuer by appending #D for DigiCert, #E for Entrust, or #M for Microsoft.
Example: `--valid-days 90#M`
Note: You can use the `valid-period` flag instead of this. | -| `--valid-period` | Use to specify the validity period certificate needs to be valid expressed as an ISO 8601 duration. This parameter has precedence over `valid-days` parameter. | -| `-z` | Use to specify the policy name configured in _Firefly_.
Example: `-z "my policy"` | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--app-info` | Use to identify the application requesting the certificate with details like vendor name and vendor product.
Example: `--app-info "Venafi VCert CLI"` | +| `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.
Example: `--cert-file /path-to/example.crt` | +| `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.
Options: `root-last` (default), `root-first`, `ignore` | +| `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | +| `--cn` | Use to specify the common name (CN). This is required for Enrollment. | +| `--csr` | Use to specify the CSR and private key location. Options: `local` (default), `service`, `file`
- local: private key and CSR will be generated locally
- service: private key and CSR will be generated within Venafi Platform
- file: CSR will be read from a file by name
Example: `--csr file:/path-to/example.req` | +| `--field` | Use to specify Custom Fields in 'key=value' format. If many values are required for the same Custom Field (key), use the following syntax: `--field key1=value1` `--field key1=value2` ... | +| `--file` | Use to specify a name and location of an output file that will contain the private key and certificates when they are not written to their own files using `--key-file`, `--cert-file`, and/or `--chain-file`.
Example: `--file /path-to/keycert.pem` | +| `--format` | Use to specify the output format. The `--file` option must be used with the PKCS#12 and JKS formats to specify the keystore file. JKS format also requires `--jks-alias` and at least one password (see `--key-password` and `--jks-password`)
Options: `pem` (default), `legacy-pem`, `json`, `pkcs12`, `legacy-pkcs12` (analogous to OpenSSL 3.x -legacy flag), `jks` | +| `--instance` | Use to provide the name/address of the compute instance and an identifier for the workload using the certificate. This results in a device (node) and application (workload) being associated with the certificate in the Venafi Platform.
Example: `--instance node:workload` | +| `--jks-alias` | Use to specify the alias of the entry in the JKS file when `--format jks` is used | +| `--jks-password` | Use to specify the keystore password of the JKS file when `--format jks` is used. If not specified, the `--key-password` value is used for both the key and store passwords | +| `--key-curve` | Use to specify the elliptic curve for key generation when `--key-type` is ECDSA.
Options: `p256` (default), `p384`, `p521` | +| `--key-file` | Use to specify the name and location of an output file that will contain only the private key.
Example: `--key-file /path-to/example.key` | +| `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, specify `--no-prompt` without specifying this option. You can specify the password using one of three methods: at the command line, when prompted, or by using a password file.
Example: `--key-password file:/path-to/passwd.txt` | +| `--key-size` | Use to specify a key size for RSA keys. Default is 2048. | +| `--key-type` | Use to specify the key algorithm.
Options: `rsa` (default), `ecdsa` | +| `--nickname` | Use to specify a name for the new certificate object that will be created and placed in a folder (which you specify using the `-z` option). | +| `--no-pickup` | Use to disable the feature of VCert that repeatedly tries to retrieve the issued certificate. When this is used you must run VCert again in pickup mode to retrieve the certificate that was requested. | +| `--pickup-id-file` | Use to specify a file name where the unique identifier for the certificate will be stored for subsequent use by pickup, renew, and revoke actions. Default is to write the Pickup ID to STDOUT. | +| `--platform` | (REQUIRED) Use to specify the Venafi Firefly platform.
Example: `--platform firefly` | +| `--replace-instance` | Force the specified instance to be recreated if it already exists and is associated with the requested certificate. Default is for the request to fail if the instance already exists. | +| `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-dns one.example.com` `--san-dns two.example.com` | +| `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-email me@example.com` `--san-email you@example.com` | +| `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | +| `--tls-address` | Use to specify the hostname, FQDN or IP address and TCP port where the certificate can be validated after issuance and installation. Only allowed when `--instance` is also specified.
Example: `--tls-address 10.20.30.40:443` | +| `-u` | Use to specify the URL of the Venafi Firefly API server.
Example: `-u https://firefly.venafi.example` | +| `--valid-days` | Use to specify the number of days a certificate needs to be valid if supported/allowed by the CA template. Indicate the target issuer by appending #D for DigiCert, #E for Entrust, or #M for Microsoft.
Example: `--valid-days 90#M`
Note: You can use the `valid-period` flag instead of this. | +| `--valid-period` | Use to specify the validity period certificate needs to be valid expressed as an ISO 8601 duration. This parameter has precedence over `valid-days` parameter. | +| `-z` | Use to specify the policy name configured in _Firefly_.
Example: `-z "my policy"` | ## Examples diff --git a/README-CLI-PLATFORM.md b/README-CLI-PLATFORM.md index 84547faf..478e409d 100644 --- a/README-CLI-PLATFORM.md +++ b/README-CLI-PLATFORM.md @@ -68,19 +68,19 @@ VCert is compatible with Trust Protection Platform 17.3 or later. The Custom Fie The following options apply to the `enroll`, `pickup`, `renew`, `retire`, and `revoke` actions: -|         Command         | Description | -| ------------------- | ------------------------------------------------------------ | -| `--config` | Use to specify INI configuration file containing connection details. Available parameters: `tpp_url`, `access_token`, `tpp_user`, `tpp_password`, `tpp_zone`, `trust_bundle`, `test_mode` | -| `--no-prompt` | Use to exclude password prompts. If you enable the prompt and you enter incorrect information, an error is displayed. This option is useful with scripting. | -| `--t` | Use to specify the token required to authenticate with Venafi Platform 20.1 (and higher). See the [Appendix](#obtaining-an-authorization-token) for help using VCert to obtain a new authorization token. | -| `--test-mode` | Use to test operations without connecting to Venafi Platform. This option is useful for integration tests where the test environment does not have access to Venafi Platform. Default is false. | -| `--test-mode-delay` | Use to specify the maximum number of seconds for the random test-mode connection delay. Default is 15 (seconds). | -| `--timeout` | Use to specify the maximum amount of time to wait in seconds for a certificate to be processed by Venafi Platform. Default is 120 (seconds). | -| `--tpp-password` | **[DEPRECATED]** Use to specify the password required to authenticate with Venafi Platform. Use `-t` instead for Venafi Platform 20.1 (and higher). | -| `--tpp-user` | **[DEPRECATED]** Use to specify the username required to authenticate with Venafi Platform. Use `-t` instead for Venafi Platform 20.1 (and higher). | -| `--trust-bundle` | Use to specify a file with PEM formatted certificates to be used as trust anchors when communicating with Venafi Platform. VCert uses the trust store of your operating system for this purpose if not specified.
Example: `--trust-bundle /path-to/bundle.pem` | -| `-u` | Use to specify the URL of the Venafi Trust Protection Platform API server.
Example: `-u https://tpp.venafi.example` | -| `--verbose` | Use to increase the level of logging detail, which is helpful when troubleshooting issues. | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--config` | Use to specify INI configuration file containing connection details. Available parameters: `tpp_url`, `access_token`, `tpp_user`, `tpp_password`, `tpp_zone`, `trust_bundle`, `test_mode` | +| `--no-prompt` | Use to exclude password prompts. If you enable the prompt and you enter incorrect information, an error is displayed. This option is useful with scripting. | +| `--t` | Use to specify the token required to authenticate with Venafi Platform 20.1 (and higher). See the [Appendix](#obtaining-an-authorization-token) for help using VCert to obtain a new authorization token. | +| `--test-mode` | Use to test operations without connecting to Venafi Platform. This option is useful for integration tests where the test environment does not have access to Venafi Platform. Default is false. | +| `--test-mode-delay` | Use to specify the maximum number of seconds for the random test-mode connection delay. Default is 15 (seconds). | +| `--timeout` | Use to specify the maximum amount of time to wait in seconds for a certificate to be processed by Venafi Platform. Default is 120 (seconds). | +| `--tpp-password` | **[DEPRECATED]** Use to specify the password required to authenticate with Venafi Platform. Use `-t` instead for Venafi Platform 20.1 (and higher). | +| `--tpp-user` | **[DEPRECATED]** Use to specify the username required to authenticate with Venafi Platform. Use `-t` instead for Venafi Platform 20.1 (and higher). | +| `--trust-bundle` | Use to specify a file with PEM formatted certificates to be used as trust anchors when communicating with Venafi Platform. VCert uses the trust store of your operating system for this purpose if not specified.
Example: `--trust-bundle /path-to/bundle.pem` | +| `-u` | Use to specify the URL of the Venafi Trust Protection Platform API server.
Example: `-u https://tpp.venafi.example` | +| `--verbose` | Use to increase the level of logging detail, which is helpful when troubleshooting issues. | ### Environment Variables @@ -94,35 +94,35 @@ vcert enroll -u --tpp-user --tpp-password --cn < ``` Options: -|         Command         | Description | -| -------------------- | ------------------------------------------------------------ | -| `--app-info` | Use to identify the application requesting the certificate with details like vendor name and vendor product.
Example: `--app-info "Venafi VCert CLI"` | -| `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.
Example: `--cert-file /path-to/example.crt` | -| `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.
Options: `root-last` (default), `root-first`, `ignore` | -| `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | -| `--cn` | Use to specify the common name (CN). This is required for Enrollment. | -| `--csr` | Use to specify the CSR and private key location. Options: `local` (default), `service`, `file`
- local: private key and CSR will be generated locally
- service: private key and CSR will be generated within Venafi Platform
- file: CSR will be read from a file by name
Example: `--csr file:/path-to/example.req` | -| `--field` | Use to specify Custom Fields in 'key=value' format. If many values are required for the same Custom Field (key), use the following syntax: `--field key1=value1` `--field key1=value2` ... | -| `--file` | Use to specify a name and location of an output file that will contain the private key and certificates when they are not written to their own files using `--key-file`, `--cert-file`, and/or `--chain-file`.
Example: `--file /path-to/keycert.pem` | -| `--format` | Use to specify the output format. The `--file` option must be used with the PKCS#12 and JKS formats to specify the keystore file. JKS format also requires `--jks-alias` and at least one password (see `--key-password` and `--jks-password`)
Options: `pem` (default), `json`, `pkcs12`, `jks` | -| `--instance` | Use to provide the name/address of the compute instance and an identifier for the workload using the certificate. This results in a device (node) and application (workload) being associated with the certificate in the Venafi Platform.
Example: `--instance node:workload` | -| `--jks-alias` | Use to specify the alias of the entry in the JKS file when `--format jks` is used | -| `--jks-password` | Use to specify the keystore password of the JKS file when `--format jks` is used. If not specified, the `--key-password` value is used for both the key and store passwords | -| `--key-curve` | Use to specify the elliptic curve for key generation when `--key-type` is ECDSA.
Options: `p256` (default), `p384`, `p521` | -| `--key-file` | Use to specify the name and location of an output file that will contain only the private key.
Example: `--key-file /path-to/example.key` | -| `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, specify `--no-prompt` without specifying this option. You can specify the password using one of three methods: at the command line, when prompted, or by using a password file.
Example: `--key-password file:/path-to/passwd.txt` | -| `--key-size` | Use to specify a key size for RSA keys. Default is 2048. | -| `--key-type` | Use to specify the key algorithm.
Options: `rsa` (default), `ecdsa` | -| `--nickname` | Use to specify a name for the new certificate object that will be created and placed in a folder (which you specify using the `-z` option). | -| `--no-pickup` | Use to disable the feature of VCert that repeatedly tries to retrieve the issued certificate. When this is used you must run VCert again in pickup mode to retrieve the certificate that was requested. | -| `--pickup-id-file` | Use to specify a file name where the unique identifier for the certificate will be stored for subsequent use by pickup, renew, and revoke actions. Default is to write the Pickup ID to STDOUT. | -| `--replace-instance` | Force the specified instance to be recreated if it already exists and is associated with the requested certificate. Default is for the request to fail if the instance already exists. | -| `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-dns one.example.com` `--san-dns two.example.com` | -| `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-email me@example.com` `--san-email you@example.com` | -| `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | -| `--tls-address` | Use to specify the hostname, FQDN or IP address and TCP port where the certificate can be validated after issuance and installation. Only allowed when `--instance` is also specified.
Example: `--tls-address 10.20.30.40:443` | -| `--valid-days` | Use to specify the number of days a certificate needs to be valid if supported/allowed by the CA template. Indicate the target issuer by appending #D for DigiCert, #E for Entrust, or #M for Microsoft.
Example: `--valid-days 90#M` | -| `-z` | Use to specify the folder path where the certificate object will be placed. VCert prepends \VED\Policy\, so you only need to specify child folders under the root Policy folder.
Example: `-z DevOps\CorpApp` | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--app-info` | Use to identify the application requesting the certificate with details like vendor name and vendor product.
Example: `--app-info "Venafi VCert CLI"` | +| `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.
Example: `--cert-file /path-to/example.crt` | +| `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.
Options: `root-last` (default), `root-first`, `ignore` | +| `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | +| `--cn` | Use to specify the common name (CN). This is required for Enrollment. | +| `--csr` | Use to specify the CSR and private key location. Options: `local` (default), `service`, `file`
- local: private key and CSR will be generated locally
- service: private key and CSR will be generated within Venafi Platform
- file: CSR will be read from a file by name
Example: `--csr file:/path-to/example.req` | +| `--field` | Use to specify Custom Fields in 'key=value' format. If many values are required for the same Custom Field (key), use the following syntax: `--field key1=value1` `--field key1=value2` ... | +| `--file` | Use to specify a name and location of an output file that will contain the private key and certificates when they are not written to their own files using `--key-file`, `--cert-file`, and/or `--chain-file`.
Example: `--file /path-to/keycert.pem` | +| `--format` | Use to specify the output format. The `--file` option must be used with the PKCS#12 and JKS formats to specify the keystore file. JKS format also requires `--jks-alias` and at least one password (see `--key-password` and `--jks-password`)
Options: `pem` (default), `legacy-pem`, `json`, `pkcs12`, `legacy-pkcs12` (analogous to OpenSSL 3.x -legacy flag), `jks` | +| `--instance` | Use to provide the name/address of the compute instance and an identifier for the workload using the certificate. This results in a device (node) and application (workload) being associated with the certificate in the Venafi Platform.
Example: `--instance node:workload` | +| `--jks-alias` | Use to specify the alias of the entry in the JKS file when `--format jks` is used | +| `--jks-password` | Use to specify the keystore password of the JKS file when `--format jks` is used. If not specified, the `--key-password` value is used for both the key and store passwords | +| `--key-curve` | Use to specify the elliptic curve for key generation when `--key-type` is ECDSA.
Options: `p256` (default), `p384`, `p521` | +| `--key-file` | Use to specify the name and location of an output file that will contain only the private key.
Example: `--key-file /path-to/example.key` | +| `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, specify `--no-prompt` without specifying this option. You can specify the password using one of three methods: at the command line, when prompted, or by using a password file.
Example: `--key-password file:/path-to/passwd.txt` | +| `--key-size` | Use to specify a key size for RSA keys. Default is 2048. | +| `--key-type` | Use to specify the key algorithm.
Options: `rsa` (default), `ecdsa` | +| `--nickname` | Use to specify a name for the new certificate object that will be created and placed in a folder (which you specify using the `-z` option). | +| `--no-pickup` | Use to disable the feature of VCert that repeatedly tries to retrieve the issued certificate. When this is used you must run VCert again in pickup mode to retrieve the certificate that was requested. | +| `--pickup-id-file` | Use to specify a file name where the unique identifier for the certificate will be stored for subsequent use by pickup, renew, and revoke actions. Default is to write the Pickup ID to STDOUT. | +| `--replace-instance` | Force the specified instance to be recreated if it already exists and is associated with the requested certificate. Default is for the request to fail if the instance already exists. | +| `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-dns one.example.com` `--san-dns two.example.com` | +| `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-email me@example.com` `--san-email you@example.com` | +| `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | +| `--tls-address` | Use to specify the hostname, FQDN or IP address and TCP port where the certificate can be validated after issuance and installation. Only allowed when `--instance` is also specified.
Example: `--tls-address 10.20.30.40:443` | +| `--valid-days` | Use to specify the number of days a certificate needs to be valid if supported/allowed by the CA template. Indicate the target issuer by appending #D for DigiCert, #E for Entrust, or #M for Microsoft.
Example: `--valid-days 90#M` | +| `-z` | Use to specify the folder path where the certificate object will be placed. VCert prepends \VED\Policy\, so you only need to specify child folders under the root Policy folder.
Example: `-z DevOps\CorpApp` | ## Certificate Retrieval Parameters ``` @@ -132,17 +132,17 @@ vcert pickup -u --tpp-user --tpp-password [--pic ``` Options: -|         Command         | Description | -| ------------------ | ------------------------------------------------------------ | -| `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.
Example: `--cert-file /path-to/example.crt` | -| `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.
Options: `root-last` (default), `root-first`, `ignore` | -| `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | -| `--file` | Use to specify a name and location of an output file that will contain certificates when they are not written to their own files using `--cert-file` and/or `--chain-file`.
Example: `--file /path-to/keycert.pem` | -| `--format` | Use to specify the output format. The `--file` option must be used with the PKCS#12 and JKS formats to specify the keystore file. JKS format also requires `--jks-alias` and at least one password (see `--key-password` and `--jks-password`)
Options: `pem` (default), `json`, `pkcs12`, `jks` | -| `--jks-alias` | Use to specify the alias of the entry in the JKS file when `--format jks` is used | -| `--jks-password` | Use to specify the keystore password of the JKS file when `--format jks` is used. If not specified, the `--key-password` value is used for both the key and store passwords | -| `--pickup-id` | Use to specify the unique identifier of the certificate returned by the enroll or renew actions if `--no-pickup` was used or a timeout occurred. Required when `--pickup-id-file` is not specified. | -| `--pickup-id-file` | Use to specify a file name that contains the unique identifier of the certificate returned by the enroll or renew actions if --no-pickup was used or a timeout occurred. Required when `--pickup-id` is not specified. | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.
Example: `--cert-file /path-to/example.crt` | +| `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.
Options: `root-last` (default), `root-first`, `ignore` | +| `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | +| `--file` | Use to specify a name and location of an output file that will contain certificates when they are not written to their own files using `--cert-file` and/or `--chain-file`.
Example: `--file /path-to/keycert.pem` | +| `--format` | Use to specify the output format. The `--file` option must be used with the PKCS#12 and JKS formats to specify the keystore file. JKS format also requires `--jks-alias` and at least one password (see `--key-password` and `--jks-password`)
Options: `pem` (default), `legacy-pem`, `json`, `pkcs12`, `legacy-pkcs12` (analogous to OpenSSL 3.x -legacy flag), `jks` | +| `--jks-alias` | Use to specify the alias of the entry in the JKS file when `--format jks` is used | +| `--jks-password` | Use to specify the keystore password of the JKS file when `--format jks` is used. If not specified, the `--key-password` value is used for both the key and store passwords | +| `--pickup-id` | Use to specify the unique identifier of the certificate returned by the enroll or renew actions if `--no-pickup` was used or a timeout occurred. Required when `--pickup-id-file` is not specified. | +| `--pickup-id-file` | Use to specify a file name that contains the unique identifier of the certificate returned by the enroll or renew actions if --no-pickup was used or a timeout occurred. Required when `--pickup-id` is not specified. | ## Certificate Renewal Parameters @@ -153,30 +153,30 @@ vcert renew -u --tpp-user --tpp-password [--id < ``` Options: -|         Command         | Description | -| ------------------ | ------------------------------------------------------------ | -| `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.
Example: `--cert-file /path-to/example.crt` | -| `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.
Options: `root-last` (default), `root-first`, `ignore` | -| `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | -| `--cn` | Use to specify the common name (CN). This is required for Enrollment. | -| `--csr` | Use to specify the CSR and private key location. Options: `local` (default), `service`, `file`
- local: private key and CSR will be generated locally
- service: private key and CSR will be generated within Venafi Platform. Depending on policy, the private key may be reused
- file: CSR will be read from a file by name
Example: `--csr file:/path-to/example.req` | -| `--file` | Use to specify a name and location of an output file that will contain the private key and certificates when they are not written to their own files using `--key-file`, `--cert-file`, and/or `--chain-file`.
Example: `--file /path-to/keycert.pem` | -| `--format` | Use to specify the output format. The `--file` option must be used with the PKCS#12 and JKS formats to specify the keystore file. JKS format also requires `--jks-alias` and at least one password (see `--key-password` and `--jks-password`)
Options: `pem` (default), `json`, `pkcs12`, `jks` | -| `--id` | Use to specify the unique identifier of the certificate returned by the enroll or renew actions. Value may be specified as a string or read from a file by using the file: prefix.
Example: `--id file:cert_id.txt` | -| `--jks-alias` | Use to specify the alias of the entry in the JKS file when `--format jks` is used | -| `--jks-password` | Use to specify the keystore password of the JKS file when `--format jks` is used. If not specified, the `--key-password` value is used for both the key and store passwords | -| `--key-curve` | Use to specify the elliptic curve for key generation when `--key-type` is ECDSA.
Options: `p256` (default), `p384`, `p521` | -| `--key-file` | Use to specify the name and location of an output file that will contain only the private key.
Example: `--key-file /path-to/example.key` | -| `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, specify `--no-prompt` without specifying this option. You can specify the password using one of three methods: at the command line, when prompted, or by using a password file. | -| `--key-size` | Use to specify a key size for RSA keys. Default is 2048. | -| `--key-type` | Use to specify the key algorithm.
Options: `rsa` (default), `ecdsa` | -| `--no-pickup` | Use to disable the feature of VCert that repeatedly tries to retrieve the issued certificate. When this is used you must run VCert again in pickup mode to retrieve the certificate that was requested. | -| `--omit-sans` | Ignore SANs in the previous certificate when preparing the renewal request. Workaround for CAs that forbid any SANs even when the SANs match those the CA automatically adds to the issued certificate. | -| `--pickup-id-file` | Use to specify a file name where the unique identifier for the certificate will be stored for subsequent use by `pickup`, `renew`, and `revoke` actions. By default it is written to STDOUT. | -| `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-dns one.example.com` `--san-dns two.example.com` | -| `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-email me@example.com` `--san-email you@example.com` | -| `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | -| `--thumbprint` | Use to specify the SHA1 thumbprint of the certificate to renew. Value may be specified as a string or read from the certificate file using the `file:` prefix. | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--cert-file` | Use to specify the name and location of an output file that will contain only the end-entity certificate.
Example: `--cert-file /path-to/example.crt` | +| `--chain` | Use to include the certificate chain in the output, and to specify where to place it in the file.
Options: `root-last` (default), `root-first`, `ignore` | +| `--chain-file` | Use to specify the name and location of an output file that will contain only the root and intermediate certificates applicable to the end-entity certificate. | +| `--cn` | Use to specify the common name (CN). This is required for Enrollment. | +| `--csr` | Use to specify the CSR and private key location. Options: `local` (default), `service`, `file`
- local: private key and CSR will be generated locally
- service: private key and CSR will be generated within Venafi Platform. Depending on policy, the private key may be reused
- file: CSR will be read from a file by name
Example: `--csr file:/path-to/example.req` | +| `--file` | Use to specify a name and location of an output file that will contain the private key and certificates when they are not written to their own files using `--key-file`, `--cert-file`, and/or `--chain-file`.
Example: `--file /path-to/keycert.pem` | +| `--format` | Use to specify the output format. The `--file` option must be used with the PKCS#12 and JKS formats to specify the keystore file. JKS format also requires `--jks-alias` and at least one password (see `--key-password` and `--jks-password`)
Options: `pem` (default), `legacy-pem`, `json`, `pkcs12`, `legacy-pkcs12` (analogous to OpenSSL 3.x -legacy flag), `jks` | +| `--id` | Use to specify the unique identifier of the certificate returned by the enroll or renew actions. Value may be specified as a string or read from a file by using the file: prefix.
Example: `--id file:cert_id.txt` | +| `--jks-alias` | Use to specify the alias of the entry in the JKS file when `--format jks` is used | +| `--jks-password` | Use to specify the keystore password of the JKS file when `--format jks` is used. If not specified, the `--key-password` value is used for both the key and store passwords | +| `--key-curve` | Use to specify the elliptic curve for key generation when `--key-type` is ECDSA.
Options: `p256` (default), `p384`, `p521` | +| `--key-file` | Use to specify the name and location of an output file that will contain only the private key.
Example: `--key-file /path-to/example.key` | +| `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, specify `--no-prompt` without specifying this option. You can specify the password using one of three methods: at the command line, when prompted, or by using a password file. | +| `--key-size` | Use to specify a key size for RSA keys. Default is 2048. | +| `--key-type` | Use to specify the key algorithm.
Options: `rsa` (default), `ecdsa` | +| `--no-pickup` | Use to disable the feature of VCert that repeatedly tries to retrieve the issued certificate. When this is used you must run VCert again in pickup mode to retrieve the certificate that was requested. | +| `--omit-sans` | Ignore SANs in the previous certificate when preparing the renewal request. Workaround for CAs that forbid any SANs even when the SANs match those the CA automatically adds to the issued certificate. | +| `--pickup-id-file` | Use to specify a file name where the unique identifier for the certificate will be stored for subsequent use by `pickup`, `renew`, and `revoke` actions. By default it is written to STDOUT. | +| `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-dns one.example.com` `--san-dns two.example.com` | +| `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-email me@example.com` `--san-email you@example.com` | +| `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | +| `--thumbprint` | Use to specify the SHA1 thumbprint of the certificate to renew. Value may be specified as a string or read from the certificate file using the `file:` prefix. | ## Certificate Revocation Parameters @@ -187,12 +187,12 @@ vcert revoke -u --tpp-user --tpp-password [--id ``` Options: -|         Command         | Description | -| -------------- | ------------------------------------------------------------ | -| `--id` | Use to specify the unique identifier of the certificate to revoke. Value may be specified as a string or read from a file using the `file:` prefix. | -| `--no-retire` | Do not disable certificate. Use this option if you intend to enroll a new version of the certificate later. Works only with `--id` | -| `--reason` | Use to specify the revocation reason.
Options: `none` (default), `key-compromise`, `ca-compromise`, `affiliation-changed`, `superseded`, `cessation-of-operation` | -| `--thumbprint` | Use to specify the SHA1 thumbprint of the certificate to revoke. Value may be specified as a string or read from the certificate file using the `file:` prefix. | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--id` | Use to specify the unique identifier of the certificate to revoke. Value may be specified as a string or read from a file using the `file:` prefix. | +| `--no-retire` | Do not disable certificate. Use this option if you intend to enroll a new version of the certificate later. Works only with `--id` | +| `--reason` | Use to specify the revocation reason.
Options: `none` (default), `key-compromise`, `ca-compromise`, `affiliation-changed`, `superseded`, `cessation-of-operation` | +| `--thumbprint` | Use to specify the SHA1 thumbprint of the certificate to revoke. Value may be specified as a string or read from the certificate file using the `file:` prefix. | ## Certificate Retire Parameters ``` @@ -200,10 +200,10 @@ vcert retire -u -t [--id | --thumbprint -t -z --file -t -z [--file --p12-file --p12-password Example: `-u https://tpp.venafi.example` | -| `--username` | Use to specify the username of a Venafi Platform user. Required if `--p12-file` or `--t` is not present and may not be combined with either. | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--client-id` | Use to specify the application that will be using the token. "vcert-cli" is the default. | +| `--format` | Specify "json" to get JSON formatted output instead of the plain text default. | +| `--password` | Use to specify the Venafi Platform user's password. | +| `--p12-file` | Use to specify a PKCS#12 file containing a client certificate (and private key) of a Venafi Platform user to be used for mutual TLS. Required if `--username` or `--t` is not present and may not be combined with either. Must specify `--trust-bundle` if the chain for the client certificate is not in the PKCS#12 file. | +| `--p12-password` | Use to specify the password of the PKCS#12 file containing the client certificate. | +| `--scope` | Use to request specific scopes and restrictions. "certificate:manage,revoke;" is the default which is the minimum required to perform any actions supported by the VCert CLI. | +| `-t` | Use to specify a refresh token for a Venafi Platform user. Required if `--username` or `--p12-file` is not present and may not be combined with either. | +| `--trust-bundle` | Use to specify a PEM file name to be used as trust anchors when communicating with the Venafi Platform API server. | +| `-u` | Use to specify the URL of the Venafi Trust Protection Platform API server.
Example: `-u https://tpp.venafi.example` | +| `--username` | Use to specify the username of a Venafi Platform user. Required if `--p12-file` or `--t` is not present and may not be combined with either. | ### Checking the validity of an Authorization Token ![Minimum Patch Level: TPP 20.2.2+ and 20.3.3+](https://img.shields.io/badge/Minimum%20Patch%20Level-%20TPP%2020.2.2%20and%2020.3.3-f9a90c) @@ -371,12 +371,12 @@ vcert checkcred -u -t ``` Options: -|         Command         | Description | -| ---------------- | ------------------------------------------------------------ | -| `--format` | Specify "json" to get JSON formatted output instead of the plain text default. | -| `-t` | Use to specify an access token for a Venafi Platform user. | -| `--trust-bundle` | Use to specify a PEM file name to be used as trust anchors when communicating with the Venafi Platform API server. | -| `-u` | Use to specify the URL of the Venafi Trust Protection Platform API server.
Example: `-u https://tpp.venafi.example` | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------| +| `--format` | Specify "json" to get JSON formatted output instead of the plain text default. | +| `-t` | Use to specify an access token for a Venafi Platform user. | +| `--trust-bundle` | Use to specify a PEM file name to be used as trust anchors when communicating with the Venafi Platform API server. | +| `-u` | Use to specify the URL of the Venafi Trust Protection Platform API server.
Example: `-u https://tpp.venafi.example` | ### Invalidating an Authorization Token ``` @@ -384,11 +384,11 @@ vcert voidcred -u -t ``` Options: -|         Command         | Description | -| ---------------- | ------------------------------------------------------------ | -| `-t` | Use to specify an access token for a Venafi Platform user. | -| `--trust-bundle` | Use to specify a PEM file name to be used as trust anchors when communicating with the Venafi Platform API server. | -| `-u` | Use to specify the URL of the Venafi Trust Protection Platform API server.
Example: `-u https://tpp.venafi.example` | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------| +| `-t` | Use to specify an access token for a Venafi Platform user. | +| `--trust-bundle` | Use to specify a PEM file name to be used as trust anchors when communicating with the Venafi Platform API server. | +| `-u` | Use to specify the URL of the Venafi Trust Protection Platform API server.
Example: `-u https://tpp.venafi.example` | ### Generating a new key pair and CSR ``` @@ -397,23 +397,23 @@ vcert gencsr --cn -o --ou --ou -l Example: `--csr-file /path-to/example.req` | -| `--format` | Generates the Certificate Signing Request in the specified format. Options: `pem` (default), `json`
- pem: Generates the CSR in classic PEM format to be used as a file.
- json: Generates the CSR in JSON format, suitable for REST API operations. | -| `--key-curve` | Use to specify the ECDSA key curve. Options: `p256` (default), `p384`, `p521` | -| `--key-file` | Use to specify a file name and a location where the resulting private key file should be written. Do not use in combination with `--csr` file.
Example: `--key-file /path-to/example.key` | -| `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, omit this option and instead specify `--no-prompt`.
Example: `--key-password file:/path-to/passwd.txt` | -| `--key-size` | Use to specify a key size. Default is 2048. | -| `--key-type` | Use to specify a key type. Options: `rsa` (default), `ecdsa` | -| `-l` | Use to specify the city or locality (L) for the Subject DN. | -| `--no-prompt` | Use to suppress the private key password prompt and not encrypt the private key. | -| `-o` | Use to specify the organization (O) for the Subject DN. | -| `--ou` | Use to specify an organizational unit (OU) for the Subject DN. To specify more than one, simply repeat this parameter for each value.
Example: `--ou "Engineering"` `--ou "Quality Assurance"` ... | -| `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-dns one.example.com` `--san-dns two.example.com` | -| `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-email me@example.com` `--san-email you@example.com` | -| `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | -| `--san-uri` | Use to specify a Uniform Resource Indicator Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-uri spiffe://workload1.example.com` `--san-uri spiffe://workload2.example.com` | -| `--st` | Use to specify the state or province (ST) for the Subject DN. | +|         Command         | Description | +|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `-c` | Use to specify the country (C) for the Subject DN. | +| `--cn` | Use to specify the common name (CN). This is required for enrollment except when providing a CSR file. | +| `--csr-file` | Use to specify a file name and a location where the resulting CSR file should be written.
Example: `--csr-file /path-to/example.req` | +| `--format` | Generates the Certificate Signing Request in the specified format. Options: `pem` (default), `json`
- pem: Generates the CSR in classic PEM format to be used as a file.
- json: Generates the CSR in JSON format, suitable for REST API operations. | +| `--key-curve` | Use to specify the ECDSA key curve. Options: `p256` (default), `p384`, `p521` | +| `--key-file` | Use to specify a file name and a location where the resulting private key file should be written. Do not use in combination with `--csr` file.
Example: `--key-file /path-to/example.key` | +| `--key-password` | Use to specify a password for encrypting the private key. For a non-encrypted private key, omit this option and instead specify `--no-prompt`.
Example: `--key-password file:/path-to/passwd.txt` | +| `--key-size` | Use to specify a key size. Default is 2048. | +| `--key-type` | Use to specify a key type. Options: `rsa` (default), `ecdsa` | +| `-l` | Use to specify the city or locality (L) for the Subject DN. | +| `--no-prompt` | Use to suppress the private key password prompt and not encrypt the private key. | +| `-o` | Use to specify the organization (O) for the Subject DN. | +| `--ou` | Use to specify an organizational unit (OU) for the Subject DN. To specify more than one, simply repeat this parameter for each value.
Example: `--ou "Engineering"` `--ou "Quality Assurance"` ... | +| `--san-dns` | Use to specify a DNS Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-dns one.example.com` `--san-dns two.example.com` | +| `--san-email` | Use to specify an Email Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-email me@example.com` `--san-email you@example.com` | +| `--san-ip` | Use to specify an IP Address Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-ip 10.20.30.40` `--san-ip 192.168.192.168` | +| `--san-uri` | Use to specify a Uniform Resource Indicator Subject Alternative Name. To specify more than one, simply repeat this parameter for each value.
Example: `--san-uri spiffe://workload1.example.com` `--san-uri spiffe://workload2.example.com` | +| `--st` | Use to specify the state or province (ST) for the Subject DN. |