mirror of
https://github.com/inspec/inspec
synced 2024-11-22 20:53:11 +00:00
Doc Review
Signed-off-by: Deepa Kumaraswamy <dkumaras@progress.com>
This commit is contained in:
Deepa Kumaraswamy
parent
e879ef89a5
commit
15f45fdaad
1 changed files with 37 additions and 47 deletions
|
|
@ -13,21 +13,17 @@ platform = "os"
|
|||
|
||||
Use the `x509_certificate` Chef InSpec audit resource to test the fields and validity of an x.509 certificate.
|
||||
|
||||
X.509 certificates use public/private key pairs to sign and encrypt documents
|
||||
or communications over a network. They may also be used for authentication.
|
||||
|
||||
Examples include SSL certificates, S/MIME certificates and VPN authentication
|
||||
certificates.
|
||||
X.509 certificate uses public or private key pairs to sign and encrypt communications and documents over a network. These certificates are also used for network authentication. Examples include Secure Sockets Layer (SSL) certificates, Secure/Multipurpose Internet Mail Extensions (S/MIME) certificates, and Virtual Private Network (VPN) authentication certificates.
|
||||
|
||||
## Availability
|
||||
|
||||
### Installation
|
||||
|
||||
This resource is distributed along with Chef InSpec itself. You can use it automatically.
|
||||
Chef InSpec distributes this resource.
|
||||
|
||||
### Version
|
||||
|
||||
This resource first became available in v1.18.0 of InSpec.
|
||||
This resource is available from InSpec version 1.18.
|
||||
|
||||
## Syntax
|
||||
|
||||
|
|
@ -43,7 +39,7 @@ The `filepath` property can also be used.
|
|||
its('validity_in_days') { should be > 30 }
|
||||
end
|
||||
|
||||
The resource also supports passing in the certificate content.
|
||||
This resource also supports passing the content of the certificate.
|
||||
|
||||
cert_content = file('certificate.pem').content
|
||||
|
||||
|
|
@ -51,23 +47,23 @@ The resource also supports passing in the certificate content.
|
|||
its('validity_in_days') { should be > 30 }
|
||||
end
|
||||
|
||||
If both `content` and `filepath` is given, the value passed in `content` is used.
|
||||
The `content` value is used if the `content` and `filepath` are specified.
|
||||
|
||||
## Properties
|
||||
|
||||
### subject.XX
|
||||
|
||||
`subject` property makes it easier to access individual subject elements.
|
||||
The `subject` (string) property accesses the individual subject elements.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
its('subject.CN') { should eq "www.mywebsite.com" }
|
||||
end
|
||||
|
||||
### subject_dn (String)
|
||||
### subject_dn
|
||||
|
||||
The `subject_dn` string returns the distinguished name of the subject field. It contains several fields separated by forward slashes. The field identifiers are the same ones used by OpenSSL to generate CSR's and certs. Use `subject.XX` instead to access the parsed version.
|
||||
The `subject_dn` (string) property returns the distinguished name of the subject field. It contains many fields separated by forward slashes (/). The field identifiers are the same ones used by OpenSSL to generate Certificate Signing Requests (CSR's) and certificates. To access the parsed version, use `subject.XX` instead.
|
||||
|
||||
e.g. `/C=US/L=Seattle/O=Chef Software Inc/OU=Chefs/CN=Richard Nixon`
|
||||
For example, `/C=US/L=Seattle/O=Chef Software Inc/OU=Chefs/CN=Richard Nixon`
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
its('subject_dn') { should match "CN=www.mywebsite.com" }
|
||||
|
|
@ -75,36 +71,33 @@ e.g. `/C=US/L=Seattle/O=Chef Software Inc/OU=Chefs/CN=Richard Nixon`
|
|||
|
||||
### issuer.XX
|
||||
|
||||
`issuer` makes it easier to access individual issuer elements.
|
||||
The `issuer` (string) property accesses the individual issuer elements.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
its('issuer.CN') { should eq "Acme Trust CA" }
|
||||
end
|
||||
|
||||
### issuer_dn (String)
|
||||
### issuer_dn
|
||||
|
||||
The `issuer_dn` is the distinguished name from a CA (certificate authority) during the
|
||||
certificate signing process. It describes which authority is guaranteeing the
|
||||
identity of our certificate.
|
||||
During the certificate signing process, the `issuer_dn` (string) property is the distinguished name from a Certificate Authority (CA). This property states which authority is guaranteeing the identity of the certificate.
|
||||
|
||||
e.g. `/C=US/L=Seattle/CN=Acme Trust CA/emailAddress=support@acmetrust.org`
|
||||
For example, `/C=US/L=Seattle/CN=Acme Trust CA/emailAddress=support@acmetrust.org`
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
its('issuer_cn') { should match "CN=Acme Trust CA" }
|
||||
its('issuer_cn') { should match "CN=NAME CA" }
|
||||
end
|
||||
|
||||
### public_key (String)
|
||||
### public_key
|
||||
|
||||
The `public_key` property returns a base64 encoded public key in PEM format.
|
||||
The `public_key` (string) property returns a base64 encoded public key in PEM format.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
its('public_key') { should match "-----BEGIN PUBLIC KEY-----\nblah blah blah..." }
|
||||
end
|
||||
|
||||
### key_length (Integer)
|
||||
### key_length
|
||||
|
||||
The `key_length` property calculates the number of bits in the public key.
|
||||
More bits increase security, but at the cost of speed and in extreme cases, compatibility.
|
||||
The `key_length` (integer) property calculates the number of bits in the public key. If the length of bits in the public key increases, the public keys are secure. However, at the cost of speed and compatibility.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
its('key_length') { should be 2048 }
|
||||
|
|
@ -112,59 +105,56 @@ More bits increase security, but at the cost of speed and in extreme cases, comp
|
|||
|
||||
### keylength
|
||||
|
||||
The `keylength` property is an alias of the `key_length` property.
|
||||
The `keylength` (integer) property is an alias of the `key_length` property.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
its('keylength') { should be 2048 }
|
||||
end
|
||||
|
||||
### signature_algorithm (String)
|
||||
### signature_algorithm
|
||||
|
||||
The `signature_algorithm` property describes which hash function was used by the CA to
|
||||
sign the certificate.
|
||||
The `signature_algorithm` (string) property describes the CA's hash function to sign the certificate.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
its('signature_algorithm') { should be 'sha256WithRSAEncryption' }
|
||||
end
|
||||
|
||||
### validity_in_days (Float)
|
||||
### validity_in_days
|
||||
|
||||
The `validity_in_days` property can be used to check that certificates are not in
|
||||
danger of expiring soon.
|
||||
The `validity_in_days` (float) property is used to check the validity of the certificates.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
its('validity_in_days') { should be > 30 }
|
||||
end
|
||||
|
||||
### not_before and not_after (Time)
|
||||
### not_before and not_after
|
||||
|
||||
The `not_before` and `not_after` properties expose the start and end dates of certificate
|
||||
validity. They are exposed as ruby Time class so that date arithmetic can be easily performed.
|
||||
The `not_before` and `not_after` (time) properties expose the start and end dates of certificate validity. These dates are exposed as Ruby **Time** class and perform date calculations.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
its('not_before') { should be <= Time.utc.now }
|
||||
its('not_after') { should be >= Time.utc.now }
|
||||
end
|
||||
|
||||
### serial (Integer)
|
||||
### serial
|
||||
|
||||
The `serial` property exposes the serial number of the certificate. The serial number is set by the CA during the signing process and should be unique within that CA.
|
||||
The `serial` (integer) property exposes the certificate's serial number. The CA sets the serial number during the signing process and should be unique within that CA.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
its('serial') { should eq 9623283588743302433 }
|
||||
end
|
||||
|
||||
### version (Integer)
|
||||
### version
|
||||
|
||||
The `version` property exposes the certificate version.
|
||||
The `version` (integer) property exposes the certificate version.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
its('version') { should eq 2 }
|
||||
end
|
||||
|
||||
### extensions (Hash)
|
||||
### extensions
|
||||
|
||||
The `extensions` hash property is mainly used to determine what the certificate can be used for.
|
||||
The `extensions` (hash) property is mainly used to determine the purpose of the certificate.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
# Check what extension categories we have
|
||||
|
|
@ -187,7 +177,7 @@ The `extensions` hash property is mainly used to determine what the certificate
|
|||
|
||||
### email
|
||||
|
||||
The `email` property checks for the email address of the certificate. This is equivalent to invoking the property `subject.emailAddress`.
|
||||
The `email` (string) property checks for the email address of the certificate. This is equivalent to invoking the property `subject.emailAddress`.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
its('email') { should_not be_empty }
|
||||
|
|
@ -196,7 +186,7 @@ The `email` property checks for the email address of the certificate. This is eq
|
|||
|
||||
### subject_alt_names
|
||||
|
||||
The `subject_alt_names` property checks for the subject alternative names of the certificate.
|
||||
The `subject_alt_names` (string) property checks for the subject alternative names (additional host names) of the certificate.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
its('subject_alt_names') { should include 'DNS:example.com' }
|
||||
|
|
@ -207,11 +197,11 @@ The `subject_alt_names` property checks for the subject alternative names of the
|
|||
|
||||
For a full list of available matchers, please visit our [matchers page](https://docs.chef.io/inspec/matchers/).
|
||||
|
||||
The specific matchers of this resource are: `be_valid`, `be_certificate` and `have_purpose`
|
||||
The specific matchers of this resource are: `be_valid`, `be_certificate` and `have_purpose`.
|
||||
|
||||
### be_valid
|
||||
|
||||
The `be_valid` matcher tests if the given certificate is valid.
|
||||
The `be_valid` matcher tests if the specified certificate is valid.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
it { should be_valid }
|
||||
|
|
@ -219,7 +209,7 @@ The `be_valid` matcher tests if the given certificate is valid.
|
|||
|
||||
### be_certificate
|
||||
|
||||
The `be_certificate` matcher tests if the given content or file is a certificate.
|
||||
The `be_certificate` matcher tests if the specified content or file is a certificate.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
it { should be_certificate }
|
||||
|
|
@ -227,7 +217,7 @@ The `be_certificate` matcher tests if the given content or file is a certificate
|
|||
|
||||
### have_purpose
|
||||
|
||||
The `have_purpose` matcher tests if the certificate has the specified purpose enabled or not.
|
||||
The `have_purpose` matcher tests if the certificate meets the specified purpose.
|
||||
|
||||
describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
|
||||
it { should have_purpose('SSL client CA : Yes') }
|
||||
|
|
|
|||
Loading…
Reference in a new issue