Class: Conjur::Variable
- Inherits:
-
RestClient::Resource
- Object
- RestClient::Resource
- Conjur::Variable
- Includes:
- ActsAsAsset
- Defined in:
- lib/conjur/variable.rb
Overview
Secrets stored in Conjur are represented by Variables. The code responsible for the actual encryption of variables is open source as part of the Slosilo library.
You should not generally create instances of this class directly. Instead, you can get them from API methods such as API#create_variable and API#variable.
Conjur variables store metadata (mime-type and secret kind) with each secret.
Variables are versioned. Storing secrets in multiple places is a bad security practice, but overwriting a secret accidentally can create a major problem for development and ops teams. Conjur discourages bad security practices while avoiding ops disasters by storing all previous versions of a secret.
Important
A common pitfall when trying to access older versions of a variable is to assume that 0
is the oldest
version. In fact, 0
references the latest version, while 1 is the oldest.
Permissions
- To read the value of a
variable
, you must have permission to'execute'
the variable. - To add a value to a
variable
, you must have permission to'update'
the variable. - To show metadata associated with a variable, but not the value of the secret, you must have
'read'
permission on the variable.
When you create a secret, the creator role is granted all three of the above permissions.
Instance Method Summary collapse
-
#add_value(value)
Add a new value to the variable.
-
#expires_in(interval) ⇒ Hash
Set the variable to expire after the given interval.
-
#kind ⇒ String
The kind of secret represented by this variable, for example,
'postgres-url'
or'aws-secret-access-key'
. -
#mime_type ⇒ String
The MIME Type of the variable's value.
-
#value(version = nil, options = {}) ⇒ String
Return the version of a variable.
-
#version_count ⇒ Integer
Return the number of versions of the variable.
Methods included from ActsAsAsset
Methods included from HasAttributes
#attributes, #invalidate, #refresh, #save, #to_json
Methods included from ActsAsResource
#deny, #permit, #resource, #resource_kind, #resourceid
Methods included from HasOwner
Methods included from Exists
Methods included from HasId
Instance Method Details
#add_value(value)
This method returns an undefined value.
Add a new value to the variable.
You must have the 'update'
permission on a variable to call this method.
153 154 155 156 157 158 159 160 |
# File 'lib/conjur/variable.rb', line 153 def add_value value log do |logger| logger << "Adding a value to variable #{id}" end invalidate do self['values'].post value: value end end |
#expires_in(interval) ⇒ Hash
Set the variable to expire after the given interval. The interval can either be an ISO8601 duration or it can the number of seconds for which the variable should be valid. Once a variable has expired, its value will no longer be retrievable.
You must have the 'update'
permission on a variable to call this method.
232 233 234 235 |
# File 'lib/conjur/variable.rb', line 232 def expires_in interval duration = interval.respond_to?(:to_str) ? interval : "PT#{interval.to_i}S" JSON::parse(self['expiration'].post(duration: duration).body) end |
#kind ⇒ String
this is not the same as the kind
part of a qualified Conjur id.
The kind of secret represented by this variable, for example, 'postgres-url'
or
'aws-secret-access-key'
.
You must have the 'read'
permission on a variable to call this method.
This attribute is only for human consumption, and does not take part in the Conjur permissions model.
122 123 124 |
# File 'lib/conjur/variable.rb', line 122 def kind attributes['kind'] end |
#mime_type ⇒ String
The MIME Type of the variable's value.
You must have the 'read'
permission on a variable to call this method.
This attribute is used by the Conjur services to set a response Content-Type
header when
returning the value of a variable. Conjur applies the same MIME Type to all versions of a variable,
so if you plan on accessing the variable in a way that depends on a correct Content-Type
header
you should make sure to store appropriate data for the mime type in all versions.
136 137 138 |
# File 'lib/conjur/variable.rb', line 136 def mime_type attributes['mime_type'] end |
#value(version = nil, options = {}) ⇒ String
Return the version of a variable.
You must have the 'execute'
permission on a variable to call this method.
When no argument is given, the most recent version is returned.
When a version
argument is given, the method returns a version according to the following rules:
- If
version
is 0, the most recent version is returned. - If
version
is less than 0 or greater than #version_count, aRestClient::ResourceNotFound
exception will be raised. - If #version_count is 0, a
RestClient::ResourceNotFound
exception will be raised. - If
version
is >= 1 andversion
<= #version_count, the version at the 1 based index given byversion
will be returned.
208 209 210 211 212 213 |
# File 'lib/conjur/variable.rb', line 208 def value(version = nil, = {}) url = 'value' ['version'] = version if version url << '?' + .to_query unless .empty? self[url].get.body end |
#version_count ⇒ Integer
Return the number of versions of the variable.
You must have the 'read'
permission on a variable to call this method.
172 173 174 |
# File 'lib/conjur/variable.rb', line 172 def version_count self.attributes['version_count'] end |