Class: Win32::Certstore

Inherits:
Object
  • Object
show all
Extended by:
Mixin::Assertions
Includes:
Mixin::Crypto, Mixin::String, StoreBase
Defined in:
lib/win32/certstore.rb,
lib/win32/certstore/version.rb,
lib/win32/certstore/store_base.rb,
lib/win32/certstore/mixin/crypto.rb,
lib/win32/certstore/mixin/helper.rb,
lib/win32/certstore/mixin/string.rb,
lib/win32/certstore/mixin/assertions.rb,
lib/win32/certstore/mixin/shell_exec.rb

Defined Under Namespace

Modules: Mixin, StoreBase

Constant Summary collapse

VERSION = 
"0.6.1".freeze

Constants included from Mixin::Crypto

Mixin::Crypto::BLOB, Mixin::Crypto::BOOL, Mixin::Crypto::BYTE, Mixin::Crypto::CERT_CLOSE_STORE_CHECK_FLAG, Mixin::Crypto::CERT_CLOSE_STORE_FORCE_FLAG, Mixin::Crypto::CERT_COMPARE_ANY, Mixin::Crypto::CERT_COMPARE_NAME_STR_W, Mixin::Crypto::CERT_COMPARE_SHA1_HASH, Mixin::Crypto::CERT_COMPARE_SHIFT, Mixin::Crypto::CERT_FIND_ANY, Mixin::Crypto::CERT_FIND_SHA1_HASH, Mixin::Crypto::CERT_FIND_SUBJECT_STR, Mixin::Crypto::CERT_INFO_SUBJECT_FLAG, Mixin::Crypto::CERT_NAME_ATTR_TYPE, Mixin::Crypto::CERT_NAME_DISABLE_IE4_UTF8_FLAG, Mixin::Crypto::CERT_NAME_DNS_TYPE, Mixin::Crypto::CERT_NAME_EMAIL_TYPE, Mixin::Crypto::CERT_NAME_FRIENDLY_DISPLAY_TYPE, Mixin::Crypto::CERT_NAME_ISSUER_FLAG, Mixin::Crypto::CERT_NAME_RDN_TYPE, Mixin::Crypto::CERT_NAME_SEARCH_ALL_NAMES_FLAG, Mixin::Crypto::CERT_NAME_SIMPLE_DISPLAY_TYPE, Mixin::Crypto::CERT_NAME_STR_ENABLE_PUNYCODE_FLAG, Mixin::Crypto::CERT_NAME_UPN_TYPE, Mixin::Crypto::CERT_NAME_URL_TYPE, Mixin::Crypto::CERT_STORE_ADD_REPLACE_EXISTING, Mixin::Crypto::CERT_STORE_ADD_USE_EXISTING, Mixin::Crypto::CERT_STORE_PROV_SYSTEM, Mixin::Crypto::CERT_SYSTEM_STORE_CURRENT_USER, Mixin::Crypto::CERT_SYSTEM_STORE_LOCAL_MACHINE, Mixin::Crypto::CERT_SYSTEM_STORE_SERVICES, Mixin::Crypto::CERT_SYSTEM_STORE_USERS, Mixin::Crypto::CRYPT_ASN_ENCODING, Mixin::Crypto::CRYPT_NDR_ENCODING, Mixin::Crypto::DWORD, Mixin::Crypto::ENCODING_TYPE, Mixin::Crypto::HCERTSTORE, Mixin::Crypto::HCRYPTPROV_LEGACY, Mixin::Crypto::INT_PTR, Mixin::Crypto::LMSTR, Mixin::Crypto::LONG, Mixin::Crypto::LPCTSTR, Mixin::Crypto::LPFILETIME, Mixin::Crypto::LPSTR, Mixin::Crypto::LPTSTR, Mixin::Crypto::LPVOID, Mixin::Crypto::PCCERT_CONTEXT, Mixin::Crypto::PCERT_INFO, Mixin::Crypto::PCTL_USAGE, Mixin::Crypto::PCTL_VERIFY_USAGE_PARA, Mixin::Crypto::PCTL_VERIFY_USAGE_STATUS, Mixin::Crypto::PKCS_7_ASN_ENCODING, Mixin::Crypto::PKCS_7_NDR_ENCODING, Mixin::Crypto::PKCS_7_OR_X509_ASN_ENCODING, Mixin::Crypto::PWSTR, Mixin::Crypto::X509_ASN_ENCODING, Mixin::Crypto::X509_NDR_ENCODING

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Mixin::Assertions

lookup_error, validate!, validate_certificate, validate_certificate_obj, validate_store, validate_thumbprint

Methods included from StoreBase

#cert_add, #cert_add_pfx, #cert_delete, #cert_get, #cert_list, #cert_search, #cert_validate, #close_cert_store

Methods included from Mixin::Helper

#cert_ps_cmd, #valid_duration?

Methods included from Mixin::ShellExec

#powershell_exec, #powershell_exec!, #shell_out_command

Methods included from Mixin::String

#utf8_to_wide, #wide_to_utf8, #wstring

Methods included from FFI::Library

#safe_attach_function

Constructor Details

#initialize(store_name, store_location: CERT_SYSTEM_STORE_LOCAL_MACHINE) ⇒ Certstore

Initializes a new instance of a certificate store. takes 2 parameters - the store name (My, Root, etc) and the location (CurrentUser or LocalMachine), it defaults to LocalMachine for backwards compatibility



36
37
38
39
40
 
# File 'lib/win32/certstore.rb', line 36

def initialize(store_name, store_location: CERT_SYSTEM_STORE_LOCAL_MACHINE)
  @store_name = store_name
  @store_location = store_location
  @certstore_handler = open(store_name, store_location: store_location)
end

Instance Attribute Details

#store_name ⇒ Object

Returns the value of attribute store_name.



32
33
34
 
# File 'lib/win32/certstore.rb', line 32

def store_name
  @store_name
end

Class Method Details

.finalize(certstore_handler) ⇒ Object 



127
128
129
 
# File 'lib/win32/certstore.rb', line 127

def self.finalize(certstore_handler)
  proc { certstore_handler.to_s }
end

.open(store_name, store_location: CERT_SYSTEM_STORE_LOCAL_MACHINE) ⇒ Object

To open given certificate store



43
44
45
46
47
48
49
50
 
# File 'lib/win32/certstore.rb', line 43

def self.open(store_name, store_location: CERT_SYSTEM_STORE_LOCAL_MACHINE)
  validate_store(store_name)
  if block_given?
    yield new(store_name, store_location: store_location)
  else
    new(store_name, store_location: store_location)
  end
end

Instance Method Details

#add(certificate_obj) ⇒ true, false

Adds a new certificate to an open certificate store

Parameters:

  • request (Object) —

    of certificate in OpenSSL::X509::Certificate.new format

Returns:

  • (true, false) —

    only true or false



55
56
57
 
# File 'lib/win32/certstore.rb', line 55

def add(certificate_obj)
  cert_add(certstore_handler, certificate_obj)
end

#add_pfx(path, password, key_properties = 0) ⇒ Boolean

Note:

Unlike other certificates, PFX can be password protected and may contain a private key. Therefore we need a different approach to import them.

Adds a PFX certificate to certificate store

Parameters:

  • path (String) —

    Path of the certificate that should be imported

  • password (String) —

    Password of the certificate if it is protected

  • key_properties (Integer) (defaults to: 0) —

    dwFlags used to specify properties of the pfx key, see certstore/store_base.rb cert_add_pfx function

Returns:

  • (Boolean) 


70
71
72
 
# File 'lib/win32/certstore.rb', line 70

def add_pfx(path, password, key_properties = 0)
  cert_add_pfx(certstore_handler, path, password, key_properties)
end

#close ⇒ Object

To close and destroy pointer of open certificate store handler



122
123
124
125
 
# File 'lib/win32/certstore.rb', line 122

def close
  close_cert_store
  remove_finalizer
end

#delete(certificate_thumbprint) ⇒ true, false

Delete existing certificate from open certificate store

Parameters:

  • request (thumbprint<string>) —

    of certificate

Returns:

  • (true, false) —

    only true or false



103
104
105
 
# File 'lib/win32/certstore.rb', line 103

def delete(certificate_thumbprint)
  cert_delete(certstore_handler, certificate_thumbprint)
end

#get(certificate_thumbprint) ⇒ Object

Return ‘OpenSSL::X509` certificate object

Parameters:

  • request (thumbprint<string>) —

    of certificate

Returns:

  • (Object) —

    of certificates in OpenSSL::X509 format



77
78
79
 
# File 'lib/win32/certstore.rb', line 77

def get(certificate_thumbprint)
  cert_get(certificate_thumbprint)
end

#get_pfx(certificate_thumbprint, store_location: @store_location, export_password:, output_path: "") ⇒ Object

Returns a filepath to a PKCS12 container. The filepath is in a temporary folder so normal housekeeping by the OS should clear it. However, you should delete it yourself anyway. them and a password is required to export them.

Parameters:

  • certificate_thumbprint (String) —

    Is the thumbprint of the pfx blob you want to capture

  • store_location: (String) (defaults to: @store_location) —

    A location in the Cert store where the pfx is located, typically ‘LocalMachine’

  • export_password: (String) —

    The password to export with. P12 objects are an encrypted container that have a private key in \

  • output_path: (String) (defaults to: "") —

    The path where the you want P12 exported to.

Returns:

  • (Object) —

    of certificate set in PKSC12 format at the path specified above



89
90
91
 
# File 'lib/win32/certstore.rb', line 89

def get_pfx(certificate_thumbprint, store_location: @store_location, export_password:, output_path: "")
  get_cert_pfx(certificate_thumbprint, store_location: store_location, export_password: export_password, output_path: output_path)
end

#list ⇒ Array

Returns all the certificates in a store

Parameters:

  • (nil)

Returns:

  • (Array) —

    array of certificates list



96
97
98
 
# File 'lib/win32/certstore.rb', line 96

def list
  cert_list(certstore_handler)
end

#search(search_token) ⇒ Array

Returns all matching certificates in a store

Parameters:

  • request (search_token<string>) —

    attributes of certificates as: CN, RDN, Friendly Name and other attributes

Returns:

  • (Array) —

    array of certificates list



110
111
112
 
# File 'lib/win32/certstore.rb', line 110

def search(search_token)
  cert_search(certstore_handler, search_token)
end

#valid?(certificate_thumbprint) ⇒ true, false

Validates a certificate in a certificate store on the basis of time validity

Parameters:

  • request (thumbprint<string>) —

    of certificate

Returns:

  • (true, false) —

    only true or false



117
118
119
 
# File 'lib/win32/certstore.rb', line 117

def valid?(certificate_thumbprint)
  cert_validate(certificate_thumbprint)
end