Memory
|
>Prerequisites for Creating a Custom-Defined Memory File >Comparison of Default and Custom-Defined Memory Files >Lifecycle Stages of a Memory File |
New to Sentinel EMS?
|
What Is a Memory File?
A memory file is a data file that is used for storing strings in a Sentinel key. Your application can read this data during runtime. Usage examples might include storing:
> customer-specific information, such as the customer name, group, or entity
>customer's purchase order number
>product-specific information, such as product configuration
>homegrown license data
>usage counters
You can associate memory files with any product in the same namespace. Using multiple memory files enables you to segregate memory data easily. (In rare cases, you may need to use memory segments to segregate data. For details, see What Is a Memory Segment?.)
Sentinel EMS provides two types of memory files for different needs—Default and Custom-Defined.
What Is a Memory Segment?
A memory segment is a defined area in a memory file. You can set the size of the segment, the offset, and so on. With segments, you must carefully calculate the sizes, offsets, and text length to ensure that data is never overwritten. You can then associate the same memory file with a product as many times as needed, so that all required segments are included. Sentinel EMS recognizes memory data as segments when a product includes multiple memory files with the same File ID and File Type.
Memory segments are useful only in certain cases, for example:
>You can include only Default memory files (not custom-defined memory files), and you need to segregate the data.
>Your data was migrated from Sentinel LDK-EMS, and you need backward compatibility for existing memory segments.
Otherwise, Thales recommends using distinct memory files, as this enables you to apply memory data as needed, without worrying about potentially overwriting other memory data. Sentinel EMS does the calculations for you and automatically positions the files sequentially, enabling you to utilize all of the memory file size effectively.
Prerequisites for Creating a Custom-Defined Memory File
A role that includes Catalog (Namespace) permissions for the relevant namespace.
Comparison of Default and Custom-Defined Memory Files
| Default Memory Files | Custom-Defined Memory Files | |
|---|---|---|
| Description |
Product-specific, out-of-the-box memory files that you can use as a basis for minimal memory data needs in Sentinel keys. Default memory files have a very small file size. Their data cannot be shared between products. |
Standalone memory files that are defined per namespace and then added to one or more products. This enables you to use the same custom-defined memory files in multiple products. Useful for large data content, pre-defined content, or multiple files. You can define and associate custom-defined memory files as needed. |
| Size and file attributes |
Each default memory file has a fixed file size, which is much smaller than the size available for custom-defined memory files*. >Default (Read/Write) 4032 bytes** >Default (Read-Only) 2048 bytes** You can associate a maximum of one read-only memory file and one read-write memory file in each product. |
Each file size is customizable, enabling you to optimize the use of available space. The overall space available for custom-defined memory files is much larger than the space available for default memory*. Each custom-defined memory file can contain read-only, read-write, or write once memory, providing you with more options than default memory. This lets you "mix-and-match" memory files with the same or different "read" attributes. In addition, "write once" memory enables you to convert a read-write file to a read-only file after a single edit. |
| Supported Sentinel Keys |
Default memory files are supported for: >Sentinel SL AdminMode keys >Sentinel SL UserMode keys >Sentinel HL (Driverless configuration) keys (excluding Sentinel HL Basic keys) >Sentinel HL (HASP configuration) keys (excluding Sentinel HL Basic keys) |
Custom-defined memory files are supported for: >Sentinel SL AdminMode keys >Sentinel SL UserMode keys >Sentinel HL (Driverless configuration) keys (excluding Sentinel HL Basic keys) |
| When do you define memory files? |
You define default memory files when creating or editing a product. You can set the text value when associating a default memory file with a product as described in Associate Memory Files. If overwrite is allowed, the order taker can set the text when creating an entitlement. |
You create custom-defined memory files in advance. Then you can associate one or more of your custom-defined memory files when creating or editing a product. If overwrite is allowed, the order taker can update the text when creating an entitlement. |
|
For best results |
>Consider the size of each file when determining the data to use. >You can use memory segments to insert multiple data strings by associating the same default memory file with a product multiple times. Default memory files are stored in a common location on the Sentinel key, regardless of the product. When you associate the same default memory files (same file ID) with multiple products in an entitlement, carefully set the offset and size of the associated default memory files in each product to prevent overlap and overwriting. |
>Include a single piece of data in each custom-defined memory file, such as a variable or a constant. >Set the file size to the maximum required for the data in that file. Smaller files generate faster than larger files. >For large amounts of data, consider the Sentinel key type when determining the maximum file size. For details, see File Size (Bytes). >To ensure efficiency and maintainability, Thales recommends that you use distinct memory files for each piece of data instead of memory segments. |
*For details on the memory file sizes available for the various Sentinel HL keys, see Sentinel HL Data Sheet.
Lifecycle Stages of a Memory File
The Deployed attribute indicates whether a memory file is included in a product or not.
>Deployed: The memory file is included in a product.
>Not Deployed: The memory file is not included in a product.
Creating a Custom-Defined Memory File
You can create memory files for use with one or more products in a namespace. For example, you may require a larger file size than available in the default memory files, or you may need to include multiple memory files in a product. After a memory file is created, you can associate the memory file with a product.
To create a memory file:
1.From the navigation pane, select Catalog > Memory to view the Memory page.
2.Click the Add Memory button.
3.Fill in the memory file attributes.
4.Click Save. The Add Memory page closes, and the memory file is added to the list on the Memory page.
Memory File Attributes
The table below describes the memory-related attributes. The actual attributes displayed in Sentinel EMS depend on the specific configuration.
NOTE The combined value of Text and Offset must not exceed the memory File Size (Bytes). For memory segments, this combined value must not exceed Size (Bytes).
| Attribute | Description | Required/Optional | Valid Values |
|---|---|---|---|
| Namespace (Visible only if more than one namespace is available.) |
|
Required |
>Any namespace in the list that is allocated for the required enforcement |
| File Name |
A descriptive name of the memory file. |
Required |
> 1-50 characters >Must be unique |
|
Integer that identifies the memory file and is used by your application to refer to that file. If you are using the Sentinel Licensing API or Sentinel Licensing REST API, make sure to use the same memory file ID. |
Required |
Integer from 1-65471 Can be: >An automatically generated, sequential file ID >Your own numeric identifier |
|
| File Type |
File permissions for the data stored in the memory file. |
Required |
One of the following: >Read Only: (Default) Data that cannot be changed. The data is read at runtime when the deployed, protected application is running. Usage examples: The product identifier, text to be used in a “Welcome” message, and fixed threshold values for counters. >Read/Write: Data that can be updated at runtime when the deployed, protected application is running. Usage example: Dynamic values for counters >Read/Write Once: Data that can be updated only once at runtime when the deployed, protected application is running. After a successful update, the memory file becomes read-only. |
|
Size of the memory file in bytes. For default memory files, the file size is set automatically and is read-only. For custom-defined memory files, if not defined, the size is determined automatically based on the text length and offset. |
Optional If not specified, the file size is assigned automatically based on the amount of data that is written to the file. |
Maximum: Custom-defined memory: >Sentinel SL keys: 65535 bytes >Sentinel HL key version 6.x keys: 65535 bytes >Sentinel HL key version 4.x keys: 25944 bytes Default memory: >Default (Read/Write): 4032 bytes* >Default (Read-Only): 2048 bytes* |
|
| Description | Description of the memory file. | Optional | Maximum: 500 characters |
|
Additional Attributes |
|||
| Ref ID 1 |
Reference identifier that identifies the memory file in an external system. |
Optional | Maximum: 100 characters |
| Ref ID 2 |
Reference identifier that identifies the memory file in an external system. |
Optional | Maximum: 100 characters |
|
A descriptive name of the memory segment. The name is intended for your convenience. You can apply the same name to multiple segments in a memory file as long as the offset is different. |
Optional |
>Maximum: 50 characters >Cannot contain: < > |
|
|
The hexadecimal starting point of the memory file or segment in bytes. You can use the offset to set the order and location of the memory data as needed. Make sure that the data do not overlap. For memory segments: Make sure that the offset and segment size fit within the memory file size. |
Optional If not specified, a default offset is assigned automatically. |
A hexadecimal number. Default: 0 |
|
|
Size of the memory segment in bytes. Make sure that the offset and segment size fit within the memory file size. |
Optional |
Maximum: Custom-defined memory: >Sentinel SL keys: 65535 bytes >Sentinel HL key version 6.x keys: 65535 bytes >Sentinel HL key version 4.x keys: 25944 bytes Default memory: >Default (Read/Write): 4032 bytes* >Default (Read-Only): 2048 bytes* |
|
|
The memory data in text format. The text must not exceed the maximum allotted space, as defined by the size and offset. NOTE To insert hexadecimal data instead of text, use the REST API for memory files. |
Optional You can also add or edit text when: >associating the memory file with a product as described in Associate Memory Files. >configuring an entitlement—if the Allow Overwrite check box is selected when creating the product containing the memory file. |
Maximum: Custom-defined memory: >Sentinel SL keys: 65535 bytes >Sentinel HL key version 6.x keys: 65535 bytes >Sentinel HL key version 4.x keys: 25944 bytes Default memory: >Default (Read/Write): 4032 bytes* >Default (Read-Only): 2048 bytes* |
|
Actions for Memory Files
| Action | Description | |
|---|---|---|
|
Edit |
Makes the data file editable so you can update the data in an existing memory file. The editable attributes depend on the lifecycle stage of the memory file. (Available only for non-default memory files.) >Deployed. You can edit: Description, Ref ID 1, Ref ID 2 >Not Deployed. You can edit all details. |
|
Delete |
Deletes the memory file. (Available only for non-default and non-deployed memory files.) |
|
End of Life |
Marks a deployed memory file as End of Life (EOL) to make the file obsolete. You cannot add EOL memory files to products, but EOL memory files may still be included in products that are already deployed. You can restore an EOL memory file by clicking Restore |
. This makes the memory file available for products. (Available only for non-default memory files.)